# Pixelle 连接凭证纳入 BoosAPI 管理 实现计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 在 BoosAPI 连接管理页加「Pixelle 连接」卡片,管 runninghub_api_key / comfyui_url / comfyui_api_key 三个凭证,保存即写入 settings 表 + 同步 Pixelle config.yaml + 重启 pixelle 容器生效。

**Architecture:** 新增 service `pixelle_connection.rs`(读写 settings 表 + 改 config.yaml YAML 三键 + docker restart)+ admin 路由(GET/PUT,密钥掩码)+ 前端 Accounts 页卡片。settings 表为真相源,config.yaml 是同步目标。

**Tech Stack:** Rust(axum, sqlx, serde_yaml<新增依赖>, tokio::process)、React/TS。

> **构建/测试:** `cargo build -j 2`(-j2 防 OOM)、`cargo test -p boosapi --lib pixelle_connection`、`npm run typecheck:web`。分支 `feat/comfy-cloud-adapter`。Pixelle compose 目录 `/opt/Pixelle-Video`,config `/opt/Pixelle-Video/config.yaml`。

---

## 文件结构

- Modify `Cargo.toml` — 加 `serde_yaml` 依赖。
- Modify `src/config.rs` — `PixelleVideoConfig` 加 `config_path` / `compose_dir` 两字段(默认 `/opt/Pixelle-Video/config.yaml`、`/opt/Pixelle-Video`)。
- Create `src/services/pixelle_connection.rs` — read/save settings + sync_to_pixelle(改 yaml)+ restart。
- Modify `src/services/mod.rs` — `pub mod pixelle_connection;`。
- Create `src/routes/admin/pixelle_connection.rs` — GET/PUT handler(掩码)。
- Modify `src/routes/admin/mod.rs` — 声明子模块 + 挂 2 条路由。
- Modify `src/web/api.ts` — adminApi 加 getPixelleConnection / savePixelleConnection。
- Modify `src/web/pages/Accounts.tsx` — 加「Pixelle 连接」卡片。

---

<!-- TASKS -->

## Task 1: 加 serde_yaml 依赖 + config 路径字段

**Files:**
- Modify: `Cargo.toml`
- Modify: `src/config.rs`

- [ ] **Step 1: Cargo.toml 加 serde_yaml**

在 `[dependencies]` 段加(版本对齐项目 serde 生态,用 0.9):
```toml
serde_yaml = "0.9"
```

- [ ] **Step 2: PixelleVideoConfig 加两字段(src/config.rs,struct 内 timeout_secs 后)**

在 `pub timeout_secs: u64,` 之后加:
```rust
    #[serde(default = "default_pixelle_config_path")]
    pub config_path: String,
    #[serde(default = "default_pixelle_compose_dir")]
    pub compose_dir: String,
```

- [ ] **Step 3: 加默认值函数(src/config.rs,default_pixelle_backend_provider 附近)**

```rust
fn default_pixelle_config_path() -> String {
    "/opt/Pixelle-Video/config.yaml".to_string()
}
fn default_pixelle_compose_dir() -> String {
    "/opt/Pixelle-Video".to_string()
}
```

- [ ] **Step 4: PixelleVideoConfig::default() 补两字段**

找到 `impl Default for ...` 或 `PixelleVideoConfig::default()`(约 line 207 区域,有 `api_base_url: Some(...)` 那个),在其字段列表末尾加:
```rust
            config_path: default_pixelle_config_path(),
            compose_dir: default_pixelle_compose_dir(),
```

- [ ] **Step 5: 构建确认**

Run: `cd /root/metapi && cargo build -j 2 2>&1 | tail -3`
Expected: `Finished`。

- [ ] **Step 6: Commit**

```bash
cd /root/metapi && git add Cargo.toml Cargo.lock src/config.rs
git commit -m "feat(pixelle): 加 serde_yaml + Pixelle config 路径配置项

Co-Authored-By: Claude <noreply@anthropic.com>"
```

<!-- T2 -->

## Task 2: pixelle_connection service(settings + yaml 同步)

**Files:**
- Create: `src/services/pixelle_connection.rs`
- Modify: `src/services/mod.rs`

- [ ] **Step 1: src/services/mod.rs 加模块声明**

```rust
pub mod pixelle_connection;
```

- [ ] **Step 2: 写失败测试 `src/services/pixelle_connection.rs`(含结构 + sync 测试)**

