使用 Docker 部署 Komga：搭建属于你自己的漫画/电子书服务器

一、Komga 应用是什么？

一款功能强大的漫画/杂志/电子书媒体服务器

基于 Java 生态开发，专为私有化部署个人数字书库设计。它原生支持 CBZ、CBR、PDF、EPUB 等主流漫画与电子书格式，可自动扫描本地文件库、智能识别丛书与分卷、抓取并管理元数据，提供网页端沉浸式阅读体验，同时支持多用户权限隔离、多端阅读进度同步、第三方阅读器接入。通过 Docker 一键部署后，可在 NAS、VPS、本地服务器上 7×24 小时运行。

项目地址：https://gitcode.com/gh_mirrors/ko/komga

官网：https://komga.org/zh/

功能特点：

• 全格式兼容覆盖：完美支持 CBZ、CBR、ZIP、RAR 等漫画压缩格式，同时兼容 PDF、EPUB 电子书与高清绘本，覆盖绝大多数本地数字读物资源

• 智能书库扫描整理：支持全量扫描、增量扫描、定时自动扫描，自动识别丛书、分卷、章节结构，智能归类整理零散文件，无需手动分层编辑

• 多端阅读进度同步：服务端统一存储阅读进度、书签、阅读状态与标注，电脑、平板、手机多设备无缝接续阅读，进度永久留存不丢失

• 完善的元数据体系：自动匹配书籍封面、作者、标签、简介、出版信息，支持手动批量编辑元数据、自定义分类与合集，打造规范化个人书库

• 适配第三方阅读器：完美适配 Mihon（原 Tachiyomi）、Yomu 等主流移动端阅读器，支持 OPDS 协议接入，拓展多端阅读场景

• 全文检索与资源治理：支持书名、作者、标签、简介全文检索；内置重复文件检测、无效资源识别能力，可一键清理冗余与破损文件

• 隐私安全私有化：所有资源与数据完全本地存储，无云端上传、无广告推送、无内容审核，数据与访问完全自主掌控

image-20260902092046618

新版用户界面：

界面更清爽，内容更聚焦

image-20260902095926540

支持的文件类型：

• Comic book archives: CBZ and CBR

• EPUB 格式的电子书

• PDF 文件

可先不安装，提供在线体验Demo： https://demo.komga.org

登录账号: demo@komga.org，密码: komga-demo

二、Komga 安装部署

采用 Java 开发的应用，我们可以在具有 Java 环境的系统中，直接从 https://github.com/gotson/komga/releases 页面下载包，然后直接运行 即可，当然更简单的方式是直接使用官方的 Docker 镜像通过容器方式进行安装。

2.1、创建本地文件夹目录

创建三级持久化目录，分别存储程序配置、书籍资源、缓存文件，避免容器重建后配置与数据丢失，执行以下命令：

 # 创建 Komga 专属目录结构  mkdir -p /opt/komga/{config,data}  # 进入工作目录  cd /opt/komga

2.2、Docker Compose 配置

推荐使用 Docker Compose 方式部署，便于后续配置修改、版本升级与运维管理。在当前目录新建 docker-compose.yml 文件，写入以下配置：

 version: "3.8"  services:   komga:     image: gotson/komga:latest     container_name: komga     restart: unless-stopped     ports:       - "25600:25600"     volumes:       - ./config:/config # 存放配置文件       - ./data:/data # 存放漫画

参数说明：

• image：指定 Komga 官方开源镜像，latest 标签为最新稳定版本，持续迭代功能与修复问题，稳定性与兼容性最优

• container_name：自定义容器名称，简化后续容器启停、日志查看、重启等运维操作，避免容器重名冲突

• restart: unless-stopped：容器重启策略，除手动停止外，容器异常退出、服务器重启时均会自动拉起服务，保障 7×24 小时稳定运行

• ports：端口映射，格式为 宿主机端口:容器内部端口，Komga 默认服务端口为 25600，可根据需求修改宿主机端口

• volumes：定义了数据卷，用于数据和配置的持久化

  "./data:/data" 和 "./config:/config"：类似于CLI方法，映射data和config目录

• TZ=Asia/Shanghai：设置容器时区为东八区，保证日志时间、阅读记录时间与本地时间一致

配置完成后，执行以下命令后台启动服务：

 docker-compose up -d

2.3、Docker 命令安装方式

单命令快速部署方案，无需编写配置文件，适合快速体验、临时部署场景，一键完成镜像拉取与容器启动：

 docker run -d  --name komga  -v $(pwd)/data:/data  -v $(pwd)/config:/config  -p 25600:25600  -e TZ=Asia/Shanghai  --restart always  gotson/komga

参数说明：

• -d：以后台模式运行容器

• --name komga：设置容器的名称为komga

• -v $(pwd)/data:/data 和 -v $(pwd)/config:/config：将主机的当前目录下的data和config目录分别映射到容器的/data和/config路径，用于数据和配置的持久化

• -p 25600:25600：将容器的25600端口映射到主机的25600端口，使得Komga的Web界面可以通过主机的端口访问

