🚀 使用 Docker Compose 部署 Komga 漫画服务器

🚀 使用 Docker Compose 部署 Komga 漫画服务器

Komga 是一款免费且开源的漫画和电子书媒体服务器，可以帮助你集中管理本地漫画资源，并通过网页浏览器或移动端应用随时随地阅读。

📖 项目简介

Komga 是一个自托管的漫画媒体服务器，主要特点包括：

• 广泛的格式支持：完美支持常见的漫画存档格式 CBZ、CBR，以及 PDF 和 EPUB 格式的电子书。
• 跨平台体验：提供响应式的 Web 界面，你可以在桌面电脑、平板或手机浏览器中直接阅读，自动同步阅读进度。
• 强大的媒体库管理：自动扫描并整理你的漫画文件夹，允许你编辑元数据、创建阅读列表和收藏。
• 多用户支持：可以管理多个用户，并为不同用户设置图书馆访问权限、年龄限制等。
• 支持 OPDS 协议：允许你使用兼容的第三方阅读器（如安卓端的 Tachiyomi 和 iOS 端的 Paperback）来访问 Komga 书库。
• 与阅读器同步：支持与 Kobo 电子书阅读器同步。

简单来说，Komga 就像是漫画界的 "Plex" 或 "Jellyfin"，为你搭建一个私有的、功能丰富的漫画云书架。

⚙️ 部署前准备

1. 环境要求

   • 确保你的系统（可以是个人电脑、服务器或 NAS）已安装 Docker 和 Docker Compose。
   • 为 Komga 的数据和配置准备足够的存储空间。

2. 创建目录结构 建议创建一个独立的工作目录，例如 komga，以便管理所有相关文件。在此目录下，你至少需要准备两个子目录：

   • config: 用于持久化保存 Komga 的应用配置、数据库等信息。
   • 一个或多个用于存放漫画资源的目录，例如示例中的 /mnt/10t/file/komga。请根据你的实际情况创建或指定相应目录。

🔧 配置 Docker Compose

在你创建的工作目录（例如 komga）下，创建一个名为 docker-compose.yml 的文件，并写入以下内容。你可以根据注释和自身需求进行调整。

version: '3.3'
services:
  komga:
    image: gotson/komga
    container_name: komga
    volumes:
      - ./config:/config  # 持久化配置目录
      - /mnt/10t/file/komga:/data  # 映射你的漫画目录，请确保此路径存在且包含你的漫画
    ports:
      - 25600:25600  # 主机端口:容器端口，可按需修改主机端口
    user: "0:0" # 使用 root 用户运行，避免权限问题。若需使用其他用户，可对应修改 PUID 和 PGID
    environment:
      - PUID=1000  # 可选：指定运行容器的用户ID，与`user`字段冲突，建议二选一
      - PGID=1000  # 可选：指定运行容器的组ID
      - TZ=Asia/Shanghai  # 设置容器时区，非常重要！
    restart: unless-stopped

关键配置说明：

• volumes (卷映射):
  • ./config:/config: 将容器内的配置目录映射到宿主机，必须配置以确保 Komga 的设置、数据库等在容器重启后不会丢失。
  • /mnt/10t/file/komga:/data: 将你存放漫画的宿主目录映射到容器内的 /data。Komga 会扫描此目录下的漫画文件。
• ports (端口映射):
  • 25600:25600: 将容器的 25600 端口映射到宿主机的 25600 端口。如果宿主机该端口已被占用，可将冒号前的 25600 修改为其他端口，例如 8080:25600。
• user 和 environment (用户和环境变量):
  • user: "0:0": 表示以 root 用户身份运行容器，有助于避免文件读写权限问题。
  • TZ=Asia/Shanghai: 设置正确的时区，对于文件时间戳等功能的准确性至关重要。

🚀 启动与验证

1. 启动 Komga 服务 在 docker-compose.yml 文件所在目录下，执行以下命令来启动服务： bash docker compose up -d 参数 -d 表示在后台运行。

2. 验证服务状态

   • 你可以使用 docker compose logs 命令查看启动日志，初步判断服务是否正常运行。
   • 使用浏览器访问 http://你的服务器IP:25600。
   • 如果看到 Komga 的初始化界面，要求你创建管理员账户，则表示服务已成功启动。

🛠️ 基础配置与使用

