故障排查
约 1625 字大约 5 分钟
Bilibili 录制以 STREAM_QUALITY 为画质上限，从高到低尝试：默认原画 10000、蓝光 400、超清 250、高清 150、流畅 80，并纳入接口声明的中间档位；每次画质协商最多请求 8 个不同档位，为标准低档保留预算。有可用地址即采用接口实际返回的 qn，同画质才按 PREFERRED_STREAM_PROTOCOL 选择协议；画质未知保留为空，不把请求值伪装为实际画质。确认直播中但所有档位均无地址时按取流临时故障重试，不解释为下播，也不为该房间失败设置平台限流。登录态、风控和网络错误按原有来源预算处理，不通过降画质绕过。录制重连重新获取临时地址，重试次数及时间上限仍有效；连续临时取流失败耗尽预算保留 ERROR 状态。只有 HTTP/TLS/TCP 日志明确出现 EOF 时才归为传输异常，普通 EOF 不证明本地媒体损坏。
优先提供程序版本、故障时间以及房间、场次或任务编号。Web 请求出现“服务处理失败”时，同时提供页面上的日志定位编号。后台“错误日志”保存 WARNING/ERROR 的安全异常链；storage/logs/blc-<进程号>-<启动标识>.log 还保留 DEBUG 信息及具体调用文件/行号。应用与 Uvicorn 服务器错误均进入同一诊断通道，访问日志不记录查询参数。两类日志使用同一脱敏规则，网络地址仅保留主机名，不记录签名路径、查询串、请求凭据或异常局部变量。提交前仍请检查个人路径等内容，不要上传 .env、数据库或模型缓存。
启动器、后端和前端分别写入独立日志，避免 Windows 中多个进程占用同一个文件而导致轮转报 WinError 32。每个文件达到 10 MB 后轮转并压缩为 ZIP；启动及轮转时清理超过 14 天的归档和已退出进程的日志，仍存活进程的未压缩日志继续保留。旧版 blc.log 与非项目日志不会自动删除。排错时收集故障时间附近各进程的 .log 和 .log.zip 文件；清理遭遇文件占用或权限错误时保留原文件并在控制台报告。
blc doctor --yes 使用当前 FFMPEG_PATH、FFPROBE_PATH、STORAGE_ROOT 和数据库配置检查环境。模型目录按运行时 BLC_MODELS_DIR 检查；未设置时明确提示使用 SDK 缓存。磁盘/内存读取失败代表未知，不代表剩余空间为零或资源充足。
录制的片段登记、stderr 排空或磁盘保护失败会结束当前录制并保留 ERROR 状态。弹幕本地故障只停止弹幕采集，记录实际确认到的覆盖时间。上传显示失败或待人工核对时，先核对平台结果；后台作业不会把这些状态当作上传完成。
| 现象 | 排查 |
|---|---|
ffmpeg 不是内部或外部命令 | 安装 FFmpeg 或在 .env 设置 FFMPEG_PATH |
check 显示未开播 | 主播未直播时无流，属正常 |
| 取流报错 / 403 | 部分高清晰度需登录态，可在设置中心登录账号或填写 Cookie |
弹幕 token 返回 code=-352 | 登录请求失败时会立即匿名兜底并定时重试；匿名请求也被风控时会按配置间隔重试，录制与实时转写继续。无需反复手动登录 |
| 片段未生成 | 看 storage/logs/blc-*.log 及其 ZIP 归档中的 [ffmpeg] 行 |
| ASR 主引擎未加载 | 确认 pip install funasr modelscope 已执行 |
转写整理与时间边界
开启 LLM 转写整理后，整理正文与摘要会持久化，转写页面、整段语义分析和整场总结使用整理结果。原始 ASR 正文与词时间戳单独保留，人工修改后旧整理结果失效。整理正文没有逐词对齐信息：已有词时间戳的局部高光及成片文案继续读取对应时间范围内的原始词；覆盖完整分段时使用整理正文。原本没有词时间戳的分段沿用按时长比例裁剪，并标记为非精确。
审核队列按当前筛选分页，可通过上一页、下一页浏览全部候选，计数包含全部历史记录。上传预检因文件缺失、标题或频率限制而跳过后，处理原因并重试即可重新预检；平台结果未知的任务仍须先核对。
Web 静态资源与服务关闭
Windows 静态 JS/MJS/CSS 响应不依赖系统 MIME 映射。白屏或“添加直播间”无响应时记录浏览器控制台错误、失败资源 URL 和响应 Content-Type；服务端仍保留 HEAD、Range、缓存与 404 语义。
Windows 双端工作台通过父进程管道通知后端正常收尾。管道自身失效时，日志记录「父进程监管管道异常」及脱敏诊断；后端完成资源清理后以失败状态退出，工作台随后回收前端。正常关闭父进程管道仍按正常退出处理。
Windows 前端及虚拟环境启动器的后代由独立 Job 管理。工作台退出或被终止后，系统回收这组前端进程并释放监听端口；后端仍通过管道关闭执行自己的资源清理。
关闭服务时先通知计算停止，再依次收尾监控、录制、Web 作业、Worker、插件及指标采样。启动失败或某一服务关闭失败仍会执行其余资源清理，并保留异常。受监管媒体命令使用独占进程树，取消、超时及主命令退出都会清理后代，不影响其他程序；关闭期间不再启动新媒体命令，中断的任务重新排队且不消耗业务重试次数。Web 作业关闭等待超时会保留运行/取消中的处理器登记并阻止新作业，不会把尚未退出的同步线程当作已完成；需要等外部请求的有限超时或处理器实际返回。Finished server process 仅表示服务器生命周期结束，须以实际 Python 进程退出及命令行返回确认关闭。