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