boos
07e31e0f7c
连接管理页加 Pixelle 连接卡片(runninghub key/comfy url/comfy key), 写 settings 表 + 同步 config.yaml + 重启容器生效。只管3凭证,写文件+重启机制。 Co-Authored-By: Claude <noreply@anthropic.com>
91 lines
4.4 KiB
Markdown
91 lines
4.4 KiB
Markdown
# Pixelle 连接凭证纳入 BoosAPI 管理 设计
|
|
|
|
日期:2026-06-18
|
|
分支:`feat/comfy-cloud-adapter`
|
|
状态:已通过 brainstorming,待用户复审
|
|
|
|
## 背景
|
|
|
|
Pixelle 的连接凭证(RunningHub API key、Comfy Cloud url/key)现在只能手动编辑
|
|
`/opt/Pixelle-Video/config.yaml` 再重启容器,很麻烦。本功能把这 3 个凭证纳入 BoosAPI
|
|
管理控制台,在 UI 里改、一键写入 Pixelle config 并重启生效。
|
|
|
|
## 已确认决策
|
|
|
|
1. 范围:只管 Pixelle 的 3 个连接凭证 —— `runninghub_api_key`、`comfyui_url`、`comfyui_api_key`。
|
|
不做整份 config.yaml 编辑,不做通用外部连接管理。
|
|
2. 同步机制:写文件 + 重启容器(BoosAPI 直接改 bind-mount 的 config.yaml,再 restart pixelle 容器)。
|
|
不给 Pixelle 加 HTTP 配置端点(避免改 Pixelle 源码)。
|
|
3. 真相源:BoosAPI settings 表;config.yaml 是被同步的目标。
|
|
4. 放置:连接管理页(`/accounts`,`src/web/pages/Accounts.tsx`)作为一个卡片/分区。
|
|
|
|
## 集成点(调查结论)
|
|
|
|
- Pixelle 无配置更新 HTTP 端点;`config.yaml` 是 bind-mount(`/opt/Pixelle-Video/config.yaml`),
|
|
BoosAPI 跑在宿主,有读写权限。
|
|
- 凭证在 config.yaml 的 `comfyui:` 段:`runninghub_api_key` / `comfyui_url` / `comfyui_api_key`。
|
|
- 改后 Pixelle 需重启容器生效(`cd /opt/Pixelle-Video && docker compose restart api`)。
|
|
- BoosAPI 有 settings 表(key-value)+ builtin_key 掩码范式可复用。
|
|
|
|
## 架构
|
|
|
|
```
|
|
连接管理页「Pixelle 连接」卡片(3 输入框 + 保存)
|
|
→ PUT /api/admin/pixelle/connection
|
|
1. 写 settings 表(pixelle.runninghub_api_key 等)
|
|
2. 备份 config.yaml → config.yaml.bak-<ts>
|
|
3. YAML 改 comfyui.{runninghub_api_key,comfyui_url,comfyui_api_key} 三键(其余保留)
|
|
4. docker compose restart api(cwd=/opt/Pixelle-Video)
|
|
→ GET /api/admin/pixelle/connection 返回当前值(密钥掩码)
|
|
```
|
|
|
|
## 三层改动设计
|
|
|
|
### 层1 后端 service `src/services/pixelle_connection.rs`(新建)
|
|
- `struct PixelleConnection { runninghub_api_key, comfyui_url, comfyui_api_key }`(均 Option<String>)。
|
|
- `read_connection(db) -> PixelleConnection`:从 settings 表读 `pixelle.*` 三键。
|
|
- `save_connection(db, conn)`:三键写 settings 表(UPSERT)。
|
|
- `sync_to_pixelle(config_path) -> AppResult<()>`:读 yaml → 改 comfyui 三键 → 备份 → 写回。
|
|
用 `serde_yaml`(确认 Cargo.toml 有;无则加)。只改这三键,其余键原样保留(读成
|
|
`serde_yaml::Value` 再定点改,不整体重序列化丢注释——注意:serde_yaml 会丢注释,
|
|
接受此代价,或保留备份)。
|
|
- `restart_pixelle(compose_dir) -> AppResult<()>`:`docker compose restart api`,cwd=compose_dir。
|
|
- 配置项:Pixelle config 路径 + compose 目录,默认 `/opt/Pixelle-Video/config.yaml`、
|
|
`/opt/Pixelle-Video`,从 BoosAPI config(新增 `[pixelle_video] config_path` / 复用现有)读。
|
|
|
|
### 层2 后端路由 `src/routes/admin/pixelle_connection.rs`(新建)+ 挂载
|
|
- `GET /api/admin/pixelle/connection`:返回三值,api_key 掩码(`••••<last4>`)。
|
|
- `PUT /api/admin/pixelle/connection`:收三字段 → save_connection → sync_to_pixelle → restart。
|
|
掩码值(`••••`)表示「不改」,跳过该字段。
|
|
- 挂到 admin router(走现有 require_admin 中间件)。
|
|
|
|
### 层3 前端 `src/web/pages/Accounts.tsx` + `api.ts`
|
|
- `api.ts` adminApi 加 `getPixelleConnection()` / `savePixelleConnection(data)`。
|
|
- Accounts 页加「Pixelle 连接」卡片:3 输入框(runninghub key、comfy url、comfy key)+ 保存。
|
|
加载时拉当前值(掩码),保存提示「已保存并重启 Pixelle，约数秒生效」。
|
|
|
|
## 错误处理
|
|
|
|
- config.yaml 不存在/无写权限 → 503 + 明确提示,**不重启**。
|
|
- docker restart 失败 → 返回错误,提示「配置已写入,但 Pixelle 重启失败,请手动重启」。
|
|
- 写文件前必备份;写失败保留原文件。
|
|
|
|
## 验证
|
|
|
|
- 后端:rstest 用临时 yaml 测 sync_to_pixelle(读→改3键→保留其余→备份生成);
|
|
`cargo build -j 2`。
|
|
- 前端:`npm run typecheck:web`。
|
|
- docker restart 部分手动验证(端到端:UI 改 runninghub key → 确认 config.yaml 变 + 容器重启)。
|
|
|
|
## 非目标
|
|
|
|
- 不做整份 config.yaml 编辑。
|
|
- 不做通用「外部服务连接」管理(只 Pixelle)。
|
|
- 不给 Pixelle 加源码/端点。
|
|
- 不动 comfy-cloud 适配器、数字人工作流。
|
|
|
|
## 提交约定
|
|
|
|
分支 `feat/comfy-cloud-adapter`。service / 路由 / 前端 分开提交,中文 commit。
|
|
serde_yaml 若需新增依赖,单独说明。
|