```rust
use crate::error::{AppError, AppResult};
use serde::{Deserialize, Serialize};
use sqlx::SqlitePool;

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PixelleConnection {
    pub runninghub_api_key: Option<String>,
    pub comfyui_url: Option<String>,
    pub comfyui_api_key: Option<String>,
}

const KEY_RH: &str = "pixelle.runninghub_api_key";
const KEY_URL: &str = "pixelle.comfyui_url";
const KEY_CK: &str = "pixelle.comfyui_api_key";

pub async fn read_connection(db: &SqlitePool) -> AppResult<PixelleConnection> {
    async fn get(db: &SqlitePool, k: &str) -> AppResult<Option<String>> {
        Ok(sqlx::query_scalar("SELECT value FROM settings WHERE key = ?")
            .bind(k).fetch_optional(db).await?)
    }
    Ok(PixelleConnection {
        runninghub_api_key: get(db, KEY_RH).await?,
        comfyui_url: get(db, KEY_URL).await?,
        comfyui_api_key: get(db, KEY_CK).await?,
    })
}

pub async fn save_connection(db: &SqlitePool, conn: &PixelleConnection) -> AppResult<()> {
    async fn put(db: &SqlitePool, k: &str, v: &Option<String>) -> AppResult<()> {
        if let Some(val) = v {
            sqlx::query("INSERT OR REPLACE INTO settings (key, value) VALUES (?, ?)")
                .bind(k).bind(val).execute(db).await?;
        }
        Ok(())
    }
    put(db, KEY_RH, &conn.runninghub_api_key).await?;
    put(db, KEY_URL, &conn.comfyui_url).await?;
    put(db, KEY_CK, &conn.comfyui_api_key).await?;
    Ok(())
}

/// 改 config.yaml 的 comfyui.{runninghub_api_key,comfyui_url,comfyui_api_key} 三键,其余保留。
/// 改前备份到 <path>.bak-<ts>。返回备份路径。
pub fn sync_to_pixelle(config_path: &str, conn: &PixelleConnection) -> AppResult<String> {
    let content = std::fs::read_to_string(config_path)
        .map_err(|e| AppError::ServiceUnavailable(format!("读取 Pixelle config 失败: {e}")))?;
    let mut doc: serde_yaml::Value = serde_yaml::from_str(&content)
        .map_err(|e| AppError::ServiceUnavailable(format!("解析 config.yaml 失败: {e}")))?;
    let comfyui = doc.get_mut("comfyui")
        .ok_or_else(|| AppError::ServiceUnavailable("config.yaml 缺少 comfyui 段".into()))?;
    let map = comfyui.as_mapping_mut()
        .ok_or_else(|| AppError::ServiceUnavailable("comfyui 段不是映射".into()))?;
    if let Some(v) = &conn.runninghub_api_key {
        map.insert("runninghub_api_key".into(), serde_yaml::Value::String(v.clone()));
    }
    if let Some(v) = &conn.comfyui_url {
        map.insert("comfyui_url".into(), serde_yaml::Value::String(v.clone()));
    }
    if let Some(v) = &conn.comfyui_api_key {
        map.insert("comfyui_api_key".into(), serde_yaml::Value::String(v.clone()));
    }
    let ts = chrono::Utc::now().format("%Y%m%d%H%M%S").to_string();
    let backup = format!("{config_path}.bak-{ts}");
    std::fs::copy(config_path, &backup)
        .map_err(|e| AppError::ServiceUnavailable(format!("备份失败: {e}")))?;
    let out = serde_yaml::to_string(&doc)
        .map_err(|e| AppError::Internal(anyhow::anyhow!(e)))?;
    std::fs::write(config_path, out)
        .map_err(|e| AppError::ServiceUnavailable(format!("写入 config 失败: {e}")))?;
    Ok(backup)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn sync_updates_three_keys_preserves_rest() {
        let dir = std::env::temp_dir().join(format!("pxtest_{}", uuid::Uuid::new_v4().simple()));
        std::fs::create_dir_all(&dir).unwrap();
        let path = dir.join("config.yaml");
        std::fs::write(&path,
            "project_name: Pixelle-Video\ncomfyui:\n  comfyui_url: https://old\n  runninghub_api_key: oldkey\n  comfyui_api_key: oldck\n  runninghub_concurrent_limit: 1\n").unwrap();
        let conn = PixelleConnection {
            runninghub_api_key: Some("newkey".into()),
            comfyui_url: Some("http://new".into()),
            comfyui_api_key: Some("newck".into()),
        };
        let backup = sync_to_pixelle(path.to_str().unwrap(), &conn).unwrap();
        assert!(std::path::Path::new(&backup).exists());
        let after = std::fs::read_to_string(&path).unwrap();
        assert!(after.contains("newkey"));
        assert!(after.contains("http://new"));
        assert!(after.contains("newck"));
        // 保留其余键
        assert!(after.contains("runninghub_concurrent_limit"));
        assert!(after.contains("project_name"));
        std::fs::remove_dir_all(&dir).ok();
    }
}
```

