better-staridc-MNBT

better-staridc-MNBT/ docs/api/docker.md 14.5 KB · 442 行原始文件
Z zfhsh first commit 1 天前
1---
2title: Docker API
3description: Docker 容器服务 API（外部开通、用户控制台、后台管理、容器生命周期与魔方财务对接）
4---
5
6# Docker API（V1.83）
7
8> **版本**：V1.83  
9> **更新日期**：2026-08-04  
10> **适用范围**：MNBT Docker 模块的内外部 API 对接，包括第三方开通接口、用户控制台 AJAX、后台管理、魔方财务对接
11
12> 本文档由原 API.md §8 与 Docker_API.md 合并去重而来。宝塔 Docker API 封装（bt_docker）、认证机制与数据库表结构见 [Docker 控制台与内部实现](./docker-console.md)。
13
14## 1. 架构概述
15
16```
17第三方平台 / 插件
18    │
19    │ POST api/docker.php?gn=kt (外部 API，mn_key 鉴权)
20    ▼
21┌──────────────────────────────────────────────────┐
22│                    MNBT 系统                       │
23│                                                    │
24│  ┌──────────────┐  ┌──────────────────────────────┐│
25│  │ api/docker.php│  │     docker/ (用户控制台)      ││
26│  │ (外部 API)    │  │                              ││
27│  │              │  │  ├─ docker/ajax.php (AJAX)    ││
28│  │ 开通/续费/删除│  │  ├─ console.php (我的容器)     ││
29│  │              │  │  ├─ appstore.php (应用商店)    ││
30│  └──────┬───────┘  │  ├─ image.php (镜像管理)      ││
31│         │          │  ├─ volume.php (存储卷)       ││
32│         │          │  └─ compose.php (Compose)     ││
33│         │          └──────────────┬───────────────┘│
34│         │                         │                 │
35│  ┌──────▼─────────────────────────▼──────────────┐ │
36│  │            MPHX/bt_docker.php                  │ │
37│  │          (宝塔 Docker API 封装)                 │ │
38│  └──────────────────────┬───────────────────────┘ │
39│                         │                          │
40│                  MN_docker_* 表                     │
41│              (node/user/plan/order)                │
42└─────────────────────────┼──────────────────────────┘
43                          │
44                          │ HTTP API (签名)
45                          ▼
46              ┌───────────────────────┐
47              │   宝塔面板 Docker 模块  │
48              │  (独立于网站管理)       │
49              └───────────────────────┘
50```
51
52**核心概念**：
53
54- **单容器模型**：每个 Docker 账户最多创建一个容器，通过 `MN_docker_user.service_name` + `container_id` 锚定
55- **独立认证**：Docker 控制台使用 `docker_token` cookie，与 `admin_token`/`user_token` 完全隔离
56- **独立节点**：Docker 节点存于 `MN_docker_node` 表，与 `MN_bt`（网站宝塔节点）解耦
57
58---
59
60## 2. 外部 API（第三方对接）
61
62**入口**：`POST api/docker.php?gn=<操作>`
63
64### 2.1 鉴权
65
66所有请求均需携带以下 POST 参数（鉴权方式与 `api/api.php` 完全一致）：
67
68| 参数 | 类型 | 说明 |
69|------|------|------|
70| `mn_key` | string | 系统后台 API 密钥（`MN_config.api` 字段值） |
71| `mn_bh` | int | Docker 节点编号（`MN_docker_node.id`） |
72| `mn_keye` | string | `md5(节点ktmy . 节点qmk)` |
73| `mn_vs` | int | 插件版本号，必须 ≥ 15 |
74| `username` | string | 待操作 Docker 账号 |
75
76可通过 `gn=cfif` 验证连接是否正常。
77
78### 2.2 连接验证
79
80```
81POST api/docker.php?gn=cfif
82```
83
84```bash
85curl -X POST "http://your-domain/api/docker.php?gn=cfif" \
86  -d "mn_bh=1&mn_key=YOUR_API_KEY&mn_keye=MD5_KEY&mn_vs=15&username=test"
87```
88
89**请求体**（鉴权参数同上，`username` 可填任意值）：
90
91| 参数 | 值 |
92|------|-----|
93| `mn_key` | 系统 API 密钥 |
94| `mn_bh` | 1 |
95| `mn_keye` | md5(节点ktmy . 节点qmk) |
96| `mn_vs` | 15 |
97| `username` | test |
98
99**成功响应**：
100
101```json
102{
103  "success": true,
104  "code": 200,
105  "msg": "连接验证成功！"
106}
107```
108
109### 2.3 开通 Docker 账户
110
111```
112POST api/docker.php?gn=kt
113```
114
115**请求体**：
116
117| 参数 | 类型 | 必填 | 说明 |
118|------|------|------|------|
119| `mn_key` | string | 是 | 系统 API 密钥 |
120| `mn_bh` | int | 是 | 节点编号 |
121| `mn_keye` | string | 是 | `md5(ktmy . qmk)` |
122| `mn_vs` | int | 是 | ≥ 15 |
123| `username` | string | 是 | Docker 账号（≥ 4 位，唯一） |
124| `password` | string | 是 | 登录密码（≥ 6 位，bcrypt 存储） |
125| `dqtime` | string | 否 | 到期时间，传 `"0"` 表示永久（默认） |
126| `plan_id` | int | 否 | 套餐 ID（`MN_docker_plan.id`，需为上架状态），不传则不绑定套餐 |
127| `email` | string | 否 | 邮箱 |
128
129```bash
130curl -X POST "http://your-domain/api/docker.php?gn=kt" \
131  -d "mn_bh=1&mn_key=YOUR_API_KEY&mn_keye=MD5_KEY&mn_vs=15&username=duser1&password=dpass123&dqtime=2026-12-31&plan_id=1"
132```
133
134**成功响应**：
135
136```json
137{
138  "success": true,
139  "code": 200,
140  "msg": "Docker 账户开通成功！"
141}
142```
143
144**错误码**：
145
146| code | 含义 |
147|------|------|
148| 100 | 参数错误 / 账号已存在 / 节点不存在 / 密钥不匹配 |
149| 300 | 插件版本过低 |
150
151> 开通仅创建账户，容器由用户登录 `docker/` 控制台后在应用商店自行创建（单容器模型）。
152
153### 2.4 续费
154
155通过系统后台订单系统续费，或直接更新 `MN_docker_user.datae`（到期时间）与 `qk='active'`；第三方平台也可直接调用外部运维 API 的 `gn=xf` 接口续费（见 [外部运维 API](#6-外部运维-api魔方财务对接)）。
156
157到期后的自动软删处理由 cron 任务 `docker_cron.php` 执行，详见 [容器生命周期](#5-容器生命周期)。
158
159### 2.5 删除
160
161通过管理后台 `admin/api/docker.php` 删除用户，或直接 DELETE `MN_docker_user`；第三方平台可调用外部运维 API 的 `gn=tj` 接口删除（见 [外部运维 API](#6-外部运维-api魔方财务对接)）。
162
163---
164
165## 3. 内部 API（用户控制台）
166
167**入口**：`POST docker/ajax.php?gn=<操作>`  
168**认证**：`docker_token` cookie（login/logout 除外）  
169**CSRF**：所有请求（login/logout 除外）需携带 CSRF Token（`MNBT_CSRF_TOKEN` 字段，或 `_csrf` 字段 / `X-CSRF-TOKEN` 头），由 `mnbt_csrf_validate_request()` 验证
170
171### 3.1 登录 / 登出
172
173#### 登录
174
175```
176POST docker/ajax.php?gn=login
177```
178
179| 参数 | 说明 |
180|------|------|
181| `username` | Docker 账号 |
182| `password` | 密码 |
183| `MNBT_CSRF_TOKEN` | CSRF Token |
184
185**响应**：
186
187```json
188{"code": 200, "msg": "登录成功"}
189```
190
191#### 登出
192
193```
194POST docker/ajax.php?gn=logout
195```
196
197### 3.2 我的容器
198
199```
200POST docker/ajax.php?gn=my_container
201```
202
203**无需额外参数**（自动读取当前用户信息）。
204
205**响应**：
206
207```json
208{
209  "code": 200,
210  "msg": "ok",
211  "container": {
212    "service_name": "mnbt_test",
213    "appname": "frps",
214    "apptitle": "FRP 服务端",
215    "appdesc": "专注于内网穿透的高性能反向代理应用",
216    "status": "running",
217    "port": ["29369", "26219", "36043", "41074"],
218    "server_ip": "150.158.137.178",
219    "host_ip": "0.0.0.0",
220    "container_id": "b0a0d1bb7d53...",
221    "m_version": "latest",
222    "s_version": "",
223    "version": "latest",
224    "home": "https://github.com/snowdreamtech/frp",
225    "appinfo": [
226      {"fieldKey": "frps_web_port", "fieldTitle": "frp服务器web端口", "fieldValue": "29369"},
227      {"fieldKey": "frps_server_port", "fieldTitle": "frp服务器端口", "fieldValue": "26219"}
228    ]
229  },
230  "me": {
231    "id": 1,
232    "username": "test",
233    "container_status": "running",
234    "container_id": "b0a0d1bb7d53...",
235    "service_name": "mnbt_test",
236    "app_name": "frps",
237    "container_spec": "{...}",
238    "qk": "active",
239    "datae": "0000-00-00"
240  },
241  "node": {
242    "btip": "150.158.137.178",
243    "ptl": "true"
244  }
245}
246```
247
248**`container` 字段说明**（来自宝塔 `get_installed_apps` 接口）：
249
250| 字段 | 说明 |
251|------|------|
252| `service_name` | 服务名（容器的唯一标识，创建时传入） |
253| `appname` | 应用英文名 |
254| `apptitle` | 应用中文名 |
255| `appdesc` | 应用简介 |
256| `status` | 容器状态（`running` / `stopped` / `creating`） |
257| `port` | 端口数组（宿主机端口，如 `["29369","26219"]`） |
258| `server_ip` | 节点外网 IP |
259| `host_ip` | 容器绑定的 host IP |
260| `container_id` | Docker 容器 ID（64 位 hex） |
261| `m_version` | 主版本号 |
262| `s_version` | 子版本号 |
263| `version` | 完整版本号 |
264| `home` | 应用主页链接 |
265| `appinfo` | 应用参数数组，每项含 `fieldKey`/`fieldTitle`/`fieldValue` |
266
267**`container_status` 枚举**：
268
269| 值 | 含义 |
270|-----|------|
271| `none` | 未创建容器 |
272| `creating` | 创建中（前端每 8 秒轮询此接口） |
273| `running` | 运行中 |
274| `stopped` | 已停止 |
275
276### 3.3 容器启停
277
278```
279POST docker/ajax.php?gn=container_start
280POST docker/ajax.php?gn=container_stop
281POST docker/ajax.php?gn=container_restart
282```
283
284**无需参数**（自动操作当前用户的容器）。
285
286**响应**：
287
288```json
289{"code": 200, "msg": "操作完成", "raw": {...}}
290```
291
292### 3.4 应用商店
293
294#### 应用列表
295
296```
297POST docker/ajax.php?gn=app_list
298```
299
300返回宝塔应用市场全部应用（约 291 个），每项含 `appname`/`apptitle`/`apptype`/`appversion`/`depend`/`env`/`field`。
301
302#### 应用详情
303
304```
305POST docker/ajax.php?gn=app_detail
306```
307
308| 参数 | 说明 |
309|------|------|
310| `appname` | 应用英文名 |
311
312#### 依赖查询
313
314```
315POST docker/ajax.php?gn=app_dependence
316```
317
318| 参数 | 说明 |
319|------|------|
320| `appname` | 应用英文名 |
321
322### 3.5 创建应用（开通容器）
323
324```
325POST docker/ajax.php?gn=app_create
326```
327
328**单容器限制**：已有容器的用户调用此接口会返回错误。
329
330**请求体**：
331
332| 参数 | 类型 | 必填 | 说明 |
333|------|------|------|------|
334| `app_name` | string | 是 | 应用英文名（如 `frps`、`wordpress`） |
335| `m_version` | string | 是 | 主版本号（如 `latest`、`8`） |
336| `s_version` | string | 否 | 子版本号（如 `0`、`7.2`），无子版本时留空 |
337| `cpus` | int | 否 | CPU 核数限制（0=不限制，受套餐上限约束） |
338| `memory_limit` | int | 否 | 内存限制 MB（0=不限制，受套餐上限约束） |
339| `allow_access` | string | 否 | 是否允许外部访问（`"1"` 或 `"0"`） |
340| 其他 | string | 否 | 应用专属参数（如 `frps_web_port`、`frps_password` 等），由前端表单动态生成 |
341
342**`service_name` 自动生成**：`mnbt_` + 用户名净化（去除非字母数字 → 小写 → 截取前 20 位）。
343
344**成功响应**：
345
346```json
347{
348  "code": 200,
349  "msg": "应用创建请求已提交，请耐心等待 1-5 分钟初始化",
350  "service_name": "mnbt_test"
351}
352```
353
354创建后系统自动设置 `container_status='creating'`，前端每 8 秒轮询 `my_container` 接口检查状态。
355
356### 3.6 镜像 / 存储卷 / Compose / 安装日志
357
358```
359POST docker/ajax.php?gn=image_list     → 镜像列表
360POST docker/ajax.php?gn=volume_list    → 存储卷列表
361POST docker/ajax.php?gn=compose_list   → Compose 模板 + 项目列表
362POST docker/ajax.php?gn=install_log    → 安装进度日志（get_cmd_log）
363```
364
365**无需额外参数**。
366
367> `install_log` 用于应用异步安装期间跟进进度（宝塔 `get_cmd_log`，注意仅返回布尔值 `true`，不返回日志内容），与 `console.php` 每 8 秒刷新容器状态配合。
368
369---
370
371## 4. 后台管理接口
372
373需管理员登录，入口 `admin/ajax.php`，指令前缀 `docker_`：
374
375| `gn` | 说明 |
376|------|------|
377| `docker_user_list` | 用户列表（bootstrap-table） |
378| `docker_user_add` / `docker_user_edit` / `docker_user_del` | 用户增改删 |
379| `docker_user_reset` | 重置密码 |
380| `docker_user_pause` / `docker_user_resume` | 暂停/恢复 |
381| `docker_plan_list` / `docker_plan_add` / `docker_plan_edit` / `docker_plan_del` | 套餐管理 |
382| `docker_node_config` | 节点 Docker 配置（get_config） |
383| `docker_node_containers` | 节点容器列表 |
384| `docker_options` | 节点/套餐下拉数据 |
385
386---
387
388## 5. 容器生命周期
389
390```
391用户开通 Docker 账户（外部 API 或管理后台）
392    │
393    │ qk=active, container_status=none
394    ▼
395用户登录控制台 → 应用商店选择应用 → 创建容器
396    │
397    │ 调用 bt_docker::app_create()
398    │ container_status=creating
399    ▼
400宝塔异步安装（1-5 分钟）
401    │
402    │ 前端每 8 秒轮询 my_container → installed_apps()
403    ▼
404status=running → container_status=running（同步到 MN_docker_user）
405    │
406    ├─ 用户操作：停止 → stopped / 启动 → running / 重启
407    │
408    └─ 到期处理（Cron 每天执行）：
409        │
410        ├─ active 且到期 → qk=expired, expired_at=到期时间
411        │
412        ├─ expired 满 7 天 → 删除节点容器 → qk=pruned, prune_due=当天
413        │
414        └─ pruned 满 7 天 → 物理删除用户行
415```
416
417### 到期软删定时任务
418
419```bash
420# 建议每 30 分钟执行
421curl "http://your-domain/docker_cron.php?my=YOUR_API_KEY"
422```
423
424三阶段软删：`active→expired`（到期）→ `pruned`（满 7 天删容器）→ 物理删除（再满 7 天）。
425
426---
427
428## 6. 外部运维 API（魔方财务对接）
429
430供魔方财务（idcsmart）server module 调用的 `zt`（暂停）/ `jc`（恢复）/ `tj`（删除）/ `xf`（续费）/ `bg`（变更套餐）/ `czmm`（重置密码）/ `ztcx`（状态查询）/ `sy`（用量查询）/ `start` / `stop` / `restart`（容器启停）接口，鉴权方式与 [2.1 鉴权](#21-鉴权) 完全一致，所有请求均携带 `mn_bh` / `mn_key` / `mn_keye` / `mn_vs=15` / `username`。
431
432完整请求/响应示例见 [外部运维 API（魔方财务对接）](./docker-mofang.md)。
433
434---
435
436## 相关文档
437
438- [Docker 控制台与内部实现](./docker-console.md) —— 宝塔 Docker API 封装、认证机制、数据库表结构
439- 产品设计：[../prd/docker.md](../prd/docker.md)
440- 测试：[../prd/docker-test.md](../prd/docker-test.md)
441- 主题：[../development/theme/index.md](../development/theme/index.md)
442- 宝塔 Docker API 文档：https://docs.bt.cn/api/docker/