两条命令部署 koreader-sync-server:Docker 快速搭建 KOReader 阅读进度同步服务完整指南
两条命令部署 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 控制台 |
两个高频配置场景:
- 关闭公开注册:默认允许任意设备注册(
ENABLE_USER_REGISTRATION=true)。家庭自用建议设为false,防止陌生人占用服务:docker run -d -p 7200:7200 -e ENABLE_USER_REGISTRATION=false --name=kosync koreader/kosync:latest - 挂在反向代理后面:如果你用 Traefik、Nginx 等处理 TLS 终止,让服务改用
17200端口(HTTP)即可,只需把映射改成-p 17200:17200。Nginx 完整配置见 config/nginx.conf。
七、在 KOReader 中接入同步服务
部署完成后,回到 KOReader 设备端:
- 打开 设置 → 同步;
- 同步服务地址填写
https://你的服务器IP:7200; - 填写用户名和密码完成设备注册;
- 此后每读完一章,进度自动上传,多设备实时保持一致。
支持的 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 同步中心。 📚