- [ ] **Step 3: 运行测试,确认失败**

Run: `cd /root/metapi && cargo test -p boosapi --lib services::pixelle_connection 2>&1 | tail -15`
Expected: FAIL —— 模块/函数未定义(首次编译错误)。

- [ ] **Step 4: 实现**

Step 2 的代码即实现(测试与实现同文件)。确保 mod.rs 已声明。

- [ ] **Step 5: 运行测试,确认通过**

Run: `cd /root/metapi && cargo test -p boosapi --lib services::pixelle_connection 2>&1 | tail -10`
Expected: PASS(1 个测试)。

- [ ] **Step 6: Commit**

```bash
cd /root/metapi && git add src/services/mod.rs src/services/pixelle_connection.rs
git commit -m "feat(pixelle): 连接凭证 service(settings 读写 + config.yaml 同步)

Co-Authored-By: Claude <noreply@anthropic.com>"
```

<!-- T3 -->

## Task 3: restart helper + admin 路由(掩码)

**Files:**
- Modify: `src/services/pixelle_connection.rs`(加 restart)
- Create: `src/routes/admin/pixelle_connection.rs`
- Modify: `src/routes/admin/mod.rs`

- [ ] **Step 1: 加 restart_pixelle(pixelle_connection.rs,sync_to_pixelle 之后)**

```rust
pub async fn restart_pixelle(compose_dir: &str) -> AppResult<()> {
    let output = tokio::process::Command::new("docker")
        .args(["compose", "restart", "api"])
        .current_dir(compose_dir)
        .output()
        .await
        .map_err(|e| AppError::ServiceUnavailable(format!("docker compose restart 启动失败: {e}")))?;
    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        return Err(AppError::ServiceUnavailable(format!(
            "Pixelle 重启失败: {}", stderr.trim()
        )));
    }
    Ok(())
}
```

- [ ] **Step 2: 写 admin 路由 `src/routes/admin/pixelle_connection.rs`**

```rust
use crate::error::AppResult;
use crate::services::pixelle_connection::{self, PixelleConnection};
use crate::AppState;
use axum::{extract::State, Json};
use serde::Deserialize;
use serde_json::{json, Value};

const MASK_SENTINEL: &str = "••••";

fn mask(v: &Option<String>) -> Value {
    match v {
        Some(s) if s.len() > 4 => json!(format!("{}{}", MASK_SENTINEL, &s[s.len()-4..])),
        Some(s) if !s.is_empty() => json!(MASK_SENTINEL),
        _ => Value::Null,
    }
}

pub async fn get_connection(State(state): State<AppState>) -> AppResult<Json<Value>> {
    let c = pixelle_connection::read_connection(&state.db).await?;
    Ok(Json(json!({
        "success": true,
        "connection": {
            // url 不算敏感,明文回;两个 key 掩码
            "comfyuiUrl": c.comfyui_url,
            "runninghubApiKey": mask(&c.runninghub_api_key),
            "comfyuiApiKey": mask(&c.comfyui_api_key),
        }
    })))
}

#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct UpdatePayload {
    runninghub_api_key: Option<String>,
    comfyui_url: Option<String>,
    comfyui_api_key: Option<String>,
}

fn keep_if_not_mask(incoming: Option<String>) -> Option<String> {
    // 掩码值(以 •••• 开头)表示"未修改",跳过
    match incoming {
        Some(s) if s.starts_with(MASK_SENTINEL) => None,
        other => other,
    }
}

pub async fn put_connection(
    State(state): State<AppState>,
    Json(p): Json<UpdatePayload>,
) -> AppResult<Json<Value>> {
    let conn = PixelleConnection {
        runninghub_api_key: keep_if_not_mask(p.runninghub_api_key),
        comfyui_url: p.comfyui_url, // url 明文,不掩码
        comfyui_api_key: keep_if_not_mask(p.comfyui_api_key),
    };
    pixelle_connection::save_connection(&state.db, &conn).await?;
    let backup = pixelle_connection::sync_to_pixelle(&state.config.pixelle_video.config_path, &conn)?;
    let restart = pixelle_connection::restart_pixelle(&state.config.pixelle_video.compose_dir).await;
    match restart {
        Ok(()) => Ok(Json(json!({ "success": true, "backup": backup, "restarted": true }))),
        Err(e) => Ok(Json(json!({
            "success": true, "backup": backup, "restarted": false,
            "warning": format!("配置已写入,但 Pixelle 重启失败,请手动重启: {e}")
        }))),
    }
}
```

