桌面应用跨平台前端【免费下载链接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.项目地址https://gitcode.com/gh_mirrors/re/readest点击查看免费下载本篇文章基于 Readest 仓库中的设计分析文档《Grimmory Native Sync》apps/readest-app/.claude/memory/grimmory-native-sync.md完整梳理在 Readest 中为GrimmoryBooklore 的一个分支Java/Spring 后端包名org.booklore构建原生阅读进度同步的完整技术方案。你将掌握 Grimmory 原生 REST API 的认证与进度协议、其 Spring Security CORS 配置的隐藏陷阱登录端点在浏览器跨域场景下不可用的根因、官方 KOReader 插件koplugin的身份映射机制以及 Readest 侧以 KOSync 为模板的扩展点设计与 OPDS 采集期身份捕获这一最佳匹配策略。一、背景为什么要原生同步而不是继续走 OPDS KOReader 兼容路径Readest 此前接入 Grimmory 的方式是借助OPDS 目录 KOReader 兼容协议绕行。该方案存在一个结构性问题同一本书的阅读进度会在KOReader ↔ Kobo ↔ Grimmory三个生态之间来回流转形成三方数据不同步desync。文档明确指出讨论见 grimmory-tools/discussions/1417。绕行路径的问题在于KOReader 兼容端点/api/koreader/**以 KOReader 自己的身份体系X-Auth-UserX-Auth-Key和进度格式CREngine XPointer工作而 Grimmory 原生体系使用 JWT 认证与自有的BookFileProgress结构。两种体系间的转换层越多进度错位、身份误判的概率就越高。因此目标很清晰接入 Grimmory 的原生 API/api/v1/**替换掉 KOReader 兼容绕行路径。二、Grimmory 原生 API 表面Native API Surface方案的核心是直接消费 Grimmory 的原生 REST API文档记录了以下接口全貌2.1 认证JWT Bearer端点方法请求体响应POST /api/v1/auth/loginPOST{username, password}{accessToken, refreshToken, expires}POST /api/v1/auth/refreshPOST{refreshToken}刷新后的 token 三元组Token 有效期设计为accessToken 2 小时、refreshToken 30 天符合典型的短期访问令牌 长期刷新令牌模式。所有后续数据端点均携带Authorization: Bearer accessToken。2.2 阅读进度与书目进度上报POST /api/v1/books/progress请求体为{ bookId: book.id, fileProgress: { bookFileId: bookFile.id, progressPercent: 0-100, positionData: CFI for EPUB, positionHref: spine href, ttsPositionCfi: TTS 朗读位置 }, dateFinished: 完成日期 }其中positionData对 EPUB 使用CFICanonical Fragment Identifier定位ttsPositionCfi用于同步 TTS 朗读位置progressPercent取值范围 0-100。书目列表GET /api/v1/books。关键限制书目 DTO不暴露文件哈希也没有原生的按哈希查询端点。这意味着无法像 KOSync 那样直接以文件哈希为键做进度关联必须退而求其次按元数据匹配详见第五节。注释/书签/下载/封面注释/api/v1/annotations/**书签/api/v1/bookmarks/**下载/api/v1/books/{id}/download支持 HTTP Range 断点续传封面/api/v1/media/{id}/cover2.3 KOReader 兼容路径将被替换的旧方案Grimmory 仍保留/api/koreader/**兼容端点使用X-Auth-UserX-Auth-KeyX-Auth-Key md5(password)头认证。这是当前 Readest 绕行路径所依赖的接口也是本次原生同步改造要替换掉的部分。三、CORS 分析Spring Security per-filter-chain 配置的隐藏陷阱文档对 Grimmory 后端的SecurityConfig.java做了逐行级分析这是整个方案中最容易出现浏览器端连不上、桌面端却一切正常诡异现象的部分。3.1 配置事实没有全局 CorsFilter / addCorsMappingsCORS 策略逐 filter-chain 独立配置。策略位于SecurityConfig.java约 340-368 行origins 默认*可用环境变量ALLOWED_ORIGINS覆盖且使用setAllowedOriginPatterns因此*可以与 credentials 并存允许所有 HTTP 方法allowed-headers 是固定白名单Authorization, Cache-Control, Content-Type, Range, If-None-Match, If-Modified-Since—— 不是*并且明确排除了X-Auth-User/X-Auth-KeyallowCredentials true。3.2 哪些链路开了 CORS哪些没开开了.cors()的链jwtApiorder 10匹配/api/**减去白名单外的路径覆盖 books/progress/annotations/bookmarks/reading-sessions/koreader-usersbookDownloadorder 8epub / audiobook / custom-font / wsorder 5-9。没开.cors()的链opdsorder 1、komgaorder 2、koreaderorder 3、koboorder 3、media/coverorder 4、catch-all staticorder 11。3.3 关键缺口登录端点无 CORS/api/v1/auth/login与/auth/refresh在SecurityConfig.java约 265-289 行被从 order 10 的 matcher 中白名单排除它们不要求 JWT因此落入了 order 11 的 catch-all 静态资源链 ——该链没有 CORS 配置。结论是跨域浏览器登录必然失败预检请求拿不到允许的跨域响应头。而这一点对 Grimmory 自带的 SPA 不可见因为它的前端与后端同源部署classpath:/static/提供静态资源浏览器根本不会触发跨域。只有像 Readest Web 这样的第三方跨域客户端才会踩中这个坑。四、对 Readest 各端的影响Tauri 原生与 Web 构建的分化文档给出了明确的端侧结论这是方案落地的关键分叉Tauri 桌面 / 移动端CORS 完全无关。Readest 在 Tauri 下使用tauri-apps/plugin-http的原生 HTTP 栈见 KOSyncClient.ts 中对tauriFetch的使用不受浏览器同源策略约束所有端点包括登录均可直连。Readest Web 构建JWT 数据端点拿到 token 后可以跨域工作但登录login和 koreader 端点必须经过服务端代理或同源反向代理 —— 这与 Readest 现有的/api/kosync、/api/opds/proxy是同一个模式。Readest 现有的 KOSync 代理实现 src/pages/api/kosync.ts 正是可复用的模板它接收{serverUrl, endpoint, method, headers, body}对 endpoint 做正则白名单校验/\/users\/create/, /\/users\/auth/, /\/syncs\/progress/、强制http/https协议、通过isLanAddress拦截内网地址SSRF 防护再把请求转发到目标服务器并透传状态码。一个/api/grimmory代理只需沿用同样的校验骨架把白名单换成/api/v1/auth/login、/api/v1/auth/refresh等即可。五、Readest 侧扩展点设计以 KOSync 为模板文档为原生同步预留了一组与现有 KOSync 功能一一对应的扩展点全部以仓库中真实存在的 KOSync 实现为模板新组件计划模板仓库现有实现职责src/services/grimmory/GrimmoryClient.tssrc/services/sync/KOSyncClient.tsconnect/getProgress/updateProgress三个核心方法对应 KOSyncClient 的connect登录 注册、getProgressGET /syncs/progress/{hash}、updateProgressPUT /syncs/progresssrc/app/reader/hooks/useGrimmorySync.tssrc/app/reader/hooks/useKOSync.ts拉取 / 推送 / 冲突处理的状态机监听push-kosync、pull-kosync、flush-kosync事件打开书籍时拉取一次、进度变化时防抖5000ms自动推送、窗口失焦时 flushGrimmorySettingsKOSyncSettingssrc/types/settings.ts服务器地址、用户名、token、设备名等配置结构GrimmoryForm.tsxKOSyncFormIntegrationsPanel.tsx 中subPage kosync分支设置页集成表单在 IntegrationsPanel 的 subPage 路由中注册5.1 进度映射是核心难点Readest 的BookProgress.location存的是CFIGrimmory 的BookFileProgress.positionData也是CFI这是二者天然对齐的地方而 Grimmory 后端另有EpubCfiService负责CFI ↔ XPointer双向转换。对照现有实现useKOSync.ts 中的generateKOProgress展示了 Readest 侧如何把内部进度转成协议格式从progress.location取 CFI经getXPointerFromCFI转为 XPointer 并缓存到config.xpointer反过来applyRemoteProgress用getCFIFromXPointer把远端 XPointer 还原为 CFI 再view.goTo(cfi)。原生 Grimmory 路径因为两端都是 CFI转换环节更少但仍然需要处理畸形 CFIisMalformedLocationCfi分支回退到上次已知良好的位置和固定版式FXL书籍按页码而不是 CFI 定位这两类边界情况这些逻辑在 KOSync hook 中已有成熟实现可直接复用。六、实现状态垂直切片已构建后按维护者要求回滚文档如实记录了这段工作的状态未发布NOT shipped2026-06-23 曾构建完整垂直切片 ——GrimmoryClientuseGrimmorySynchook /api/grimmory代理 GrimmoryForm/IntegrationsPanel 集成 settings/types 类型 BookConfig 中缓存元数据匹配身份 原生/api/v1/books/progress上报测试与 lint 全绿 —— 但随后按维护者要求回滚not ready yet。工作树已完全恢复grimmory 相关文件全部删除7 个被改动的共享文件已还原lint test 恢复通过。回滚的原因是原生进度的身份匹配方案identity story被判定还不够成熟—— 更稳健的路径OPDS 采集期捕获、或镜像官方 koplugin 的做法当时尚未构建。因此文档将本次分析沉淀为两条核心发现FINDING A / FINDING B以备后续重试。七、FINDING A官方 koplugin 的身份映射机制它并不使用原生进度接口官方插件grimmory-tools/grimmory.koplugin的实践是文档最重要的外部参照系其核心设计是双 ID 分离本地 SQLite 表book(book_path, partial_md5, grimmory_id)每个文件同时存两个 ID。路径一grimmory 原生 IDgrimmory_idbook.id用于会话sessions/下载/书架。解析方式是只按 ISBN13/ISBN10/ISBN/ASIN 精确匹配doc_metadata.lua的isBook判定不按书名/作者匹配匹配成功后通过repository.upsertBook(path, book.id)持久化。会话上报走POST /api/v1/reading-sessions以grimmory_id为键。路径二阅读进度仍然走 KOReader 兼容端点GET/PUT /api/koreader/syncs/progress[/{partialMD5}]以 KOReader 自己的util.partialMD5(book_path)为键不是 grimmory_id。凭证由原生接口GET/PUT /api/v1/koreader-users/me自动配发getKoreaderCredentials→md5(secret)→X-Auth-User/X-Auth-Key。结论官方插件中被验证过的进度路径恰恰是复用现有 KOSync 的 XPointer / partial-MD5 机制去打/api/koreader/...而不是原生进度 API。对 Readest 而言这意味着已有的 KOSync 基础设置可以原样迁移。7.1 必须验证的哈希陷阱Java 移位溢出 vs LuaJIT 移位文档记录了一个非常隐蔽的兼容性风险点值得任何实现者先行验证后端FileFingerprint.generateHash在采样时计算1024L -2Java 中 long 位移量超出范围会被掩码-2最终落到偏移0而 KOReader 的 LuaJITbit.lshift(1024, -2)得到偏移256两者对文件的第一块采样位置可能不一致导致同一文件算出的 partial-MD5 不同 ⇒按哈希的进度同步可能静默失配。文档明确要求在依赖该路径前拿一个真实下载的文件用两种方式各算一次哈希进行核验。八、FINDING BOPDS 采集期捕获 —— 最优身份策略尚未构建这是文档选定的最佳匹配方案核心洞察是Grimmory 的 OPDS 源在采集下载时就把两个 ID 都暴露出来了OPDS 指纹OpdsFeedService.java每个id都是urn:booklore:*根urn:booklore:root、书目urn:booklore:book:{bookId}feed 标题为Booklore Catalogself/start 链接指向/api/v1/opds。采集链接同时编码两个 IDlink href/api/v1/opds/{bookId}/download?fileId{fileId} relhttp://opds-spec.org/acquisition/路径中的bookId 查询参数fileId一次全部拿到。Readest 侧的实现落点已经有现实基础OPDS 页面 src/app/opds/page.tsx 在下载书目时持有url且仓库已实现upsertOPDSSourceMappingsrc/services/opds/sourceMap.ts把(catalogId, sourceUrl, bookHash)写入opds_source_mappings表ON CONFLICT(catalog_id, source_url) DO UPDATE并可经findBookByOPDSSources反查书目。原生同步只需在 OPDS 下载点解析bookIdpath与fileIdquery再用urn:booklore:条目 ID 或与配置的 grimmory serverUrl 同源来佐证把两个 ID 写入 BookConfig 即可。为什么这是最优解身份来自权威来源Grimmory 自己下发的链接无需任何元数据猜测对 Grimmory 来源的书目而言是唯一不会错配的身份策略。九、身份匹配策略完整排序当书籍不是经 Grimmory OPDS 采集而来例如本地导入时需要按如下优先级做身份匹配文档给出的原生路径排序OPDS 采集期捕获权威从下载链接直接拿到bookIdfileId缓存 ID此前匹配成功过的(path, grimmory_id)映射ISBN / ASIN 精确匹配唯一被官方插件验证的元数据字段受限的 书名作者 匹配必须额外要求格式format与fileSizeKb一致才放行遇到歧义时必须弃权—— 因为错误匹配会污染另一本书的进度。fileSizeKb在 BookFile 上有暴露可作为尺寸佐证哈希不暴露。文档特别强调了策略 4 的纪律宁可不同步不可错同步。这与 useKOSync.ts 中远端 XPointer 无法本地解析时保持 unresolved 状态、绝不拿百分比硬凑的冲突处理哲学一脉相承。十、结论与工程启示这份设计分析文档的价值在于它是一份可执行的失败复盘完整记录了 API 契约、逐行级 CORS 分析、端侧分化结论、扩展点模板映射、以及两轮身份匹配研究官方 koplugin 实证 OPDS 采集期捕获设计。对后续任何要重新发起 Grimmory 原生同步的开发者它直接给出了四条可落地结论认证走 JWT 原生接口但 Web 端登录必须过代理SecurityConfig.java的白名单排除导致/api/v1/auth/login无 CORS模板是 src/pages/api/kosync.ts进度同步优先复用 KOSync 的 partial-MD5 / XPointer 机制打/api/koreader/**这是官方 koplugin 验证过的路径但在依赖前必须核验 Java1024L -2与 LuaJITbit.lshift(1024,-2)的哈希采样差异身份匹配以 OPDS 采集期捕获为最优解urn:booklore:* 双 ID 下载链接落点已具备upsertOPDSSourceMapping基础设施元数据兜底匹配必须用 ISBN/ASIN 或书名作者格式文件大小四元组并严格弃权扩展点全部以现有 KOSync 实现为模板GrimmoryClient↔KOSyncClient、useGrimmorySync↔useKOSync、GrimmoryForm↔KOSyncForm、GrimmorySettings↔KOSyncSettings进度字段 CFI 两端天然对齐工程量可控。Readest 侧可继续深入阅读的仓库资源KOSyncClient.ts、useKOSync.ts、IntegrationsPanel.tsx、src/pages/api/kosync.ts、sourceMap.ts、xcfi 转换工具。赞分享桌面应用跨平台前端【免费下载链接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.项目地址https://gitcode.com/gh_mirrors/re/readest点击查看免费下载相关推荐Predis集群分片策略Hash算法与SlotRange映射原理Predis集群分片策略Hash算法与SlotRange映射原理 你是否在使用Redis集群时遇到过数据分布不均、热点Key集中导致性能瓶颈的问题Predi数据库后端FillableLoaders 动画原理深入剖析如何通过 CAShapeLayer 实现流畅进度动画FillableLoaders 动画原理深入剖析如何通过 CAShapeLayer 实现流畅进度动画 FillableLoaders 是一个基于 SwiftTypeSpec Java 客户端发射器per-service api-version 映射的处理策略与单版本客户端生成原理TypeSpec Java 客户端发射器per service api version 映射的处理策略与单版本客户端生成原理 本文以 TypeSpec 仓库中编程语言编译器后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考