用 Komga 整理自己的漫画与电子书：Docker 部署、书库扫描和阅读进度

漫画和电子书放在网盘里，最常见的问题是能下载，却不方便接着读。手机上的进度留在某个阅读器里，电脑上的文件又按另一套目录排列。Komga 可以为自己有权使用的书籍建立书库，提供浏览器阅读和账号，让目录、封面与阅读记录有一个固定入口。

部署前先整理文件，而不是把整块磁盘交给扫描器。挑一个系列和几本样书，确认格式、目录、排序及文件是否完整，再扩大范围。不同文件的版式和元数据质量会影响阅读体验，不能因为软件支持某种格式，就默认所有同扩展名文件都能正确展示。

部署前先确认 VPS 的磁盘、内存和公网访问条件，也可以查看雨云云服务器；注册时填写优惠码 KuZhuJi。

书籍文件和应用数据库要分开保存

Komga 的 /config 包含应用配置和数据库，官方要求使用本地文件系统，不能放在 CIFS 或 NFS 网络共享上。/data 则是书籍所在目录。删除容器不会自动删除已经挂载的文件，但删除持久目录会造成实际损失。

阅读器负责访问书库，书籍原文件和应用记录各自需要保留。只复制书籍，可以找回内容，却未必能恢复用户和阅读进度；只备份配置，也不能凭空找回原文件。

先查看 VPS 的磁盘容量和可用空间。扫描、封面处理与首次导入会使用资源，存放资料的服务器也需要做异地副本。VPS 的可访问性不等于数据已经有备份，原书应另外保留。

Docker 从小书库开始

下面使用官方普通镜像，运行用户设置为 1000:1000。目录权限按实际 UID/GID 调整，配置目录需要可写；书籍目录在这个基础方案中只读挂载，适合只扫描和阅读，不在应用里处理导入写入或修改原文件。

mkdir -p ~/services/komga/config ~/services/komga/books
cd ~/services/komga
sudo chown -R 1000:1000 config books

保存 compose.yaml：

services:
  komga:
    image: gotson/komga:latest
    user: "1000:1000"
    environment:
      TZ: Asia/Shanghai
    ports:
      - "127.0.0.1:25600:25600"
    volumes:
      - ./config:/config
      - ./books:/data:ro
    restart: unless-stopped

Komga 官方镜像说明中的 latest 跟随最新提交，不能将它说成固定稳定版本。这里用于初次验证，正式保存长期书库前应从发行版本中选定并固定已核对的标签或镜像摘要。更新前保留旧版本和配置副本。

docker compose config --quiet
docker compose up -d
docker compose logs --tail=100 komga

将少量样书放进宿主机 books 下，先按系列分目录。启动后不要立刻移动几千份文件，先验证这个小目录在容器里对应 /data，扫描器能读取它。

私人访问先用 SSH 转发

ssh -L 15600:127.0.0.1:25600 user@your-server

本机打开 http://127.0.0.1:15600，按当前版本的首次启动界面创建管理账号。回环端口不会直接成为公网书库。需要域名访问时，再由 HTTPS 反向代理接到宿主机 25600，并验证登录、阅读和图片请求。

正式书库使用独立用户，管理员账号只负责维护。家人或同事使用时，为每人设置账号和可访问书库，不共享阅读进度。公开传播未经授权的作品并不是这个部署方案的用途，放入服务器的文件应来自自己有权保存和阅读的资料。

准备独立实例时，可在雨云选择适合的云服务器配置，优惠码 KuZhuJi。配置按实际任务选择，数据库和附件另做备份。

新建书库时填写容器路径

选择 /data 或它的子目录，例如 /data/comics。不要在网页里填写宿主机的 ~/services/komga/books，应用看到的是挂载后的路径。书库命名可以按资料种类或使用者划分，细到每本书一个书库通常不利于管理。

第一次扫描完成后，核对系列名、卷序、封面和页数。文件名中带有数字，不一定会按自己想象的顺序排列；先在一个系列上修正命名和元数据规则，再批量整理。扫描识别失败时查看日志和原文件，不要只反复点击扫描按钮。

如果希望应用执行导入或其他会写入书籍的操作，需要另行安排可写目录及权限。这篇采用只读书库，所以相关写入功能可能无法工作。确认自己确实需要这些功能后，再对指定目录开放写入，不把整个挂载统一改成完全可写。

阅读进度要在第二个设备上验证

用普通用户打开样书，翻到中间位置，退出阅读后刷新页面，再从另一台设备登录同一账号。检查是否能看到预期进度和已经读过的状态，别仅在同一个浏览器标签中观察。

再用另一个用户打开相同书籍，确认两人的记录没有混在一起。手机浏览器的阅读方向、分页和缩放与桌面可能不同，拿实际常读的文件试一次。长页漫画与普通分页书籍的体验不能用一张封面截图判断。

遇到页面加载很慢，分别检查原文件大小、扫描任务、服务器负载和网络传输。书籍在远端不代表一定比本地阅读快；慢请求也不一定是 CPU 不够，可能是带宽、磁盘或并发处理。没有对照数据时，不把一次等待改写成某个配置的性能结论。

需要增加服务器时，可以打开雨云选购页面，填写优惠码 KuZhuJi；迁移前保留数据与原有部署配置。

调整目录时留一份可以对照的清单

扫描后再批量改名或移动系列，可能影响识别及已有记录。先拿测试系列验证当前版本如何处理移动和重命名，再改正式目录。记下旧路径、新路径和操作时间，出了问题才知道扫描的是哪一份文件。

新增文件可以分批放入，检查几本后继续。对自己制作的 EPUB 或文档，保留生成源文件和原始版本；阅读服务里的文件并不替代编辑源文件。损坏的压缩包或缺页资料，应当先修复原件再重新扫描。

数据库目录空间也要观察。封面、分析结果和记录会占用空间，不能只按书籍文件的体积估算需求。升级和维护时留出额外磁盘余量，避免在磁盘满的状态下继续扫描或写入数据库。

恢复测试同时检查书籍和进度

应用暂停后备份配置，书籍按自己的数据备份方式另存。下面示例将小书库一起打包，适合首次演练，不意味着大型书库每次都应全量复制。

mkdir -p backups
docker compose stop komga
tar -czf "backups/komga-$(date +%F-%H%M%S).tar.gz" config books compose.yaml
docker compose start komga

把副本转移到服务器之外。恢复时使用独立目录、旧镜像和另一个回环端口，检查普通用户登录、系列排序、书籍能否阅读，以及刚才的阅读进度。没有恢复原书的测试只能证明一部分应用数据可读，不能当作完整恢复。

若换机器或升级后出现问题，先保留现场日志和数据，避免新旧实例同时写同一份 config。数据库迁移发生后，回退应使用升级前的配置和对应版本，不只是把容器镜像换回旧标签。