🚀 使用 Docker Compose 部署 BangumiKomga 漫画刮削器

🚀 使用 Docker Compose 部署 BangumiKomga

本教程将指导您如何使用 Docker Compose 部署 BangumiKomga，这是一个用于在 Bangumi 番组计划（一个专注于动画、漫画、游戏、音乐等ACG领域的中文社区平台）和 Komga（一款开源的漫画/电子书媒体服务器）之间同步和管理数据的工具。

📝 项目简介

BangumiKomga 项目旨在搭建 Bangumi 与 Komga 之间的桥梁，主要功能包括：

• 数据同步：将您在 Bangumi 上标记的ACG作品收藏状态、进度和评分等信息同步到 Komga 的漫画或电子书元数据中。
• 元数据管理：利用 Bangumi 丰富且结构化的 ACG 资料库来增强 Komga 库中作品的元数据。
• 个性化配置：支持根据库或集合进行同步，并可选择是否使用 Bangumi 的缩略图。
• 多种运行模式：支持一次性同步或定时轮询同步，满足不同需求。

组合使用优势：通过 BangumiKomga，您可以实现 ACG 收藏管理的自动化与一体化，尤其在管理漫画、画集等作品时，能确保 Komga 中的信息与您的 Bangumi 收藏记录保持一致。

---

📝 项目简介2

bangumikomga 是一款专为漫画 / 电子书管理工具 Komga 设计的元数据同步工具，核心功能是对接 Bangumi（番组计划）平台，自动为 Komga 中的漫画 / 小说匹配并同步元数据（如封面、标题、作者、简介等）。其核心特点包括：

• 元数据自动同步：批量将 Komga 中的媒体库 / 集合与 Bangumi 条目关联，自动填充详细信息
• 灵活的同步策略：支持「一次性同步」或「定时轮询同步」，可自定义轮询间隔
• 离线支持：可缓存 Bangumi 元数据到本地（archivedata 目录），减少重复请求
• 精细控制：可指定同步的 Komga 库或集合，区分漫画与小说，设置匹配精度阈值
• 通知集成：支持通过 Gotify、Webhook 等方式发送同步结果通知
• 轻量部署：基于 Python 构建，通过 Docker 容器快速部署，依赖少易维护

---

⚙️ 部署前准备

1.服务器准备 * 一台云服务器（如腾讯云、阿里云）或本地设备（如 NAS、个人电脑）。操作系统推荐 Linux (如 Ubuntu 或 Debian)。

