init biliup-next
This commit is contained in:
theshy
476
docs/control-plane-guide.md
Normal file
476
docs/control-plane-guide.md
Normal file
@ -0,0 +1,476 @@
|
||||
# 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。
|
||||
Reference in New Issue
Block a user