r
82426b1941
新增侧栏「宝塔面板」菜单、代理 API 与连接配置页；通过 SSH 读写子机 api.json 自动写入凭据，5 分钟后台重试，含审计修复、检测缓存与并发锁。 Co-authored-by: Cursor <cursoragent@cursor.com>
79 lines
3.3 KiB
Markdown
79 lines
3.3 KiB
Markdown
# 宝塔面板独立模块 — 设计文档
|
||
|
||
> 日期：2026-06-20
|
||
> 状态：已批准实施
|
||
|
||
## 背景与目标
|
||
|
||
用户在 Nexus 管理 2000+ 台装宝塔的子机，需要**独立菜单**操作宝塔能力（一键登录、监控、网站/库/任务/服务），**不与**现有服务器页、文件、调度等功能合并 UI。
|
||
|
||
## 方案选定
|
||
|
||
| 层 | 方案 |
|
||
|----|------|
|
||
| 凭据 | 每台 `servers.extra_attrs.bt_panel`：`base_url`、`api_key_enc`（Fernet）、`verify_ssl` |
|
||
| 登录 A1/A5 | 优先 `POST /config?action=set_temp_login`；失败则 SSH `tools.py get_temp_login_ipv4` |
|
||
| 其它能力 | 中心 HTTP 代理宝塔 API（签名 + Redis Cookie 复用） |
|
||
| 前端 | 新导航分组「宝塔面板」+ 9 个子路由，共享服务器选择器 |
|
||
|
||
## 功能映射
|
||
|
||
| 编号 | Nexus 路由 | 宝塔 API / 方式 |
|
||
|------|-----------|----------------|
|
||
| A1/A5 | `/btpanel/login` | `set_temp_login` / SSH tmp_token |
|
||
| B1–B3 | `/btpanel/monitor` | `GetSystemTotal` / `GetDiskInfo` / `GetNetWork` |
|
||
| C1,C6 | `/btpanel/sites` | `getData sites` / `SiteStart` `SiteStop` |
|
||
| C4 | `/btpanel/sites/create` | `AddSite` + `GetPHPVersion` |
|
||
| C10 | `/btpanel/domains` | `getData domain` / `AddDomain` / `DelDomain` |
|
||
| C15 | `/btpanel/ssl` | 站点 SSL 字段 + `SetSSL` / `apply_cert` |
|
||
| D1–D4 | `/btpanel/databases` | `getData databases` / `AddDatabase` / `ResDatabasePassword` / `ToBackup` |
|
||
| F1 | `/btpanel/crontab` | `GetCrontab`（只读） |
|
||
| H1 | `/btpanel/services` | `ServiceAdmin` |
|
||
| 配置 | `/btpanel/settings` | 读写 `extra_attrs.bt_panel` |
|
||
|
||
## 安全
|
||
|
||
- 所有路由 `Depends(get_current_admin)`
|
||
- API Key 仅写入加密字段；响应 `api_key_set: bool`
|
||
- 生成登录链接、建站、删库等写操作记 `audit_logs`
|
||
- 中心机 IP 须在各子机宝塔 API 白名单；SSH Bootstrap 可自动追加 `limit_addr`（见下节）
|
||
|
||
## SSH Bootstrap（2026-06-20 增补）
|
||
|
||
子机 Linux 宝塔 API 配置位于 `/www/server/panel/data/api.json`。中心通过 root SSH 执行 `ssh_bootstrap.py`：
|
||
|
||
1. 无面板目录 → `bt_not_installed`（状态 `installing`，5min 重试）
|
||
2. 读/写 `api.json`：保留 token、开启 API、追加中心 IP 到 `limit_addr`
|
||
3. 原子写 + `bt reload`；stdout JSON → 加密写入 `api_key_enc` + `base_url`
|
||
|
||
### 状态机（`extra_attrs.bt_panel`）
|
||
|
||
| `bootstrap_state` | 含义 | 5min 重试 |
|
||
|-------------------|------|-----------|
|
||
| `pending` | 等待首次/下次 | 是 |
|
||
| `installing` | 宝塔尚未装好 | 是 |
|
||
| `ready` | 已写入凭据 | 否 |
|
||
| `failed` | SSH 认证失败等 | 否 |
|
||
| `disabled` | 用户关闭自动 | 否 |
|
||
|
||
### Background Loop
|
||
|
||
- `server/background/bt_panel_bootstrap_loop.py`，primary worker，默认 300s
|
||
- 每轮最多 `BT_PANEL_BOOTSTRAP_BATCH`（20）台
|
||
- 触发：创建服务器、凭据轮询成功、UI「立即 SSH 获取」、批量 `bt-panel-bootstrap`
|
||
|
||
### API
|
||
|
||
| 方法 | 路径 |
|
||
|------|------|
|
||
| POST | `/api/btpanel/servers/{id}/bootstrap` |
|
||
| POST | `/api/btpanel/servers/batch-bootstrap` |
|
||
| GET/PUT | `/api/btpanel/settings`（中心 IP、全局开关） |
|
||
|
||
## 验收
|
||
|
||
1. 侧栏见独立「宝塔面板」分组及子项，与「运维」分组分离
|
||
2. 配置 API 后可一键打开 tmp_token 登录页
|
||
3. 各子页选定服务器后能拉取对应宝塔数据或执行操作
|
||
4. `pytest tests/test_btpanel*.py` + `vite build` 通过
|