两条命令部署 koreader-sync-server:Docker 快速搭建 KOReader 阅读进度同步服务完整指南

原创2026-10-26 11:38:571,417 阅读

两条命令部署 koreader-sync-server:Docker 快速搭建 KOReader 阅读进度同步服务完整指南

koreader-sync-server 是一个可自托管(self hostable)的 KOReader 同步服务,它能让多台电纸书、平板上的 KOReader 设备自动同步阅读进度。基于 Docker,你只需 两条命令 就能完成生产环境部署,全程无需安装 Lua、Redis 等任何依赖。

一、koreader-sync-server 是什么?

简单理解:你有一台 PocketBook、一台 Kindle 改装设备或安卓平板,都用 KOReader 看书。每读完一章,进度就会自动上传到你自己搭建的同步服务器;换一台设备打开同一本书时,进度自动拉取回来,从上次读到的地方继续。

它的技术架构非常轻量:

组件 作用
Gin JSON-API 框架 提供 RESTful 接口
OpenResty + Lua Web 服务运行时
Redis 存储用户账号与阅读进度

整个镜像自带 Nginx、Redis 和自签名 HTTPS 证书,开箱即用。项目基于 AGPL v3 开源协议,见 COPYING。

二、Docker 一键快速体验(单条命令)

先用一条命令跑个"沙盒版",验证环境没问题:

docker run -d -p 7200:7200 --name=kosync koreader/kosync:latest

⚠️ 该方式不挂载数据卷,容器删除后进度数据会丢失,仅适合快速测试。

三、生产环境部署:只需两条命令

正式使用时挂载 Redis 数据卷来持久化状态,核心就是下面两条命令:

# 第一条:创建日志与数据目录
mkdir -p ./logs/{redis,app} ./data/redis

# 第二条:启动同步服务容器
docker run -d -p 7200:7200 \
    -v `pwd`/logs/app:/app/koreader-sync-server/logs \
    -v `pwd`/logs/redis:/var/log/redis \
    -v `pwd`/data/redis:/var/lib/redis \
    --name=kosync koreader/kosync:latest

三个挂载目录的作用一目了然:

宿主机目录 容器内路径 用途
./logs/app /app/koreader-sync-server/logs 应用日志
./logs/redis /var/log/redis Redis 日志
./data/redis /var/lib/redis 阅读进度数据(关键)

项目中的 Makefile 提供了等价的 make start / make stop 快捷方式,效果与上述命令一致。

💡 备选方案:docker compose 部署

仓库自带 docker-compose.yml,一条命令搞定,并且默认开启了用户注册开关:

docker compose up -d --build

四、从源码构建自定义镜像

想二次开发或修改配置?先 clone 仓库:

git clone https://gitcode.com/gh_mirrors/ko/koreader-sync-server
cd koreader-sync-server
docker build --rm=true --tag=koreader/kosync .

构建逻辑全部写在 Dockerfile 中:基于 Debian 精简版安装 OpenResty、Redis,生成自签名 SSL 证书,并用 runit 管理多进程守护。手动搭建服务器时直接参考它即可。

五、验证服务是否就绪

用官方健康检查接口确认服务状态:

curl -k -v -H "Accept: application/vnd.koreader.v1+json" https://localhost:7200/healthcheck

返回 {"state":"OK"} 即部署成功。注意两点:

  • 服务使用 自签名证书,所以 curl 需要 -k 忽略证书校验;
  • 该检查脚本同时被 Docker 健康检查复用,实现见 scripts/healthcheck.sh。

六、关键端口与配置速查

各环境端口定义在 config/settings.lua:

环境 端口 说明
production 7200 默认生产端口,HTTPS 自签证书
test 7201 测试环境
development 7202 开发环境,附带 API 控制台

两个高频配置场景:

  1. 关闭公开注册:默认允许任意设备注册(ENABLE_USER_REGISTRATION=true)。家庭自用建议设为 false,防止陌生人占用服务:
    docker run -d -p 7200:7200 -e ENABLE_USER_REGISTRATION=false --name=kosync koreader/kosync:latest
    
  2. 挂在反向代理后面:如果你用 Traefik、Nginx 等处理 TLS 终止,让服务改用 17200 端口(HTTP)即可,只需把映射改成 -p 17200:17200。Nginx 完整配置见 config/nginx.conf。

七、在 KOReader 中接入同步服务

部署完成后,回到 KOReader 设备端:

  1. 打开 设置 → 同步;
  2. 同步服务地址填写 https://你的服务器IP:7200;
  3. 填写用户名和密码完成设备注册;
  4. 此后每读完一章,进度自动上传,多设备实时保持一致。

支持的 API 端点可在 config/routes.lua 中查看,包括账号创建、鉴权、进度上报、进度查询、修改密码与注销账户等。

八、隐私说明:服务器到底存了什么?

很多用户担心自托管同步服务的隐私问题。koreader-sync-server 不存储文件名,也不存储任何书籍内容,它只保存:

  • 每本书的 32 位 MD5 指纹(用于在多台设备间识别同一文档);
  • 该文档最远的阅读进度(百分比 + XPath 定位);
  • 设备名称、账号密钥(客户端 MD5 哈希后的密码)。

所有设备与服务器之间的通信均通过 HTTPS 加密传输。

九、常见问题

Q:容器重启后数据还在吗? A:只要用了第三节的挂载方式,Redis 数据持久化在 ./data/redis,重启、升级镜像都不会丢进度。

Q:如何停止 / 升级服务? A:docker stop kosync && docker rm kosync,再执行新的 docker run 命令即可;升级前建议备份 ./data/redis 目录。

Q:忘记密码怎么办? A:服务不支持找回,需用 PUT /users/password 接口在仍知道当前密码时修改(详见 README.md 的 Changing a password 一节)。

按照以上步骤,你只需要两条 Docker 命令,就能拥有一个私有、安全、多设备共享阅读进度的 KOReader 同步中心。 📚

登录后查看全文
koreader-sync-server