技术博客
首页 所有文章 标签 分类 关于
技术博客

目录

专为KOReader打造的同步服务KOmpanion

 收录于 未分类
   约 1509 字   预计阅读 4 分钟 
https://bing.ee123.net/img/rand?artid=146197702

专为KOReader打造的同步服务KOmpanion

https://i-blog.csdnimg.cn/direct/5d25c0fafad849729b63355ae1958230.png

本文题图背景由 AI 生成；

简介

什么是 KOReader ?

KOReader 是一款维护了十多年的开源项目，他是 主要针对电子墨水阅读器的文档查看器 ，它支持几乎所有主流的电子书格式。 包括 EPUB 、 MOBI 、 PDF ， TXT 、 DJVU ， KOReader 都能轻松应对。

什么是 KOmpanion ？

KOmpanion 是一个为 KOReader 用户设计的极简自托管 Web 应用程序，旨在方便用户管理和同步阅读数据。它主要提供书籍上传和查看、 OPDS 下载、 KOReader 同步进度 API 以及通过 WebDAV 获取 KOReader 书籍统计等功能，从而增强 KOReader 的使用体验。

主要功能

  • 书架管理 ：用户可以上传和查看自己的书籍列表。
  • OPDS 支持 ：允许用户下载书籍。
  • 同步进度 API ：支持设备间的阅读进度同步。
  • 书籍统计 ：通过 WebDAV 提供书籍阅读统计信息。

https://i-blog.csdnimg.cn/img_convert/2e8cd0b4685e7b81debc3cdead17ba7d.png

该项目并非用于网页端阅读或格式转换，而是专注于与 KOReader 的紧密集成，并提供了多种安装方式，包括 Railway 、 Docker 和预编译的二进制文件。

安装

在群晖上以 Docker 方式安装。

在注册表中搜索 kompanion ，选择第一个 vanadium23/kompanion ，版本选择 latest 。

本文写作时， latest 版本对应为 v0.0.2 ；

https://i-blog.csdnimg.cn/img_convert/45b67a866bad6520dfac4791ef637360.png

需要用到 2 个镜像，采用 docker-compose 安装，将下面的内容保存为 docker-compose.yml 文件

version: '3'

services:
  postgres:
    image: postgres:16
    container_name: ko-postgres
    restart: unless-stopped
    # ports:
    #   - 5432:5432
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: 'user'
      POSTGRES_PASSWORD: 'pass'
      POSTGRES_DB: 'postgres'

  app:
    image: vanadium23/kompanion:latest
    container_name: ko-web
    restart: unless-stopped
    # user: "${UID}:${GID}"
    ports:
      - 8322:8080
    volumes:
     - ./data:/data
    environment:
      KOMPANION_PG_URL: 'postgres://user:pass@postgres:5432/postgres'
      KOMPANION_AUTH_USERNAME: 'user'
      KOMPANION_AUTH_PASSWORD: 'password'
    depends_on:
      - postgres
  • postgres 容器环境变量的简单说明
可变值及说明
POSTGRES_USER数据库的用户名，设置为 user 。
POSTGRES_PASSWORD数据库用户的密码，设置为 pass 。
POSTGRES_DB要创建的默认数据库名称，设置为 postgres 。

如果修改了数据库的账号和密码，记得对应的 KOMPANION_PG_URL 也要相应的做调整；

  • kompanion 容器环境变量的简单说明
可变值及说明
KOMPANION_AUTH_USERNAME必需 ，用于设置管理员用户名。
KOMPANION_AUTH_PASSWORD必需 ，用于设置管理员密码。
KOMPANION_AUTH_STORAGE存储类型，可以是 postgres 或 memory ，默认值为 postgres 。
KOMPANION_HTTP_PORT服务运行的端口，默认值为 8080 。
KOMPANION_LOG_LEVEL日志级别，可以设置为 debug 、 info 或 error ，默认值为 info 。
KOMPANION_PG_POOL_MAX数据库连接池的最大连接数，默认为 2 。
KOMPANION_PG_URLPostgreSQL 数据库的连接 URL ，例如 postgres://... 。
KOMPANION_BSTORAGE_TYPE书籍存储类型，可以是 postgres 、 memory 或 filesystem ，默认值为 postgres 。
KOMPANION_BSTORAGE_PATH如果使用文件系统存储，则指定存储书籍的路径。
KOMPANION_STATS_TYPE上传的 SQLite3 统计文件的临时存储类型，可以是 postgres 、 memory 或 filesystem ，默认值为 memory 。
KOMPANION_STATS_PATH如果使用文件系统存储，则指定存储统计文件的路径。

然后执行下面的命令

# 新建文件夹 kompanion 和 子目录
mkdir -p /volume1/docker/kompanion/{data,pgdata}

# 进入 kompanion 目录
cd /volume1/docker/kompanion

# 将 docker-compose.yml 放入当前目录

# 一键启动
docker-compose up -d

https://i-blog.csdnimg.cn/img_convert/209f613041a341846e566204a39fa854.png

运行

在浏览器中输入 http://群晖IP:8322 就能看到主界面

https://i-blog.csdnimg.cn/img_convert/f1e3f430cf1f0016853f89773954dda1.png

使用 KOMPANION_AUTH_USERNAME 和 KOMPANION_AUTH_PASSWORD 设置的值登录

https://i-blog.csdnimg.cn/img_convert/adbbd0b0977a2e1567d880a8210a3550.png

