Skip to main content

使用 Kobo 阅读

Kobo 集成基于原生的 Kobo 同步功能，您的 Kobo 电子阅读器将同步至 Komga 服务器而非官方 Kobo 服务器。

支持的功能和限制​

以下是当前支持的功能：

  • 只有来自所有书库的 EPUB 书籍以及它们的元数据和封面图像会被同步。
  • 在 Komga 中编辑书籍元数据或封面后，Kobo 电子阅读器上的内容也会同步更新。
  • 在 Komga 中删除的书籍也会从 Kobo 电子阅读器中删除。
  • 阅读进度双向同步
  • 如果已配置并启用了 Kepubify（参见Kepubify），Kobo 设备在下载 EPUB 电子书时会自动将其转换为 KEPUB 格式
  • 如果在 服务器设置 中启用了 Kobo 代理功能，Komga 会将请求转发至官方 Kobo 服务器，并将 Komga 内容和 Kobo 内容一并返回给 Kobo 电子阅读器。 如果您有官方 Kobo 购买记录，这会很有用。

阅读进度同步方式如下：

  • 对于预分页的书籍，阅读进度将按页准确显示。
  • 对于常规的 EPUB 书籍，Kobo 只能记录章节开头的阅读进度，无法记录章节内的进度。 切换 Kobo 和 Komga 时，章节阅读进度将会丢失。 这是 Kobo 的限制。
  • 对于Kobo EPUB (KEPUB)的书籍，Kobo使用自己的机制跟踪阅读进度。 Komga 会尽力将 Kobo 特定的阅读进度映射到 Komga 中，但可能会有几页的误差。

配置​

要使用 Kobo 与 Komga 同步，Komga 用户必须具有角色 KOBO_SYNC 和 FILE_DOWNLOAD 。

在 服务器设置 中可以启用将未知请求代理到官方Kobo服务器的功能。 此功能已为服务器上的所有用户全局启用。

生成 API 密钥​

Kobo 同步 Komga API 使用了一套专用端点，需要 API 密钥来访问。 用户可以在 账户设置 页面生成API密钥。 请务必记下生成的密钥，因为它以后不会再显示。

如果您有多个 Kobo 设备，建议对每个设备使用不同的 API 密钥。

Kepubify​

Komga 在 Kobo 请求文件时使用 Kepubify 自动将 EPUB 书转换为 KEPUB 格式。

Kepubify 已预装在以下发行版中：

  • Windows 应用程序
  • macOS 应用程序
  • Docker amd64
  • Docker arm64
  • Docker arm

使用 jar 时，您需要在 服务器设置 中配置 kepubify 或 kepubify.exe 的路径。

配置 Kobo​

将您的 Kobo 电子阅读器连接到您的计算机并打开 .kobo/Kobo eReader.conf 文件(您可能需要在 Mac/Linux 上显示隐藏的文件)。

该文件应包含以下行（以及其他内容）：

api_endpoint=https://storeapi.kobo.com

如果该行不存在，必须在 [OneStoreServices] 分组下创建。

您需要用您的外部服务器地址替换此行，遵循以下格式：

api_endpoint=https://<your_komga_address>/kobo/<api_key>

例如：

api_endpoint=https://demo.komga.org/kobo/ABC123456123ABCD

或者本地连接(视需要调整端口)：

api_endpoint=http://192.168.1.54:25600/kobo/ABC123456123ABCD

强制使用外部端口​

Kobo 电子阅读器不发送有效的 HTTP Host 头，这可能会在某些情况下破坏封面和文件下载。 Komga 会尽力自动修复错误的 Kobo 标头，但在某些特定情况下可能无法完成。

如果在从 Kobo 下载封面或文件时遇到问题，您需要将 Kobo同步外部端口 （位于 服务器设置 中）配置为您的 Kobo 正在使用的端口。 通常它应该是您在 api_endpoint 中配置的。

这种情况的一个例子是，当你直接访问你的 Komga 服务器（没有使用反向代理），Komga 运行在 Docker 中，并且 Docker 映射的端口与 Komga 内部端口不同时。

从 Calibre-Web 迁移​

如果你之前使用过 Calibre-Web 与 Kobo 同步功能，可以通过修改 Kobo eReader.conf 文件，将其指向你的 Komga 服务器来迁移至 Komga。

由 Calibre-Web 添加的书籍应保留在您的 Kobo 设备上。

如果您启用了 Kobo 代理功能，Komga 能够透明地从 Calibre-Web 令牌（存储在 Kobo 上）中提取您的 Kobo 身份验证令牌。

隐私和安全​

Kobo 电子阅读器在同步协议过程中会发送敏感信息。 强烈建议仅通过 HTTPS 使用 Kobo 同步功能。

API 密钥与您的用户名和密码一样敏感。 由于API密钥是 Kobo 同步的 URL 的一部分，您不应该与任何人共享此 URL。

分享 Komga 日志或 Kobo 日志时请谨慎，务必删除所有敏感信息。

问题排查​

Sync fails with Invalid character found in the request target​

Kobo 在发送请求时不遵循 HTTP 标准。 如果您的 Kobo 被配置为直接连接到 Komga，同步将失败，Komga 日志将包含类似于：

java.lang.IllegalArgumentException: Invalid character found in the request target [/kobo/abcdefdf8e0f24842a514c37d133e2ff3/v1/assets?DiffRequests=[%7BKey:EPD-KoboPlus-ReadOnly-NeverSubscribed,ETag:%7D] ]. The valid characters are defined in RFC 7230 and RFC 3986

你可以配置 Komga 以允许这些无效字符：

在您的application.yml中添加以下项：

server.tomcat.relaxed-query-chars: "[,]"

强制 Kobo 同步​

如果 Kobo 电子阅读器与 Komga 出现不同步的情况，您可以在 账户设置 页面强制进行完全同步。 找到 API 密钥，然后点击 强制Kobo同步 图标。

访问 Kobo 电子阅读器日志​

Kobo设备上的日志是加密的，连接到计算机时无法读取。

为了获得可读日志，您需要启用开发者选项：

  • 在搜索栏中，输入 devmodeon 并搜索
  • 这将不会显示任何搜索结果，但你可以在 设置 > 设备信息 > 开发者选项 下访问开发者选项
  • 在 日志类别 部分，启用以下选项：sync、packetdump
  • 重启 Kobo 电子阅读器

设置完成后，您就可以使用 netcat 流式传输 Kobo 的日志了。 在与 Kobo 同一网络上的计算机上使用以下命令。 用 Kobo 的实际 IP 替换 <kobo IP address> 。

nc -v <kobo IP address> 5001

Komga 日志​

通过将 logging.level.org.springframework.web.filter.CommonsRequestLoggingFilter 设置为 DEBUG，Komga 可以记录所有传入的 HTTP 请求，包括请求头和请求体。

要记录向官方 Kobo 商店发出的 HTTP 请求，请将logging.level.org.gotson.komga.infrastructure.kobo设置为DEBUG。

你也可以在 Komga 服务器的/actuator/httpexchanges端点下查看最近的 HTTP 交换记录。