Bilibili 音频解析链路与排障专题

Source: ts3audiobot/03-bilibili-audio-troubleshooting.md

文档日期：2026-07-08 适用对象：TS3AudioBot 中的 !bili、yt-dlp、cookies 与本机音频代理

1. 链路概览

当前 Bilibili 播放有两条路径：

text

路径 A：!bili BV号
-> <Bilibili 命令插件>
-> yt-dlp / yt-dlp-bili
-> <Bilibili cookies 文件>
-> 下载 mp3
-> 播放本地文件

text

路径 B：!play http://127.0.0.1:<Bilibili 代理端口>/bv/BV号.mp3
-> <Bilibili 音频代理脚本>
-> yt-dlp
-> <Bilibili cookies 文件>
-> HTTP 流式返回
-> TS3AudioBot 播放 URL

路径 A 是主要使用方式，路径 B 是备用验证方式。

2. 关键文件

text

<TS3AudioBot 数据目录>/<Bilibili cookies 文件>
<TS3AudioBot 数据目录>/plugins/<Bilibili 命令插件>
<TS3AudioBot 数据目录>/bots/default/music/bili/
<TS3AudioBot 程序目录>/<Bilibili 音频代理脚本>
/usr/local/bin/yt-dlp
/usr/local/bin/yt-dlp-bili

宿主机对应：

text

<TS3AudioBot compose 目录>/data/<Bilibili cookies 文件>
<TS3AudioBot compose 目录>/data/plugins/<Bilibili 命令插件>
<TS3AudioBot compose 目录>/data/bots/default/music/bili/

3. 一次性检查命令

bash

docker exec ts3audiobot sh -c '
  echo "== tools =="
  command -v ffmpeg || true
  command -v yt-dlp || true
  command -v yt-dlp-bili || true
  echo "== files =="
  ls -l <TS3AudioBot 数据目录>/<Bilibili cookies 文件> 2>/dev/null || true
  ls -l <TS3AudioBot 数据目录>/plugins/<Bilibili 命令插件> 2>/dev/null || true
  ls -ld <TS3AudioBot 数据目录>/bots/default/music/bili 2>/dev/null || true
'

4. cookies 问题

如果 Bilibili 解析失败，优先检查 cookies：

bash

docker exec ts3audiobot sh -c 'ls -lh <TS3AudioBot 数据目录>/<Bilibili cookies 文件>'

常见问题：

文件不存在。
文件为空。
cookies 已过期。
cookies 权限导致容器内用户不可读。
cookies 对应账号无法访问目标视频。

注意：<Bilibili cookies 文件> 等同登录凭证，不要提交到公开仓库。

5. yt-dlp 路径问题

检查：

bash

docker exec ts3audiobot sh -c 'command -v yt-dlp; command -v yt-dlp-bili 2>/dev/null || true'

如果插件调用的是 yt-dlp-bili，但容器里只有 yt-dlp，需要补包装脚本或修改插件调用路径。

反过来，如果配置中写的是 youtube-dl，也要确认它实际指向哪个可执行文件。

6. 下载目录权限问题

检查：

bash

docker exec ts3audiobot sh -c 'ls -ld <TS3AudioBot 数据目录>/bots/default/music/bili'

如果不可写，修复：

bash

cd <TS3AudioBot compose 目录>
mkdir -p data/bots/default/music/bili
chown -R 1000:1000 data/bots/default/music

实际 UID/GID 以 Dockerfile 中的 ts3ab 用户为准。

7. 插件日志与代理日志

常用日志：

bash

tail -100 <TS3AudioBot compose 目录>/data/bili-command.log
tail -100 <TS3AudioBot compose 目录>/data/yt-dlp-bili.log
tail -100 <TS3AudioBot compose 目录>/data/plugin-load.log
docker logs --tail=120 ts3audiobot

判断方向：

plugin-load.log 异常：先查插件是否加载。
bili-command.log 异常：查插件执行、参数和下载目录。
yt-dlp-bili.log 异常：查解析工具、cookies 和 Bilibili 权限。
docker logs 异常：查 TS3AudioBot 本体、ffmpeg、库依赖。

8. 备用代理验证

如果 !bili 插件暂时不可用，可以用代理路径验证解析链路：

text

!play http://127.0.0.1:<Bilibili 代理端口>/bv/BV1gK4y1a7yZ.mp3

如果代理路径可用，说明 yt-dlp、cookies 和音频解析大概率没问题，故障更可能在插件加载或 !bili 命令注册。

如果代理路径也不可用，优先查：

<Bilibili 音频代理脚本> 是否启动。
yt-dlp 是否存在。
cookies 是否有效。
视频是否需要登录或地区权限。

9. 常见故障判断

text

!bili 返回基础命令列表
=> 插件没有加载

!bili 有响应但下载失败
=> yt-dlp、cookies、Bilibili 权限或下载目录问题

!play 代理 URL 失败
=> 代理、yt-dlp 或 cookies 问题

日志显示 ffmpeg not found
=> TS3AudioBot 播放链路问题，不是 Bilibili 解析问题

日志显示 Permission denied
=> 数据目录权限问题

10. 最小恢复顺序

text

1. 重启容器
2. 确认插件加载
3. 测试 !bili
4. 测试代理 URL
5. 检查 cookies
6. 检查 yt-dlp
7. 检查下载目录权限
8. 查看日志定位具体错误