Bangumi-syncer

Appearance

🔧 常见同步失败原因 ​

同步记录里出现 error 状态时，可以先按本页列出的常见原因排查。若仍无法解决，欢迎到 GitHub Issues 反馈。

排查第一步：看 debug 日志

在「同步记录」页面点击失败记录的 重试同步 按钮，会弹出实时 debug 日志，可直接定位到具体失败环节（账号 / 网络 / 匹配 / 集数 等）。本页各章节也都会提示对应的关键日志字样。

按症状速查 ​

你看到的现象直接跳转章节
同步记录报「认证失败」「access_token」相关错误1. Bangumi 账号问题
同步记录一直显示「未匹配到条目」或匹配错了番2. 标题匹配失败
调试日志里显示连接超时、拒绝连接、401/4033. 接入媒体源失败
多账号模式下「找不到对应 Bangumi 账号」4. 未设置媒体服务器用户名
推送的集数对不上、特别篇 / OVA / 剧场版失败5. 集数与特殊格式
Archive 启用后一直没生效、命中结果不对6. Bangumi Archive 相关问题
Replay 队列一直不补发、API 一直不可达7. Bangumi Replay 待同步队列问题

1. Bangumi 账号问题 ​

最常见的一类失败，通常表现为 认证失败、access_token 相关错误。

  • 未配置 Bangumi 账号：在「配置管理」→「Bangumi 账号配置」中通过 OAuth 授权或手动添加账号，保存后重试。
  • access_token 失效：长期运行后 token 可能过期（Bangumi 的 token 有效期约 1 年）。OAuth 授权的账号会自动刷新，无需干预；手动添加的账号需到「配置管理」里重新 生成并填写 一次。
  • 账号密码变更：如果在 Bangumi 网站改过密码，需要同步更新本程序里的配置。
  • 多账号模式下用户名不匹配：配置了多个 Bangumi 账号时，按「媒体服务器用户名」路由到对应账号，若媒体服务器用户名与配置里的不一致，会找不到对应的 Bangumi 账号。

排查方法：在「配置管理」里检查 Bangumi 账号配置是否完整，必要时点「测试连接」验证。

2. 标题匹配失败 ​

程序会把媒体库推送的标题拿去 Bangumi 搜索匹配，匹配不到就会失败。这是非账号类失败中最常见的一类。

2.1 译名差异 ​

媒体库里的标题是中文译名，Bangumi 上用的是日文原名或英文译名。

解决方法：到「映射管理」里添加 自定义映射，手动指定「标题 → Bangumi 条目 ID」，程序会优先使用映射规则。

2.2 多季合并 ​

媒体库把多季合并成一个条目（如「某番剧 第二季」），与 Bangumi 上的分季条目对不上。

解决方法：使用 季度感知映射 分别指定每一季对应的 Bangumi 条目 ID。

2.3 标题带额外信息 ​

媒体库标题里带了分辨率、字幕组、年份等后缀（如 [1080p] 某番剧 S02），干扰匹配。

解决方法：

  • 在「映射管理」里用精确标题指定 Bangumi ID。
  • 或在「配置管理 → 同步配置」的 屏蔽关键词 里加上这类后缀，让程序跳过不必要的同步。

2.4 不在 ACG 范围内 ​

Bangumi 是以 ACG（动画、漫画、游戏）为主的站点，非 ACG 内容（如欧美剧、纪录片、真人秀等）通常不会被收录。同步这类内容会因找不到条目而失败。

解决方法：在「配置管理」的 屏蔽关键词 里添加这类标题关键词，让程序自动跳过，避免产生失败记录。

想同步日剧 / 真人电影？

在「配置管理 → 同步配置」里打开 启用三次元（日剧/电影）支持，匹配失败时会继续尝试 Bangumi 的三次元条目（真人版、日剧、真人电影等）。

3. 接入媒体源失败 ​

程序需要能访问到媒体服务器或 Bangumi API，网络不通会导致失败。

3.1 不在局域网内 ​

  • 程序部署在与媒体服务器不同的网络环境（如 Docker 网络隔离、跨网段、VPN 未连通）。
  • 飞牛 / fongmi 等定时同步场景下，程序需要主动访问媒体服务器 API，若网络不通会探测失败。

3.2 网络连接失败 ​

  • 无法访问 bgm.tv：检查服务器到 Bangumi 的网络连通性，必要时在「配置管理 → 高级配置」里配置 HTTP 代理。
  • 无法访问媒体服务器：检查媒体服务器地址、端口是否正确，防火墙是否放行。
  • DNS 解析失败：服务器 DNS 配置异常，导致无法解析域名。

