Komga私人漫画库搭建和信息刮削简明教程

本文主要内容

系统环境

• Ubuntu 20-24 / Debian 11-13 命令行环境均可

部署项目

• docker + docker compose —— 容器环境
• nginx proxy manager + docker network —— 反代 + 隐藏端口（可选）
• komga —— 主项目
• bangumikomga —— 刮削器
• conda + crontab —— 自动化刮削器（可选）

本文涉及的项目链接

• Komga服务端：gotson/komga: Media server for comics/mangas/BDs/magazines/eBooks with API and OPDS support (github.com)
• BangumiKomga刮削器：chu-shen/BangumiKomga: A Metadata Provider for Komga using Bangumi (github.com)
• Tachiyomi安卓客户端：Home | Tachiyomi（被傻逼棒子版权炮干死了）
• Tachiyomi的Komga插件：Extensions | Tachiyomi（被傻逼棒子版权炮干死了）
• Mihon安卓客户端：https://github.com/mihonapp/mihon （Tachiyomi后继者）
• Mihon的Komga插件：通过在Mihon里添加keiyoushi插件库下载

更新日志

2024/01

• Initial release

2025/06

• 一些细枝末节的修正
• 更新推荐使用的安卓客户端Mihon
• 更新bangumikomga配置，使用crontab定时于服务器自动进行刮削

2025/07

• crontab命令修正，防止bangumikomga输出过长终止crontab运行

2025/10

• 又一些细枝末节的修正
• docker&docker compose&nginx proxy manager相关配置不再引用旧博文，一篇文章不跳转搞定部署
• 删除旧版docker-compose的相关内容

Step1 – Docker & Docker compose安装

首先我们还是得把docker跟docker compose给装好，这是一切的基础。

• 使用docker官方提供的脚本安装

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh ./get-docker.sh

安装完后分别输入docker version和docker compose version，有版本号出来就是装好喽~

Step2 – NPM反代部署配置（可选）

NPM反代是为了给自己的Komga绑定上公网可访问的域名，因为自己的是公网服务器，使用https能够确保安全性也能蹭到cf，如果没有事先准备好的域名，或者只是内网使用Komga可以跳过这两部分（NPM反代部署配置&使用Docker network）。

• 首先创建 network

docker network create nginx-proxy

• 接着使用nano创建docker compose配置文件

# 找个合适的地方创建，比如/home/nginx之类的
nano docker-compose.yml

# docker-compose.yml

services:
  nginx-proxy-manager:
    #extra_hosts:
    #  - host.docker.internal:host-gateway
    image: 'jc21/nginx-proxy-manager:latest'
    ipc: host
    restart: unless-stopped
    ports:
      # These ports are in format <host-port>:<container-port>
      - '80:80' # Public HTTP Port
      - '443:443' # Public HTTPS Port
      - '81:81' # Admin Web Port
      # Add any other Stream port you want to expose
      # - '21:21' # FTP
    environment:
      DB_SQLITE_FILE: "/data/database.sqlite"
      # Uncomment this if IPv6 is not enabled on your host
      # DISABLE_IPV6: 'true'
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

networks:
  default:
    external: true
    name: nginx-proxy

• 启动NPM容器

docker compose up -d

这个时候我们访问小鸡ip:81，应该可以进到NPM的后台管理登陆页面，默认的账户密码如下：

• admin@example.com
• changeme

然后我们进去改成自己的用户名邮箱密码之后，就可以创建一个给NPM用的Proxy Host，填好域名，转发主机名/IP跟端口（这里是81）之后，再去Cloudflare设置（二级）域名解析到小鸡的ip，然后在对应的Proxy host内申请SSL证书，申请完毕之后就可以用https域名访问NPM后台了。

Step2.1 – 使用Docker network（可选）

细心的同学大概会发现我们在一开始创建的nginx-proxy根本没用上，创建这东西是为了避免容器端口直接暴露在公网，增强安全性，下面以NPM本身来讲一下这玩意怎么用。

• 首先看一下NPM的docker-compose.yml的最底下这几行

networks:
  default:
    external: true
    name: nginx-proxy

我们只要在docker-compose.yml里加上这段就可以把对应的容器加进nginx-proxy这个网络，我们在刚刚安装的时候就已经写好了，于是接下来这么操作。

docker ps -a

首先用以上命令获得NPM容器的容器名字，一般显示在最后NAMES一列，会显示类似npm-nginx-proxy-manager-1这样的名字，把他复制下来。

