專為KOReader打造的同步服務(wù)KOmpanion

六渾書齋 2025-08-01 發(fā)布于浙江

展開全文

本文題圖背景由 AI 生成；

簡介

什么是 KOReader ?

KOReader 是一款維護(hù)了十多年的開源項目，他是主要針對電子墨水閱讀器的文檔查看器，它支持幾乎所有主流的電子書格式。包括 EPUB、MOBI、PDF，TXT 、DJVU，KOReader 都能輕松應(yīng)對。

什么是 KOmpanion ？

KOmpanion 是一個為 KOReader 用戶設(shè)計的極簡自托管 Web 應(yīng)用程序，旨在方便用戶管理和同步閱讀數(shù)據(jù)。它主要提供書籍上傳和查看、OPDS 下載、KOReader 同步進(jìn)度 API 以及通過 WebDAV 獲取 KOReader 書籍統(tǒng)計等功能，從而增強 KOReader 的使用體驗。

主要功能

書架管理：用戶可以上傳和查看自己的書籍列表。
OPDS 支持：允許用戶下載書籍。
同步進(jìn)度 API：支持設(shè)備間的閱讀進(jìn)度同步。
書籍統(tǒng)計：通過 WebDAV 提供書籍閱讀統(tǒ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ù)運行的端口，默認(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)計文件的臨時存儲類型，可以是 `postgres`、`memory` 或 `filesystem`，默認(rèn)值為 `memory`。
`KOMPANION_STATS_PATH`	如果使用文件系統(tǒng)存儲，則指定存儲統(tǒng)計文件的路徑。

然后執(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

運行

在瀏覽器中輸入 http://群暉IP:8322 就能看到主界面

使用 KOMPANION_AUTH_USERNAME 和 KOMPANION_AUTH_PASSWORD 設(shè)置的值登錄

登錄成功后的主界面

上傳電子書

支持 epub、pdf 和 fb2 格式的電子書

隨便上傳了一本 epub

保存之后

一共上傳了 2 本

添加設(shè)備

只要設(shè)備名稱和密碼就可以

KOReader

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

OPDS 下載

在 KOReader 中，找到 OPDS 書目，點擊進(jìn)入

點左上角的 + 號，添加 OPDS 書目

書目名稱：主要用于識別，無所謂的；
書目 URL： http://192.168.0.197:8322/opds/，別忘了最后的 /；
用戶名：KOMPANION_AUTH_USERNAME 設(shè)置的值；
密碼： KOMPANION_AUTH_PASSWORD 設(shè)置的值

保存之后，點擊新建的 書目名稱

能看到我們在 Web 上傳的電子書

可以直接下載，如果出現(xiàn)顯示問題

把 渲染模式 從 網(wǎng)頁 改為 書籍 就可以了

同步進(jìn)度

打開書籍，進(jìn)度同步 --> 自定義同步服務(wù)器

然后就可以上傳本設(shè)備進(jìn)度或者從其他設(shè)備拉取進(jìn)度了

書籍統(tǒng)計

找到 云存儲

點左上角的 + 號，添加 WebDAV

·服務(wù)器顯示名稱：主要用于識別，無所謂的；
WebDAV 地址： http://192.168.0.197:8322/webdav
用戶名：前面在網(wǎng)頁上添加的設(shè)備名稱，這里是 oppo
密碼：前面為設(shè)備設(shè)置的密碼，這里是 123456

打開書籍，閱讀統(tǒng)計 --> 設(shè)置 --> 云同步 --> 編輯

選中后，點 長按選擇當(dāng)前文件夾，長按選擇目錄

現(xiàn)在可以同步閱讀統(tǒng)計信息了，在網(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