3.3 账号鉴权失败 ​

  • 媒体服务器的 API Token / 密码错误或已过期。
  • Plex / Emby / Jellyfin 的 webhook 密钥与本程序配置的「Webhook 认证密钥」不一致。
  • 飞牛 / fongmi 的登录凭证失效。

排查方法：重试时弹窗里的 debug 日志会显示具体的连接错误信息（超时、拒绝连接、401/403 等），按提示检查对应配置。

4. 未设置媒体服务器用户名 ​

配置了多个 Bangumi 账号时，程序依赖媒体服务器推送过来的 用户名 字段来路由到对应的 Bangumi 账号。

  • 用户名大小写或空格不一致：媒体服务器里的用户名与「配置管理」里填写的 Bangumi 用户名需要严格一致（包括大小写）。
  • fongmi 的用户名比较特殊：为设备名（来自 fongmi /device 接口的 name 字段，不是 IP），可在「调试工具」的 fongmi 扫描结果或同步日志中查看。

排查方法：在「同步记录」详情里查看 user_name 字段是否为空或与配置不符；必要时在媒体服务器侧调整 webhook 配置，确保携带正确的用户名。

媒体服务器用户名是必须的

媒体服务器用户名是同步与否的关键依据，请不要忘记设置，这关系到是否会触发同步动作。

5. 集数与特殊格式 ​

5.1 集数不存在 ​

  • 番剧实际还没有这一集（如推送了第 13 集但 Bangumi 上只登记了 12 集）。
  • 季数解析错误，导致去错误的季度里找集数。
  • 特别篇 / OVA / 剧场版的集数编号规则与正片不同，可能对不上。

排查方法：到 Bangumi 条目页面确认对应季度的章节列表是否包含推送的集数。

5.2 特殊名称 ​

  • 标题里包含特殊字符（如全角括号、特殊标点），导致字符串比对失败。
  • 标题与 Bangumi 上的同名条目撞名（如多部同名作品），自动匹配选错了条目。

解决方法：在「映射管理」里用精确的标题字符串指定正确的 Bangumi ID。

5.3 媒体类型混淆 ​

  • 电影 vs 剧集类型混淆：媒体库把剧场版标记为剧集，或把剧集标记为电影，导致程序走了错误的解析分支。
  • 自定义 Webhook 字段缺失：使用自定义 webhook 时，推送的 JSON 里缺少 title、season、episode 等必需字段。

排查方法：在「调试工具」页面用「测试同步」功能模拟一条请求，或查看重试弹窗里的 debug 日志，确认程序收到的原始数据是否符合预期。

6. Bangumi Archive 相关问题 ​

启用了 Bangumi Archive 离线查询层 后，同步会优先查本地 SQLite。本节列出 archive 相关的常见问题，未启用 Archive 可跳过本节。

6.1 启用后一直未生效 ​

排查步骤：

  1. 查看状态：在「调试工具」或通过 GET /api/bangumi_archive/status 检查 enabled / last_error / import_in_progress / current_progress 字段。
  2. 查看进度日志：GET /api/bangumi_archive/progress_log?task_id=xxx 看完整阶段变化。
  3. 常见原因：
    • 磁盘空间不足：可用空间低于 磁盘阈值 (MB)（默认 3000MB）会跳过导入。
    • 网络代理配置错误：Archive 的 HTTP 代理留空但 [dev] script_proxy 也未配置。
    • GitHub 下载失败：直连与镜像源 fallback 链均不通，建议配置代理或手动下载 zip 后通过 /api/bangumi_archive/import_local 上传。

6.2 导入失败后重试 ​

  • 自动重试：失败后 1 小时自动重试。
  • 手动重试：在「调试工具」点击强制重新下载导入，或 POST /api/bangumi_archive/trigger?force=true。

6.3 索引未就绪降级到 API ​

archive 启用但标题索引未构建完成时（首次启用约 3-8 分钟），查询会自动降级到 API：

  • 不影响同步成功率，只是该次查询走 API 较慢。
  • 其他直接查数据库的方法（不依赖标题索引）可正常工作。
  • 索引构建在子线程进行，不阻塞主流程，构建完成后自动开始命中。