然后我们进去NPM的Web后台，编辑刚刚给NPM写的那条Proxy Host，将Forward Hostname改成刚刚复制的容器名后保存。

然后我们Shift+F5强制刷新一下页面，看看Web后台可不可以正常使用域名访问，没问题的话继续下一步。

• 还是NPM的docker-compose.yml，但是删掉一点东西

# docker-compose.yml

services:
  nginx-proxy-manager:
    #extra_hosts:
    #  - host.docker.internal:host-gateway
    image: 'jc21/nginx-proxy-manager:latest'
    ipc: host
    restart: unless-stopped
    ports:
      # These ports are in format <host-port>:<container-port>
      - '80:80' # Public HTTP Port
      - '443:443' # Public HTTPS Port
      # - '81:81' # Admin Web Port 注释掉这一行
      # Add any other Stream port you want to expose
      # - '21:21' # FTP
    environment:
      DB_SQLITE_FILE: "/data/database.sqlite"
      # Uncomment this if IPv6 is not enabled on your host
      # DISABLE_IPV6: 'true'
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

networks:
  default:
    external: true
    name: nginx-proxy

将容器暴露81端口这行注释掉，保存。

• 更新容器

docker compose up -d

然后我们再Shift+F5刷新一下Web后台可不可以正常使用域名访问，如果能正常访问，那么之后Komga的容器我们也按这个流程操作，这个时候你输入小鸡ip:81你会发现已经不能访问NPM的Web后台了，只能通过域名访问，这个就算是我们想达到的效果，这种方法对大部分使用docker compose部署的容器都通用。

Step3 – Komga部署配置

• 当上面的基础环境配置好了之后，我们开写Komga的docker-compose.yml

services:
  komga:
    image: gotson/komga
    container_name: komga
    volumes:
      - type: bind
        #下方需要修改，例：/home/komga/config
        source: /path/to/config
        target: /config
      - type: bind
        #下方需要修改，这个是你的漫画文件保存路径，例：/home/transmission/downloads/manga
        source: /path/to/data
        target: /data
      - type: bind
        source: /etc/timezone #alternatively you can use a TZ environment variable, like TZ=Europe/London
        target: /etc/timezone
        read_only: true
    ports:
      - 25600:25600 #新版端口改成了25600，没什么影响
    user: "1000:1000"
    # remove the whole environment section if you don't need it
    # 下面两行额外的环境变量行，用不着，直接删除或者注释掉
    # environment:
    #   - <ENV_VAR>=<extra configuration> 
    restart: unless-stopped

# 添加之前创建的网络（如果你没配上面的反代那就不加下面这段）
networks:
  default:
    external: true
    name: nginx-proxy

• 启动容器

docker compose up -d

• 如果你没打算配域名，那么现在已经可以使用http://IP:25600来访问你的Komga了
• 如果你打算配域名，那么请在NPM里面配置好Nginx反代，参照刚刚部署配置NPM的流程来注释掉docker-compose.yml里的25600端口，更新容器，至此Komga部署和配置完成，下面我们来讲讲刮削器怎么用。

Step4 – BangumiKomga部署配置

2025/10补丁：BangumiKomga项目随着项目功能增加会时不时做出一点breaking change，使得从下面开始的内容并不能随时100%对应到最新项目的运行。这意味着后面的部分你只能作为参考而不能无脑复制粘贴运行。因为作者对于这种项目是部署好了没问题就不会去更新的那一种人。下面是对于一些breaking change的举例，比如config文件放进了config文件夹里使用config.py，比如将入口文件从refreshMetadata.py换回了main.py，比如refreshMetadata.log文件甚至logs文件夹并不会在项目首次运行时自动创建，比如config.py里新增的变量不会给default值等等，这些都会需要你根据报错logs参照项目主页readme灵活应对，实在搞不定再在评论区问，看到了都会回。

在整理漫画库存的时候，偶尔在站内发现有人提起这个问题，本来嘛，只是看漫画而已，刮削信息什么的如果纯手动的话确实有点嫌时间太多了，但是如果有这个脚本的话，跑一下就能刮到八九不离十的信息就比较值得去用了，毕竟信息刮好的漫画封面墙真的很好看。

在项目readme里面的快速开始我觉得写得不够快速，主要是config.py的指引读起来有点费劲，直接上实例config来说明，也当作自己做笔记方便后面换设备了再起来一遍。（2025.06补丁：现在的项目readme写的很清楚了，看官方的readme也能够比较轻松的配起来了）

漫画命名建议

