# Control Plane Guide

本文档面向 `biliup-next` 控制台的日常使用。

默认地址：

```text
http://127.0.0.1:8787/
```

如果当前机器已经开放公网访问，也可以使用服务器 IP + `8787` 端口访问。

## 页面分区

控制台主要分成两列：

- 左侧：全局状态、服务、动作流、导入入口、任务列表、Settings
- 右侧：当前任务详情、步骤、产物、历史、时间线、模块、日志

建议的使用顺序是：

1. 先看 `Runtime`
2. 再看 `Tasks`
3. 选中一个任务后，看右侧详情
4. 如果任务异常，再看 `Logs` 和 `History`

## Runtime

这里可以看 3 个汇总指标：

- `Health`
- `Doctor`
- `Tasks`

含义：

- `Health = OK`
  - API 服务本身还活着
- `Doctor = OK`
  - 关键路径、二进制和依赖文件都存在
- `Tasks`
  - 当前数据库里的任务数

如果 `Doctor` 不是 `OK`，优先不要继续点任务操作，先修运行环境。

## Services

这里可以查看并控制：

- `biliup-next-worker.service`
- `biliup-next-api.service`
- 如果还保留旧服务，也可能看到 `biliup-python.service`

可执行操作：

- `start`
- `restart`
- `stop`

建议：

- 页面打不开时，先看 `biliup-next-api.service`
- 任务不推进时，先看 `biliup-next-worker.service`
- 不要随便再启动旧 `biliup-python.service`，除非你明确知道自己要同时跑旧链路

## Recent Actions

这里显示最近的控制面动作流，例如：

- `worker_run_once`
- `task_run`
- `retry_step`
- `reset_to_step`
- `stage_import`
- `stage_upload`
- `service_action`

可过滤：

- 仅当前任务
- `status`
- `action_name`

用途：

- 判断最近有没有人工操作过任务
- 判断任务是不是被重试过
- 判断服务是不是被重启过

## Import To Stage

这里有两种入口。

### 1. 复制本机已有文件到隔离 stage

输入服务器上的绝对路径，例如：

```text
/home/theshy/video/test.mp4
```

点击：

```text
复制到隔离 Stage
```

适合：

- 服务器本地已有文件
- 想快速把已有文件丢进新系统测试

### 2. 浏览器直接上传文件

选择本地文件后点击：

```text
上传到隔离 Stage
```

适合：

- 本地电脑上的测试视频
- 不想先手动传到服务器

上传成功后，`worker` 会自动扫描 `stage` 并开始建任务。

## Tasks

这里列出任务列表。

每个任务会显示：

- 标题
- 当前状态
- 任务 ID

常见状态：

- `created`
- `transcribed`
- `songs_detected`
- `split_done`
- `published`
- `commented`
- `collection_synced`
- `failed_retryable`
- `failed_manual`

建议：

- 先选中你关心的任务
- 再看右侧 `Task Detail / Steps / Logs`

## Task Detail

显示当前选中任务的核心信息：

- `Task ID`
- `Status`
- `Title`
- `Source`
- `Created`
- `Updated`

上方有 3 个操作按钮：

- `执行当前任务`
- `重试选中 Step`
- `重置到选中 Step`

### 执行当前任务

作用：

- 手动推进当前任务一次

适合：

- 你刚改完配置
- 你不想等下一轮 worker 轮询

### 重试选中 Step

作用：

- 从当前选中的 step 重新尝试

适合：

- 某一步是临时失败
- 不需要删除后续产物

### 重置到选中 Step

作用：

- 清理该 step 之后的产物和标记
- 把任务回拨到该 step
- 然后重新执行

适合：

- 后续结果已经不可信
- 需要从某一步重新跑整段链路

注意：

- 这是破坏性动作
- 页面会要求确认

## Steps

这里显示任务步骤列表，例如：

- `ingest`
- `transcribe`
- `song_detect`
- `split`
- `publish`
- `comment`
- `collection_a`
- `collection_b`

点击某个 step 之后：

- 这个 step 会成为“当前选中 step”
- 然后你就可以点：
  - `重试选中 Step`
  - `重置到选中 Step`

排查原则：

- `transcribe` 失败：先看 `Groq API Key`、`ffmpeg`
- `song_detect` 失败：先看 `codex_cmd`
- `publish` 失败：先看 `cookies.json`、`biliup`
- `collection_*` 失败：再看任务历史和日志

评论规则补充：

- `comment`
  - 纯享版视频下默认发“编号歌单”，不带时间轴
  - 完整版主视频下默认才发“带时间轴评论”
  - 如果当前任务找不到 `full_video_bvid.txt`，也没能从最近发布列表解析出完整版 BV，主视频评论会跳过

## Artifacts

这里显示任务当前已经产出的文件，例如：

- `source_video`
- `subtitle_srt`
- `songs_json`
- `songs_txt`
- `clip_video`
- `publish_bvid`

