• Bangumi metadata scraper for Komga
  • 简介
  • 功能
    • 已完成
    • TODO
  • 先决条件
  • 快速开始
  • Komga 配置（必填）
    • 为小说添加元数据
  • Bangumi 配置（可选）
  • 消息通知（可选）
  • 创建失败收藏（可选）
  • 其他配置说明
  • 交互式配置生成
  • 服务运行方式
  • 如何修正错误元数据
  • 同步阅读进度
  • 命名建议
  • Issues & Pull Requests
  • Contributors
  • 致谢

该脚本获取您 Komga 实例上可用的漫画列表, 挨个在 Bangumi 上查询, 并按配置获取指定系列的元数据。 然后将这些元数据转换为与 Komga 兼容的格式, 并更新到 Komga 服务器的具体漫画条目中。

• 为失败的系列创建收藏（可选）
• 通知执行结果（可选）
• 漫画系列添加元数据
• 单册漫画添加元数据
• 自动跳过已刷新元数据的条目
• 系列及单册优先使用手动配置的 Bangumi 链接(cbl)
• 配置 Bangumi 登录
• 同步观看进度至 Bangumi
• 可选择处理范围：①所有书籍系列；②指定库的书籍系列；③指定收藏的书籍系列
• 区分单册和单话👉未匹配的书也会重新排序
• 添加同人志👉推荐使用LANraragi
• 可使用 Bangumi 图片替换系列、单册封面
• 排序标题，支持字母导航
• 提高匹配准确率：使用 FUZZ 对 bgm 搜索结果进行过滤和排序
• 使用bangumi/Archive离线数据代替联网查询
• 可常驻后台轮询更新元数据
• 使用滑动窗口限制联网查询频率
• 支持命令行交互式配置生成器及网页版配置生成器

处理逻辑见DESIGN

• 更新 Komga 封面时，判断：类型（'GENERATED'）、大小
• 重构元数据更新范围及覆盖逻辑
• 增强文件名解析
• 自动化测试 完善测试用例
• 支持在匹配书籍后导出 comicinfo.xml, info.json(eze) 和 series.json
• 进一步提升检索准确性

• 一个有 ADMIN 权限的 Komga 用户，最低版本1.19.0
• 使用 Windows/Linux/MAc 等主流操作系统, 也可在其上使用 Docker
• 如需在 Windows, Linux 或 Mac 上直接执行脚本, 应安装有Python

1. 安装依赖包

   # 准备环境
   pip3 install -r install/requirements.txt
   
   # 亦可使用 docker compose
   version: '3'
   services:
   bangumikomga:
       image: chu1shen/bangumikomga:main
       container_name: bangumikomga
       volumes:
       - /path/BangumiKomga/config.py:/app/config/config.py   # 内容更改见 step.2
       - /path/BangumiKomga/recordsRefreshed.db:/app/recordsRefreshed.db
       - /path/BangumiKomga/logs:/app/logs
       - /path/BangumiKomga/archivedata:/app/archivedata # 离线元数据（可选），详见`ARCHIVE_FILES_DIR`

2. 根据模板config/config.template.py 创建配置文件：config/config.py, 然后填写必需配置。(推荐优先使用交互式配置生成)

3. 用 python main.py 执行脚本, 或者用 docker start bangumikomga 启动Docker容器(默认执行后容器将自动关闭，详细说明见服务运行方式)

修改 KOMGA_BASE_URL, KOMGA_EMAIL 和 KOMGA_EMAIL_PASSWORD 以便程序访问你的 Komga 实例(此用户需要有 Komga 元数据修改权限)。

KOMGA_LIBRARY_LIST 处理指定库中的书籍系列。Komga 界面点击库（对应链接）即可获得，形如：'0B79XX3NP97K9'，对应地址：http://IP:PORT/libraries/0B79XX3NP97K9/series。配置示例：[{"LIBRARY": "0B79XX3NP97K9", "IS_NOVEL_ONLY": False}]

KOMGA_COLLECTION_LIST 处理指定收藏中的书籍系列。Komga 界面点击收藏（对应链接）即可获得，形如：'0B79XX3NP97K9'。配置示例：[{"COLLECTION": "0B79XX3NP97K9", "IS_NOVEL_ONLY": False}]

Komga 并没有区分漫画与小说，建议不同类型使用不同库

