2026-11-21 | Windows Docker Desktop 实测 + 群晖 NAS 部署 + frp/1Panel 外网访问 | 结论先行:BookOrbit 把阅读进度、高亮笔记、统计全都集中到自建服务端,手机和电脑进度自动一致;它不只是电子书,还管有声书和漫画,最打动我的是那套完整的阅读统计——像一份自己的阅读成长档案。
一、痛点:手机和电脑的阅读进度,永远对不上
事情从一个很小的需求开始:我希望手机和电脑看同一本书,进度能同步;看到写得好的句子,能划线做笔记,而且笔记可以搜;界面要好看,符合自己的使用习惯。之前在用的本地阅读服务已经跑了一段时间,但在这几方面都不太满足,于是调研一圈后,把目标锁定在 BookOrbit(服务端)+ Readest(阅读客户端) 这套组合上。
真正让我决定动手的,不是"同步"本身,而是 BookOrbit 首页那套阅读统计:阅读时长、活动热力图、连续天数、按周/月/年的图表,还有"各设备读了多少"的占比条。它不像一个书架,更像一份能回头看自己成长的阅读档案。而且它把电子书、有声书、漫画放在同一个体系里——这是单纯 Calibre 或阅读 App 给不了的。
二、为什么现成方案救不了
我评估过几条"看起来更省事"的路,都不成立:
| 常规做法 | 为什么不行 |
|---|---|
| 继续用之前那套本地阅读服务 | 进度、笔记、统计分散,缺少跨书可搜索的笔记中心 |
| 只装 Readest,用官方云同步 | 数据放在别人服务器,不满足"自建、局域网优先"的诉求 |
| 改用 Kavita / Komga | 进度同步成熟,但高亮/笔记与阅读器的双向同步长期是未落地的议题,笔记搜索弱 |
| Calibre + Calibre-Web | 书库管理强,但 annotations 同步至今是 feature request,且 UI 偏传统 |
BookOrbit 的差异点很清楚:它把"阅读状态"当成一等公民——进度、高亮、笔记、阅读时长、设备来源,全进同一个数据库,还给了跨书搜索的 Annotations 页面和一套完整统计。
三、方案:三个角色,各司其职
整套东西拆开看,就三个角色:
- BookOrbit:自建服务端,跑在 NAS 的 Docker 里,装 PostgreSQL 数据库。它是唯一数据源,提供 WebUI 书架、阅读统计、笔记搜索、OPDS 供客户端拉书。
- Readest:跨平台阅读器(Windows/安卓/iOS/Web),负责读书和做笔记,通过 KOReader 同步协议连 BookOrbit。
- Syncthing:把本地下载的书同步到 NAS 的书籍目录,形成"本地下载 → 自动同步 → BookOrbit 扫描入库"的半自动流水线。
外网访问再叠一层:frp 把 NAS 的服务穿透到有公网 IP 的服务器,服务器上用 1Panel 做反向代理 + 免费自动续期证书,绑定子域名。
链路全景:
本地书籍目录 ──Syncthing──> NAS books/ ──扫描──> BookOrbit
│
Readest(电脑/手机) ──KOReader协议──> BookOrbit <──WebUI/统计/笔记搜索── 浏览器
│
外网设备 ──https://子域名──> 1Panel ──frp隧道──> NAS:3000四、关键决策:每一个都踩过坑
决策 1:Readest 的 Server URL 只填 IP + 端口,不带 API 路径
BookOrbit 的设置页会显示一个形如 http://host:3000/api/v1/koreader 的完整地址。直接复制到 Readest 是错的——Readest 要的是 origin,它自己会拼 API 路径。
✅ http://localhost:3000/
❌ http://localhost:3000/api/v1/koreader这个坑不踩不知道,踩了就是"凭据都对、就是连不上"。
决策 2:镜像不用 latest,一律固定版本
最初导出镜像时用的是 ghcr.io/bookorbit/bookorbit:latest。latest 是可变标签,任何一次 pull 都可能拉到新版,造成本地和 NAS 版本漂移。后来全部改成固定版本:
- 主程序:
bookorbit/bookorbit:v3.9.0(官方 ghcr 只发 latest,我按镜像里的 version label 打了固定 tag) - 数据库:
pgvector/pgvector:0.8.7-pg18(Docker Hub 官方精确版本,与 pg18 是同一镜像,digest 一致)
启动也加上 --pull never,强制只用本地导入的镜像。
决策 3:APP_URL 不用改成 NAS IP,保持 localhost 也能跑
我一度以为 APP_URL 必须填 NAS 的局域网 IP,否则访问不了。实测推翻了这个假设:
- WebUI 访问、Readest 同步、OPDS 拉书,BookOrbit 都按请求的 Host 头动态生成链接
- 也就是说,你用哪个地址访问,它就用哪个地址生成链接,跟 APP_URL 填什么无关
- APP_URL 真正派上用场的是反向代理、Kobo、OIDC 这类"需要固定对外 origin"的场景
所以纯局域网玩法,APP_URL 保持 http://localhost:3000 完全没问题;只有走域名反代时才改成 https://你的子域名。
五、时间线与量化
整个部署过程可以拆成几个阶段:
| 阶段 | 关键动作 | 量化 |
|---|---|---|
| 调研 | 对比 6 个开源方案,锁定 BookOrbit + Readest | 6 个候选 |
| 本地验证 | Docker Desktop 部署,浏览器实测 WebUI、手机+电脑 Readest 同步 | 2 个容器 |
| 镜像固化 | 导出固定版本镜像包,SHA256 校验后上传 NAS | 2 个 tar,约 1.46GB(1010MB + 450MB) |
| NAS 部署 | 导入镜像、启动服务、frp + 1Panel 配域名 | 端口 3000(服务默认端口) |
| 数据整理 | 70 本书按题材重分 11 类 | 70 本:52 epub / 13 pdf / 2 txt / 1 azw3 / 1 mobi / 1 rar |
| 建库踩坑 | 扫描模式选错,只显示 10 本,改"文件为 Book"后正常 | 70 本全部入库 |
六、抄作业步骤
先决条件
- NAS 能跑 Docker(群晖 Container Manager / 通用 Linux Docker)
- 有公网服务器(可选,仅在要外网访问时需要)
- 书是 EPUB/PDF 这类文字格式才能享受"划线笔记 + 搜索"
本地先验证
- Docker Desktop 部署 BookOrbit:
docker compose up -d - 浏览器打开
http://localhost:3000,用.env里的SETUP_BOOTSTRAP_TOKEN初始化管理员 - 创建 KOReader 同步凭据(设置 → 设备 → KOReader),记下用户名密码
- Readest 里填 Server URL =
http://localhost:3000/+ 上面凭据,四个同步开关全开 - 放一本书,读几页,回 WebUI 看进度是否一致
固化为固定版本并迁移 NAS
docker tag ghcr.io/bookorbit/bookorbit:latest bookorbit/bookorbit:v3.9.0
docker tag pgvector/pgvector:pg18 pgvector/pgvector:0.8.7-pg18
docker save bookorbit/bookorbit:v3.9.0 -o bookorbit-v3.9.0.tar
docker save pgvector/pgvector:0.8.7-pg18 -o pgvector-0.8.7-pg18.tar把两个 tar + .env + docker-compose.yml 上传 NAS:
docker load -i bookorbit-v3.9.0.tar
docker load -i pgvector/pgvector:0.8.7-pg18.tar
docker compose up -d --pull never外网访问(可选)
- frp:把 NAS 的 3000 映射到服务器端口
- 1Panel:建反向代理站点,域名填子域名,代理地址
http://127.0.0.1:<frp远端端口> - 申请免费自动续期证书,开启强制 HTTPS
- DNS 加 A 记录指向服务器公网 IP(新子域名要等传播,几分钟到几小时)
建库(最容易翻车的一步)
新建 Library 时,扫描模式只能创建时选、之后不能改:
- 书籍库:选 "文件为 Book"(默认"文件夹作为书"会把整个分类目录当成一本书,我就在这里翻车,70 本书只显示 10 本)
- 漫画库:选 Series folders(每部漫画一个文件夹)
- 音频库:选 Folder as Book(多轨有声书要聚在一起)
七、验证方式
诚实说明:以下都是我在本次实践中真实做过的。
| 验证项 | 方法 | 结果 |
|---|---|---|
| 本地部署 | docker compose ps + WebUI HTTP 200 + 浏览器初始化页 | ✅ 两个容器 healthy |
| 多端同步 | 本地 Windows + 安卓手机 Readest 各读一本书,回 WebUI 对照进度 | ✅ 用户实测一致(口述) |
| 镜像完整性 | 本地/NAS 两次 SHA256 比对 | ✅ 一致 |
| 外网访问 | 服务器 IP + 端口能访问,DNS 解析检查,最终域名可访问 | ✅ 用户确认搞定(口述) |
| Syncthing 同步 | 修权限后重启套件,文件夹标记生成 | ✅ 自动同步成功 |
| 建库数量 | 改成"文件为 Book"后重新扫描 | ✅ 70 本全部入库(用户确认) |
未逐一验证的部分:阅读统计里每个具体图表和指标,我是从官方文档与界面截图了解的功能,没有在账号里逐项截图比对,这里不写"实测通过"。
八、生态位对比
| 方案 | 强项 | 弱项 |
|---|---|---|
| BookOrbit(本文) | 阅读状态集中、笔记可搜、统计丰富、EPUB/音频/漫画统一 | 生态较新,客户端要配 KOReader 协议 |
| Kavita / Komga | UI 成熟、漫画管理强 | 笔记与高亮双向同步长期未落地 |
| Calibre + Calibre-Web | 书库管理老牌、插件多 | annotations 同步仍是 feature request,UI 传统 |
| 纯 Readest 官方云 | 零部署 | 数据在别人服务器,不满足自建 |
先试再装:官方有在线 Demo,点开就能看界面和统计是否符合你的口味——https://demo.bookorbit.app/。
九、红线 / 速查
- Readest 的 Server URL 只填 IP + 端口,不带
/api/v1/koreader - 镜像别用 latest,固定 tag +
--pull never - 纯局域网 APP_URL 保持 localhost 即可,别画蛇添足改 IP
- 建库的"扫描模式"创建后不可改,书籍库务必选"文件为 Book"
- 只有一个库时删不掉,想重建就先把旧库的文件夹指向改到空目录
- Syncthing 套件用户要对书籍目录有写权限,否则
.stfolder建不出来
十、结语
从"手机电脑进度对不上"这个念头,到跑通本地验证、镜像固化、NAS 部署、frp + 1Panel 域名外网访问、Syncthing 半自动同步、70 本书重分类入库——整个过程真正费神的不是部署命令,而是那几个"看起来无害的默认选项":Server URL 多带了一段路径、latest 标签的漂移、扫描模式的不可逆、以及 APP_URL 的误解。
但值了。现在我打开 BookOrbit,看到的不是一堆文件,而是自己读过多少、读了多久、在哪台设备上读的——一份持续生长的阅读档案。它管的不只是电子书,还有有声书和漫画,是我心里"现代个人媒体库"该有的样子。
- BookOrbit 官网:<https://bookorbit.app/>
- 在线 Demo(先点这里看看喜不喜欢):<https://demo.bookorbit.app/>
- GitHub:<https://github.com/bookorbit/bookorbit>(AGPL-3.0)
- 配套阅读器 Readest:<https://github.com/readest/readest>
一句话收束:好的自建服务,不是把书堆起来,而是把读过的痕迹留下来。
原文首发:www.firstsaofan.top
本文首发于我的个人博客,其他平台为同步发布。若样式丢失或图片不显示,请到站内阅读完整版。
为了统一手机和电脑的阅读进度,我自建了一套 BookOrbit
https://www.firstsaofan.top/archives/bookorbit-readest-reading-sync-and-stats
评论