用途：

- 判断任务跑到了哪一步
- 判断关键输出是否已经落盘

如果开启了 cleanup 配置，任务在 `collection_synced` 后：

- `source_video` 对应的原始视频可能会被删除
- `clip_video` 对应的 `split_video/` 目录也可能被清理

这是正常收尾行为，不代表任务失败。

## History

这里是单任务动作历史。

和 `Recent Actions` 的区别：

- `Recent Actions` 看全局
- `History` 只看当前任务

可以看到：

- 动作名
- 状态
- 摘要
- 时间
- 结构化 `details_json`

用途：

- 判断某次 `retry` 或 `reset` 的结果
- 判断 worker 最近对这个任务做了什么

## Timeline

这里把任务事件串成一条时间线：

- `Task Created`
- step started / finished
- artifact created
- action records

适合：

- 回放任务完整过程
- 查清楚任务到底卡在什么时候

## Modules

这里显示当前注册的模块 / provider。

用途：

- 确认当前用的是哪套 provider
- 确认模块有没有注册成功

如果将来切 provider，这里会很有用。

## Doctor Checks

这里比顶部的 `Doctor = OK/FAIL` 更详细。

会列出：

- workspace 目录
- `cookies_file`
- `upload_config_file`
- `ffprobe`
- `ffmpeg`
- `codex_cmd`
- `biliup_path`

如果某个依赖显示 `(external)`，表示它还在用系统或父项目路径，不是 `biliup-next` 自己目录内的副本。

## Logs

这里可以看日志文件。

支持：

- 切换日志文件
- 刷新日志
- 按当前任务标题过滤

使用建议：

- 任务异常时，先选中任务
- 再勾选“按当前任务标题过滤”
- 然后查看相关日志

这样比直接翻整份日志快很多。

## Settings

Settings 分成两层：

- 上半部分：schema 驱动表单
- 下半部分：`Advanced JSON Editor`

### 表单区

这里适合日常参数调整，例如：

- `min_duration_seconds`
- `groq_api_key`
- `codex_cmd`
- `retry_count`
- `season_id_a`
- `season_id_b`
- `post_split_comment`
- `post_full_video_timeline_comment`
- `delete_source_video_after_collection_synced`
- `delete_split_videos_after_collection_synced`

支持：

- 搜索配置项
- 高频参数优先展示
- 低频参数收纳到 `Advanced Settings`

### Advanced JSON Editor

适合：

- 批量调整
- 一次改多个字段
- 需要直接编辑原始 JSON

页面上有两个同步按钮：

- `表单同步到 JSON`
- `JSON 重绘表单`

### 敏感字段规则

敏感字段会显示为：

```text
__BILIUP_NEXT_SECRET__
```

规则：

- 保留占位符：不改原值
- 改成空字符串：清空原值
- 改成新的字符串：更新为新值

## 推荐操作流

### 新上传一个测试视频

1. 打开控制台
2. 在 `Import To Stage` 上传视频
3. 看 `Tasks` 是否出现新任务
4. 选中该任务
5. 观察 `Steps / Artifacts / Timeline`
6. 如需加速，点击 `执行当前任务`

### 某个任务失败

1. 选中任务
2. 看 `Task Detail` 当前状态
3. 看 `Steps` 哪一步失败
4. 看 `Logs`
5. 若只是临时失败：
   - 选中 step
   - 点 `重试选中 Step`
6. 若后续产物也需要重建：
   - 选中 step
   - 点 `重置到选中 Step`

### 修改合集或上传参数

1. 打开 `Settings`
2. 搜索目标参数，例如 `season` / `retry`
3. 修改表单
4. 点击 `保存 Settings`
5. 对目标任务执行：
   - `执行当前任务`
   - 或 `重置到相关 step`

### 控制评论与清理行为

1. 打开 `Settings`
2. 搜索：
   - `post_split_comment`
   - `post_full_video_timeline_comment`
   - `delete_source_video_after_collection_synced`
   - `delete_split_videos_after_collection_synced`
3. 修改后保存
4. 新任务会按新规则执行

建议：

- 如果你希望纯享版评论更适合分P浏览，保持 `post_split_comment = true`
- 如果你不希望尝试给完整版主视频发时间轴评论，可以关闭 `post_full_video_timeline_comment`
- 如果磁盘紧张，再开启 cleanup；默认建议先关闭，等确认流程稳定后再开

### 服务异常

1. 看 `Services`
2. 优先 `restart biliup-next-worker.service`
3. 如果页面自身异常，再 `restart biliup-next-api.service`
4. 重启后看：
   - `Health`
   - `Doctor`
   - `Recent Actions`

## 安全建议

当前控制台已经对公网开放时，建议立刻设置：

- `runtime.control_token`

设置后：

- 除 `/` 和 `/health` 外，其余 API 都要求 `X-Biliup-Token`

如果你通过公网访问控制台，不建议长期保持空 token。