• -e TZ=Asia/Shanghai：设置容器的环境变量TZ，用于指定时区

• --restart always：确保容器在退出时自动重启

• gotson/komga：指定使用的Docker镜像

默认访问地址：http://服务器IP:25600

三、使用教程

3.1 初始化

无默认账号密码，首次启动需创建管理员账号：

image-20260902094621980

1. 容器启动后等待 10~30 秒初始化完成，浏览器访问 http://服务器IP:25600 进入欢迎页面

2. 根据页面提示输入管理员账号、邮箱与密码，点击创建账号

3. 设置界面语言，默认英文，可修改为中文

4. 账号创建完成后自动跳转登录界面，输入账号密码即可进入系统主页

安全提示：公网部署时，建议使用高强度密码，并避免使用 admin 等常见用户名，降低暴力破解风险

3.2 首次配置与书库添加

1、添加书库：登录后点击右上角「设置」-「书库」，点击「添加书库」，填写书库名称，路径选择 /data，选择内容类型（漫画/电子书），配置扫描规则；

image-20260902090517827

可设置多个库用于存储数据：可以在宿主机目录的目录下面创建一个子目录用来保存我们添加的库的元数据

设置扫描器的扫描间隔等配置

image-20260902090909348

默认把第一张图片作为封面，可修改

2、扫描资源：保存书库后点击「扫描」，程序开始自动扫描目录下的书籍文件，识别丛书、分卷与元数据；扫描时长取决于文件数量与服务器性能，扫描完成后即可在书库中查看。

设置规则后会自动扫描，也可以手动扫描库，右键库名称，点击扫描库文件

image-20260902091341216

3.3、查阅漫画

鼠标放到漫画封面，会出现阅读按钮，点击阅读按钮

image-20260902095620510

image-20260902095733371

可下载到本地

image-20260902095820309

3.4、 基础操作

• 浏览与搜索：首页可查看最近阅读与新增书籍，顶部搜索框支持书名、作者、标签全文检索；左侧导航栏可按书库、分类、作者筛选资源

• 阅读操作：点击书籍封面进入详情页，选择章节即可开始阅读；阅读器支持键盘左右键翻页、滚轮缩放，移动端支持触控滑动翻页，可在设置中切换阅读方向与显示模式。

• 元数据管理：在书籍详情页点击「编辑」，可修改封面、书名、作者、标签、简介等信息，支持批量编辑，规范书库元数据。

• 用户管理：管理员可在设置-用户页面创建普通用户，分配对应书库的访问权限，实现多用户隔离使用。

3.4 第三方客户端接入

Komga 支持 OPDS 协议，可对接 Mihon 等移动端阅读器

1. 在 Mihon 中选择「添加来源」-「OPDS」

2. 填写 Komga 服务地址 http://服务器IP:25600/opds/v1.0，输入账号密码

3. 连接成功后即可在移动端直接浏览、阅读书库资源，进度自动同步

四、Komga 使用技巧

4.1 书库管理优化

• 规范目录结构：在数据目录下按照「丛书名称/卷册文件」的二级结构存放资源，可大幅提升自动识别准确率，减少手动修正元数据的工作量

• 增量扫描替代全量扫描：新增书籍后使用「增量扫描」，仅扫描新增与修改的文件，大幅降低服务器性能消耗，海量书库也能快速更新

• 定期清理冗余资源：利用系统内置的重复文件检测、损坏文件扫描功能，定期清理无效与重复资源，释放存储空间，提升书库整洁度

• 标签化分类管理：为书籍添加题材、作者、阅读状态等标签，结合全文检索功能，可在海量书库中秒级定位目标资源

4.2 阅读体验

• 针对性设置阅读模式：日漫开启「从右至左」阅读模式，条漫开启「连续滚动」模式，文字类电子书使用「单页适配」，针对不同类型读物单独配置偏好

• 开启页面预加载：在阅读器设置中开启后台预加载，提前渲染下一页内容，实现翻页零卡顿，提升沉浸式阅读体验

4.3 运维与稳定性技巧

• 一键版本更新：Compose 部署方式下，进入部署目录执行 docker-compose pull && docker-compose up -d，即可一键拉取最新镜像并重启服务，所有配置与数据自动保留

• 日志故障排查：服务异常时执行 docker logs komga 查看运行日志，可快速定位启动失败、扫描报错、访问异常等问题

• 端口冲突处理：若 25600 端口被占用，直接修改部署配置中的宿主机端口（如 25601:25600），重启容器即可生效，无需修改程序内部配置

• 定期数据备份：定期备份 config 目录下的数据库文件，避免系统故障导致用户数据、阅读进度与元数据丢失

• 自动化书库同步：配合脚本实现下载目录自动同步到 Komga 书库，结合定时扫描，实现新资源自动入库

• API 自动化运维：Komga 提供 REST API，可对接自动化脚本，实现批量元数据编辑、书库监控、用户管理等自动化操作

作者声明本文无利益相关，欢迎值友理性交流，和谐讨论～