1. 初始化账户

   • 首次访问 Web 界面时，系统会引导你"认领"初始管理员账户。请按照提示设置邮箱和密码。
   • 注意：在 Komga 某些早期版本（如 v1.12.1 至 v1.12.x）中，初始管理员账户可能存在权限不完整的问题（例如缺少 Kobo Sync 角色）。建议部署时尽量使用最新版本的 Komga 镜像。若发现问题，可参考官方文档或社区建议，通过创建第二个管理员账户并为初始账户授权来解决。

2. 创建你的第一个漫画库

   • 登录后，点击侧边栏的 "Libraries"（图书馆）。
   • 点击 "ADD LIBRARY"（添加图书馆）。
   • 输入库的名称（例如 "我的漫画"）。
   • 在 "Root folder"（根文件夹）中，选择或输入 /data。这是因为在 Docker 容器内，你的漫画目录被映射到了 /data。
   • 其他设置（如扫描模式）可暂时保持默认，点击保存。Komga 会自动开始扫描 /data 目录下的所有漫画文件。

3. 开始阅读

   • 扫描完成后，漫画封面和信息会出现在首页。
   • 点击任意漫画即可在 Web 阅读器中开始阅读。Web 阅读器支持多种模式，例如在手机浏览器上可以尝试开启 "Webtoon 模式"以获得更好的滚动阅读体验。

4. 配置客户端应用

   • 安卓：推荐使用 Tachiyomi。安装后，在"浏览"页面添加 "Komga" 扩展，并配置服务器地址（http://你的服务器IP:25600）和登录凭证。
   • iOS：推荐使用 Paperback。同样需要添加 Komga 源并配置服务器信息。

🔄 维护与管理

1. 更新 Komga 当有新版本发布时，你可以通过以下步骤进行更新： bash # 进入 docker-compose.yml 所在目录 docker compose down # 停止当前容器 docker compose pull # 拉取最新的 Komga 镜像 docker compose up -d # 重新启动容器

2. 数据备份

   • 定期备份你所配置的 ./config 目录。这个目录包含了 Komga 所有的配置、用户数据和阅读进度。
   • 同样，确保你的漫画源文件（即映射到 /data 的目录）有可靠的备份。

3. 日志与监控

   • 如果需要排查问题，可以查看 Komga 的日志： bash docker compose logs komga
   • 在 Komga 的 Web 界面 "设置" -> "服务器管理" -> "作业" 中，可以监控扫描任务等后台进程的状态。

❓ 常见问题排查

1. 容器启动失败或无法访问

   • 检查端口冲突：确认宿主机的 25600 端口未被其他程序占用。
   • 检查目录权限：如果未使用 user: "0:0"，请确保 ./config 和漫画数据目录对容器运行的 PUID/PGID 指定的用户可读写。

2. Komga 扫描不到漫画

   • 检查路径映射：确保在创建图书馆时，"根文件夹" 设置为容器内的 /data。
   • 检查文件格式：确认你的文件是 Komga 支持的格式（如 .cbz, .cbr, .pdf 等）。
   • 注意压缩包内文件结构：对于 CBZ/CBR 文件，压缩包内图片文件最好不要嵌套多层文件夹，否则可能导致封面无法提取或阅读异常。建议解压后直接是一层图片文件。
   • 手动触发扫描：在图书馆设置中，点击 "SCAN LIBRARY FILES" 手动重新扫描。

3. 大容量漫画库扫描异常或服务不稳定 当你的漫画库容量非常大（例如达到 TB 级别）时，可能会遇到扫描中断或性能问题。

   • 优化目录结构：避免将所有漫画文件堆放在一个目录下。可以按作者、系列等建立子文件夹分类存放。
   • 排除非漫画文件：确保漫画库目录中不要混入大量非漫画文件（如音乐、文档等），这些文件可能会干扰扫描进程。
   • 分批扫描：可以尝试先建立一个小型图书馆进行扫描测试，稳定后再逐步添加其他目录。
   • 关注系统资源：Komga 在扫描和处理大量文件时可能会占用较多内存，请确保 Docker 容器有足够的内存分配。

4. Web 界面 Metrics 监控数据不更新 在某些旧版本（如 v1.11.2）中，可能存在 Web 界面监控数据不实时更新的问题。这通常是由前端请求了不存在的监控指标导致，建议升级到最新版本以获得修复。

希望这篇教程能帮助你顺利搭建属于自己的私人漫画库！如果在使用过程中遇到更具体的问题，可以查阅 Komga 官方文档或在社区寻求帮助。