- [ ] **Step 3: src/routes/admin/mod.rs 声明子模块 + 挂路由**

模块声明区(`mod users;` 附近)加:
```rust
mod pixelle_connection;
```
在 `routes()` 的路由链里(`/api/admin/user-balances` 那一带)加:
```rust
        .route(
            "/api/admin/pixelle/connection",
            get(pixelle_connection::get_connection).put(pixelle_connection::put_connection),
        )
```
确认 `get`/`put` 已从 axum::routing 引入(文件顶部应已 `use axum::routing::{get, post, ...}`;若缺 put 则补)。

- [ ] **Step 4: 构建确认**

Run: `cd /root/metapi && cargo build -j 2 2>&1 | tail -3`
Expected: `Finished`。

- [ ] **Step 5: Commit**

```bash
cd /root/metapi && git add src/services/pixelle_connection.rs src/routes/admin/pixelle_connection.rs src/routes/admin/mod.rs
git commit -m "feat(pixelle): 连接凭证 admin 端点(GET/PUT 掩码 + 重启)

Co-Authored-By: Claude <noreply@anthropic.com>"
```

<!-- T4 -->

## Task 4: 前端连接管理卡片

**Files:**
- Modify: `src/web/api.ts`
- Modify: `src/web/pages/Accounts.tsx`

- [ ] **Step 1: api.ts adminApi 加方法**

在 adminApi 对象里(找 `request(` 范式的 admin 方法群)加:
```typescript
  getPixelleConnection: () =>
    request<{ success: boolean; connection: { comfyuiUrl?: string | null; runninghubApiKey?: string | null; comfyuiApiKey?: string | null } }>("/api/admin/pixelle/connection"),
  savePixelleConnection: (data: { runninghubApiKey?: string; comfyuiUrl?: string; comfyuiApiKey?: string }) =>
    request<{ success: boolean; backup?: string; restarted?: boolean; warning?: string }>("/api/admin/pixelle/connection", {
      method: "PUT",
      body: JSON.stringify(data),
    }),
```

- [ ] **Step 2: Accounts.tsx 加「Pixelle 连接」卡片**

先读 `src/web/pages/Accounts.tsx` 顶部,确认 `api`/`adminApi` 的导入名和 toast 用法。在页面主体某处(如页尾)加一个卡片组件块。最小实现(state + 加载 + 保存):
```tsx
  // —— Pixelle 连接(加在组件内 state 区)——
  const [pxConn, setPxConn] = useState({ comfyuiUrl: '', runninghubApiKey: '', comfyuiApiKey: '' });
  const [pxSaving, setPxSaving] = useState(false);
  useEffect(() => {
    adminApi.getPixelleConnection()
      .then((r) => setPxConn({
        comfyuiUrl: r.connection?.comfyuiUrl || '',
        runninghubApiKey: r.connection?.runninghubApiKey || '',
        comfyuiApiKey: r.connection?.comfyuiApiKey || '',
      }))
      .catch(() => {});
  }, []);
  const savePxConn = async () => {
    setPxSaving(true);
    try {
      const res = await adminApi.savePixelleConnection({
        runninghubApiKey: pxConn.runninghubApiKey || undefined,
        comfyuiUrl: pxConn.comfyuiUrl || undefined,
        comfyuiApiKey: pxConn.comfyuiApiKey || undefined,
      });
      if (res.warning) toast.error(res.warning);
      else toast.success('已保存并重启 Pixelle,约数秒生效');
    } catch (e: any) {
      toast.error(e?.message || '保存失败');
    } finally {
      setPxSaving(false);
    }
  };
```
卡片 JSX(加到 return 的合适位置,样式对齐页面现有 card):
```tsx
      <div className="card" style={{ marginTop: 16, padding: 16 }}>
        <h3>Pixelle 连接</h3>
        <label style={{ display: 'block', marginBottom: 8 }}>
          <span>ComfyUI URL</span>
          <input value={pxConn.comfyuiUrl} onChange={(e) => setPxConn((s) => ({ ...s, comfyuiUrl: e.target.value }))} placeholder="http://172.17.0.1:4000/comfy-cloud" style={{ width: '100%' }} />
        </label>
        <label style={{ display: 'block', marginBottom: 8 }}>
          <span>RunningHub API Key</span>
          <input value={pxConn.runninghubApiKey} onChange={(e) => setPxConn((s) => ({ ...s, runninghubApiKey: e.target.value }))} placeholder="留空••••表示不改" style={{ width: '100%' }} />
        </label>
        <label style={{ display: 'block', marginBottom: 8 }}>
          <span>Comfy Cloud API Key</span>
          <input value={pxConn.comfyuiApiKey} onChange={(e) => setPxConn((s) => ({ ...s, comfyuiApiKey: e.target.value }))} placeholder="留空••••表示不改" style={{ width: '100%' }} />
        </label>
        <button type="button" className="btn btn-primary" disabled={pxSaving} onClick={savePxConn}>
          {pxSaving ? '保存中...' : '保存并重启 Pixelle'}
        </button>
      </div>
```
> 注:`useState`/`useEffect` 若未导入需补;`adminApi`/`api` 用 Accounts.tsx 实际的导入名(读文件确认是 `api` 还是 `adminApi`)。若提交掩码值(`••••...`)后端会跳过不改,符合预期。

