Bangumi-syncer

Appearance

🗄️ Bangumi Archive 离线查询层 ​

Bangumi Archive 是一项本地归档功能：把 Bangumi 官方 Archive 项目 发布的全站数据快照下载到本地，启用后同步流程会优先查本地，命中即返回、未命中再回退到 Bangumi 官方 API。

为什么要开启 ​

  • 更精准：开启Archive后可使用分割匹配场景，将匹配成功率提升到99%以上。
  • 更快：原本要走 API 的查询延迟从秒级降到毫秒级，同步响应更快。
  • 更稳：命中本地后不消耗 API 调用次数，能显著降低对 Bangumi 官方 API 的依赖，避免触发频率限制或网络抖动导致的同步失败。
  • 离线可用：配合 Bangumi Replay 可在 Bangumi API 完全不可达时仍能匹配条目并入队待补发，实现端到端无网缓存。

默认关闭，需要手动在「配置管理」里开启。

适用场景 ​

场景是否建议启用说明
大批量同步历史观看记录✅ 强烈建议数千条记录首次同步时，archive 可把绝大多数查询转为本地，避免 API 风控
网络环境差或不稳定✅ 建议命中本地后无需等待 API，规避长尾延迟
跨季续集链查找✅ 建议一次拿完整续集链，避免逐跳 API 调用
磁盘空间紧张（可用 <3GB）⚠️ 不建议导入峰值约 2.6GB，常态占用约 1.3GB
排查匹配问题⚠️ 可临时关闭关闭后走纯 API 路径，便于对比是 archive 数据问题还是 API 数据问题

配置项 ​

在 Web 的「配置管理」→「Bangumi Archive 离线查询层」卡片里填写，对应 config.ini 的 [bangumi-archive] 段。

配置项默认值说明
启用 Archive关闭总开关。从「关闭」切到「开启」会自动触发首次导入与索引构建，无需重启程序
定时更新 Cron0 8 * * 3五段式 cron，默认每周三 08:00（北京时间）执行，晚于官方 05:00 发布
数据目录./data/archive存放归档数据库的目录。Docker 部署建议挂载到 /app/data，避免容器重建时数据丢失
HTTP 代理空下载 dump zip 时使用的代理。留空则自动继承 [dev] script_proxy，国内用户建议配置
磁盘阈值 (MB)3000低于此可用空间时跳过导入，避免磁盘写满
SSL 校验开启下载时是否校验 SSL 证书，自签名环境可关闭

推荐配置示例 ​

ini
[bangumi-archive]
enabled = true
data_dir = ./data/archive
http_proxy = http://127.0.0.1:7890       ; 国内建议配置代理
ssl_verify = true
update_cron = 0 8 * * 3                  ; 每周三 08:00 自动更新
min_disk_space_mb = 3000

配置立即生效

保存配置后无需重启程序。从「关闭」切到「开启」时会自动触发首次导入。

启用后的行为 ​

首次启用流程 ​

  1. 保存配置触发后台导入
  2. 后台下载并导入：从 GitHub 下载全站数据快照（约 400MB，含校验），导入到本地数据库
  3. 导入期间不阻塞同步：未导入完成时查询会自动降级到 API，调用方无感知
  4. 导入完成：查询开始命中本地，享受毫秒级响应

查询优先级 ​

本地数据库  →  Bangumi 官方 API
  ↑                ↑
命中即返回      未命中兜底

与 Bangumi Replay 的关系 ​

Archive 与 Replay 是两个互相独立的功能，可各自启停，但搭配使用能覆盖「API 完全不可达」的端到端场景：

能力仅 ReplayReplay + Archive
API 不可达时，已匹配的写操作入队补发✅✅
API 不可达时，匹配新条目（读操作）❌ 走 API 仍失败✅ 命中本地数据集
API 不可达时，端到端「无网匹配 + 入队 + 补发」❌ 无法匹配✅ 完整闭环

简言之：

  • Archive 提供读降级：API 不可达时，读操作（搜索 / 查条目）命中本地数据集，仍能匹配新条目
  • Replay 提供写降级：API 不可达时，写操作（点在看 / 标章节）入队待补发

磁盘占用 ​

双库设计仅在导入时短暂并存（active 库 + 新库），导入完成切换指针后旧库立即清理，常态仅保留 active 库。

项目大小
active 库（导入前已存在）约 0.8GB
新库（导入时新建）约 0.8GB
解压后的临时文件（解压完成立即删除 zip）约 1GB
导入峰值合计约 2.6GB
常态占用（仅 active 库）约 1.3GB

min_disk_space_mb = 3000 是导入前的硬性阈值，低于此值会跳过导入并记录错误日志。

Docker 部署提示 ​

Docker 部署时建议把 data_dir 挂载到宿主机，避免容器重建时数据丢失：

yaml
volumes:
  - ./data:/app/data

默认 data_dir = ./data/archive，对应容器内 /app/data/archive。

番剧放送日历与今日提醒 ​

启用 Archive 后会自动解锁两项额外能力（未启用 Archive 时自动隐藏，不消耗资源）：

  • 仪表板番剧放送日历卡片：查看未来 7/14/30 天的放送日程，支持「仅我在追」筛选（需配置 Bangumi 账号）。数据来源于本地数据库，不额外请求 API。
  • 今日放送提醒定时任务：每日通过 Cron 查询当日放送番剧章节，汇总后通过 Webhook / 邮件 / 企业微信 / 钉钉推送。配置段为 [notify-airing-today]，通知类型为 airing_today，需在「通知配置」中订阅该事件才会真正推送。详见 ⚙️ 配置说明 · 今日放送提醒。

仅在 Archive 启用时可用

放送日历与今日放送提醒依赖 Archive 的 episode.airdate 数据，未启用 Archive 时：

  • 仪表板不显示放送日历卡片
  • airing_today 定时任务自动跳过执行（即使 enabled = true）
  • Archive 数据未导入时同样跳过，不触发通知

常见问题 ​

启用后一直未生效 ​

  1. 查状态：在「调试工具」或通过 GET /api/bangumi_archive/status 检查 enabled / last_error / import_in_progress 字段
  2. 常见原因：
    • 磁盘空间不足：可用空间低于 min_disk_space_mb（默认 3000MB）会跳过导入
    • 网络代理配置错误：http_proxy 留空但 [dev] script_proxy 也未配置
    • GitHub 下载失败：直连与镜像源 fallback 链均不通，建议配置代理或手动下载 zip 后通过 /api/bangumi_archive/import_local 上传

导入失败后重试 ​

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

索引未就绪降级到 API ​

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

  • 不影响同步成功率，只是该次查询走 API 较慢
  • 索引构建在子线程进行，不阻塞主流程，构建完成后自动开始命中

数据陈旧 ​

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

archive 命中但结果不对 ​

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

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

磁盘占用过大 ​

  • 双库仅在导入时短暂并存，导入完成后旧库自动清理
  • 若磁盘紧张可关闭 archive，并删除 data_dir 下的 bangumi_archive_*.db 文件

接下来 ​