IS_NOVEL_ONLY：设置为True时，将只匹配小说数据；默认设置为False，匹配漫画数据

• BANGUMI_ACCESS_TOKEN: 用于读取 NSFW 条目

  • 请自行确认账号能否正常访问 NSFW 条目
  • 在 https://next.bgm.tv/demo/access-token 创建个人令牌
  • 如果不使用，请设置为''

• USE_BANGUMI_ARCHIVE: 指定是否优先使用 bangumi/Archive离线元数据

  • 需搭配 ARCHIVE_FILES_DIR 使用
  • 不含图像数据因此无法离线刷新封面。如果开启 USE_BANGUMI_THUMBNAIL，则仍需调用 BGM API 才能替换海报
  • 可选值为 True 和 False

• ARCHIVE_FILES_DIR: 指定储存 bangumi/Archive的本地目录，形如：./archivedata/

  • 启用 USE_BANGUMI_ARCHIVE 后，程序会自动从Github下载并解压元数据(可能较慢)
  • 离线元数据亦可提前手动解压至该目录中, 另外最好同时创建 archive_update_time.json 并添加日期，内容示例：{"last_updated": "2025-04-22T21:03:01Z"}

[!TIP] 已过时

• 如果将archive_update_time.json中时间修改为2099等较大值，可在很长时间内禁用自动更新

请使用ARCHIVE_UPDATE_INTERVAL↓↓↓

• ARCHIVE_UPDATE_INTERVAL: 指定 bangumi/Archive 离线元数据的更新间隔, 单位为小时。置为0表示不检查更新，其余值则会在启动时立即执行一次检查

• USE_BANGUMI_THUMBNAIL: 设置为True且未曾上传过系列海报时，使用 Bangumi 封面替换系列海报

  • 旧海报为 Komga 生成的缩略图，因此还可以通过调整Komga 服务器设置->缩略图尺寸（默认 300px，超大 1200px）来获得更清晰的封面
  • USE_BANGUMI_THUMBNAIL_FOR_BOOK: 设置为True且未曾上传过单册海报时，使用 Bangumi 封面替换单册海报

• FUZZ_SCORE_THRESHOLD：满分 100，默认值80。用于过滤搜索结果

  • 值越小匹配到错误元数据的可能性越大
  • 值越大匹配失败的可能性越大
  • 默认值80并不是一个经验值，有更好的评分请开 issue

消息通知支持Gotify、Webhook（如：飞书）、Healthchecks（定时任务监控）

• NOTIF_TYPE_ENABLE: 启用的消息通知类型

• Gotify

  • NOTIF_GOTIFY_ENDPOINT: Gotify base URL
  • NOTIF_GOTIFY_TOKEN: Application token

• Webhook

  • NOTIF_WEBHOOK_ENDPOINT: URL of the HTTP request. 如飞书中创建自定义机器人时的 webhook 地址

• Healthchecks

  • NOTIF_HEALTHCHECKS_ENDPOINT: URL of the HTTP request

将CREATE_FAILED_COLLECTION配置为True，程序会在刷新完成后，将本次刷新失败的系列添加到指定收藏（默认名：FAILED_COLLECTION）。

• RECHECK_FAILED_SERIES: 重新检查刷新元数据失败的系列

  • 其他情况下建议设置为False，可缩短程序运行时间

• RECHECK_FAILED_BOOKS: 重新检查刷新元数据失败的书

  • 意义不明的参数，建议设置为False，可缩短程序运行时间
  • 如果刷新书时，bangumi 数据不完整，则可以在数据补充后使用此参数修正此书元数据

• SORT_TITLE：设置为True时，在刷新元数据后会在系列元数据-排序标题前添加一个首字母用于导航

  • 此为临时方案，详细讨论见：
    • gotson/komga#1883
    • https://komga.org/docs/guides/edit-metadata#sort-titles
    • chu-shen/BangumiKomga#37
  • 如果要对此功能启用前的系列进行修改，请在scripts目录下手动运行一次python sortTitleByLetter.py

• 大部分配置项可通过交互式配置生成器生成
• 若 BangumiKomga 启动后发现在 config 目录下不存在有效的 config.py 文件，将会以命令行启动交互式配置生成器

修改配置的几种方式：

1. 将 config/config.template.py 重命名为 config/config.py，手动修改配置项

