vincentbitter/koreader-calibre-web-sync

KOReader Calibre-Web Sync

镜像概述和主要用途

KOReader Calibre-Web Sync是一款用于同步KOReader阅读数据到Calibre-Web的工具，能够自动将KOReader中阅读进度达100%的书籍在Calibre-Web中标记为“已读”，简化电子书阅读状态管理流程。

核心功能和特性

• 作为KOReader的阅读进度同步服务器，接收并处理阅读进度数据
• 当检测到KOReader中书籍阅读进度达100%（访问最后一页）时，自动登录Calibre-Web并更新书籍状态为“已读”
• 支持通过自定义URL配置同步服务器，适应局域网或公网部署场景

使用场景和适用范围

适用于使用KOReader电子阅读器并通过Calibre-Web管理电子书库的用户，尤其适合希望自动同步阅读状态，避免手动在Calibre-Web中更新书籍阅读状态的场景。

详细使用方法和配置说明

部署方式

应用以Docker镜像形式分发，可通过以下命令快速部署：

bash
docker run --restart=always -d -p 5000:5000 \
        --name=koreader \
        vincentbitter/koreader-calibre-web-sync:latest

注意事项

• 认证兼容性：仅在默认认证方式下测试通过，不支持LDAP、OAuth或反向代理认证；不支持双因素认证（2FA），需使用常规登录表单
• Calibre-Web配置：在Calibre-Web的基本配置页面→功能配置中，必须禁用“保存到磁盘时转换标题和作者中的非英文字符”选项，否则可能导致书籍哈希计算不一致，无法匹配
• KOReader设置：在KOReader中需将“文档匹配方法”设置为“文件名”（Filename）

工作原理

KOReader允许配置自定义同步服务器以同步阅读进度。本工具作为KOReader的阅读进度服务器，接收进度数据后进行判断：当检测到书籍阅读进度为100%（即访问最后一页）时，通过模拟用户登录Calibre-Web的方式，将对应书籍标记为“已读”。

使用步骤

1. 确认访问URL：部署完成后，确保电子阅读器可访问Docker容器的URL，可为局域网地址（如http://10.0.0.100:5000）或公网URL（如https://stats.mykoreader.com）

2. 配置KOReader同步服务器：

   • 在KOReader中打开任意书籍，进入“工具”菜单，选择“进度同步”
   • 在“自定义同步服务器”中填入部署好的工具URL（如https://stats.mykoreader.com）

3. 登录验证：

   • 点击“注册/登录”，在用户名栏使用特殊格式填写Calibre-Web凭据：<Calibre-Web用户名>:<Calibre-Web密码>@<Calibre-Web URL>
   • 示例：若Calibre-Web部署在https://my.calibre-web.com，用户名为vincent，密码为secret，则用户名字段填写vincent:secret@https://my.calibre-web.com
   • 密码字段可填写任意值（将被忽略），点击“登录”验证凭据

4. 凭据更新：若Calibre-Web用户名、密码或URL变更，需先在KOReader中登出，再重新登录以更新凭据