- [ ] **Step 3: typecheck**

Run: `cd /root/metapi && npm run typecheck:web 2>&1 | tail -5`
Expected: 无 TS 错误。

- [ ] **Step 4: Commit**

```bash
cd /root/metapi && git add src/web/api.ts src/web/pages/Accounts.tsx
git commit -m "feat(pixelle): 连接管理页加 Pixelle 连接卡片

Co-Authored-By: Claude <noreply@anthropic.com>"
```

<!-- T5 -->

## Task 5: 部署 + 端到端验证

**Files:** 无(部署 + 运行时)

- [ ] **Step 1: 重建并重启 BoosAPI(含前后端改动)**

```bash
cd /root/metapi && ./build-and-run.sh --fast-release 2>&1 | tail -15
```
Expected: 构建成功,BoosAPI 起在 :4000。动线上服务,确认时机。

- [ ] **Step 2: 连接管理页确认「Pixelle 连接」卡片**

硬刷新管理控制台连接管理页(`/accounts`),确认出现「Pixelle 连接」卡片,
ComfyUI URL 显示当前值,两个 key 显示掩码(`••••xxxx`)。

- [ ] **Step 3: 改一个值测试同步**

把 RunningHub API Key 改成一个新值,保存。确认:
```bash
grep runninghub_api_key /opt/Pixelle-Video/config.yaml | sed 's/[a-f0-9]\{20\}/.../'
ls -t /opt/Pixelle-Video/config.yaml.bak-* | head -1
rtk proxy docker ps --filter name=pixelle --format '{{.Names}} {{.Status}}'
```
Expected: config.yaml 的 key 变成新值;有新备份文件;容器重启后 healthy。

- [ ] **Step 4: 掩码不改测试**

只改 ComfyUI URL、两个 key 保持掩码原值,保存。确认 config.yaml 里两个 key **没变**
(掩码值被后端跳过),URL 变了。

- [ ] **Step 5: 成功标准**

UI 改 Pixelle 凭证 → settings 表存值 + config.yaml 同步 + 容器重启,不再需要手动编辑文件。

---

## 完成标准

- 后端:pixelle_connection service(读写 settings + sync_to_pixelle + restart)+ admin GET/PUT 端点,`cargo build -j 2` 通过,service 单测通过。
- 前端:连接管理页有「Pixelle 连接」卡片,typecheck 干净。
- 端到端:UI 改凭证 → config.yaml 同步 + 容器重启生效;掩码值不误改。
- 向后兼容:不改 Pixelle 源码;config.yaml 其余键保留;每次改前备份。

## 已知风险 / 备注

- serde_yaml 重序列化会丢 config.yaml 注释(已接受;每次有时间戳备份兜底)。
- BoosAPI 进程需有 docker compose 执行权限 + config.yaml 读写权限(同宿主 root 运行,满足)。
- Task 5 重启 BoosAPI 动线上服务,确认时机。
- 备份文件会累积(config.yaml.bak-*),长期可加清理,本期不做。