biliup-next/docs/control-plane-guide.md

Control Plane Guide

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

默认地址：

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

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

/home/theshy/video/test.mp4

点击：

复制到隔离 Stage

适合：

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

2. 浏览器直接上传文件

选择本地文件后点击：

上传到隔离 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 失败：先看 song_detect.provider，再看 codex_cmd 或 qwen_cmd
• publish 失败：先看 cookies.json、biliup
• collection_* 失败：再看任务历史和日志

评论规则补充：

• comment
  • 纯享版视频下默认发 session 级聚合“编号歌单”
  • 内容按 P1/P2/P3 分组
  • 同一 session 只由 anchor task 发一次
  • 完整版主视频下默认才发 session 级“带时间轴评论”
  • 内容按 P1/P2/P3 分组
  • 同一 session 只由 anchor task 发一次
  • 如果当前任务找不到 full_video_bvid.txt，也没能从最近发布列表解析出完整版 BV，主视频评论会跳过

session 规则补充：

• 同主播、文件名时间 3 小时内的任务会自动归到同一 session
• session 的 session_key 使用最早片段标题
• 同一 session 内：
  • 只有 anchor task 真正执行纯享版上传
  • 纯享版上传会聚合整组 split_video
  • 整组 task 共用同一个 bvid.txt
  • split/full 评论都只发一次

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 或 qwen_cmd
• biliup_path

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

Logs

这里可以看日志文件。

支持：

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

使用建议：

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

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

Settings

Settings 分成两层：

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

表单区

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

• min_duration_seconds
• groq_api_key
• codex_cmd
• qwen_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 重绘表单

敏感字段规则

敏感字段会显示为：

__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. 新任务会按新规则执行

建议：

• 如果你希望纯享版评论以 session 级聚合歌单展示，保持 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。