专为KOReader打造的同步服务KOmpanion

本文题图背景由 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 文件

yaml 复制代码

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`	如果使用文件系统存储，则指定存储统计文件的路径。

然后执行下面的命令

bash 复制代码

# 新建文件夹 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，违反了数据库中定义的唯一约束。当然，这只是老苏的猜测

log 复制代码

ko-web      | {"level":"info","time":"2025-03-09T06:53:44Z","caller":"/go/pkg/mod/github.com/gin-gonic/[email protected]/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/