better-staridc-MNBT
1---
2title: MNBT 虚拟主机 × 魔方财务（idcsmart）对接 PRD
3description: 魔方财务 server module 对接 MNBT 宝塔虚拟主机产品的产品需求文档（已实现）
4---
5
6# MNBT 虚拟主机 × 魔方财务（idcsmart）server module 对接插件 PRD
7
8> 版本：v1.0（M1-M3 已交付，待联调验证）
9> 日期：2026-08-07
10> 状态：已实现
11> 关联文档：[Docker×魔方财务 PRD](./docker-idcsmart.md)、[API 总览](../api/overview.md)、`api/api.php` 实现、魔方财务《[服务器模块（server module）开发文档](https://docs.idcsmart.com/docs/%E8%B4%A2%E5%8A%A1%E7%B3%BB%E7%BB%9F%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/%E6%9C%8D%E5%8A%A1%E5%99%A8%E6%A8%A1%E5%9D%97%EF%BC%88server%20module%EF%BC%89)》
12
13---
14
15## 1. 背景与目标
16
17### 1.1 背景
18
19MNBT（梦奈宝塔主机系统，V1.83）的核心产品线是**宝塔虚拟主机分销**：通过 `api/api.php` 外部 API 完成开通（`kt`）、暂停（`zt`）、续费（`xf`）、恢复（`jc`）、删除（`tz`）、重置密码（`czmm`）、修改配额（`zjmode`）等生命周期动作，数据落库 `MN_bt`（节点）/ `MN_zj`（主机）。
20
21此前已完成 **Docker 容器**与魔方财务的对接插件（`mnbtdocker`），验证了 server module 对接模式可行。现需将 **虚拟主机**同样接入魔方财务，作为标准服务器产品对外销售。
22
23### 1.2 与 Docker 对接的核心差异
24
25| 维度 | Docker 对接（已完成） | 虚拟主机对接（本 PRD） |
26|------|----------------------|------------------------|
27| 业务模型 | 容器（单容器/应用商店） | 宝塔站点（FTP + MySQL + 配额） |
28| 开通语义 | 仅建账号，容器后建 | **开通即建站**（`webkt`） |
29| 配额管理 | create_app 时 cpus/mem | **空间/数据库/流量三级配额**（hxa/hxb/llmax） |
30| 状态查询 | 需新增 `ztcx` | **需新增 `ztcx`/`sy`**（现无状态查询 gn） |
31| 容器启停 | start/stop/restart | 站点启停（siteqt），魔方 On/Off 可选 |
32| 对外 API | `api/docker.php`（M1 扩展） | `api/api.php`（生命周期已成熟，仅补查询） |
33| 节点标识 | `MN_docker_node.id` | **`MN_bt.btdh`**（宝塔开通代号） |
34
35### 1.3 范围
36
37| 期次 | 内容 |
38|------|------|
39| **P0（本期）** | 魔方侧：`mnbthost` 模块骨架 + 生命周期闭环（CreateAccount/Suspend/Unsuspend/Terminate/Renew/ChangePackage/CrackPassword）+ **站点启停（On/Off）** + TestLink + ClientArea（登录信息+配额用量展示）。MNBT 侧：`api/api.php` 新增 `ztcx`（状态+配额用量查询）、`start`/`stop`（站点启停） |
40| **P1（下期）** | `sy` 用量单独接口 + UsageUpdate 批量定时上报 + 前台图表（空间/流量占用） |
41
42---
43
44## 2. 总体架构
45
46### 2.1 架构图
47
48```
49┌─────────────────────────────────────────────────────────────┐
50│ 魔方财务（idcsmart） │
51│ 前台用户 ──下单/续费/删除/控制台──▶ shd_host / 订单体系 │
52│ │ │
53│ ▼ │
54│ /modules/servers/mnbthost/mnbthost.php │
55│ (server module：CreateAccount/Renew/Status/...) │
56└──────────────────────────────────┬──────────────────────────┘
57 │ HTTPS POST（mn_bh/mn_key/mn_keye 鉴权）
58 ▼
59┌─────────────────────────────────────────────────────────────┐
60│ MNBT 外部 API：api/api.php │
61│ cfif/kt/zt/xf/jc/tz/czmm/zjmode（已成熟） │
62│ + ztcx（本期新增：状态 + 配额用量） │
63└──────────────────────────────────┬──────────────────────────┘
64 │
65 ┌────────────────────┼────────────────────┐
66 ▼ ▼ ▼
67 MN_bt（节点） MN_zj（主机/站点） MPHX/bt_api.php
68 btdh/btmy/ktmy/qmk hxa/hxb/llmax 配额 （宝塔站点 API）
69```
70
71**核心模型**：虚拟主机 = 宝塔站点。`CreateAccount` 调 `kt` **立即建站**（含 FTP、数据库），配额（网站空间 hxa / 数据库空间 hxb / 流量 llmax）随产品配置选项落库，魔方侧负责计费与生命周期管理。
72
73### 2.2 模块命名
74
75| 项 | 值 |
76|----|----|
77| 模块目录 | `/modules/servers/mnbthost/` |
78| 主文件 | `mnbthost.php` |
79| 显示名 | 梦奈宝塔虚拟主机 |
80
81> ⚠️ 不使用 `mnbt_host`（含下划线，不符合魔方"仅小写字母和数字"命名约束）。
82
83---
84
85## 3. 魔方侧：server module 设计
86
87### 3.1 目录结构
88
89```
90modules/servers/mnbthost/
91├── mnbthost.php # 模块主文件（全部方法）
92├── templates/
93│ └── console.html # ClientAreaOutput 登录信息页（P0）
94└── README.md # 安装/配置说明
95```
96
97### 3.2 MetaData
98
99```php
100function mnbthost_MetaData() {
101 return [
102 'DisplayName' => '梦奈宝塔虚拟主机',
103 'APIVersion' => '1.1',
104 'HelpDoc' => 'https://github.com/1181469655/MNBT', // 指向 MNBT 仓库
105 ];
106}
107```
108
109### 3.3 ConfigOptions（产品级配额配置）
110
111> 与 noKVM 相同模式：**连接信息全部走服务器字段**（§3.4），ConfigOptions 只承载产品配额与展示项，开通时通过 `$params['configoptions']` 读取。
112
113| # | key | 类型 | 必填 | 默认 | 说明 |
114|---|-----|------|------|------|------|
115| 1 | `webdx` | text | 否 | `500` | 网站空间（MB），即 `kt` 的 `webdx` |
116| 2 | `sqldx` | text | 否 | `100` | 数据库空间（MB），即 `kt` 的 `sqldx` |
117| 3 | `sizemax` | text | 否 | `0` | 流量上限（MB，0=不限），即 `kt` 的 `sizemax` |
118| 4 | `ymbds` | text | 否 | `1` | 域名绑定上限（个），即 `kt` 的 `ymbds` |
119| 5 | `console_url` | text | 否 | 空 | 虚拟主机用户控制台地址（如 `https://mnbt.example.com/user/login.php`） |
120
121### 3.4 服务器字段映射（连接信息）
122
123| 魔方服务器字段 | 用途 | MNBT 侧 |
124|----------------|------|---------|
125| `server_ip` / `server_host` | API 主机 | MNBT 站点域名 |
126| `port` | API 端口 | 80/443 |
127| `secure` | HTTPS | 按站点是否 HTTPS |
128| `server_username` | 节点编号 | **`MN_bt.btdh`**（⚠️ 注意：虚拟主机节点标识是 `btdh` 开通代号，不是自增 `id`，与 Docker 的 `MN_docker_node.id` 不同） |
129| `server_password` | 调用密钥 | `md5(节点ktmy . 节点qmk)`，空则自动兜底 `md5('')` |
130| `accesshash` | 系统 API 密钥 | `$conf['api']` |
131
132API 地址 = `{scheme}://{host}[:port]/api/api.php`，由模块自动拼装，无需单独配置。
133
134### 3.5 内置方法实现规格
135
136通用约定（与 Docker 模块一致）：
137- `POST {api_url}?gn=<动作>`，表单携带 `mn_bh`（btdh）、`mn_key`、`mn_keye`、`mn_vs=15`、`username`。
138- 成功判定：MNBT 返回 `code==200` 且 `success==true`（对齐 `api/api.php` 现有 `api_json_exit` 风格）。
139- 失败返回 `['status'=>'error','msg'=>...]`；成功返回 `'success'` 或 `['status'=>'success']`。
140- 用户名：**使用魔方 `$params['domain']`**（主机名，随机唯一），空时兜底 `zh_{hostid}`。密码用 `$params['password']`，空时随机生成。
141
142| 魔方方法 | MNBT gn | 关键入参 | 说明 |
143|----------|---------|----------|------|
144| `TestLink` | `cfif` | username=`test` | 校验连接与鉴权（返回 `['status'=>200,'data'=>['server_status'=>1|0,'msg'=>...]]`） |
145| `CreateAccount` | `kt` | username、password、`webdx`/`sqldx`/`sizemax`/`ymbds`（取自 configoptions）、`dqtime`=nextduedate（永久/空传 `0`） | **开通即建站**（FTP+数据库+站点） |
146| `SuspendAccount` | `zt` | username | 停站点+FTP，`qk=false` |
147| `UnsuspendAccount` | `jc` | username | `qk=true`，恢复站点+FTP |
148| `TerminateAccount` | `tz` | username | 删站点 → 删 `MN_zj` 行 |
149| `Renew` | `xf` | username、`setdate`=nextduedate | 更新 `datae`，必要时恢复 |
150| `ChangePackage` | `zjmode` | username、`websize`/`sqlsize`/`ll`（新配额绝对值） | 升降级后更新配额；通过 `configoptions_upgrade` 检测变更项（参照 noKVM 写法） |
151| `CrackPassword` | `czmm` | `$new_pass`（第二参数） | 重置 FTP+控制面板密码 |
152| `Status` | `ztcx`（新增） | username | 状态映射（见 §5） |
153| `Sync` | `ztcx` | username | 同步状态/配额回魔方 |
154| `On` | `start`（新增） | username | 启动站点（SiteStart）；`qk=false` 拒绝 |
155| `Off` | `stop`（新增） | username | 停止站点（SiteStop） |
156| `UsageUpdate`（P1） | `sy`（新增） | 全量 hostID | 空间/流量用量批量上报 |
157
158**CreateAccount 细节**：
1591. `mn_vs=15`；`username` 用魔方 `domain`（如 `seri914WksqNY`），保证唯一且不与现有用户冲突。
1602. `dqtime`：`nextduedate` 为 `0000-00-00` 或空 → 传 `0`（永久）。
1613. 配额参数单位与 MNBT 现有口径一致（hxa/hxb/llmax 直接存值，PRD 假定 MB，联调时以魔方/宝塔实际口径校准，见 Q1）。
1624. 返回 `ok` 后魔方自动回写账号密码到产品表（`shd_host.username/password`）。
163
164**ChangePackage 细节**：`zjmode` 接收 `websize`/`sqlsize`/`ll` 三个**绝对值**参数（见 api/api.php L192-202：`$hxa_array['max'] = $_POST['websize']`）。魔方侧遍历 `$params['configoptions_upgrade']`，对变更的 `webdx/sqldx/sizemax` 分别传值；未变更的项不传（保持原值）。php 版本字段由 MNBT 节点默认值管理，不参与升降级。
165
166### 3.6 ClientArea 前台自定义输出
167
168```php
169function mnbthost_ClientArea($params) {
170 return [
171 'console' => ['name' => '主机信息'],
172 ];
173}
174```
175
176`ClientAreaOutput`（key=`console`）：
177- 调 `gn=ztcx` 查询状态与配额用量。
178- 模板（`templates/console.html`）展示：**控制台地址（可点击+一键复制）、账号、密码、网站/数据库/流量用量进度条、状态图标**。
179- 样式沿用 Docker 模块的轻量 CSS+JS 方案（不依赖 UI 框架，含 `dockerCopy` 一键复制脚本），保持一致观感。
180
181### 3.7 ClientButton 前台自定义按钮
182
183```php
184function mnbthost_ClientButton($params) {
185 return [
186 'console' => ['place' => 'console', 'name' => '打开主机控制台'],
187 ];
188}
189```
190
191自定义方法 `mnbthost_console` 返回 `['status'=>'success','url'=>$console_url]`（P0 外链跳转，用户用主机账号登录）。
192
193---
194
195## 4. MNBT 侧：外部 API 扩展（api/api.php）
196
197### 4.1 现状（已成熟，无需改动）
198
199| gn | 动作 | 魔方对应 |
200|----|------|----------|
201| `cfif` | 连接验证 | TestLink |
202| `kt` | 开通主机（建站+FTP+数据库） | CreateAccount |
203| `zt` | 暂停（停站点+FTP） | SuspendAccount |
204| `jc` | 恢复 | UnsuspendAccount |
205| `xf` | 续费（`setdate`） | Renew |
206| `tz` | 删除（删站点+删行） | TerminateAccount |
207| `czmm` | 重置密码 | CrackPassword |
208| `zjmode` | 修改配额（`websize`/`sqlsize`/`ll`） | ChangePackage |
209
210> 现有 8 个 gn 已满足生命周期闭环，**本期新增 3 个只读/操作 gn**：`ztcx`（状态+配额查询）、`start`/`stop`（站点启停）。其余不改动。
211
212### 4.2 新增 gn：`ztcx` 状态与配额查询
213
214```
215POST api/api.php?gn=ztcx
216```
217
218**逻辑**：按 `username` 查 `MN_zj` → 解析 `hxa/hxb/llmax`（JSON，`max`/`dq` 字段）→ 组装返回。
219
220**响应**：
221
222```json
223{
224 "success": true, "code": 200, "msg": "ok",
225 "data": {
226 "user": {
227 "username": "seri914WksqNY", "qk": "true", "datae": "2027-12-31",
228 "domain": "seri914WksqNY", "sqluser": "seri914", "btid": "12",
229 "created_at": "2026-08-07"
230 },
231 "quota": {
232 "web_size_max": 500, "web_size_used": 123, "unit": "MB",
233 "sql_size_max": 100, "sql_size_used": 12, "unit": "MB",
234 "flow_max": 0, "flow_used": 0, "unit": "MB"
235 },
236 "node": { "btip": "150.158.137.178", "ptl": "true" }
237 }
238}
239```
240
241- 用户不存在 → `code 100`。
242- 配额单位沿用 `MN_zj.hxa/hxb/llmax` 存储口径（MB），与 `kt`/`zjmode` 入参一致。
243- 不调宝塔接口（用量存于本地 JSON 字段），响应快、不依赖节点在线。
244
245### 4.3 新增 gn：`start` / `stop` 站点启停
246
247```
248POST api/api.php?gn=start # 启动站点（SiteStart）
249POST api/api.php?gn=stop # 停止站点（SiteStop）
250```
251
252**逻辑**：
253- 按 `username` 查 `MN_zj`，用户不存在 → `code 100`。
254- `start` 额外校验：`qk=false`（已暂停）→ 拒绝，提示"该主机已暂停，请先解除暂停"。
255- 调宝塔 `siteqt($btid, $sqldz, $start)`，成功（`status==1`）→ `code 200`；失败返回宝塔 `msg`。
256
257响应：`{"success":true,"code":200,"msg":"站点启动成功！"}` / `"站点停止成功！"`
258
259> 与 `zt`/`jc`（账户暂停/恢复，改 `qk` 并停 FTP）语义不同：`start`/`stop` 仅操作站点运行状态，**不改变 `qk` 账户状态**。
260
261### 4.4 预留 gn：`sy` 用量查询（P1）
262
263单账号/批量（逗号分隔）返回 `web_size_used`/`sql_size_used`/`flow_used`，供魔方 `UsageUpdate` 定时拉取。P0 不做。
264
265---
266
267## 5. 状态与用量映射
268
269### 5.1 Status 映射表
270
271| MNBT 侧状态 | 魔方 status | des |
272|-------------|-------------|-----|
273| `qk=true` 且未到期 | `on` | 运行中 |
274| `qk=false`（暂停） | `suspend` | 已暂停 |
275| `datae` 已过（非永久） | `suspend` | 已到期 |
276| 用户不存在 / 查询失败 | `unknown` | 未知状态 |
277
278> 虚拟主机开通为**同步建站**，无 `creating/waiting` 中间态（与 Docker 不同）。
279
280### 5.2 用量模型（P1 UsageUpdate）
281
282```php
283['status' => 'success', 'data' => [
284 ['hostid' => 1, 'web_size_used' => 123, 'web_size_max' => 500,
285 'sql_size_used' => 12, 'sql_size_max' => 100,
286 'flow_used' => 0, 'flow_max' => 0, 'unit' => 'MB'],
287]]
288```
289
290---
291
292## 6. 安全设计
293
294| 项 | 方案 |
295|----|------|
296| 鉴权 | 沿用 MNBT 三层：系统密钥（`mn_key`）+ 节点调用密钥 md5（`mn_keye`）+ 节点启用校验（`MN_bt.qk`） |
297| 密钥存储 | 魔方侧 `server_password`（调用密钥）、`accesshash`（系统密钥），不回显不落日志 |
298| 日志 | MNBT `api_lifecycle_log` 仅记录用户名与动作，不记录密码 |
299| 越权 | 所有 gn 按 `username` 定位 `MN_zj`，无跨用户访问路径 |
300| 传输 | HTTPS 建议项；`api_url` 仅接受 `http(s)://` |
301
302---
303
304## 7. 安装部署与配置
305
306### 7.1 安装模块
307
3081. 将 `mf_modules/servers/mnbthost/` 复制到魔方财务 `/modules/servers/mnbthost/`。
3092. 清魔方缓存，后台「产品 → 服务器」确认模块出现。
310
311### 7.2 服务器接口设置
312
313| 字段 | 值 |
314|------|-----|
315| 服务器 IP/域名 | MNBT 域名 |
316| 端口 | 80/443 |
317| 用户名 | `MN_bt.btdh`（宝塔开通代号，⚠️ 非自增 id） |
318| 密码 | `md5(节点ktmy . 节点qmk)` 或留空 |
319| Access Hash | 系统 API 密钥（`$conf['api']`） |
320| SSL | 按站点勾选 |
321
322### 7.3 产品关联模块
323
324后台「产品 → 添加产品」→ 类型「服务器产品」→ 模块「梦奈宝塔虚拟主机」→ 配置产品配额（网站空间/数据库空间/流量/域名数）。
325
326### 7.4 联调验证流程
327
3281. 前台下单 → 支付 → 自动开通 → MNBT 后台「主机列表」出现站点（含 FTP/数据库）。
3292. 后台执行 暂停/恢复/续费/删除/改密/升降级 → `MN_zj` 状态与配额正确变化。
3303. 前台点「开机/关机」→ 站点运行状态同步变化（`siteqt`）。
3314. 前台「主机信息」页显示账号密码、配额用量进度条、状态图标。
332
333---
334
335> 后续章节（里程碑与验收、决策点、风险与开放问题）及部署配置速览见 [hosting-idcsmart-appendix.md](./hosting-idcsmart-appendix.md)。