KOReader 跨设备同步怎么配：批注与阅读进度 5 分钟上云指南-平芜编程栈

KOReader 跨设备同步怎么配：批注与阅读进度 5 分钟上云指南

【免费下载链接】koreaderAn ebook reader application supporting PDF, DjVu, EPUB, FB2 and many more formats, running on Cervantes, Kindle, Kobo, PocketBook and Android devices项目地址: https://gitcode.com/GitHub_Trending/ko/koreader

墨水屏上读到第 5 章、随手记了 3 条批注，切到手机想继续——进度回到第 1 页，批注也没了。这篇指南用大约 5 分钟，帮你在 KOReader 里配好跨设备同步：以 Dropbox、WebDAV 或 FTP 作为云端中转，让阅读进度和批注数据跟到哪台设备都能接着读。

1. 先选型：Dropbox、WebDAV、FTP 哪个适合你

KOReader 的云存储功能由 plugins/cloudstorage.koplugin/ 插件提供，开箱即支持三家服务。三者差别不在"功能多少"，而在"数据放哪、你愿意花多少力气"：

服务	上手成本	数据可控性	适合人群
Dropbox	最低：开发者控制台拿令牌，填进去就能用	数据存在 Dropbox 服务器，用它的空间配额	个人用户、有多台设备的读者
WebDAV	较高：需要一台 WebDAV 服务器（自搭或租用）	数据在自己手里，规则自己定	重视数据自主权的人、小团队
FTP	中等：需要一台 FTP 服务器	可自持，但协议本身加密弱	内网里的技术用户

🔒 一句话提醒：FTP 传输几乎不加密，只建议放在可信的内网里用，别暴露到公网。

2. 快速上手：5 分钟完成 KOReader Dropbox 配置

下面以 Dropbox 为例走一遍，共 5 步。WebDAV / FTP 的界面结构相同，只是填的字段换成服务器地址、账号密码。

在 Dropbox 拿三样凭证。打开 Dropbox 开发者控制台，创建一个应用并开启 Dropbox API 权限，然后记下：APP_KEY:APP_SECRET（应用身份，格式类似abc123:def456）和Refresh Token（刷新令牌，可以理解为一张不过期的"授权书"，KOReader 用它随时换新的短期访问令牌）。
打开云存储菜单。在 KOReader 主菜单里找到Cloud storage（云存储）项。
添加服务器并填 4 个字段。点添加后会出现一个对话框（源码在 plugins/cloudstorage.koplugin/providers/dropbox.lua）：
- Name：随便起的显示名，如我的 Dropbox
- Dropbox refresh token：第 1 步拿到的 Refresh Token
- Dropbox <APP_KEY>:<APP_SECRET>：应用密钥对
- Start folder：起始目录，例如/books（填/则是根目录）
指定同步目录。回到服务器列表，用Sync folder功能设置两个目录：远程源文件夹（云端的哪一层）和本地目标文件夹（下载到设备哪个位置）。两个都设好后，同步菜单项才会变为可用。
点同步。界面会逐个显示"Downloading file (n/N)"，结束后出现Successfully synchronized.的提示。

3. 验证同步生效：一个双设备小实验 🧪

配完别急着收工，花 3 分钟做个实验，确认链路真的通了。

设备 A：把一个小文件（比如一段笔记test.md）放进 Dropbox 的 Start folder（/books）下。
设备 A：执行第 2 节的同步，打开本地目标文件夹，确认test.md出现了。
设备 B：用同一账号按第 2 节配好同样的服务器与同步目录，执行同步。

✅成功的判定标准：设备 B 的目标文件夹里出现了同一份test.md，内容一致。

❌失败了怎么办：直接跳到第 6 节：故障排查，按顺序过一遍即可。

阅读进度本身还有更省事的通道：内置的Progress sync插件（plugins/kosync.koplugin/）注册 KOReader 服务器账号后，会自动把你的阅读进度推到服务器，设备 B 打开同一本书，进度就停在你上次的位置。

4. 幕后原理：同步的到底是什么？

这一节只回答三个问题，不贴代码。

同步的内容分三条线

阅读进度：由 Progress sync 负责，把页码等进度推到 KOReader 服务器，可选是否附带书籍元数据。
批注与阅读数据：Statistics（阅读统计）和 Vocabulary builder（生词本）这类插件的数据文件，通过云存储走三文件机制同步（下一小节）。
书籍与文件：云存储的 Sync folder 做的是文件级同步——远端有、本地没有或大小不同的文件，会被下载到目标文件夹。

冲突怎么解：三份文件一起比较

同步某一数据文件时，KOReader 手里其实有三份：正在用的本地文件、刚从云端拉下来的临时文件（.temp）、以及上一轮上传时的缓存副本（.sync）。

为什么要第三份？只比较本地和云端的话，你在 A 设备删掉的条目，会因为 B 设备还留着而"复活"。用缓存副本对照，才能认出"哪些是最近被删的"，先剔除再合并，删掉的内容不会死灰复燃。上传时还带版本校验，若云端文件在此期间被别人改过，就重新下载再合并，直到一次成功。

何时触发

进度：开启自动同步后按你设定的翻页间隔推送，两次操作间隔不足 25 秒的会合并，避免刷屏式请求；后台还有定时推送兜底。
云存储：从 Cloud storage 菜单手动触发，不会悄悄跑流量。

5. 进阶玩法：让同步更合身

选择性同步

Progress sync 支持分别控制"向前/向后同步"的策略：询问、静默执行或完全关闭；也可以选择不发送书籍元数据，只同步进度本身。也就是说，你可以只让进度跟手，批注类数据留在本地。

弱网环境优化 📶

推送有 25 秒防抖：连续快速翻页只会产生一次请求。
不稳定的网络下，建议关掉自动同步，改用手动，或依赖它的定时推送。
同步的是小文件（进度、统计数据），单次流量本身不大，不必担心。

云端空间清理

Dropbox 服务器条目里有Info按钮，点一下能看到账户类型、已用空间和总空间。隔段时间把不再需要的旧文件从同步文件夹里删掉即可。

6. 故障排查：按顺序查这 4 步

网络：设备离线时请求会被挂起，网络恢复后 KOReader 会自动重跑，先确认能正常联网。
凭证过期：Dropbox 短期令牌只有 4 小时有效期，每次会话用 Refresh Token 换新。如果反复报错，优先复查APP_KEY:APP_SECRET和 Refresh Token 是否填对、应用是否还有效。
本地空间：目标文件夹所在磁盘是否还有空间，尤其是一口气同步大书的时候。
看日志定位：打开 KOReader 的日志文件，搜索DropBoxApi或sync关键词。cannot get access token指向凭证问题，cannot upload/download file指向网络或权限问题，报错里的 HTTP 状态码（如 401、409）能进一步缩小范围。

7. 安全提醒（4 条）

Refresh Token 等于长期授权，泄露后去 Dropbox 控制台吊销；配置完成后它保存在 KOReader 本地设置文件里，设备借人前留意一下。
日常访问用的 4 小时短期令牌风险窗口小，但仍不建议把凭证截图发到聊天群。
WebDAV / FTP 自架服务器要管好访问控制；FTP 仅内网使用。
重要批注和生词本，定期用内置的导出功能存一份到本地或另一台设备，双保险。