# 宝塔面板独立模块 — 设计文档

> 日期：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` 通过