一、介绍
1.1 Komga 是什么？
Komga 是一个自托管的在线书库，用于管理您的漫画、杂志和其他电子书等。
仅需几个简单的步骤，即可使用 Komga：
- 在计算机或者NAS上安装并运行 Komga。
- 按图书类型创建库，并拷贝图书到库中。
- 使用 Komga 本身提供的 web 界面或者任何第三方兼容的客户端访问。
- 开始阅读。
让我们预览一下软件web界面：
主页
库
系列
阅读
1.2 支持的媒体和设备有哪些？
Komga 支持以下文件类型
- 漫画书档案：CBZ 和 CBR（不支持固态档案，对于 RAR5 见下文）
- EPUB 格式的电子书
- PDF 文件
- ZIP 压缩包
RAR 5 仅在某些平台上受支持，因为它依赖于用于解码的本地库。
| Platform | RAR 5 |
|---|---|
| macOS 应用 | ✔️ |
| Windows 应用 | ✔️ |
| Docker amd64 | ✔️ |
| Docker arm64 | ✔️ |
| Docker arm | ❌ |
当使用 jar 时，您需要自行提供本地库，并使用正确的参数运行 Java。
Komga 服务器兼容性
Komga 可以在任何能够运行 Java 或 Docker 的系统上运行：
- Windows
- macOS
- Linux
- 许多流行的 NAS 设备，如 QNAP、Synology 等
1.3 官方演示网站
在部署前，您可能想了解一下软件功能和界面，那么您可以访问官方演示网站： https://demo.komga.org
您可以使用以下凭据登录：
- 登录名：demo@komga.org
- 密码：komga-demo
二、使用 Docker 部署
2.1 镜像仓库
Komga 的 Docker 镜像发布在以下平台：
- DockerHub
- ghcr.io
2.2 版本
Docker 镜像提供了可用的不同版本。
| 标签 | 描述 |
|---|---|
| latest | 最新的提交 |
| MAJOR.x | 最新的 MAJOR 版本，例如 0.x |
| x.y.z | 版本 x.y.z |
2.3 用法
以下是一些示例片段，帮助您开始。
2.3.1 原生 Docker 命令方式
创建容器
docker create \
--name=komga \
--user 1000:1000 \
-p 25600:25600 \
--mount type=bind,source=/path/to/config,target=/config \
--mount type=bind,source=/path/to/data,target=/data \
--restart unless-stopped \
gotson/komga
启动容器：
docker start komga
2.3.2 docker-compose 方式
---
version: '3.3'
services:
komga:
image: gotson/komga
container_name: komga
volumes:
- type: bind
source: /path/to/config
target: /config
- type: bind
source: /path/to/data
target: /data
- type: bind
source: /etc/timezone # 或者您可以使用 TZ 环境变量，例如 TZ=Europe/London
target: /etc/timezone
read_only: true
ports:
- 25600:25600
user: "1000:1000"
# 如果您不需要，可以删除整个环境变量部分
environment:
- <ENV_VAR>=<extra configuration>
restart: unless-stopped
2.4 参数
容器镜像通过运行时传递的参数进行配置。这些参数用冒号分隔，分别表示外部：内部。例如，-p 8080:80 将容器内部的 80 端口暴露为主机 IP 的 8080 端口。
| 参数 | 功能 |
|---|---|
-p 25600:25600 |
Komga API 和网页界面的端口 |
--user 1000:1000 |
用户：组标识符 - 见下文说明 |
--mount type=bind,source=/path/to/config,target=/config |
数据库和 Komga 配置 |
--mount type=bind,source=/path/to/data,target=/data |
磁盘上数据目录的位置。选择一个包含图书和硬链接所需导入位置的文件夹。 |
-e ENV_VAR=value |
任何配置环境变量 |
2.5 用户 / 组标识符
使用卷（-v 标志）时，主机操作系统和容器之间可能会出现权限问题，Komga 允许您指定用户 ID 和组 ID 来避免此问题。
确保主机上的任何卷目录都由您指定的相同用户拥有，这样权限问题就会神奇地消失。
在此实例中，UID=1000 和 GID=1000，要查找您的 UID 和 GID，可以使用 id <your_user>，如下所示：
$ id <your_user>
uid=1000(jdoe) gid=1000(jdgroup) groups=1000(jdgroup)
2.6 内存限制
默认情况下，Java 进程的最大内存（RAM）使用量通常被限制为 1GB。如果您在日志中遇到一些 OutOfMemoryException异常，您可能需要增加 Komga 可以使用的最大内存。
为此，您可以使用 JAVA_TOOL_OPTIONS=-Xmx<limit> 环境变量，其中 <limit> 可以是任意数量，例如 2048m、4g 等。例如，要以最大 4GB 内存运行 Komga：
JAVA_TOOL_OPTIONS=-Xmx4g
2.7 查询日志
在容器运行时访问 Shell：docker exec -it komga /bin/bash
实时监控容器日志：docker logs -f komga
2.8 更新
容器更新方法
2.8.1 通过 Docker Run/Create
- 更新镜像：
docker pull gotson/komga - 停止正在运行的容器：
docker stop komga - 删除容器：
docker rm komga - 使用上述相同的
docker create参数重新创建新容器（如果正确映射到主机文件夹，您的/config文件夹和设置将被保留）。 - 启动新容器：
docker start komga - 移除旧的孤立镜像：
docker image prune
2.8.2 通过 Docker Compose
- 更新所有镜像：
docker-compose pull - 或者更新单个镜像：
docker-compose pull komga - 让 Compose 根据需要更新所有容器：
docker-compose up -d - 或者更新单个容器：
docker-compose up -d komga - 移除旧的孤立镜像：
docker image prune
三、使用
3.1 创建管理员账号
一旦 Komga 启动，你可以通过以下地址访问网络界面：http://<your-server>:<port>(/baseUrl)。
如果你是在本地运行 Komga，
<your-server>将是localhost。
默认的<port>是25600。
(/baseUrl)是可选的，仅在你配置了它的情况下使用。
系统会要求你创建一个用户账户。选择一个电子邮件和密码，然后点击“创建用户账户”。第一个创建的账号系统权限为管理员。
登录成功后，首先将语言设置为中文
3.2 图书管理
您可以将内容分组到不同的库中，一个库就是一组图书。库的访问权限还可以限制为特定用户。
每个库都有一个根文件夹，库的根文件夹配置不能存在重复和包含关系。
例如，如果您有一个根路径为 /books/mangas 的库，就不能创建一个根路径为 /books 的库，因为这两个根路径会有重叠。不过，您可以创建一个根路径为 /books/comics 的库。
3.2.1 创建库
通过网络界面：
- 点击侧边栏 库 旁的 + 图标
- 为您的库选择一个 名称
- 点击 浏览 按钮并选择一个包含图书的根文件夹
- 点击 继续
您还可以指定额外的选项。
3.2.2 扫描器
每次扫描后自动清理垃圾
默认情况下，从库中移除的图书会被放入垃圾桶，直到垃圾桶被清空为止。如果您希望服务器在每次扫描后自动清空垃圾桶，可以勾选此框。
启用此选项后，图书将立即从库中移除，在发生错误时将无法恢复。保持默认即可，不建议勾选。
强制目录修改时间
此选项将强制目录的最后修改时间为该目录自身的最后修改时间与目录内所有图书的最后修改时间中的最大值。仅当您的文件系统在目录内文件被修改时不会更新目录的最后修改时间（例如 Google Drive）时使用。
建议保持默认，不必勾选。
启动时扫描
如果启用，在 Komga 启动时将扫描该库。
扫描间隔
选择基于时间间隔扫描所有库的方式。从下拉菜单中选择可用的频率：
- 禁用
- 每小时
- 每 6 小时
- 每 12 小时
- 每天
- 每周
扫描间隔基于 Komga 启动时间，或者您更改该库设置的时间。例如，如果设置为“每 6 小时”并且服务器在 12:35 启动，那么将在大约 18:35 开始扫描。
单行本目录
Komga 要求每个系列都必须在硬盘上有自己的目录。对于 单行本漫画 这显得相当麻烦，因为每一本书都需要放置在专属的目录中。
可配置某一路径为单行本图书，不必创建目录。
如果不明白此配置含义，留空即可。
扫描这些文件类型
此选项将配置扫描器仅查找具有特定扩展名的文件。可用类型包括：
- 漫画归档文件：
cbz、zip、cbr、rar - PDF 文件：
pdf - Epub 文件：
epub
建议全选。
目录排除
您可以指定任何模式以在扫描时排除某些目录子树。
在扫描期间，任何目录的完整路径中包含已配置的模式都会被忽略。
模式会匹配目录路径的任何部分：
- 例如，
#recycle将匹配：/data/books/Comics/#recycle/data/books/Comics/My weirdly named #recycle comic
如果只匹配以提供字符串开头的目录，请在模式前加上
/，例如/#recycle。
建议保持默认即可。
3.2.3 选项
分析
为文件计算哈希值
Komga 将为您的文件计算哈希值。这是“从回收站恢复”功能和检测重复文件所必需的。
在大型库或低性能硬件上，这可能会消耗大量资源。
非常重要的特性，建议勾选。
为页面计算哈希值
Komga 将为每本书的前 3 页和最后 3 页计算哈希值（仅限 cbz 文件）。这用于检测重复页面。
在大型库或低性能硬件上，这可能会消耗大量资源。
如无cbz格式图书，可留空。
为 KOReader 计算文件哈希值
Komga 将为您的文件计算 KOReader 的哈希值。这是 KOReader 同步 功能所必需的。
在大型库或低性能硬件上，这可能会消耗大量资源。
不使用KOReader时，直接留空。
分析页面尺寸
Komga 将检索每页的尺寸（宽度和高度）。这对以下场景很有用：
- 在网络阅读器中使用双页视图时，正确显示横向页面
- 在“导入”对话框中比较页面尺寸
在大型库或低性能硬件上，这可能会消耗大量资源。
非常重要的特性，建议勾选。
文件管理
自动修复不正确的文件扩展名
具有不正确扩展名的文件将在后台自动重命名。例如，扩展名为 .cbr 的 zip 文件将会被重命名为 .cbz。
自动转换为 CBZ 格式
以 rar/cbr 格式存储的图书将自动在后台转换为 cbz 格式。zip 文件将以 DEFLATE 方法创建且无压缩。
系列封面
选择系列使用哪本书的封面。
3.2.4 元数据
元数据配置，全部勾选即可。
3.2.5 编辑库
要编辑库，请找到操作菜单图标 … 并点击 编辑。
- 如果更改库的根文件夹，并且 新路径与之前的路径没有任何共享部分 ，您将丢失该库的所有系列、图书和阅读进度。
- 如果路径更改为 当前路径的父目录 ，您不会丢失内容。
- 如果路径更改为 当前路径的子目录 ，您将丢失部分内容。
3.2.6 删除库
要删除库，请找到操作菜单图标 … 并点击 删除。
删除库将移除库中包含的所有系列和图书。这些图书的阅读进度也将被删除。您的图书文件不会受到影响。此操作无法撤销。
3.3 扫描、分析和刷新元数据
在创建库后，Komga 会对其进行处理，以便将所有图书与系列匹配并收集元数据。随着时间推移，您可能会向库中添加或移除图书，或者进行其他更改，这可能导致库不再是最新状态。您可以通过扫描库使其保持最新。扫描、分析和刷新库的功能各有不同。
3.3.1 扫描库文件
扫描库使 Komga 检查其文件夹和子文件夹是否有新增或已移除的图书。如果发现新媒体，系统会将其引入库。可以将扫描视为“检查新内容或已更改的内容”。
在以下情况下，您应该扫描库文件：
- 添加或删除了文件或文件夹
- 重命名了文件或文件夹
- 将文件或文件夹从一个位置移动到另一个位置
默认情况下，Komga 会定期扫描库。
深度扫描
深度扫描会强制扫描器将所有扫描的图书与数据库中的图书进行比较。通常不需要深度扫描，因为 Komga 会根据父文件夹的最后修改时间来决定是否比较图书，但某些文件系统可能会表现得不同。
如果 Komga 在扫描后遗漏了一些图书，可以触发深度扫描。
扫描过程中发生了什么？
Komga 会根据硬盘上的文件生成库的表示形式。Komga 的库并不完全等同于您的文件夹结构：
- Komga 会为库的任何子文件夹创建一个系列，无论该子文件夹在目录结构中的深度如何
- Komga 会为找到的每个文件创建一个图书，并将其放置在对应的父文件夹系列中
3.3.2 分析图书
当图书被添加到您的库时，系统会自动执行分析。在少数情况下，Komga 的新版本可能会更新媒体分析功能以修正某些内容或增加检测新内容的能力。在这种情况下，当服务器版本更新时，可能会重新分析图书。
分析时会发生什么？
每当库中添加新图书或者系列时，Komga 会对其进行一些分析以收集信息。此外，所有被分析的文件也会刷新其元数据。
收集媒体属性
媒体分析的主要目的是收集该媒体项的信息。添加到库的所有媒体都有一些有用的属性，例如：
- 容器类型：ZIP、RAR、EPUB、PDF 等
- 图像格式：JPEG、PNG、WEBP 等
这些媒体属性的作用是什么？您的服务器及其相关应用程序可以利用这些信息来决定内容是否（以及如何）能够播放。
例如：假设您有一个包含 WEBP 图像的 CBR 文件，但您使用的是不支持 WEBP 的 Internet Explorer（IE）。由于网页阅读器知道您的浏览器能够显示哪种内容，并且媒体分析检测到图书包含 WEBP 图像，您的 Komga 服务器可以将这些图像转换为兼容的格式（如 JPEG），以便您能够成功阅读这本书。
生成默认艺术作品
在分析过程中，系统会自动从图书文件中提取艺术作品。第一页将被用作海报或缩略图。
分析您的内容
您可以以多种方式分析内容：按图书、按系列，甚至按整个库。
查找操作菜单图标 … 并点击“分析”。
根据库的大小，分析可能需要一段时间。
媒体分析页面
您可以在媒体分析页面上查看所有分析未成功的媒体。您可以通过媒体管理 > 媒体分析访问该页面。
页面显示的图书状态可能为：
- 错误：Komga 无法分析这本书。如果可能，会有一个评论描述错误。
- 不支持：Komga 不支持这些文件。评论会提供更多信息。
3.3.3 刷新元数据
刷新库、系列或单本图书的元数据会强制更新这些项目的元数据，即使它们已经有元数据。可以将刷新视为“即使已有元数据，也更新请求的项目的元数据”。
在以下情况下，您应该刷新库或单个项目：
- 更改了库的选项
- 添加了“本地媒体资产”（如艺术作品）
元数据来源包括以下内容：
- 位于 CBZ 或 CBR 文件内部的本地
ComicInfo.xml文件 - EPUB 文件的元数据
- 本地媒体资产
元数据刷新依赖于库的选项配置。
3.3.3.1 从 CBR/CBZ 中的 ComicInfo.xml 文件导入元数据
图书元数据
将从 ComicInfo.xml 文件中导入以下元素到 Komga：
Year、Month和Day作为发布日期Writer、Penciller、Inker、Colorist、Letterer、CoverArtist、Editor和Translator作为带有相应角色的作者。使用,分隔的多个名称将被拆分为不同的作者。Title、Summary和Number转换为 Komga 中的等效项- 有效的
Web链接作为图书链接 Tags元素将通过,分隔并添加到图书的标签- 如果
GTIN元素包含有效的 ISBN，则作为图书的ISBN
系列元数据
将从系列图书的 ComicInfo.xml 文件中导入以下元素到 Komga：
Series和Volume元素将用于覆盖系列标题，格式为<Series> (<Volume>)，如果Volume元素不存在、为1或者禁用了“附加卷号到系列标题”，则格式为<Series>。如果存在多个值，将使用所有图书中最常见的值。- 各种
AgeRating值将转为 Komga 中的数字，所有图书中最高的值将被使用。 - 最常见的
Publisher值将被用作 Komga 的等效项。 - 如果
Manga元素的值为YesAndRightToLeft，则阅读方向将标记为“从右到左”。所有图书中最常见的值将被使用。 Genre元素将通过,分隔，所有图书中的流派将被添加到系列。LanguageISO元素将用作系列的语言。所有图书中最常见的值将被使用。Count中的最高值将被用作图书总数。
收藏
SeriesGroup 元素将通过 , 分隔，用于创建具有这些名称的收藏，或者将系列添加到现有收藏中（如果存在）。
如果系列中的 SeriesGroup 元素在每本书中设置了不同的值，则这些值将分别创建收藏。
阅读列表
AlternateSeries 或 StoryArc 元素将用于创建具有该名称的阅读列表，或者将图书添加到具有该名称的现有阅读列表中。
如果设置了 AlternateNumber 元素，它将用于在阅读列表中为图书定位。
故事情节编号（StoryArcNumber）
如果设置了 StoryArcNumber 元素，它将与 StoryArc 结合使用，为图书在阅读列表中定位。
StoryArc 和 StoryArcNumber 元素都可以包含多个值，以 , 分隔。Komga 将尽力匹配每对值：
- 如果两个元素都已设置，但值的数量不同，则额外的值将被忽略
- 如果存在无效值（如空字符串或无效数字），则整对值将被忽略
3.3.3.2 从 EPUB 文件导入元数据
图书元数据
将从 EPUB 元数据导入以下字段到 Komga：
dc:title元素作为标题dc:description元素作为摘要dc:date元素作为发布日期dc:identifier元素作为ISBN（如果是有效的 ISBN）dc:creator元素作为作者。角色将从opf:role属性或meta元素中包含的role属性和marc:relators方案中导入。使用,分隔的多个名称将被拆分为不同的作者。
系列元数据
将从 EPUB 元数据导入以下字段到 Komga：
dc:publisher元素作为出版商dc:language元素作为语言spine元素的page-progression-direction属性作为阅读方向belongs-to-collection元素作为系列标题。如果存在多个值，将使用所有图书中最常见的值。
3.3.3.3 导入由 Mylar 生成的元数据
Mylar 可以在系列文件夹中生成一个 series.json 文件。此选项将以下字段导入到 Komga：
name字段将用作系列标题。如果volume字段已设置且不为1，则year字段将追加到标题中，格式为<name> (<year>)。status将用于设置系列状态。description_formatted或description_text将用作系列摘要。publisher将用作系列出版商。age_rating将用作系列年龄评级。total_issues将用作图书总数。
3.3.3.4 导入本地媒体资产
此选项允许导入本地艺术作品。
3.3.3.5 从条形码中导入 ISBN
Komga 将检查每本书的前 3 页和最后 3 页是否包含条形码。如果条形码中包含 ISBN 代码，它将被导入。