
本文题图背景由 AI 生成;
简介
什么是 KOReader ?
KOReader
是一款维护了十多年的开源项目,他是主要针对电子墨水阅读器的文档查看器 ,它支持几乎所有主流的电子书格式。 包括EPUB
、MOBI
、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/