首先，请确保你漫画库里的资源命名遵照这里提到的格式，也就是[漫画名称][作者][出版社][卷数][其他1][其他2]的格式，不然在匹配时可能会出现差错，这是使用该脚本的前提。

第一次运行

• 环境配置没什么好说的，请参照项目的readme来配置好，Komga版本尽量保持最新，这里用的是1.10.0，这个版本加入了对RAR5压缩包的支持，喜大普奔
• 然后我们来填config.py，文件在config文件夹下面，请复制一份config.template.py改名改成config.py，然后按照下面的提示填写

# get access token from: https://next.bgm.tv/demo/access-token

BANGUMI_ACCESS_TOKEN = '去上面的地址登入创建，查询r-18刊物的时候才需要用到'
KOMGA_BASE_URL = "服务器地址，注意不要带后面的斜杠"
KOMGA_EMAIL = "Komga登入邮箱"
KOMGA_EMAIL_PASSWORD = "Komga登入密码"
FORCE_REFRESH_LIST = []
KOMGA_LIBRARY_LIST = ['填入整个库的id',]
KOMGA_COLLECTION_LIST = []

# 按需改True，第一次润的时候全部保持False即可
RECHECK_FAILED_SERIES = False
RECHECK_FAILED_BOOKS = False

# 创建刮削失败收藏，大概用不着
CREATE_FAILED_COLLECTION = False

# ……后面的可以无视

• 填好之后就可以润refreshMetadata.py了，然后转到生成的refreshMetadata.log观察是否正常运行，如果一切正常，运行完成之后Komga库里所有的信息都会刮削好。

修正错误元数据/匹配失败的书籍

这里使用的是项目里面提到的cbl功能，也就是手动指定bgm.tv的链接来让脚本来爬取信息。

• 首先在匹配错误/没匹配到的书籍系列中，编辑新增一个链接

• 然后我们来修改config.py

# ……前面的保持不变

FORCE_REFRESH_LIST = ['填入刚刚这本失败书籍/系列在Komga里的id', '如果有多本，那就继续填写',]
KOMGA_LIBRARY_LIST = ['填入整个库的id',]
KOMGA_COLLECTION_LIST = []

# 改True（2025.06更新：项目官方说这里不改True也行，自行测试）
RECHECK_FAILED_SERIES = True
RECHECK_FAILED_BOOKS = False

# ……后面的可以无视

• 填好之后就可以润refreshMetadata.py了，这个时候脚本就会按照你手动填写的bgm链接来重新匹配信息。

以上是这个工具的基本配置和运行，感谢工具作者写了个这么方便的强迫症友好工具，接下来让我们把刮削好的库丢去晒吧（不是），祝大家漫画阅读愉快！

Step5 – 定时自动运行刮削器（可选）

原理很简单，就是在服务器上配好crontab定时任务让bangumikomga在指定时候自动运行刮削，配合全站rss + komga自动定期扫库，解放双手无人驾驶（？），具体步骤如下：

• 安装miniconda和cron还有bangumikomga的依赖
• 按照上述步骤配置好config.py
• 添加定时任务，搞定

安装miniconda请参照官方提供的步骤进行，根据自己的系统选择合适的脚本，别问我群晖怎么搞，它应该有自己的crontab。miniconda安装到最后的时候请选择默认进入conda的base环境，这样用起来会很方便，不用自己每次进ssh都conda activate base一遍。

crontab的安装很简单，直接apt install cron -y

bangumikomga的依赖和config.py照样参照项目readme来进行即可，但是前提是在conda的base环境内进行依赖库的安装，这意味着执行pip3 install -r install/requirements.txt前，你的ssh终端的开头应该显示着(base)，表示你目前在conda的base环境里。

然后就是这一节的核心，增加一个自动刮削的定时任务：

• 首先，crontab -e，第一次进入会问你选择哪个文本编辑器，用默认的nano就可以；
• 新增一行0 3 */1 * * cd /home/BangumiKomga && /root/miniconda3/bin/python3 /home/BangumiKomga/refreshMetadata.py > /dev/null

其中：

• 0 3 */1 * *意味着会在每天凌晨3点运行一次刮削脚本，根据自己的实际需求来调整
• cd /home/BangumiKomga表示进入你bangumikomga的项目本地储存位置，请根据自身实际修改
• /root/miniconda3/bin/python3是conda的base环境默认的python3位置，如果你的conda安装在别的地方，请找到对应的目录修改
• /home/BangumiKomga/refreshMetadata.py就是执行脚本，没什么好说的。
• > /dev/null不输出脚本执行状况，如果输出的话默认crontab给的日志字节数不足，会导致脚本提前终止运行

