两台设备接力读一本书：KOReader 云同步完整指南

两台设备接力读一本书KOReader 云同步完整指南【免费下载链接】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晚上在 Kobo 上读到 137 页第二天换 Kindle 继续。KOReader 的云同步能让进度和书签跟过来不用手动记页码。它由两个插件分工plugins/cloudstorage.koplugin/负责文件和数据的上传下载plugins/kosync.koplugin/负责每本书的阅读进度。读完这篇你能配好服务、讲清原理、还会自己排查同步失败。数据是怎么在设备间跑的核心就四步都在 plugins/cloudstorage.koplugin/ 里加载 provider。插件启动时getProviders()见 main.lua扫描 plugins/cloudstorage.koplugin/providers/ 目录凡是实现了config、run、listFolder三个接口的 Lua 文件都会注册为一个云服务商。目前仓库内置三个Dropbox、WebDAV、FTP。过网络与凭证检查。每个 provider 的run()都先调NetworkMgr:willRerunWhenOnline——没网就排队等网好了再跑Dropbox 还会在这一层用 refresh token 换取新的短期访问令牌见DropBox.genAccessTokenproviders/dropbox.lua。执行文件操作。列目录、下载、上传、删除各 provider 各自实现 HTTP 细节返回统一的条目结构。落盘并记账。服务器列表、默认服务器、下载/上传目录都记在settings/cloudstorage.luaCloud.settings_file重启不丢。注意provider 是插件化的。往providers/里放一个满足接口的文件就能加一种新的云服务不用改主程序。KOReader 云存储怎么配四步走通每步只做一件事按顺序来。第 1 步添加云服务。文件管理器 → 菜单 → Cloud storage → 左上角 → 选 Dropbox。弹出的是MultiInputDialog填四栏名称随便起用于显示refresh tokenDropbox 开发者控制台生成旧版长期 token 也可填但已标注 deprecatedAPP_KEY:APP_SECRET应用密钥对长期 token 场景留空起始文件夹如/books留空就是根目录保存后服务器出现在列表页。长按服务器可以设为默认列表里显示 ★、删除、调序。第 2 步下载一本书。进入服务器后点文件即下载默认存到本地下载目录首次用上次浏览目录可改。长按文件可进入多选批量下载、删除。第 3 步设置同步文件夹。长按服务器 → Sync settings分别指定远程文件夹source云端的目录本地文件夹destination设备上的目录两项都设好后服务器弹窗里的 Sync now 才可用见showServerDialog。手动触发后它把远程文件夹的文件按本地缺失或大小不同逐个拉下来逻辑在syncCloud()cloudstorage.lua。第 4 步同步阅读进度。菜单 → Progress sync → 注册/登录然后打开 Automatically keep documents in sync。这部分由 KOSync 插件走同步服务器的 APIplugins/kosync.koplugin/和文件同步是两条独立的通道。三种内置服务的差别一览服务认证方式传输特点Dropboxrefresh token 应用密钥HTTPS API配置稍多有Info可看账户空间WebDAV用户名/密码HTTP PROPFIND适合自建私有服务器FTP用户名/密码FTP简单建议仅可信内网用拆开来看三文件合并和 412 冲突循环同步最容易翻车的两件事KOReader 都有明确对策。① 三文件合并防删除复活。Cloud:sync()plugins/cloudstorage.koplugin/main.lua处理一个数据文件时手里始终有三个版本local_file本地正在用的income_file刚从云端下载的路径带.tempcached_file上一轮上传成功的副本路径带.sync如果只拿本地和云端做并集合并某台设备上删掉的条目会在另一台设备上复活。cached_file记录的是上一轮双方公认的状态拿它和本地比消失的就是本地新删的拿它和云端比消失的就是别处删的。把这些新删除项从两边剔除后再合并结果才正确。源码上方那段长注释把这套算法写得非常清楚值得直接读。② etag 乐观锁遇到 412 就重试。下载云端文件时会带回etag上传时放进If-Match请求头DropBoxApi.uploadFile。上传前文件若被别人改过服务端返回 412代码就删掉刚下载的临时文件、重新下载、重新合并再试循环直到成功while code_response 412 do。合并和上传的具体规则由调用方通过sync_cb回调注入所以 Statistics、Vocabulary Builder 等插件也复用了同一套机制。进度同步什么时候触发自动同步有三个触发点都在 plugins/kosync.koplugin/main.lua打开文档时onReaderReady里若开了auto_sync先拉一次其他设备的最新进度getProgress。翻页累计达标后每翻一页计数器加一达到pages_before_updatePeriodically sync every N pages就调度一次推送设 0 表示不基于翻页自动推。防抖合并所有 API 调用之间有 25 秒 debounceAPI_CALL_DEBOUNCE_DELAY连续快速翻页不会把网络打满。另外两个方向各有三档策略Sync to a newer state云上有更新状态和Sync to an older state云上有更旧状态各自可选 Silently静默执行/ Prompt弹窗询问/ Never不执行。默认前者是 Prompt、后者是 Never——只跟新不往回退。进阶设置与网络优化这些项都在 Progress sync 菜单和云存储设置里改完即保存文档匹配方式Binary整文件 MD5 一致才算同一本或 Filename同名即同一本。同一本书换了源文件时选 Filename 更省事。Custom sync server把进度同步指向自建的同步服务器。Device hostname给本机起个同步用的主机名多设备日志里好认。Send document metadata默认关官方服务器会忽略自建服务器可用来利用。KOSync 的设置结构长这样default_settings{ auto_sync false, -- 默认关手动开 pages_before_update 5, -- 每 5 页推送一次进度 sync_forward 1, -- 遇到更新状态1 询问 / 2 静默 / 3 禁用 sync_backward 3, -- 遇到更旧状态默认禁用 checksum_method 0, -- 0 二进制比对 / 1 按文件名 }网络侧的建议自动同步依赖 Wi-Fi 在位。Android 上若 自动开 Wi-Fi 策略不是 turn_on插件会直接把auto_sync降级关闭并在日志里给出警告。大批量上传用 Trapper 包裹可中途暂停或取消不必担心卡死。Dropbox 大目录列文件时走 cursor 分页fetchAdditionalFolders几百个文件也不会一次超时。记住 Sync now 是单向的只把云端有的拉到本地本地文件要上传请用菜单里的 Upload。同步失败的排查清单按出现概率从高到低排网络断了或没连上。提示 Could not fetch servers content 或 Something went wrong when syncing 时先确认 Wi-Fi。日志在koreader/crash.log搜CloudStorage、DropBoxApi能看到每次失败的状态码。Dropbox 授权失效。短期 token 只有 4 小时有效期代码每次会话自动用 refresh token 换新的genAccessToken如果 refresh token 本身过期或APP_KEY:APP_SECRET填错就回到设置里重新生成。412 冲突反复重试。通常重下重传即可成功如果一直卡多半是两台设备正对着同一个云端文件写错开操作时间。单文件超过 150 MB。上传入口会直接拦截File size must be less than 150 MB大文件先压缩或换服务。进度同步不自动跑。检查 Automatically keep documents in sync 是否勾选Android 上再确认 Wi-Fi 自动开启策略日志里有Automatic sync has been disabled就是它干的。收尾Cloud Storage 管文件和数据的搬运KOSync 管阅读进度两条通道各走各的协议互不阻塞。把 provider 接口和三文件合并这两处读懂之后剩下就是按需调参数。云存储插件源码plugins/cloudstorage.koplugin/Dropbox API 封装token 换取、上传/下载plugins/cloudstorage.koplugin/providers/dropbox.lua进度同步插件plugins/kosync.koplugin/数据存储说明doc/DataStore.md【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考