Joplin 同步目标快照格式详解从笔记序列化到同步版本迁移测试【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin本文以 Joplin 仓库中的一份真实同步快照文件 4782f467eb8c4d769b3538f069c39cfe.md 为解剖对象完整讲解 Joplin 笔记在同步目标sync target中的序列化格式正文、资源引用、元数据头、字段类型与取值语义。同时结合 syncTargetUtils.ts 与 synchronizer_MigrationHandler.test.ts说明这类快照文件如何被用于驱动同步版本迁移测试。读完本文你将掌握 Joplin 数据文件在存储层的真实形态能够自行阅读、校验甚至构造这类快照文件。一、快照是什么Joplin 同步目标在测试中的定格Joplin 的同步功能会把本地数据推送到各类同步目标文件系统、Nextcloud、WebDAV、Joplin Cloud 等同步目标上的数据本质上是一组按约定命名的文件。为了让同步版本升级migration可被自动化验证仓库把某个历史版本首次同步后的同步目标内容整体保存下来形成syncTargetSnapshots快照目录。同步目标快照目录 的组织方式为syncTargetSnapshots/ ├── 1/ │ ├── e2ee/ # 端到端加密模式下的快照 │ └── normal/ # 未加密模式下的快照 ├── 2/ │ ├── e2ee/ │ └── normal/ └── 3/ ├── e2ee/ └── normal/顶层数字1/2/3对应syncVersion同步协议版本号代表快照所处的历史版本normal子目录保存未加密同步数据e2ee子目录保存启用了端到端加密E2EE后的数据形态。在 synchronizer_MigrationHandler.test.ts 的注释里明确写明了快照的用途与生成方式To create a sync target snapshot for the current syncVersion... These tests work by a taking a sync target snapshot at a version n and upgrading it to n1.即测试流程是取版本 n 的快照 → 升级到 n1 → 校验数据没有被破坏。被选中的这份1/normal/4782f467eb8c4d769b3538f069c39cfe.md正是 syncVersion 1、未加密模式下的一条笔记数据。二、笔记序列化格式正文 元数据头Joplin 把每条同步项保存为一个独立的.md文件。打开 4782f467eb8c4d769b3538f069c39cfe.md可以看到它由两大部分构成正文区与元数据头Front Matter。2.1 正文区与资源引用语法文件开头是笔记内容note1 [](https://link.gitcode.com/i/d9d3df84eacb38270325541fdd87d1f4)第一行note1是笔记标题与正文内容该测试笔记内容极简第二行是图片的 Markdown 引用其 URL 为:/4b938c5212c24110afdfe523e0d85fef。这里的:/是 Joplin 特有的资源引用协议前缀冒号后紧跟资源 IDresource id。渲染时 Joplin 会将其解析为本地缓存或同步目标上的真实图片文件。在 syncTargetUtils.ts 的校验逻辑checkTestData中正是用markdownUtils.extractImageUrls(note.body)从正文提取图片 URL取urls[0].substr(2)得到资源 ID再用Resource.load(resourceId)验证资源确实存在——这从测试代码侧印证了:/resourceId的解析规则。正文区之后空一行紧接着是键值对形式的元数据头每行格式为字段名: 值。2.2 身份与归属字段字段快照中的值语义id4782f467eb8c4d769b3538f069c39cfe32 位十六进制全局唯一 ID也是文件名主体parent_id36ad2ccddc2542a9a5c41a1fbde269b1父对象 ID此处为所在文件夹 subFolder2type_1对象类型枚举值1 表示笔记Notetype_直接对应 BaseModel.ts 中的ModelType枚举export enum ModelType { Note 1, Folder 2, Setting 3, Resource 4, Tag 5, NoteTag 6, Search 7, Alarm 8, MasterKey 9, ItemChange 10, NoteResource 11, ResourceLocalState 12, Revision 13, Migration 14, SmartFilter 15, Command 16, NoteEmbedding 17, ConflictNoteState 18, }BaseModel还维护了MODEL_TYPE_TO_NAME映射TYPE_NOTE→ModelType.Note、TYPE_FOLDER→ModelType.Folder等序列化时通过type_字段区分同步目标的顶层条目类型。2.3 时间字段字段快照中的值语义created_time2020-07-25T10:36:57.196Z服务端/同步记录中的创建时间UTC ISO 8601updated_time2020-07-25T10:36:57.400Z最近更新时间user_created_time2020-07-25T10:36:57.196Z用户视角的创建时间user_updated_time2020-07-25T10:36:57.400Z用户视角的最近更新时间Joplin 区分系统时间与用户时间前者用于同步冲突处理与排序后者用于展示用户手动设置笔记时间时只会影响 user_ 前缀字段。快照中两组时间完全一致说明这条笔记没有经过手动改时。2.4 排序字段orderorder: 1595673417196order是笔记在文件夹内的排序键。取值1595673417196恰好是created_time2020-07-25T10:36:57.196Z对应的 Unix 毫秒时间戳说明 Joplin 默认以毫秒时间戳作为排序依据值越大排序越靠后。2.5 功能开关类字段字段值语义is_conflict0是否为冲突副本1表示该笔记是同步冲突时生成的副本is_todo0是否为待办checkbox 列表1为待办todo_due0待办截止时间毫秒时间戳0表示未设置todo_completed0待办完成时间0表示未完成markup_language1笔记标记语言1 Markdown2 HTMLis_shared0笔记是否参与共享Joplin Server 共享笔记本场景markup_language的取值在 renderer/types.ts 中定义export enum MarkupLanguage { Markdown 1, Html 2, }is_conflict在 Note.ts 中被列入同步字段白名单并且在查询、统计、通知等大量 SQL 中以is_conflict 0作为过滤条件如 Note.ts冲突笔记默认不会出现在正常列表里。当两客户端同时修改同一笔记时Joplin 会把其中一个版本存为冲突笔记并置is_conflict 1参见 Note.ts。2.6 来源与审计字段字段值语义author空作者标识多数场景下为空source_url空来源 URL剪藏clipper时记录原始网页地址sourcejoplin数据来源类型标识source_applicationnet.cozic.joplintest-cli创建该数据的应用标识此处表明是测试环境下的 CLI 客户端net.cozic.joplin为 Joplin 应用标识test-cli后缀表示测试构建application_data空应用私有扩展数据source_application这类字段对调试很有价值当同步目标上出现异常数据时可以通过它快速判断是哪个客户端、哪个渠道写入的。2.7 加密字段encryption_cipher_text: encryption_applied: 0encryption_applied: 0表示该笔记当前未加密encryption_cipher_text为空字符串。启用端到端加密后这两个字段会发生变化encryption_applied置1encryption_cipher_text写入密文。与之形成对照的是目录 1/e2ee 下的快照文件——同名测试数据在 E2EE 模式下的完整序列化形态正文内容会被密文取代。2.8 地理信息字段latitude: 0.00000000 longitude: 0.00000000 altitude: 0.0000笔记支持记录经纬度与海拔移动端拍照/定位场景。快照中均为0表示该笔记未附加地理信息。三、资源与文件夹的序列化配套快照解读note1引用的图片资源在同步目标上也是独立的.md文件4b938c5212c24110afdfe523e0d85fef.mdphoto.jpg id: 4b938c5212c24110afdfe523e0d85fef mime: image/jpeg filename: created_time: 2020-07-25T10:36:57.397Z updated_time: 2020-07-25T10:36:57.397Z user_created_time: 2020-07-25T10:36:57.397Z user_updated_time: 2020-07-25T10:36:57.397Z file_extension: jpg encryption_cipher_text: encryption_applied: 0 encryption_blob_encrypted: 0 size: 2720 is_shared: 0 type_: 4type_: 4对应ModelType.Resource文件首行photo.jpg是资源原始文件名测试中由 syncTargetUtils.ts 的shim.attachFileToNote(note, supportDir/photo.jpg)附加mime、file_extension、size描述文件本体实际图片字节作为二进制 blob 另行存储size: 2720即其字节数encryption_blob_encrypted: 0表示资源二进制内容也未加密。文件夹同样以.md文件序列化。note1的父级是 36ad2ccddc2542a9a5c41a1fbde269b1.mdsubFolder2再往上是 77007052daa34970ba8c88b56c8789ac.mdfolder1。文件夹元数据相对精简id、时间、parent_id、is_shared、type_: 2且没有正文区。由此可以还原出本快照对应的完整目录树folder1 (77007052daa34970ba8c88b56c8789ac) └── subFolder2 (36ad2ccddc2542a9a5c41a1fbde269b1) └── note1 (4782f467eb8c4d769b3538f069c39cfe) └── 资源 photo.jpg (4b938c5212c24110afdfe523e0d85fef, image/jpeg, 2720 B)这与 syncTargetUtils.ts 中的testData结构一致folder1.subFolder2.note1带resource: true且打了tags: [tag1]说明整组快照正是由这套测试数据生成器产出的。四、这些快照如何驱动同步版本迁移测试快照文件不是孤立的数据它们是 synchronizer_MigrationHandler.test.ts 迁移测试的核心输入。4.1 快照装载与数据校验工具syncTargetUtils.ts 提供了三个关键函数createTestData(data)按testData树形结构递归创建文件夹、笔记用shim.attachFileToNote附加图片、用Tag.addNoteTagByTitle打标签——它是快照的生产者checkTestData(data)递归按同构结构反查笔记、父文件夹、图片资源与标签关联任何缺失即抛错——它是迁移后的数据完整性校验器deploySyncTargetSnapshot(syncTargetType, syncVersion)把snapshotBaseDir/version/type整体拷贝到syncDir模拟老版本客户端留下的同步目标见 syncTargetUtils.ts。另外文件底部的main(syncTargetType)展示了快照的再生成流程初始化数据库 → 生成testData→ 如需 E2EE 则setEncryptionEnabled(true)并加载主密钥 → 启动同步 → 把syncDir拷贝回快照目录见 syncTargetUtils.ts。4.2 迁移测试的执行链路核心测试函数testMigration(migrationVersion, maxSyncVersion)的流程synchronizer_MigrationHandler.test.tsdeploySyncTargetSnapshot(normal, migrationVersion - 1)装载上一版本快照fetchSyncInfo(fileApi())断言快照版本号确实是migrationVersion - 1Setting.setConstant(syncVersion, migrationVersion)并调用migrationHandler().upgrade(migrationVersion)执行升级再次fetchSyncInfo断言版本已升至新值并执行该版本的目录结构断言migrationTests若已到最新版本则启动同步器synchronizer().start()随后checkTestData(testData)验证数据未受损切换到第二个客户端switchClient(2)重新同步并再次校验模拟另一台设备同步升级后的目标。E2EE 版本testMigrationE2EE在此基础上增加了解密环节先装载e2ee快照升级后启动decryptionWorker解密校验通过切换到客户端 2 后在未解密时应校验失败expectThrow填充主密钥密码encryption.passwordCache并解密后应校验成功expectNotThrow见 synchronizer_MigrationHandler.test.ts。4.3 迁移后的目标结构断言迁移测试对升级后的同步目标长什么样有明确断言migrationTests[2]与migrationTests[3]expect(items.filter(i i.path .resource i.isDir).length).toBe(1); expect(items.filter(i i.path locks i.isDir).length).toBe(1); expect(items.filter(i i.path temp i.isDir).length).toBe(1); expect(items.filter(i i.path info.json !i.isDir).length).toBe(1); const versionForOldClients await fileApi().get(.sync/version.txt); expect(versionForOldClients).toBe(2);对照快照目录可以看到版本演进1/normal顶层直接平铺笔记/资源/文件夹文件2/normal与3/normal出现了locks/目录与info.json。也就是说迁移过程会把资源整理进.resource、创建锁与临时目录、写入记录版本的info.json并保留.sync/version.txt供旧客户端读取。同时 synchronizer_MigrationHandler.test.ts 还验证了版本防护逻辑目标版本低于客户端抛outdatedSyncTarget高于客户端抛outdatedClient防止新旧客户端错误互操作。五、快照文件的生成与维护注意事项生成方式新版本发布前需用node tests/support/createSyncTargetSnapshot.js normal与... e2ee分别生成两套快照见 synchronizer_MigrationHandler.test.ts 顶部注释同步目标类型限制迁移测试必须使用filesystem同步目标因为快照是普通文件beforeEach中通过setSyncTargetName(filesystem)强制切换synchronizer_MigrationHandler.test.ts超时配置涉及真实网络目标的测试可能很慢测试文件将超时设为60000 * 10并指出 Jest 全局超时需单独设置版本上限maxSyncVersion Number(Object.keys(migrationTests).sort().pop())迁移测试只覆盖到已登记断言的最新版本新增版本时必须补充对应的migrationTests条目。总结1/normal/4782f467eb8c4d769b3538f069c39cfe.md这份快照文件浓缩了 Joplin 同步层的核心设计以正文 元数据头的.md文件承载笔记用:/resourceId协议引用资源用type_枚举区分对象类型用markup_language标记 Markdown/HTML并保留完整的时间、加密、排序、来源字段。它既是一份可直接阅读的序列化格式样例又是驱动 synchronizer_MigrationHandler.test.ts 迁移测试的基准数据。理解这套格式是深入 Joplin 同步机制、排查同步问题或为其贡献新同步版本迁移逻辑的第一步。【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考