2. 用户可手动启动命令行交互式配置生成器：

   • 以名为 BangumiKomga 的容器为例，通过 docker exec 命令启动: sudo docker exec -it BangumiKomga python conifg/configuration_generator.py。
   • 原生部署的实例，可直接启动： python conifg/configuration_generator.py。

   [!TIP]

   若命令行交互式配置生成器在 config 目录下没有足够的文件读写权限，可能会导致配置生成失败或配置文件覆盖失败，请检查目录和 Linux 账户的读写权限，或使用 mv 命令手动覆盖 config.py 文件。

3. 用户亦可手动启动网页配置生成器：

   • 方式一：浏览器访问 web 目录下的 index.html 即可
   • 方式二：访问Github Pages

更多细节，详见文档

• BANGUMI_KOMGA_SERVICE_TYPE：服务运行方式，可选值：'once', 'poll', 'sse'
  • 'once'：以单次任务方式启动。执行后程序自动退出。推荐使用
  • 'sse'：以事件服务方式启动。官方 API 支持，常驻后台，持续接收新变化。推荐有频繁更新需求的使用
  • 'poll'：以轮询服务方式启动。常驻后台，需搭配以下配置使用
    • BANGUMI_KOMGA_SERVICE_POLL_INTERVAL：后台增量更新轮询间隔，单位秒
    • BANGUMI_KOMGA_SERVICE_POLL_REFRESH_ALL_METADATA_INTERVAL：多少次轮询后执行一次全量刷新

高级配置：SSE 事件服务搭配 Nginx

人工修正错误元数据可以使用cbl(Correct Bangumi Link)，只需在系列元数据的链接中填入cbl和该漫画系列的 bangumi 地址。将强制使用此链接，不再进行刮削。与RECHECK_FAILED_SERIES配置无关

下面分三种情况说明具体操作：

• 自此系列添加至 komga 后还未运行过此程序：

  • 填入上面提到的信息
  • 正常执行python refreshMetadata.py

• 系列元数据更新失败，即「标题」与「排序标题」一样：

  • 填入上面提到的信息
  • 如果未填写，也可以尝试使用最新版本重新匹配之前失败的系列
    • 只需将RECHECK_FAILED_SERIES配置为True，重新匹配失败的系列；将RECHECK_FAILED_BOOKS配置为True，重新匹配失败的单行本
  • 正常执行python refreshMetadata.py

• 系列元数据更新错误，即匹配错误，刮削成其他条目：

  • 填入上面提到的信息
  • 正常执行python refreshMetadata.py

同步内容：

• 仅同步卷数，不同步话数

1. 步骤同刷新元数据

2. 步骤同刷新元数据

   注意：

   • 同步当前获取的所有系列的漫画进度（当前有3种范围：所有、仅指定库、仅指定收藏）。为避免污染时间线，请谨慎操作

3. python scripts/updateReadProgress.py

[漫画名称][作者][出版社][卷数][其他1][其他2]

• [漫画名称]：以漫画封面实际名称为准，繁体不必转简体。

• [作者]：作者名字亦以单行本所给名字为准

  • 繁体不转为简体，若有日文假名亦保留，如[島崎讓]、[天王寺きつね]；
  • 若作者为多人，则以×或&符号连接各作者（注意：不是英文x），将作画作者列于最后，如[矢立肇×有贺ヒトシ]、[手塚治虫×浦沢直树]、[堀田由美×小畑健]。

• [出版社]：例如[玉皇朝]、[青文]。

• [卷数]：例如[Vol.01-Vol.12]。

• [其他1]、[其他2]：其他信息。例如[完结]、[来源]。

例如：

[碧蓝之海][井上堅二×吉岡公威][Vol.01-Vol.18]
[相合之物][浅野伦][Vol.01-Vol.13]
[海王但丁][皆川亮二×泉福朗][Vol.01-Vol.13][境外版]

命名建议修改自某喵

欢迎提交新规则、问题、功能……

Made with contrib.rocks.

本项目部分代码及思路来自Pfuenzle/AnisearchKomga，部分代码生成自chatgpt，在此表示感谢！

语料库数据来源，感谢公开：

• bangumi_person.txt文件提取自bangumi/Archive
• Japanese_Names_Corpus（18W）.txt文件来自wainshine/Chinese-Names-Corpus

另外，也感谢以下优秀项目：

• gotson/komga
• bangumi/api