biliup-next/docs/cold-start-checklist.md

biliup-next Cold Start Checklist

目标：在一台没有旧环境残留的新机器上，把 biliup-next 启动到“可配置、可 doctor、可进入控制面”的状态。

1. 基础环境

• 安装 python3
• 安装 ffmpeg 和 ffprobe
• 如需完整歌曲识别，安装 codex
• 如需完整上传链路，准备 biliup 可执行文件

2. 获取项目

git clone <your-repo> biliup
cd biliup/biliup-next

3. 一键初始化

bash setup.sh

初始化完成后，项目会自动生成：

• config/settings.json
• config/settings.staged.json
• runtime/cookies.json
• runtime/upload_config.json
• data/workspace/*

注意：

• 这些文件默认都是模板或占位内容
• 此时项目应当已经能执行 doctor，但不代表上传链路已经可用

4. 填写真实运行资产

• 编辑 runtime/cookies.json
• 编辑 runtime/upload_config.json
• 把 biliup 放到 runtime/biliup，或在 settings.json 里改成系统路径
• 填写 transcribe.groq_api_key
• 按机器实际情况调整 song_detect.provider
• 如果用 codex，调整 song_detect.codex_cmd
• 如果用 qwen_cli，调整 song_detect.qwen_cmd
• 按需要填写 collection.season_id_a / collection.season_id_b

5. 验收

./.venv/bin/biliup-next doctor
./.venv/bin/biliup-next init-workspace
./.venv/bin/biliup-next serve --host 127.0.0.1 --port 8787
bash cold-start-smoke.sh

浏览器打开：

http://127.0.0.1:8787/

验收通过标准：

• doctor 输出可读，缺失项只剩你尚未填写的外部依赖
• 控制面可以打开
• Settings 页可正常保存
• stage 目录可导入或上传文件
• cold-start-smoke.sh 能完整通过

6. 完整链路前检查

在开始真实处理前，确认以下项目已经真实可用：

• runtime/cookies.json
• runtime/upload_config.json
• publish.biliup_path
• song_detect.provider
• song_detect.codex_cmd 或 song_detect.qwen_cmd
• transcribe.groq_api_key
• collection.season_id_a / collection.season_id_b