yuyu的官网

1.1 Komga 核心定义#

Komga 是一款开源、免费、轻量高性能的漫画 / 图像合集自托管服务器，基于 Java + SpringBoot 开发，主打海量资源适配、稳定扫描、精准元数据、细粒度权限，完全免费开源、无广告、无资源水印、无数量限制。

支持的资源格式覆盖全网主流漫画格式：

• 压缩包格式：zip、cbz、rar、cbr、7z、cb7

• 图片格式：jpg、png、webp、jpeg 整文件夹漫画

• 画册、同人本、单行本、连载合集、图集全部兼容

1.2 对比其他漫画工具的核心优势（万级库专属）#

市面上大部分漫画工具只适合几百本小库，一旦资源过千就会崩，而 Komga 的核心优势就是海量资源适配：

1. 数据库优化顶级：采用 H2 嵌入式数据库 + 增量扫描机制，3 万本漫画扫描仅需十余分钟，不会全量重扫

2. 智能增量更新：仅扫描新增、修改、删除资源，旧资源不重复解析，极大节省性能

3. 封面缓存机制完善：支持多级缓存、缩略图预生成，数万本书封面秒加载

4. 严格的资源识别逻辑：自动区分单行本、合集、短篇，极少出现归类错乱

5. 企业级多用户权限：支持创建多个用户，不同用户隔离不同漫画库，适合家庭、朋友共享

6. 完美适配 Tachiyomi：支持 API 对接，手机 APP 可直接在线阅读、同步阅读进度

1.3 适用场景#

• 个人海量漫画收藏本地永久存储、云端统一阅读

• NAS 私有漫画图书馆搭建，全家多人分开权限阅读

• 工作室、小团队漫画资源共享、分类管理

• 替代百度网盘、阿里云盘在线阅读，无压缩、无和谐、不限速

2.1 最低运行配置（仅测试、几百本小库）#

• CPU：单核 2.0G 以上（低功耗 ARM/Intel 均可）

• 内存：1GB 可用内存（低于 1GB 必然启动失败、扫描闪退）

• 存储：任意硬盘，要求读写速度 ≥ 50MB/s

• 系统：Linux、Windows、MacOS、NAS 全系支持

避坑提醒：不要用老旧超低配单盘 NAS、OpenWrt 小路由部署，内存太小，扫描大压缩包直接 OOM 崩溃。

2.2 万本漫画库推荐配置（1000-10000 本）#

• CPU：双核 2.5G 以上，推荐 Intel 低功耗 CPU（解码、扫描速度远超 ARM）

• 内存：2GB 以上可用内存（核心！扫描解析压缩包极度吃内存）

• 存储：机械硬盘 RAID / SATA 硬盘，读写 100MB/s 以上

• 运行环境：Docker 部署（稳定性吊打原生部署）

2.3 数万本漫画库顶配配置（1 万 - 5 万本，我的自用配置）#

• CPU：4 核 4 线程及以上 Intel CPU

• 内存：4GB 及以上（可完全杜绝内存溢出、扫描卡顿）

• 存储：漫画资源存机械盘，Docker 缓存 / 数据库挂载 SSD

• 系统：Debian / Ubuntu / 群晖 DSM / 威联通 QTS

2.4 系统环境要求#

1. 优先 Docker 环境部署，跨平台、隔离性强、升级简单

2. 系统时区必须为 Asia/Shanghai，否则漫画时间、排序错乱

3. 磁盘挂载权限必须为 可读写，禁止只读挂载（无法写入数据库和缓存）

3.1 方式一：Docker CLI 快速部署（极简入门）#

适合只想快速跑通服务、不需要频繁改配置的用户，一条命令直接部署。

1
docker run -d \
2
  --name komga \
3
  --restart always \
4
  -e TZ=Asia/Shanghai \
5
  -e KOMGA_SERVER_PORT=25600 \
6
  -p 25600:25600 \
7
  -v /opt/komga/config:/config \
8
  -v /opt/komga/library:/library \
9
  gotson/komga

3.2 方式二：Docker Compose 部署（主力推荐，生产环境首选）#