6.4 数据陈旧 ​

  • Bangumi 官方每周三 05:00（北京时间）发布新 dump。
  • 默认 update_cron = 0 8 * * 3 每周三 08:00 自动拉取。
  • 如需立即更新：在「archive」点击强制更新，或 POST /api/bangumi_archive/trigger?force=true。

6.5 archive 命中但结果不对 ​

archive 数据来自 Bangumi 官方 dump，可能存在数据延迟或边缘情况：

  1. 临时关闭 archive 走纯 API 路径，对比结果是否一致。
  2. 在「调试工具」用「测试同步」功能复现问题。
  3. 必要时到 GitHub Issues 反馈。

6.6 磁盘占用过大 ​

  • 双库仅在导入时短暂并存，解压后立即删 zip，导入峰值 ≈ 2.6GB（active 库 ~0.8GB + 解压 ~1GB + 新库 ~0.8GB + WAL 余量）。
  • 导入成功切换 active 指针后，旧库会自动清理，常态占用约 1.3GB（仅 active 库）。
  • 若磁盘紧张可关闭 archive，并删除 data_dir 下的 bangumi_archive_*.db 文件。

更详细的 archive 说明请看 🗄️ Bangumi Archive 离线查询层。

7. Bangumi Replay 待同步队列问题 ​

启用了 Bangumi Replay 待同步队列补发 后，API 不可达时的写操作会进入待同步队列。本节列出 replay 相关的常见问题，未启用 Replay 可跳过本节。

Replay 默认开启

Replay 默认就是开启的（与 Archive 互相独立）。如果你没专门关闭过它，本节内容可能与你相关。

7.1 同步记录显示 queued 但一直不补发 ​

排查步骤：

  1. 确认开关：在「配置管理 → Bangumi Replay」里确认「启用 Replay」未被关闭。
  2. 查看调度器状态：GET /api/bangumi_replay/status，关注 enabled / running / cron / next_run：
    • running = false：调度器未启动，定时补发与立即触发都不会执行。保存一次 Replay 配置触发 apply_config_after_save，或重启程序。
  3. 手动触发补发：在「待同步队列」页面点击「批量补发」，或 POST /api/bangumi_replay/replay。
  4. 看日志关键字：
    • 📚 待同步队列为空，本轮跳过：队列已被其他线程补发完，正常。
    • 📚 Bangumi API 仍不可达，本轮补发跳过：API 还没恢复，等下一轮。
    • 📚 API 探测失败：探测请求本身异常，看具体堆栈。

7.2 API 一直不可达 ​

「待同步队列」页面点击「探测 API」或调度器日志一直报告不可达：

  1. 检查 Bangumi 账号配置：探测使用当前激活的 Bangumi 账号，若账号未配置或访问令牌为空会直接返回失败（日志：📚 无可用账号配置用于探测 API）。可在「配置管理」→「Bangumi 账号配置」中通过 OAuth 授权或手动添加账号。
  2. 检查代理与 SSL：「高级配置」里的 HTTP 代理不通或 SSL 校验配置错误都会让探测请求失败。
  3. 手动验证账号可用性：用相同 access_token 直接请求 https://api.bgm.tv/v0/subjects/1，确认 token 未过期（有效期约 1 年）。
  4. 强制清除不可达标记：调度器探测成功后会自动清除；如仍异常可重启服务。

7.3 队列堆积过多 ​

  • 单条任务最大重试次数由 最大重试次数 控制（默认 50），超过后标记为 abandoned 不再重试。
  • 可在队列页手动删除不需要的任务（如已用映射解决的旧失败记录）。
  • 长时间堆积通常意味着 Bangumi API 长期不可达，建议先解决 API 可达性问题（代理 / token / 网络）。

更详细的 replay 说明请看 🔄 Bangumi Replay 待同步队列补发。

仍然无法解决？ ​

如果以上原因都不符合，可以：

  1. 在「同步记录」页面找到失败记录，点击 重试同步，观察弹窗里的实时 debug 日志，定位具体失败环节。
  2. 到 GitHub Issues 提交一个新 Issue，附上：
    • 失败记录的截图（含标题、集数、错误消息）
    • 重试弹窗里的完整 debug 日志
    • 程序版本号（在「仪表板」页面可见）
    • 对应的媒体服务器类型（Plex / Emby / Jellyfin / 自定义等）

收到完整信息后会尽快协助排查。

注意隐私管理

debug 日志会带有详细的请求信息，其中会有token信息，记得隐去；其他人得到token会有盗号风险。