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 页面和一套完整统计。

三、方案:三个角色,各司其职

整套东西拆开看,就三个角色:

  1. BookOrbit:自建服务端,跑在 NAS 的 Docker 里,装 PostgreSQL 数据库。它是唯一数据源,提供 WebUI 书架、阅读统计、笔记搜索、OPDS 供客户端拉书。
  2. Readest:跨平台阅读器(Windows/安卓/iOS/Web),负责读书和做笔记,通过 KOReader 同步协议连 BookOrbit。
  3. 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 + Readest6 个候选
本地验证Docker Desktop 部署,浏览器实测 WebUI、手机+电脑 Readest 同步2 个容器
镜像固化导出固定版本镜像包,SHA256 校验后上传 NAS2 个 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 这类文字格式才能享受"划线笔记 + 搜索"

本地先验证

  1. Docker Desktop 部署 BookOrbit:docker compose up -d
  2. 浏览器打开 http://localhost:3000,用 .env 里的 SETUP_BOOTSTRAP_TOKEN 初始化管理员
  3. 创建 KOReader 同步凭据(设置 → 设备 → KOReader),记下用户名密码
  4. Readest 里填 Server URL = http://localhost:3000/ + 上面凭据,四个同步开关全开
  5. 放一本书,读几页,回 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 / KomgaUI 成熟、漫画管理强笔记与高亮双向同步长期未落地
Calibre + Calibre-Web书库管理老牌、插件多annotations 同步仍是 feature request,UI 传统
纯 Readest 官方云零部署数据在别人服务器,不满足自建

先试再装:官方有在线 Demo,点开就能看界面和统计是否符合你的口味——https://demo.bookorbit.app/。

九、红线 / 速查

  1. Readest 的 Server URL 只填 IP + 端口,不带 /api/v1/koreader
  2. 镜像别用 latest,固定 tag + --pull never
  3. 纯局域网 APP_URL 保持 localhost 即可,别画蛇添足改 IP
  4. 建库的"扫描模式"创建后不可改,书籍库务必选"文件为 Book"
  5. 只有一个库时删不掉,想重建就先把旧库的文件夹指向改到空目录
  6. Syncthing 套件用户要对书籍目录有写权限,否则 .stfolder 建不出来

十、结语

从"手机电脑进度对不上"这个念头,到跑通本地验证、镜像固化、NAS 部署、frp + 1Panel 域名外网访问、Syncthing 半自动同步、70 本书重分类入库——整个过程真正费神的不是部署命令,而是那几个"看起来无害的默认选项":Server URL 多带了一段路径、latest 标签的漂移、扫描模式的不可逆、以及 APP_URL 的误解。

但值了。现在我打开 BookOrbit,看到的不是一堆文件,而是自己读过多少、读了多久、在哪台设备上读的——一份持续生长的阅读档案。它管的不只是电子书,还有有声书和漫画,是我心里"现代个人媒体库"该有的样子。

一句话收束:好的自建服务,不是把书堆起来,而是把读过的痕迹留下来。


原文首发:www.firstsaofan.top

本文首发于我的个人博客,其他平台为同步发布。若样式丢失或图片不显示,请到站内阅读完整版。