这是我自用、全网大佬通用的部署方式，支持自定义参数、内存限制、日志配置、一键升级、一键备份，适合长期使用。

1
version: "3.8"
2

3
services:
4
  komga:
5
    image: https://list.yppp.net/d/image/2026-03-22-5d60eeacf9c6c26f446d3fd3f3942c23.jpg
6
    container_name: komga
7
    restart: always
8
    environment:
9
      TZ: Asia/Shanghai
10
      # JVM内存限制，根据你的设备调整，杜绝内存溢出
11
      JAVA_TOOL_OPTIONS: "-Xms512m -Xmx2048m"
12
      # 开启增量扫描、关闭无用日志
13
      KOMGA_LIBRARY_SCAN_STARTUP: false
14
      KOMGA_LOGGING_LEVEL_ROOT: WARN
15
    ports:
16
      - "25600:25600"
17
    volumes:
18
      # 配置&数据库持久化
19
      - ./config:/config
20
      # 漫画资源库挂载（修改为你自己的漫画绝对路径）
21
      - ./library:/library
22
    # 最大文件打开数，解决海量文件扫描报错
23
    ulimits:
24
      nofile:
25
        soft: 65535
26
        hard: 65535

1
# 后台启动
2
docker-compose up -d
3

4
# 查看运行日志，排查报错
5
docker-compose logs -f komga

3.3 方式三：NAS 专属部署（群晖 / 威联通）#

4.1 管理员账号创建#

1. 首次打开会强制注册超级管理员账号

2. 用户名自定义，密码设置高强度密码

3. 务必记住管理员账号，拥有所有库的最高权限

4.2 核心基础设置（必改）#

进入后台 设置(Settings)，修改以下关键参数：

1. Language：切换为 简体中文

2. 时区确认：Asia/Shanghai

3. 关闭自动全局扫描：防止设备空闲被占用性能

4. 开启封面缓存：全局开启缩略图缓存

4.3 新建漫画资料库#

1. 侧边栏点击「资料库」-「新建资料库」

2. 资料库路径填写容器内挂载路径 /library

3. 资料库类型选择 漫画 / 合集

4. 取消勾选「启动时扫描」（万级库核心优化）

5. 保存完成

5.1 官方最优文件夹结构（适配万级库）#

遵循 作者 / 漫画名 / 单行本文件 层级结构，百分百识别成功：

Plain Text /library ├─ 岸本齐史 │ ├─ 火影忍者 │ │ ├─ 火影忍者_第01-10卷.cbz │ │ └─ 火影忍者_短篇集.zip ├─ 尾田荣一郎 │ └─ 海贼王 └─ 同人合集

5.2 绝对禁止的错误结构#

1. 文件夹嵌套过深（超过 4 层会扫描超时）

2. 文件名带特殊乱码、表情、特殊符号

3. 压缩包嵌套压缩包（无法解析封面和内容）

4. 中英文混杂无规律命名

5.3 海量库专属扫描策略#

针对数万本漫画，不要直接全局扫描，采用分步扫描法：

1. 新增资源后，仅扫描新增文件夹（右键文件夹 - 扫描）

2. 每周一次全局增量扫描，不重复解析旧数据

3. 夜间空闲时段执行全库扫描，避开使用高峰

5.4 元数据刮削优化#

Komga 支持自动刮削漫画元数据（作者、简介、章节、发布时间）：

1. 进入资料库设置，开启「自动元数据匹配」

2. 优先匹配本地文件名，其次联网刮削

3. 对于小众无网络元数据的漫画，可手动编辑标签、作者、评分

6.1 JVM 内存精准分配#

根据设备内存对应修改 docker-compose.yml 的 JAVA 参数：

• 2G 内存设备：-Xms512m -Xmx1024m

• 4G 内存设备：-Xms1024m -Xmx2048m

• 8G + 内存设备：-Xms2048m -Xmx4096m

参数解释：Xms 是初始内存，Xmx 是最大内存，限制过高会浪费资源，过低会崩溃。

6.2 封面缓存优化（秒开封面核心）#

1. 设置中开启「预生成所有缩略图」

2. 缓存目录挂载 SSD，机械盘缓存封面会严重卡顿

