本文題圖背景由 AI 生成；
簡介
什么是 KOReader ?
KOReader 是一款維護(hù)了十多年的開源項(xiàng)目，他是主要針對電子墨水閱讀器的文檔查看器，它支持幾乎所有主流的電子書格式。 包括 EPUB、MOBI、PDF，TXT 、DJVU，KOReader 都能輕松應(yīng)對。
什么是 KOmpanion ？
KOmpanion 是一個為 KOReader 用戶設(shè)計(jì)的極簡自托管 Web 應(yīng)用程序，旨在方便用戶管理和同步閱讀數(shù)據(jù)。它主要提供書籍上傳和查看、OPDS 下載、KOReader 同步進(jìn)度 API 以及通過 WebDAV 獲取 KOReader 書籍統(tǒng)計(jì)等功能，從而增強(qiáng) KOReader 的使用體驗(yàn)。
主要功能
- 書架管理：用戶可以上傳和查看自己的書籍列表。
- OPDS 支持：允許用戶下載書籍。
- 同步進(jìn)度 API：支持設(shè)備間的閱讀進(jìn)度同步。
- 書籍統(tǒng)計(jì)：通過
WebDAV 提供書籍閱讀統(tǒng)計(jì)信息。
該項(xiàng)目并非用于網(wǎng)頁端閱讀或格式轉(zhuǎn)換，而是專注于與 KOReader 的緊密集成，并提供了多種安裝方式，包括 Railway、Docker 和預(yù)編譯的二進(jìn)制文件。
安裝
在群暉上以 Docker 方式安裝。
在注冊表中搜索 kompanion ，選擇第一個 vanadium23/kompanion，版本選擇 latest。
本文寫作時， latest 版本對應(yīng)為 v0.0.2；
需要用到 2 個鏡像，采用 docker-compose 安裝，將下面的內(nèi)容保存為 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
yaml
postgres 容器環(huán)境變量的簡單說明
| 可變 | 值及說明 |
|---|
POSTGRES_USER | 數(shù)據(jù)庫的用戶名，設(shè)置為 user。 | POSTGRES_PASSWORD | 數(shù)據(jù)庫用戶的密碼，設(shè)置為 pass。 | POSTGRES_DB | 要創(chuàng)建的默認(rèn)數(shù)據(jù)庫名稱，設(shè)置為 postgres。 |
如果修改了數(shù)據(jù)庫的賬號和密碼，記得對應(yīng)的 KOMPANION_PG_URL 也要相應(yīng)的做調(diào)整；
kompanion 容器環(huán)境變量的簡單說明
| 可變 | 值及說明 |
|---|
KOMPANION_AUTH_USERNAME | 必需，用于設(shè)置管理員用戶名。 | KOMPANION_AUTH_PASSWORD | 必需，用于設(shè)置管理員密碼。 | KOMPANION_AUTH_STORAGE | 存儲類型，可以是 postgres 或 memory，默認(rèn)值為 postgres。 | KOMPANION_HTTP_PORT | 服務(wù)運(yùn)行的端口，默認(rèn)值為 8080。 | KOMPANION_LOG_LEVEL | 日志級別，可以設(shè)置為 debug、info 或 error，默認(rèn)值為 info。 | KOMPANION_PG_POOL_MAX | 數(shù)據(jù)庫連接池的最大連接數(shù)，默認(rèn)為 2。 | KOMPANION_PG_URL | PostgreSQL 數(shù)據(jù)庫的連接 URL，例如 postgres://...。 | KOMPANION_BSTORAGE_TYPE | 書籍存儲類型，可以是 postgres、memory 或 filesystem，默認(rèn)值為 postgres。 | KOMPANION_BSTORAGE_PATH | 如果使用文件系統(tǒng)存儲，則指定存儲書籍的路徑。 | KOMPANION_STATS_TYPE | 上傳的 SQLite3 統(tǒng)計(jì)文件的臨時存儲類型，可以是 postgres、memory 或 filesystem，默認(rèn)值為 memory。 | KOMPANION_STATS_PATH | 如果使用文件系統(tǒng)存儲，則指定存儲統(tǒng)計(jì)文件的路徑。 |
然后執(zhí)行下面的命令
# 新建文件夾 kompanion 和 子目錄
mkdir -p /volume1/docker/kompanion/{data,pgdata}
# 進(jìn)入 kompanion 目錄
cd /volume1/docker/kompanion
# 將 docker-compose.yml 放入當(dāng)前目錄
# 一鍵啟動
docker-compose up -d
bash
運(yùn)行
在瀏覽器中輸入 http://群暉IP:8322 就能看到主界面
使用 KOMPANION_AUTH_USERNAME 和 KOMPANION_AUTH_PASSWORD 設(shè)置的值登錄
登錄成功后的主界面
上傳電子書
支持 epub、pdf 和 fb2 格式的電子書
隨便上傳了一本 epub
保存之后
一共上傳了 2 本
添加設(shè)備
添加設(shè)備
只要設(shè)備名稱和密碼就可以
KOReader
KOReader 的下載地址 https://github.com/koreader/koreader/releases
OPDS 下載
在 KOReader 中，找到 OPDS 書目，點(diǎn)擊進(jìn)入
點(diǎn)左上角的 + 號，添加 OPDS 書目
- 書目名稱： 主要用于識別，無所謂的；
- 書目
URL： http://192.168.0.197:8322/opds/，別忘了最后的 /； - 用戶名：
KOMPANION_AUTH_USERNAME 設(shè)置的值； - 密碼：
KOMPANION_AUTH_PASSWORD 設(shè)置的值
保存之后，點(diǎn)擊新建的 書目名稱
能看到我們在 Web 上傳的電子書
可以直接下載，如果出現(xiàn)顯示問題
把 渲染模式 從 網(wǎng)頁 改為 書籍 就可以了
同步進(jìn)度
打開書籍，進(jìn)度同步 --> 自定義同步服務(wù)器
然后就可以上傳本設(shè)備進(jìn)度或者從其他設(shè)備拉取進(jìn)度了
書籍統(tǒng)計(jì)
找到 云存儲
點(diǎn)左上角的 + 號，添加 WebDAV
- ·服務(wù)器顯示名稱：主要用于識別，無所謂的；
WebDAV 地址： http://192.168.0.197:8322/webdav- 用戶名： 前面在網(wǎng)頁上添加的設(shè)備名稱，這里是
oppo - 密碼：前面為設(shè)備設(shè)置的密碼，這里是
123456
打開書籍，閱讀統(tǒng)計(jì) --> 設(shè)置 --> 云同步 --> 編輯
選中后，點(diǎn) 長按選擇當(dāng)前文件夾，長按選擇目錄
現(xiàn)在可以同步閱讀統(tǒng)計(jì)信息了，在網(wǎng)頁上能看到
但是似乎只有第一次可以，之后再同步，會顯示 同步中發(fā)生錯誤，請檢查您的網(wǎng)絡(luò)連接并稍后重試
從日志看，應(yīng)該是程序的 bug，違反了數(shù)據(jù)庫中定義的唯一約束。當(dāng)然，這只是老蘇的猜測
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"
log
參考文檔
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./r/koreader/comments/1it186y/kompanion_a_self_hosted_backend_for_koreader/
|
