BILIVE 部署与运行常见问题排查指南
BILIVE 是一款支持 7x24 小时无人值守录制的 B 站直播工具，具备自动切片、渲染弹幕及字幕投稿等功能，对硬件要求较低。在实际部署过程中，环境配置和依赖管理往往是卡点所在。这里整理了一些从安装到运行的常见坑点及解决思路，希望能帮大家少走弯路。
一、安装阶段常见问题
1.1 克隆项目失败
执行 git clone --recurse-submodules 时若遇到网络超时或子模块拉取不全，别急着重试。建议先检查能否访问仓库地址，如果网络波动较大，可以分两步走：先克隆主项目，再进入目录手动执行 git submodule update --init --recursive 补充子模块。
1.2 依赖安装错误
运行 pip install -r requirements.txt 报错通常是因为 Python 版本或环境冲突。务必确认使用的是 Python 3.10 版本（可通过 python --version 查看）。强烈建议创建虚拟环境隔离依赖，执行 python -m venv venv 并激活后安装。如果是 aarch64 架构用户，由于 PyPI 缺少 triton 的 release 包，记得在 requirements.txt 中注释掉该依赖项。
1.3 FFmpeg 缺失
程序启动提示缺少 FFmpeg 很常见。Linux 下直接通过包管理器安装即可：Ubuntu/Debian 用 sudo apt-get install ffmpeg，CentOS 用 sudo yum install ffmpeg。Windows 用户需下载对应版本并将可执行文件路径加入系统环境变量。
二、配置阶段常见问题
2.1 Whisper 语音识别配置
配置 ASR 时若无法识别或 API 调用失败，主要看两点：
- API 模式：在
bilive.toml中设置asr_method = "api"并填入有效的WHISPER_API_KEY。注意 Groq 免费层有频率限制，超限后可考虑升级。 - 本地部署：需要 NVIDIA 显卡且驱动正常，用
nvidia-smi和nvcc -V验证。模型文件需放在src/subtitle/models目录下，确保显存充足（如 small 模型至少 2.7GB）。
2.2 大模型与图像生成
自动切片或封面生成功能依赖外部模型。先在 bilive.toml 开启 auto_slice = true 和 generate_cover = true，然后按文档申请对应的 API Key。不同模型接口差异较大，建议查阅官方说明获取最新接入方式。
三、运行阶段常见问题
3.1 录制服务启动失败
执行 ./record.sh 后若无法启动，优先检查 RECORD_KEY 环境变量。密码需由字母数字组成，长度 8-80 位。临时设置可用 export RECORD_KEY=your_password，持久化则写入 .bashrc。若提示端口占用，修改脚本中的端口号或用 lsof -i :端口号 查杀进程。
3.2 上传功能异常
视频无法上传多半是登录态问题。源码部署需先 pip install bilitool 并运行 bilitool login --export 扫码导出 cookie.json 至根目录；Docker 部署则通过 docker logs bilive_docker 查看二维码扫码。此外，可在 bilive.toml 中将 upload_line 设为 "auto" 自动探测线路，或指定 "bldsa" 等固定节点。