3. 关闭高清原图预览，日常阅读使用缩略图缓存

6.3 数据库优化#

1. 定期在后台执行「数据库优化」，清理冗余缓存

2. 每月备份一次 /config 目录，防止数据库损坏

3. 禁止频繁全库重扫，优先增量扫描

6.4 后台进程优化#

1. 关闭实时监控扫描，改为手动触发

2. 限制后台解析线程数，避免 CPU 占满

3. 闲置时自动休眠扫描进程

7.1 创建普通用户#

1. 后台设置 - 用户 - 新建用户

2. 设置用户名、密码

3. 关闭管理员权限

7.2 资料库权限单独分配#

1. 进入对应漫画资料库设置

2. 权限管理中，勾选可访问的普通用户

3. 未勾选用户完全看不到该资料库

7.3 权限细分功能#

• 可单独开启 / 关闭：下载权限、编辑元数据权限、删除资源权限

• 可限制用户仅阅读，无法修改任何资源

• 支持多人同时在线阅读，互不冲突

8.1 前置条件#

1. 拥有域名 + 域名 SSL 证书

2. 服务器 / NAS 可公网访问（端口转发 / 公网 IP/DDNS）

8.2 Nginx 反向代理核心配置#

1
server {
2
    listen 443 ssl;
3
    server_name 你的域名;
4

5
    ssl_certificate /ssl/fullchain.pem;
6
    ssl_certificate_key /ssl/privkey.pem;
7

8
    # 核心反向代理
9
    location / {
10
        proxy_pass http://127.0.0.1:25600;
11
        proxy_set_header Host $host;
12
        proxy_set_header X-Real-IP $remote_addr;
13
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
14
        proxy_set_header X-Forwarded-Proto $scheme;
15
        # 长连接支持，解决阅读中断连
16
        proxy_http_version 1.1;
17
        proxy_set_header Upgrade $http_upgrade;
18
        proxy_set_header Connection "upgrade";
19
    }
20
}

8.3 外网访问最终效果#

1. 输入域名即可 HTTPS 加密访问

2. 支持 Tachiyomi 外网同步阅读进度

3. 无广告、不限速、无压缩，原版画质阅读

9.1 问题 1：大批量扫描缓慢、卡死#

原因：默认线程过高、文件数限制不足、机械盘缓存 解决：修改 ulimits 文件数、关闭开机全扫、分步增量扫描、缓存迁移 SSD

9.2 问题 2：启动报错内存溢出 OOM#

原因：JVM 最大内存设置过低 解决：根据设备内存调高 Xmx 参数，2G 以下设备不建议万级库

9.3 问题 3：封面空白、不显示#

原因：文件夹嵌套太深、压缩包损坏、挂载只读 解决：规范目录结构、重新解压损坏文件、开启文件夹读写权限

9.4 问题 4：外网无法登录、API 失效#

原因：端口映射错误、反向代理缺少升级头 解决：严格使用上方 Nginx 配置，禁止自定义容器端口

9.5 问题 5：漫画排序混乱、时间错乱#

原因：系统时区错误 解决：强制设置 Asia/Shanghai 时区，重启容器

9.6 问题 6：新增资源扫描不到#

原因：文件夹权限不足、特殊字符文件名 解决：统一重命名文件、授予目录 775 读写权限

10.1 教程总结#

看完本篇教程，你已经搭建完成企业级稳定的数万本漫画私有服务器，对比网盘、第三方阅读软件，拥有绝对优势：永久存储、无和谐、不限速、高清原图、多用户共享、进度同步、完全私有化。

本教程覆盖从硬件选型、三种部署、初始化配置、资源规范、性能调优、权限管理、外网访问、排错避坑全流程，是目前全网最完整的 Komga 实战指南。

10.2 进阶拓展玩法#

1. 对接 Tachiyomi 手机 APP，实现移动端无缝阅读

2. 配置自动备份脚本，定时备份数据库和配置

3. 搭配 Cloudflare 实现外网高速访问、隐藏真实 IP

4. 搭建多库分类，实现漫画、画集、小说多资源统一管理

5. 配置自动元数据刮削插件，全自动整理漫画信息

（注：部分内容可能由 AI 生成）