better-staridc-MNBT
1---
2title: 外部对接 API
3description: api/api.php 主机生命周期 API 与 api/node.php MNBT 节点 API 对接说明
4---
5
6# 外部对接 API
7
8## 4.1 主机生命周期 API（api/api.php）
9
10**入口**：`POST /api/api.php?gn=<动作>`
11**文件**：api/api.php
12**Content-Type**：`application/json; charset=UTF-8`
13
14### 鉴权参数（所有请求必带）
15
16| 参数 | 说明 |
17|------|------|
18| `mn_bh` | 宝塔节点编号（`MN_bt.btdh`） |
19| `mn_key` | 系统密钥（= `MN_config.api`） |
20| `mn_keye` | 宝塔调用密钥 = `md5(MN_bt.ktmy . MN_bt.qmk)` |
21| `mn_vs` | 插件版本号（必须 >= 15） |
22| `username` | 主机用户名（`MN_zj.user`） |
23
24### 接口列表
25
26| `gn` | 功能 | 额外参数 | 返回 |
27|------|------|----------|------|
28| `cfif` | 连接验证 | 无 | `{"success":true,"code":200,"msg":"连接验证成功！"}` |
29| `kt` | 开通主机 | `password`、`sizemax`、`dqtime`、`webdx`、`sqldx`、`ymbds` | 同上 |
30| `zt` | 暂停主机 | 无 | 同上 |
31| `jc` | 解除暂停 | 无 | 同上 |
32| `tz` | 删除主机 | 无 | 同上 |
33| `xf` | 续费主机 | `setdate`（续期日期） | 同上 |
34| `czmm` | 重置 FTP/面板密码 | `password` | 同上 |
35| `zjmode` | 修改主机配额 | `websize`、`sqlsize`、`ll` | 同上 |
36
37### 请求示例
38
39```http
40POST /api/api.php?gn=kt HTTP/1.1
41Host: your-domain.com
42Content-Type: application/x-www-form-urlencoded
43
44mn_bh=1&mn_key=YOUR_API_KEY&mn_keye=MD5_OF_BT_KEY&mn_vs=15&username=testuser&password=testpass123&sizemax=1024&dqtime=2026-12-31&webdx=1024&sqldx=512&ymbds=5
45```
46
47### 响应示例
48
49```json
50{
51 "success": true,
52 "code": 200,
53 "msg": "主机开通成功！"
54}
55```
56
57```json
58{
59 "success": false,
60 "code": 100,
61 "msg": "错误！该主机已经存在，请重新开通！"
62}
63```
64
65### 开通规则
66
67- 账号、密码长度 >= 6
68- 账号不能重复
69- 自动检测节点 PHP 版本（优先使用 `MN_bt.mrbts_php`，否则取最新已安装版本）
70- 自动触发 `host.created` 钩子（插件可监听）
71
72### 协议兼容开关（`MN_config.api_compat`）
73
74V1.83+ 在不变的传输包络（POST 表单 + `{success,code,msg}` 响应）之上加入了若干**行为约束**，仍在使用 1.81 版对接模块（`wp_seller_plugin`、魔方财务 `mnbthost` server module）的客户升级 MNBT 后可能被拒。为此提供开关：
75
76- 取值：`0` = 新版协议（1.83+ 严格，默认）；`1` = 兼容 1.81 对接模块
77- 后台切换：系统设置 → API 设置 → 「对外 API 协议模式」
78- 代码判断：`api/api.php` 内统一走 `mnbt_api_compat_mode()`（`MPHX/function.php`）读取该配置
79
80两种模式的行为差异（仅 `api/api.php`）：
81
82| 差异点 | 新版协议（api_compat=0） | 兼容 1.81（api_compat=1） |
83|--------|--------------------------|---------------------------|
84| 跨节点归属校验（除 `kt`/`cfif` 外，含 `zjmode`） | `MN_zj.ssbt` 与 `mn_bh` 严格比较，不一致返回 `主机不属于该节点` | 跳过该校验（老模块传的 `username` 可能与节点代号对不上） |
85| 空主机检查 | `不存在主机用户名` | 保留不变（1.81 靠弱类型访问空行是 bug，不还原） |
86| `kt` 站点名 | `mnbt.<随机>.<后缀>`，写库失败重取号重试 | `mnbt.<max(id)+1><随机>.<后缀>`，单次取号插入（老模块按 id 序列猜站点名） |
87| `zjmode` 配额 | 仅在传入 `websize`/`sqlsize`/`ll` 非空时覆盖 | 无条件覆盖，缺参即清零（老模块依赖该语义） |
88| `xf` 续费自动解停 | 仅当 `qk=='false'`（真暂停）才解停 | 对 `qk` 做真值判断（1.81 原行为：总会解停） |
89| 宝塔调用密钥校验失败 | `调用密钥不匹配！`，日志带 key 前缀 | `错误！您所传输的宝塔调用密钥与该宝塔的调用密钥不匹配！`，日志不带前缀（老模块按 msg 文案分支） |
90| `kt` 主机存在判断 | `if($et_zj)` | 同左，刻意不还原 1.81 的恒真表达式（那是 bug 不是兼容需求） |
91| `tz` 删除主机 | 级联删除 `MN_plugin_hosting_asset` | 同左，保留不动 |
92
93> **提示：** 兼容模式只是过渡期方案，会放宽跨节点归属等安全约束。建议尽快将对接模块升级到适配 1.83+ 协议的版本，然后切回「新版协议」。
94
95---
96
97## 4.2 MNBT 节点 API（api/node.php）
98
99**入口**：`POST /api/node.php?act=<动作>`
100**文件**：api/node.php
101**Content-Type**：`application/json`（请求体为 JSON）
102**鉴权**：通过 `mnbt_node_authenticate()` 校验 `node_id` + `node_secret`
103
104### 接口列表
105
106| `act` | 功能 | 请求体 | 返回 |
107|-------|------|--------|------|
108| `heartbeat` | 心跳上报 | 节点状态信息 | `{"success":true,"msg":"heartbeat ok","server_time":"..."}` |
109| `pull_task` | 拉取待执行任务 | 无 | `{"success":true,"msg":"pull task ok","task":{...}}` |
110| `report_result` | 上报任务结果 | 任务执行结果 | `{"success":true,"msg":"..."}` |
111| `get_config` | 获取节点配置 | 无 | `{"success":true,"msg":"config ok","config":{"forbidden_scan":{...}}}` |
112
113### `get_config` 返回的违禁词扫描配置
114
115```json
116{
117 "config": {
118 "forbidden_scan": {
119 "enabled": true,
120 "content": "违禁词1,违禁词2",
121 "scan_changed_only": true,
122 "scan_dir": "/www/wwwroot",
123 "skip_dirs": ".git,node_modules,vendor,runtime,cache,logs",
124 "skip_exts": ".jpg,.png,.gif,.webp,.mp4,.zip,.rar,.7z,.pdf,.woff,.ttf",
125 "max_file_size": 5242880,
126 "max_matches": 1000,
127 "full_scan_enabled": true,
128 "full_scan_cron": "0 3 * * *"
129 }
130 }
131}
132```
133
134### 监控任务执行入口
135
136| 文件 | 用途 | 触发方式 |
137|------|------|----------|
138| `jk_monitor.php` | URL 监控 + 资源监控 + 到期/流量提醒 | 宝塔计划任务每分钟访问 `?my=API密钥` |
139| `jk.php` | 域名/文件监控 | 内部调用 |
140
141---
142
143[API 参考总览](../api/overview.md)