BoosAPI/docs/superpowers/specs/2026-06-18-pixelle-connection-management-design.md

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)。
• 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 若需新增依赖,单独说明。