better-staridc-MNBT
1---
2title: MNBT Docker × 魔方财务（idcsmart）对接 PRD — 附录
3description: Docker×魔方财务 PRD 的附录：安全设计、安装部署与配置、里程碑与验收、决策点、风险与开放问题，及部署配置速览
4---
5
6# MNBT Docker × 魔方财务（idcsmart）对接 PRD — 附录
7
8> 本文为 [Docker×魔方财务 PRD](./docker-idcsmart.md)（§1-§5）的附录部分，含安全设计、安装部署与配置、里程碑与验收、决策点、风险与开放问题，以及部署配置速览。
9
10---
11
12## 6. 安全设计
13
14| 项 | 方案 |
15|----|------|
16| 传输 | 强制 HTTPS 建议项；`api_url` 仅接受 `http(s)://`，模块校验协议头 |
17| 鉴权 | 沿用 MNBT 三层鉴权：系统密钥（`mn_key`）＋ 节点调用密钥 md5（`mn_keye`）＋ 节点启用校验 |
18| 密钥存储 | 魔方侧 `api_key/call_key` 用 `password` 类型配置项存储；不写入日志、不回显 |
19| 日志脱敏 | MNBT `api_lifecycle_log` 仅记录用户名与动作，不记录密码/密钥 |
20| 越权隔离 | MNBT `ztcx/sy/start/stop/restart` 一律按 `username` 定位用户，容器操作以 `MN_docker_user.service_name` 为锚点，无越权路径 |
21| 自动登录（P1） | `gn=dl` 一次性票据：`md5(uid . timestamp . SYS_KEY)`，5 分钟有效、单次使用、不落明文密码；`docker/login.php?token=` 兑换会话后立即作废 |
22| 请求超时 | 模块侧 curl 超时（同步 30s / 查询 60s），失败即返回错误，不静默 |
23
24---
25
26## 7. 安装部署与配置
27
28### 7.1 安装模块
29
301. 将 `modules/servers/mnbtdocker/` 上传至魔方财务根目录。
312. 清魔方缓存（后台或 `runtime` 缓存目录）。
323. 后台「产品 → 服务器」确认模块出现在模块下拉中。
33
34### 7.2 服务器接口设置（可选，兜底用）
35
36后台「产品 → 服务器」添加服务器：
37- 服务器 IP/域名：MNBT 域名
38- 端口：MNBT 站点端口
39- 用户名：节点编号（`MN_docker_node.id`）
40- 密码：调用密钥 md5
41- Access Hash：系统 API 密钥
42- SSL：按站点是否 HTTPS 勾选
43
44### 7.3 产品关联模块
45
46后台「产品 → 添加产品」：
47- 类型：**服务器产品**
48- 模块：**MNBT Docker**
49- 配置选项：按需填写 `api_url`/`api_key`/`node_id`/`call_key`/`plan_id`/`console_url`（若 §7.2 已填服务器兜底字段，可只填 `plan_id`）
50- 可配置选项：如「套餐 ID」字段映射到 `plan_id` key，则按用户所选套餐自动传参
51
52### 7.4 开通闭环验证流程
53
541. 前台下单购买该产品 → 支付 → 自动开通 → 魔方后台该产品「操作」显示成功。
552. 用户前台「产品详情 → 容器控制台」标签页显示容器概要。
563. 后台执行 暂停/恢复/删除/续费/升降级/改密 → 对应 MNBT `MN_docker_user` 状态正确变化，操作日志可见。
574. 用户在前台点「开机/关机/重启」→ MNBT 容器状态同步变化。
58
59---
60
61## 8. 里程碑与验收
62
63### M1 — MNBT API 扩展（前置依赖）
64- [ ] `api/docker.php` 新增 `zt/jc/tj/xf/bg/czmm/ztcx/sy/start/stop/restart`。
65- [ ] 各 gn 写操作日志、触发钩子；与 `api/api.php` 现有风格一致。
66- **验收**：curl 逐一验证 12 个 gn 的正常/异常用例；`MN_docker_user` 状态流转正确。
67
68### M2 — 魔方模块骨架＋生命周期闭环
69- [ ] `mnbtdocker.php`：MetaData/ConfigOptions/参数解析。
70- [ ] CreateAccount/SuspendAccount/UnsuspendAccount/TerminateAccount/Renew/ChangePackage。
71- **验收**：魔方后台可下单开通、暂停、恢复、续费、删除、升降级，MNBT 侧状态与日志全部正确。
72
73### M3 — 状态/前台集成
74- [ ] Status/Sync；ClientArea ＋ ClientAreaOutput（P0 外链控制台）。
75- [ ] On/Off/Reboot、CrackPassword。
76- **验收**：前台产品页显示容器状态与控制台入口；开机/关机/重启/改密全链路可用。
77
78### M4 — 文档与收尾
79- [ ] 模块 README、API.md 增加魔方对接章节、DOCKER_TEST.md 增加联调用例。
80- [ ] （P1）自动登录 `gn=dl`、UsageUpdate、Chart。
81
82---
83
84## 9. 决策点（待评审）
85
86| # | 决策 | 建议 |
87|---|------|------|
88| D1 | 模块命名 | `mnbtdocker`（单单词，符合魔方命名约束），最终以负责人确认为准 |
89| D2 | `TerminateAccount` 语义 | **立即删除容器与账号行**（推荐，与 api.php `tz` 一致）；不走 7 天软删 |
90| D3 | 连接参数配置方式 | **config option 优先＋服务器字段兜底**（§3.4），两种用法并存 |
91| D4 | 前台控制台呈现 | **P0 外链跳转**；P1 自动登录票据＋iframe（需评审票据安全） |
92| D5 | 套餐升降级是否调整运行中容器 | **P0 仅更新 `plan_id` 记录**，配额在重装/重建容器时生效 |
93| D6 | `ChangePackage` 触发 | 魔方可配置选项「套餐 ID」key 与 `plan_id` 绑定，升降级自动调 `gn=bg`；无映射则不调用 |
94
95---
96
97## 10. 风险与开放问题
98
99| # | 风险/问题 | 影响 | 应对 |
100|---|-----------|------|------|
101| R1 | MNBT `api/docker.php` 现状仅 `cfif/kt`，生命周期动作全部依赖本期扩展 | 阻塞 M2 | 将 M1 设为前置里程碑，先交付后联调 |
102| R2 | 双登录体系：魔方登录态 ≠ MNBT `docker_token` | 用户需二次登录控制台 | P0 外链说明；P1 自动登录票据方案 |
103| R3 | `create_app` 异步（1-5 分钟） | 魔方 `Status` 短时间显示 waiting | 状态映射已覆盖 `creating→waiting` |
104| R4 | 原 PRD 决策 7（开通校验节点 Docker 可达）当前 `kt` 未实现 | 开通时节点 Docker 故障仍会成功 | 本期在 `kt` 补充 `get_config` 校验（需真机验证）或在决策中降级 |
105| R5 | 宝塔接口字段不稳定（`container_list` 端口为空、`get_cmd_log` 仅返回布尔等已知问题） | 状态/用量口径偏差 | 以 `installed_apps` 为主要数据源，沿用 DOCKER_TEST.md 的兼容处理 |
106| Q1 | 魔方 server module 的 `Renew`/`ChangePackage` 具体传参（如 `nextduedate` 格式、可配置选项变更回传） | 影响实现细节 | M2 联调时以魔方实际 `$params` 打印为准 |
107| Q2 | `UsageUpdate` 返回结构魔方文档未给出示例 | 影响 P1 | 参照 noKVM 模块源码对齐，P0 不做 |
108| Q3 | `gn=dl` 票据方案与 `docker/login.php` 改造涉及 MNBT 控制台 | 影响 P1 与安全 | P1 单独评审，本期不动登录页 |
109
110---
111
112## 11. 部署配置速览
113
114> 摘要自魔方模块自带文档 `mf_modules/servers/mnbtdocker/README.md`，完整部署说明见该文件。
115
116### 前置条件
117
118- **魔方财务**：已安装并正常运行
119- **MNBT V1.83+**：Docker 模块已完成 M1 API 扩展（`api/docker.php` 支持 `gn=kt/zt/jc/tj/xf/bg/czmm/ztcx/sy/start/stop/restart`）
120- MNBT 后台已配置 Docker 节点（`MN_docker_node`）、套餐（`MN_docker_plan`）
121
122### 安装模块
123
1241. 将 `mf_modules/servers/mnbtdocker/` 整个目录复制到魔方财务的 `/modules/servers/mnbtdocker/`
1252. 清魔方缓存（后台清或删除 `runtime/cache/`）
1263. 后台「产品 → 服务器」→ 模块下拉应出现「梦奈宝塔Docker对接插件」
127
128### 服务器字段（方式一：服务器接口设置，推荐）
129
130| 字段 | 填写 |
131|------|------|
132| 服务器 IP/域名 | MNBT 站点域名 |
133| 端口 | MNBT 站点端口（80/443） |
134| 用户名 | 节点编号（`MN_docker_node.id`） |
135| 密码 | 调用密钥 md5（`md5(ktmy.qmk)`） |
136| Access Hash | 系统 API 密钥（`$conf['api']`） |
137| SSL | 按站点是否 HTTPS 勾选 |
138
139产品关联模块后只需填写可选配置（如 `plan_id`），其余从服务器字段自动解析。
140
141### 产品关联要点
142
1431. 后台「产品 → 添加产品」→ 类型：**服务器产品** → 模块：**梦奈宝塔Docker对接插件**
1442. 可配置选项添加「套餐 ID」字段，映射 key 为 `plan_id`（可选，用于升降级）
1453. 上架后即可前台购买
146
147> 完整部署说明见魔方模块自带文档 `mf_modules/servers/mnbtdocker/README.md`（保持纯文本路径）。