在crontab -e打开的文本编辑器里新增这一行，保存退出即可，定时任务就会被添加并执行。

测试运行可以通过在base环境执行cd /home/BangumiKomga && /root/miniconda3/bin/python3 /home/BangumiKomga/refreshMetadata.py验证，如果能正常刮削，那么定时任务也肯定能正常运行。cd /home/BangumiKomga不能漏掉，bangumikomga脚本里应该是写了根据当前目录寻找refreshMetadata.log文件的逻辑，如果找不到refreshMetadata.log，刮削就会失败报错。

Epilogue1 – 错误排除

• 评论区里有提到一个这个插件有机会出现拿不到[‘metadata’][‘links’]的报错，这个在我之前的部署里也出现过一次，那次的原因是因为我的komga版本过于古老，并没有[‘metadata’][‘links’]这个内容，更新komga版本就解决了，如果出现了一样或者类似的问题，大家可以尝试访问自己的komga地址（http:ip:port）后面加/api/v1/series这个api，然后看看里面的”metadata”里面有没有”links”项目，如果有的话应该是不会出现这个问题的，没有的话那就升级komga版本。

• Mihon里的信息不随Komga刮削完成之后刷新，这个是老毛病了，除了手动清除Mihon缓存之外似乎没有什么有效的解决方法。

Epilogue2 – 一些题外话/实用技巧

• 批量单独打包文件夹内的复数文件夹的bash/shell命令

如果你觉得这小标题很绕，没错我也觉得，不如直接看图

如果凑巧你也是从nyaa的mangaroo（该上传者失联已久，希望人没事）那边拿日语资源的话，你会发现他的资源都是以文件夹装001.avif、002.avif类似这种散装形式来上传的，也就意味着Komga不能直接识别。然后正常来讲我们会把一个系列好几卷的漫画全都下载到一个文件夹（这个文件夹按照BangumiKomga的命名规则来命名），于是我们剩下要做的只是将里面的分卷文件夹分别打包压缩就可以了，但是面对动则十几二十卷的漫画一卷一卷来明显很费劲，于是有了以下命令。

首先我们cd进这个系列漫画的文件夹，默认复数的卷数文件夹都已经按[漫画名][卷数]之类的形式命名（理论上有卷数就够了），然后我们只需要在bash里跑这一条命令：

for i in */; do zip -r "${i%/}.zip" "$i"; done

等待压缩完成，就可以去Komga里面扫描库导入了~

• AVIF vs JPEG

有空再唠嗑下AVIF这对比JPEG的35%的压缩率对文件保存和网络传输是多么的友好。

关于格式兼容性，因为AVIF/AV1都是谷歌的东西，所以安卓端的支持肯定是没有问题的。至于苹果，忘了ios/mac支不支持AVIF来着，之前看了官方的客户端好像是不支持的，但是服务端支持的话客户端是什么表现也不清楚，暂且认为苹果不支持吧。

以上面狐仙大人的这一页为例，如果在平板/电脑这种稍大的屏幕上看，因为AVIF那套的分辨率大概是JPG那套的三分之一，因此线条是没有JPG那套观感上锐利的，这个是分辨率或者说源的区别。然后JPG那套是供给蜀黍的源，阴影是上的网纹点，AVIF那套淡的阴影是用的灰度填充，其实在电子设备在观看的话灰度填充会比网纹点观感要好，不会因为设备缩放出现奇怪的纹，不过这个也是源的差距了，跟AVIF和JPEG的压缩率没什么关系，如果你是用的手机看漫画，这两页基本上没有观感上的差距。

假设这是一个公开的服务器，很明显，一卷250MB跟一卷20MB的大小，对服务器水管的压力会很不一样，这点在自用的时候看页面加载速度就能感觉出来，一页120kB跟一页1.3MB在服务器带宽不充裕的情况下可能就是10倍的加载速度的区别，对阅读体验会有显著影响。另外就是寸土寸金的服务器硬盘了，用AVIF无疑同一套漫画能省下三分之一的空间，这点对于运营来说值得考量。

• 一个作者已经完成了的课题，但是更新在这里会使本文过于繁杂，于是我决定只丢一个引子（2025/10）

已知/已测试在netbird组网的情况下，看漫画的加载体验远好于公网优化线路的nginx反代，你会有兴趣尝试把komga结合netbird组网 + nginx proxy manager更改配置 + 调整懂的都懂的软件的分流 + 路由配置吗？具体其实配置不算复杂，但是作者暂时懒得写，所以说这是一个引子~