2.环境要求 * 确保系统已安装 Docker 和 Docker Compose。 * 可通过以下命令安装 Docker Compose (适用于 Linux)：

        sudo curl -L "https://github.com/docker/compose/releases/download/$(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep -oP '"tag_name": "\K(.*)(?=")')/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
        sudo chmod +x /usr/local/bin/docker-compose

安装后可通过 docker-compose -v 验证。

3.获取 Bangumi 访问令牌 (Access Token) * 此令牌用于授权 BangumiKomga 访问您的 Bangumi 账户数据。您需要在 Bangumi 官网 (https://bangumi.tv) 登录您的账户，在设置中找到访问令牌或类似选项来生成一个。请妥善保管此令牌，后续配置会用到。

4.确认 Komga 服务可访问 * 确保您已经部署了 Komga 服务，并且知道其访问地址（例如 http://192.168.0.5:25600）、管理员邮箱和密码。

🚀 配置 Docker Compose

1.创建项目目录 创建一个目录来存放所有配置文件和数据。

    mkdir -p ~/bangumikomga && cd ~/bangumikomga

2.创建 docker-compose.yml 文件 在该目录下创建 docker-compose.yml 文件，内容如下：

services:
  bangumikomga:
    image: chu1shen/bangumikomga:main  # 官方镜像
    container_name: bangumikomga       # 容器名称
    restart: unless-stopped            # 非手动停止时自动重启
    #restart: always  # 容器退出后自动重启（保障服务稳定，避免断连）

    volumes:
      #- ./config.py:/app/config/config.py
      #- ./bangumi-config/recordsRefreshed.db:/app/recordsRefreshed.db
      #- .recordsRefreshed.db:/app/recordsRefreshed.db
      #- ./config:/app/config
      #- ./config.py:/app/config/main.py

      #- ./config.py:/app/config/config.py
      #- ./recordsRefreshed.db:/app/recordsRefreshed.db

      - ./config.py:/app/config/config.py            # 挂载核心配置文件   # 内容更改见 step.2
      - ./recordsRefreshed.db:/app/recordsRefreshed.db # 挂载同步记录数据库
      - ./logs:/app/logs                             # 挂载日志目录
      - ./archivedata:/app/archivedata               # 挂载离线元数据目录（可选） # 离线元数据（可选），详见`ARCHIVE_FILES_DIR`

**关键配置说明**：
*   `volumes`: 这部分非常重要，它确保了容器内产生的数据（如配置、同步状态、日志）能够持久化保存在宿主机上，避免容器重启后数据丢失。
    *   `./config.py:/app/config/config.py`: 将主机的配置文件映射到容器内。
    *   `./recordsRefreshed.db:/app/recordsRefreshed.db`: 用于持久化记录同步状态，避免重复同步。
    *   `./logs:/app/logs`: 方便在主机上直接查看应用程序日志。
    *   `./archivedata:/app/archivedata`: 用于存储离线元数据（如果配置中启用）。

3.创建 config.py 配置文件 在 ~/bangumikomga 目录下创建 config.py 文件，这是能运行的配置，请确保关键参数正确： 1. 用于刮削NSFW条目，默认为空。BANGUMI_ACCESS_TOKEN，去BANGUMI注册后创建个人令牌写上token也叫NSFW账号。 2. KOMGA_BASE_URL填写komga的服务器，KOMGA_EMAIL填账号与KOMGA_EMAIL_PASSWORD密码 3. 发邮件通知用的 NOTIF_GOTIFY_ENDPOINT和NOTIF_WEBHOOK_ENDPOINT与NOTIF_HEALTHCHECKS_ENDPOINT请填写上gotify、webhook搭建后的链接等信息，不需要就留空默认好了。

BANGUMI_ACCESS_TOKEN = 'aENcXS1ygIdZkLxM2TMLTyr01MXqbotOhozcunyE'
KOMGA_BASE_URL = 'http://192.168.0.1:15600'
KOMGA_EMAIL = 'admin@komga.io'
KOMGA_EMAIL_PASSWORD = 'aaaaaa123'
#KOMGA_LIBRARY_LIST = [{"LIBRARY":"0MW9GNJ2QXSP0","IS_NOVEL_ONLY":False}]
#KOMGA_COLLECTION_LIST = [{"COLLECTION":"0KWDRTT52V1QY","IS_NOVEL_ONLY":True}]
KOMGA_LIBRARY_LIST = []
KOMGA_COLLECTION_LIST = []
USE_BANGUMI_ARCHIVE = False
ARCHIVE_FILES_DIR = './archivedata/'
ARCHIVE_UPDATE_INTERVAL = 168
BANGUMI_KOMGA_SERVICE_TYPE = 'once' #'poll'
BANGUMI_KOMGA_SERVICE_POLL_INTERVAL = 20
BANGUMI_KOMGA_SERVICE_POLL_REFRESH_ALL_METADATA_INTERVAL = 10000
USE_BANGUMI_THUMBNAIL = False
USE_BANGUMI_THUMBNAIL_FOR_BOOK = False
SORT_TITLE = False
FUZZ_SCORE_THRESHOLD = 80
RECHECK_FAILED_SERIES = False
RECHECK_FAILED_BOOKS = False
CREATE_FAILED_COLLECTION = True
NOTIF_TYPE_ENABLE = []
NOTIF_GOTIFY_ENDPOINT = 'http://IP:PORT'
NOTIF_GOTIFY_TOKEN = 'TOKEN'
NOTIF_GOTIFY_PRIORITY = 1
NOTIF_GOTIFY_TIMEOUT = 10
NOTIF_WEBHOOK_ENDPOINT = 'http://IP:PORT'
NOTIF_WEBHOOK_METHOD = 'POST'
NOTIF_WEBHOOK_HEADER = '{"Content-Type": "application/json"}'
NOTIF_WEBHOOK_TIMEOUT = 10
NOTIF_HEALTHCHECKS_ENDPOINT = 'http://IP:PORT'
NOTIF_HEALTHCHECKS_TIMEOUT = 10

打开 config.py，根据准备的信息修改以下核心参数（其他参数可保持默认）：

# Bangumi 访问令牌 - 务必替换为您在部署前准备中获取的真实令牌
BANGUMI_ACCESS_TOKEN = '你的Bangumi Access Token'

# Komga 服务配置 - 根据你的实际 Komga 部署信息修改
# Komga 服务器的基地址 # 替换为你的Komga访问地址（如http://192.168.0.5:25600）
KOMGA_BASE_URL = 'http://Komga的IP或域名:端口'
# Komga 管理员邮箱
KOMGA_EMAIL = 'admin@komga.io'
# Komga 管理员密码 # 替换为你的Komga管理员密码
KOMGA_EMAIL_PASSWORD = '你的Komga密码'

# 同步范围配置（至少配置一个，否则无同步目标）
# 如果 KOMGA_LIBRARY_LIST 为空列表，则会同步所有有权限的库
# 如果 KOMGA_COLLECTION_LIST 为空列表，则会同步所有有权限的集合
#KOMGA_LIBRARY_LIST = [{"LIBRARY":"0MW9GNJ2QXSP0","IS_NOVEL_ONLY":False}]
#KOMGA_COLLECTION_LIST = [{"COLLECTION":"0KWDRTT52V1QY","IS_NOVEL_ONLY":True}]

# 方式1：同步指定Komga库（推荐）
# 格式：[{"LIBRARY":"库ID","IS_NOVEL_ONLY":False}]，False=漫画，True=小说
KOMGA_LIBRARY_LIST = []

# 方式2：同步指定Komga集合（可选，与库二选一或同时配置）
# KOMGA_COLLECTION_LIST = [{"COLLECTION":"集合ID","IS_NOVEL_ONLY":True}]
KOMGA_COLLECTION_LIST = []


# 离线元数据存档配置  # 是否使用离线元数据（True=启用，需archivedata目录）
USE_BANGUMI_ARCHIVE = False
# 离线元数据文件目录
ARCHIVE_FILES_DIR = './archivedata/'
# 离线元数据更新间隔（小时）
ARCHIVE_UPDATE_INTERVAL = 168

# 服务运行模式与间隔  # 服务类型: 'once' (一次性) 或 'poll' = 定时轮询（需配置轮询间隔）
# 如果 BANGUMI_KOMGA_SERVICE_TYPE 设置为 'poll'，以下间隔设置才会生效
BANGUMI_KOMGA_SERVICE_TYPE = 'once' #'poll'
# 轮询间隔（分钟，仅poll模式生效）
BANGUMI_KOMGA_SERVICE_POLL_INTERVAL = 20
# 全量刷新元数据间隔（分钟）
BANGUMI_KOMGA_SERVICE_POLL_REFRESH_ALL_METADATA_INTERVAL = 10000

# 缩略图与排序配置  # 是否使用 Bangumi 缩略图
USE_BANGUMI_THUMBNAIL = False
# 是否对书籍使用 Bangumi 缩略图
USE_BANGUMI_THUMBNAIL_FOR_BOOK = False
# 是否对标题排序
SORT_TITLE = False

# 同步精度与控制  # 模糊匹配阈值（越高越严格，建议70-90），高于此分数才认为是同一作品
FUZZ_SCORE_THRESHOLD = 80
# 是否重新检查同步失败的系列
RECHECK_FAILED_SERIES = False
# 是否重新检查同步失败的书籍
RECHECK_FAILED_BOOKS = False
# 是否为同步失败的项创建集合
CREATE_FAILED_COLLECTION = True

# 通知配置 (默认未启用，如需使用请配置相应变量)  # 启用通知类型，例如 ['gotify', 'webhook']
# ... 其他 NOTIF_* 配置根据您的通知服务设置
NOTIF_TYPE_ENABLE = []
NOTIF_GOTIFY_ENDPOINT = 'http://IP:PORT'
NOTIF_GOTIFY_TOKEN = 'TOKEN'
NOTIF_GOTIFY_PRIORITY = 1
NOTIF_GOTIFY_TIMEOUT = 10
NOTIF_WEBHOOK_ENDPOINT = 'http://IP:PORT'
NOTIF_WEBHOOK_METHOD = 'POST'
NOTIF_WEBHOOK_HEADER = '{"Content-Type": "application/json"}'
NOTIF_WEBHOOK_TIMEOUT = 10
NOTIF_HEALTHCHECKS_ENDPOINT = 'http://IP:PORT'
NOTIF_HEALTHCHECKS_TIMEOUT = 10

如何获取 Komga 库 ID？

4.创建必要的目录和文件 在 ~/bangumikomga 目录下，运行以下命令创建 volumes 中映射的目录和文件：

    mkdir logs archivedata
    touch recordsRefreshed.db

🎯 启动与验证

1.启动服务 在 docker-compose.yml 文件所在目录，执行以下命令以后台模式启动服务：

    docker-compose up -d

2.验证服务状态 使用以下命令检查容器是否正常运行：

    docker-compose ps

如果看到 bangumikomga 容器的状态 (State) 为 Up，则表示启动成功。

3.查看日志 通过查看日志可以了解同步过程的详细信息，帮助验证是否正常运行：

    docker-compose logs -f bangumikomga

首次启动时，请关注日志中是否有明显的错误信息，例如 Bangumi 认证失败、Komga 连接异常等。

🔧 基础配置与使用

1.配置 Komga 库/集合同步 * 全库同步：如果 KOMGA_LIBRARY_LIST 和 KOMGA_COLLECTION_LIST 设置为空列表 []，BangumiKomga 会尝试同步您 Komga 账户有权限访问的所有库和集合。 * 指定同步：如果需要同步特定的库或集合，您需要填写它们的 ID。 * 获取库 ID：在 Komga 的 Web UI 中，进入库设置，查看浏览器地址栏或库信息，可以找到库 ID。 * 获取集合 ID：类似地，在集合页面可以找到集合 ID。 * 修改 config.py 中的 KOMGA_LIBRARY_LIST 或 KOMGA_COLLECTION_LIST，例如：

            KOMGA_LIBRARY_LIST = [{"LIBRARY":"你的库ID", "IS_NOVEL_ONLY": False}]
            KOMGA_COLLECTION_LIST = [{"COLLECTION":"你的集合ID", "IS_NOVEL_ONLY": True}]

2.理解并配置服务运行模式 * 一次性同步 (once)：容器启动后执行一次同步任务，然后退出。这对于使用外部工具（如 Crontab）调度任务非常有用。 * 轮询同步 (poll)：容器会持续运行，并根据 BANGUMI_KOMGA_SERVICE_POLL_INTERVAL 设置的时间间隔（分钟）定期执行同步任务。 * 根据您的需求修改 config.py 中的 BANGUMI_KOMGA_SERVICE_TYPE。

3.（可选）配置通知 如果您希望接收同步任务状态的通知（如成功、失败），可以配置 config.py 中的 NOTIF_TYPE_ENABLE 及相关通知服务（如 Gotify、Webhook）的参数。

🛠️ 维护与管理

• 更新服务 当有新版本的 BangumiKomga 镜像发布时，可以通过以下步骤更新：

  # 进入 docker-compose.yml 所在目录
  cd ~/bangumikomga
  # 拉取最新镜像
  docker-compose pull
  # 重新启动服务
  docker-compose up -d
  # 可选择性删除旧镜像
  docker image prune

• 数据备份 定期备份整个 ~/bangumikomga 目录，或至少备份 config.py、recordsRefreshed.db 以及 logs 目录。这些文件包含了您的所有配置和同步状态记录。

• 日志管理

• 日志文件默认存储在 ./logs 目录下，定期检查日志有助于发现问题。
• 如果日志文件过大，可以考虑使用日志轮转工具进行管理。

❓ 常见问题排查

• 容器启动失败

  1. 检查 docker-compose.yml 语法：使用 docker-compose config 验证 YAML 文件格式是否正确。
  2. 检查目录权限：确保宿主机上挂载的目录（如 logs, archivedata）对于 Docker 容器内的进程有可写权限。
  3. 查看详细日志：使用 docker-compose logs bangumikomga 查看具体的错误信息。

• 同步失败或无数据同步

  1. 验证 Bangumi Access Token：确认 config.py 中的 BANGUMI_ACCESS_TOKEN 正确无误，且在 Bangumi 上是有效的。
  2. 检查 Komga 连接配置：确认 KOMGA_BASE_URL、KOMGA_EMAIL 和 KOMGA_EMAIL_PASSWORD 正确，并且当前运行 BangumiKomga 的服务器能够访问该 Komga 地址。
  3. 检查库/集合 ID：如果配置了特定的 KOMGA_LIBRARY_LIST 或 KOMGA_COLLECTION_LIST，请确认 ID 是否正确。
  4. 提高日志级别：如果配置允许，可以调整应用日志级别为 DEBUG 以获取更详细的运行信息。

• 性能问题或同步缓慢

  1. 调整同步间隔：如果使用轮询模式且觉得同步过于频繁，可以适当增大 BANGUMI_KOMGA_SERVICE_POLL_INTERVAL。
  2. 关注网络状况：同步过程涉及与 Bangumi API 和 Komga 的通信，网络延迟可能会影响速度。
  3. Komga 服务器负载：大量元数据更新可能会对 Komga 服务器造成一定压力，请确保 Komga 所在服务器资源充足。

通过以上步骤，你应该已经成功部署并配置了 BangumiKomga，享受在 Bangumi 和 Komga 之间自动化同步和管理 ACG 作品数据的便利吧！

---

❓ 常见问题排查2

1. 连接 Komga 失败

• 日志报错 Could not connect to Komga：
  • 检查 KOMGA_BASE_URL 是否正确（需包含 http:// 或 https://，端口是否正确）
  • 确认 Komga 服务是否运行，且与 bangumikomga 容器网络互通（同一局域网或容器在同一网络）
  • 检查 KOMGA_EMAIL 和 KOMGA_EMAIL_PASSWORD 是否正确（区分大小写）

2. Bangumi 令牌错误

• 日志报错 Invalid Bangumi access token：
  • 重新获取 Bangumi Access Token（令牌可能过期，需在 Bangumi 应用页面重新生成）
  • 确保 BANGUMI_ACCESS_TOKEN 无多余空格或引号

3. 无同步目标（日志显示 No libraries/collections to sync）

• 未配置 KOMGA_LIBRARY_LIST 或 KOMGA_COLLECTION_LIST，至少需填写一个
• 库 ID 或集合 ID 错误，重新核对 Komga 中的 ID

4. 匹配成功率低

• 降低 FUZZ_SCORE_THRESHOLD（如从 80 改为 70）
• 确保 Komga 中漫画 / 小说的文件名规范（如包含正确的标题和卷数）

5. 容器启动后立即退出

• 检查 config.py 格式错误（如逗号缺失、引号不匹配），Python 对语法格式敏感
• 检查文件权限：执行 chmod -R 777 /opt/bangumikomga 确保容器可读写挂载的文件

通过以上步骤，即可快速部署 bangumikomga 并实现 Komga 与 Bangumi 的元数据同步，让漫画库管理更高效。如需进阶配置，可参考项目文档调整 config.py 中的其他参数。

---

🎯 参考链接

漫画党必备！NAS 部署 Komga 教程：打造个人专属漫画媒体服务器~ - 攻略分享 飞牛私有云论坛 fnOS Bangumi番组计划官网入口 - 免费新番交流社区网站 动画排行 | 番组计划 Bangumi 番组计划 Bangumi 番组计划

1. Komga私人漫画库搭建和信息刮削简明教程 – 白磷茶室
2. BangumiKomga – 白磷茶室
3. GitHub - chu-shen/BangumiKomga: A Metadata Provider for Komga using Bangumi
4. BangumiKomga 配置生成器
5. WXRedian | 可爱的小Cherry | NAS表番里番漫画/小说元数据刮削，基于Komga的Bangumi刮削神器
6. KomgaBangumi 漫画服务元数据刮削器 | 泛舟湖上