专为KOReader打造的同步服务KOmpanion

发表于 更新于 分类于 Waline： 阅读次数： 本文字数： 4k 阅读时长 ≈ 4 分钟
KOmpanion 是专为书籍爱好者打造的自托管后端，与 KOReader 紧密集成。

本文题图背景由 AI 生成；

简介

什么是 KOReader ?

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

什么是 KOmpanion ？

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

主要功能

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

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

安装

在群晖上以 Docker 方式安装。

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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_URL PostgreSQL 数据库的连接 URL，例如 postgres://...。
KOMPANION_BSTORAGE_TYPE 书籍存储类型，可以是 postgres、memory 或 filesystem，默认值为 postgres。
KOMPANION_BSTORAGE_PATH 如果使用文件系统存储，则指定存储书籍的路径。
KOMPANION_STATS_TYPE 上传的 SQLite3 统计文件的临时存储类型，可以是 postgres、memory 或 filesystem，默认值为 memory。
KOMPANION_STATS_PATH 如果使用文件系统存储，则指定存储统计文件的路径。

然后执行下面的命令

1
2
3
4
5
6
7
8
9
10
# 新建文件夹 kompanion 和 子目录
mkdir -p /volume1/docker/kompanion/{data,pgdata}

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

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

# 一键启动
docker-compose up -d

运行

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

使用 KOMPANION_AUTH_USERNAME 和 KOMPANION_AUTH_PASSWORD 设置的值登录

登录成功后的主界面

上传电子书

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

随便上传了一本 epub

保存之后

一共上传了 2 本

添加设备

添加设备

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

KOReader

KOReader 的下载地址 https://github.com/koreader/koreader/releases

OPDS 下载

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

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

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

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

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

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

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

同步进度

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

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

书籍统计

找到 云存储

点左上角的 + 号，添加 WebDAV

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

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

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

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

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

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

1
2
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
地址：https://github.com/vanadium23/kompanion

koreader/koreader: An ebook reader application supporting PDF, DjVu, EPUB, FB2 and many more formats, running on Cervantes, Kindle, Kobo, PocketBook and Android devices
地址：https://github.com/koreader/koreader

KOmpanion - a self hosted backend for KOreader : r/koreader
地址：https://www.reddit.com/r/koreader/comments/1it186y/kompanion_a_self_hosted_backend_for_koreader/