登录成功后的主界面

https://i-blog.csdnimg.cn/img_convert/58d29566dde1d335ec35887f1d4656b6.png

上传电子书

支持 epub 、 pdf 和 fb2 格式的电子书

https://i-blog.csdnimg.cn/img_convert/e461fbfaeb35de77860d613d386cd211.png

随便上传了一本 epub

https://i-blog.csdnimg.cn/img_convert/ec2efe631a5c3231c9796246d332f434.png

保存之后

https://i-blog.csdnimg.cn/img_convert/8983eae3f596ac88b5b7f6cdee034ee4.png

一共上传了 2 本

https://i-blog.csdnimg.cn/img_convert/25b93f1a84945d12faa6bf515da76584.png

添加设备

添加设备

https://i-blog.csdnimg.cn/img_convert/3aeff59c40b9b966d17e225274fcb599.png

只要设备名称和密码就可以

https://i-blog.csdnimg.cn/img_convert/562e73f37ef1bd609a02371d28df73f3.png

KOReader

KOReader 的下载地址

https://i-blog.csdnimg.cn/img_convert/21c4a079eec368322976ad5c79a8c769.png

OPDS 下载

在 KOReader 中，找到 OPDS 书目 ，点击进入

https://i-blog.csdnimg.cn/img_convert/d9016f52e9093aafc5a55ff5cb88cd07.jpeg

点左上角的 + 号，添加 OPDS 书目

  • 书目名称： 主要用于识别，无所谓的；
  • 书目 URL ： http://192.168.0.197:8322/opds/ ，别忘了最后的 / ；
  • 用户名： KOMPANION_AUTH_USERNAME 设置的值；
  • 密码： KOMPANION_AUTH_PASSWORD 设置的值

https://i-blog.csdnimg.cn/img_convert/35abf3c208d39541a6b74b3203cdc476.jpeg

保存之后，点击新建的 书目名称

https://i-blog.csdnimg.cn/img_convert/271bf199d74fb60f13c285dddd1ce154.jpeg

能看到我们在 Web 上传的电子书

https://i-blog.csdnimg.cn/img_convert/17ef360000c39c1de8e283c6086f65e4.jpeg

可以直接下载，如果出现显示问题

https://i-blog.csdnimg.cn/img_convert/d82caf7c80b8ac05fc3833609b42acf2.jpeg

把 渲染模式 从 网页 改为 书籍 就可以了

https://i-blog.csdnimg.cn/img_convert/67bf64a29a83ea33a9d60ef2b268548e.jpeg

同步进度

打开书籍， 进度同步 –> 自定义同步服务器

https://i-blog.csdnimg.cn/img_convert/b41d7c08587a0d8fa33abb53150647fa.jpeg

然后就可以上传本设备进度或者从其他设备拉取进度了

书籍统计

找到 云存储

https://i-blog.csdnimg.cn/img_convert/56b478f1b2d5e2befae7fbfd483fcb21.jpeg

点左上角的 + 号，添加 WebDAV

https://i-blog.csdnimg.cn/img_convert/cd720a6d462fdca83ba1a934aadc72ef.jpeg

  • ·服务器显示名称：主要用于识别，无所谓的；
  • WebDAV 地址： http://192.168.0.197:8322/webdav
  • 用户名： 前面在网页上添加的设备名称，这里是 oppo
  • 密码：前面为设备设置的密码，这里是 123456

https://i-blog.csdnimg.cn/img_convert/96db9f9816387e699782e2465fd712c2.jpeg

打开书籍， 阅读统计 –> 设置 –> 云同步 –> 编辑

https://i-blog.csdnimg.cn/img_convert/f919dc445e9c2963d0f546b975bd4a58.jpeg

选中后，点 长按选择当前文件夹 ，长按选择目录

https://i-blog.csdnimg.cn/img_convert/cd3f326275e4662aeef3d9b5f8621ac4.jpeg

现在可以同步阅读统计信息了，在网页上能看到

https://i-blog.csdnimg.cn/img_convert/2592d934cbf969f2b0d93e26dde4383b.png

但是似乎只有第一次可以，之后再同步，会显示 同步中发生错误，请检查您的网络连接并稍后重试

从日志看，应该是程序的 bug ，违反了数据库中定义的唯一约束。当然，这只是老苏的猜测

ko-web      | {"level":"info","time":"2025-03-09T06:53:44Z","caller":"/go/pkg/mod/github.com/gin-gonic/gin@v1.7.7/context.go:168","message":"error writing statistics%!(EXTRA *fmt.wrapError=PostgresStorage - Write - r.Pool.Exec: ERROR: duplicate key value violates unique constraint \"storage_blob_file_path_key\" (SQLSTATE 23505))"}
ko-web      | [GIN] 2025/03/09 - 06:53:44 | 500 |    9.265288ms |      172.18.0.1 | PUT      "/webdav/statistics.sqlite3"

参考文档

vanadium23/kompanion: a self hosted backend for bookworms, tightly coupled with KOReader

地址：

koreader/koreader: An ebook reader application supporting PDF, DjVu, EPUB, FB2 and many more formats, running on Cervantes, Kindle, Kobo, PocketBook and Android devices

地址：

KOmpanion - a self hosted backend for KOreader : r/koreader

地址：

更新于 2025-03-12
 群晖, 电子书, Docker
返回 | 主页