Joplin 同步机制技术解析Synchronizer 三步流程、Sync Target 架构与 info.json 冲突协调【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplinJoplin 是一款离线优先offline-first的笔记应用数据保存在各设备本地多设备间的数据一致性依赖一套通用的同步过程每个设备把笔记、笔记本、标签、附件等对象上传到同步目标sync target同时下载自己没有的对象和最新变更本地删除的对象也会被删除到同步目标并最终传播到所有设备。本文基于仓库中的同步规格文档 sync.md 及其对应的核心实现完整梳理 Joplin 同步体系的术语、通用流程、分层代码架构、三步同步算法、info.json同步目标属性以及测试配置方式读完后你将能够理解Synchronizer、SyncTarget、FileApi三层之间如何协作并具备阅读和调试 Joplin 同步代码的能力。核心术语理解同步代码之前需要先统一三个概念Clients同步客户端即 Joplin 的各个应用本体——桌面版、移动版和终端CLI应用。所有客户端共用packages/lib中同一套同步逻辑。Sync targets同步目标数据最终被保存的位置例如 Joplin Server、Nextcloud 实例或 WebDAV 服务器。它是同步数据的中转存储各客户端围绕它进行上传与下载。Items条目需要被同步的对象包括笔记notes、笔记本notebooks、标签tags和附件资源resources。从 SyncTargetRegistry.ts 的实现看每种同步目标在注册时都会暴露一组元数据id、name、label、description以及能力开关supportsSelfHosted、supportsConfigCheck、supportsRecursiveLinkedNotes、supportsShare这正对应规格文档中暴露名称、描述、支持的选项等元数据的描述。通用同步流程按照规格文档的定义Joplin 的同步由两条时间线索驱动即时上传只要用户对某个对象做了修改它会在几秒内被上传到同步目标。尽早上传可以显著减少冲突概率——这样任何后续连接同步目标的客户端都更有可能拿到该对象的最新版本周期轮询每隔几分钟客户端会轮询同步目标下载最新变更并应用到本地数据集合。即时上传的具体入口可以从 registry.ts 中同步调度相关方法reg.scheduleSync(reg.syncAsYouTypeInterval(), ...)等印证Synchronizer在收尾阶段如果发现仍有未上传的变更会再次调度一次同步见 Synchronizer.ts把同步刚完成时又产生的变更尽快补传出去。代码架构四层结构同步规格文档把整个实现划分为若干文件类别以下逐层对照源码说明。Synchronizer主同步过程packages/lib/Synchronizer.ts 负责主同步过程下载变更、上传变更、应用删除操作。该类相对通用接收一个SyncTarget提供的FileApi对象来处理与具体同步目标相关的操作当启用 E2EE端到端加密时Synchronizer 还负责对对象做加解密。从 Synchronizer.ts 的源码注释可以直接看到主流程被定义为三个主要步骤// 1. UPLOAD: 把自上次同步以来变更的对象发送到同步目标。 // 2. DELETE_REMOTE: 在同步目标上删除已在本地删除的对象。 // 3. DELTA: 在同步目标上找出被修改或删除的对象并把变更应用到本地。start()方法通过syncSteps选项控制执行哪些步骤默认值为[update_remote, delete_remote, delta]Synchronizer.ts。同步过程中的每个动作都会通过logSyncOperation()记录并汇总到ProgressReport创建/更新/删除的本地与远端对象计数、错误列表等该报告最终以SYNC_COMPLETED等形式派发给 UI。同步开始前Synchronizer会通过LockHandler获取同步锁见 Synchronizer.ts并在同步期间自动刷新锁防止多个客户端同时写坏同一个同步目标——这是规格文档中提及的锁机制在代码中的落点。SyncTarget*.ts各同步目标的入口packages/lib下与SyncTarget对应的文件是各同步目标的入口。它们暴露名称、描述、支持的选项等元数据部分实现还提供配置检查函数供配置界面验证当前配置是否可用这类文件的核心职责是初始化一个FileApi实例。以最简单的 SyncTargetNone.ts 为例export default class SyncTargetNone extends BaseSyncTarget { public static id() { return 0; } public static targetName() { return none; } public static label() { return _((None)); } public async fileApi(): PromiseFileApi { return null; } ... }而 SyncTargetRegistry.ts 是所有SyncTarget类的注册表通过addClass()按id登记、通过nameToId()/infoByName()查询元数据供配置界面和同步引擎按名称找到目标。仓库中实际存在的目标包括SyncTargetJoplinCloud.ts、SyncTargetJoplinServer.ts、SyncTargetWebDAV.ts、SyncTargetNextcloud.ts、SyncTargetOneDrive.ts、SyncTargetFilesystem.ts、SyncTargetMemory.ts、SyncTargetDropbox.ts、SyncTargetAmazonS3.js、SyncTargetJoplinServerSAML.ts等均位于 packages/lib 目录。file-api-driver-*.ts文件式抽象这一层必须实现创建、更新、删除、列出文件等通用文件操作。同步引擎正是通过这套文件 API 来完成对象的创建、更新和删除。对应基类是 packages/lib/file-api.ts 中的FileApi它把底层 driver 统一封装为一组语义化方法get(path, options)/put(path, content, options)读取与写入put支持source: file从本地文件直接上传list(path, options)/stat(path)/delete(path)/mkdir(path)目录与文件操作delta(path, options)增量变更查询这是三步流程中 DELTA 步骤的核心调用supportsAccurateTimestamp、supportsMultiPut、supportsLocks等能力标志让Synchronizer能按目标能力走不同分支。每个 driver 负责把上述调用落到真实介质上file-api-driver-local用fs读写文件file-api-driver-amazon-s3调用 S3 APIfile-api-driver-webdav.js、file-api-driver-dropbox.js、file-api-driver-onedrive.ts等则分别对接对应云服务。*Api.ts低层服务 API当不存在现成的低层文件 API 时仓库会单独创建一个*Api.ts文件供 file-api-driver 调用。例如 JoplinServerApi.ts 用于连接 Joplin Serveronedrive-api.ts、WebDavApi.ts 等也是同一模式的产物。BaseModel / BaseItem 与 sync_items 表数据库中的每个对象对应一个BaseModel子类而可同步的对象则对应继承自BaseModel的BaseItem类BaseItem.ts。大量同步相关的工具方法都集中在这里BaseItem.itemsThatNeedSync()找出需要同步的对象——UPLOAD 步骤的主循环就是反复调用它每批 100 条见 Synchronizer.ts直到返回没有更多BaseItem.syncedItemIds()/remoteItemMetadata()供 delta 阶段比对本地与远端状态BaseItem.pathToId()/systemPath()对象 ID 与同步目标上系统路径如note/id.md之间的互相转换启用 E2EE 时对对象做加密的方法。每个对象的同步状态保存在sync_items表中关键字段sync_time对象最后一次成功同步的时间是判断哪些对象需要同步的主要依据sync_disabled用于对象完全无法同步的少数情形例如被 Dropbox 以受限内容版权拒绝或在 Joplin Cloud 上超过大小限制。Synchronizer中handleCannotSyncItem()会调用ItemClass.saveSyncDisabled()写入该标记避免同一个坏对象反复阻塞同步sync_target每条sync_items记录都绑定一个具体的同步目标 ID。这意味着同一份数据理论上可以同时同步到多个同步目标各目标的状态互相隔离。三步同步流程的源码细节start()的实际执行顺序是先做delete_remote把本地已删除的对象从目标上删掉再进入update_remote上传本地变更最后是delta拉取远端变更并应用到本地。三个步骤各有明确的算法依据。DELETE_REMOTE该步骤被抽取为独立函数syncDeleteStepsyncDeleteStep.ts遍历本地标记为已删除的对象调用FileApi.delete()将其从同步目标上移除并更新sync_items状态。UPDATE_REMOTE上传与冲突判定上传主循环Synchronizer.ts对每个待同步对象做如下决策先stat远端路径远端不存在且本地sync_time为空则执行CreateRemote远端已被删除但本地又有新变更则记为冲突NoteConflict/ResourceConflict/ItemConflict若远端存在会拉取并反序列化远端内容比较内容中的updated_time与本地sync_time远端更新时间晚于本地最后同步时间说明两端都改过判定为冲突否则执行UpdateRemote。源码注释解释了为什么必须读内容而不是只看文件时间戳——同步目标上的文件时间戳精度不够例如 OneDrive 的lastModifiedDateTime可能比实际设置值快几秒而对象内的updated_time由客户端管理始终准确资源附件上传时会比较blob_updated_time与sync_time如果数据块没变仅元信息变化就跳过 blob 上传只更新元数据文件上传成功后调用ItemClass.saveSyncTime()把sync_time设为updated_time并把当前正文/标题记为冲突基准base_body/base_title供后续冲突三方合并使用。代码中还处理了一个隐蔽的竞态同步运行期间用户仍在编辑同一对象时同一path可能在两轮循环中再次出现。Synchronizer通过donePaths检测重复处理并抛出带明确错误码的异常processingPathTwice、changedDuringSync其中changedDuringSync会重新触发一次同步而非报错Synchronizer.ts防止同步刚完成时又产生了新变更的窗口被遗漏。DELTA拉取远端变更并应用本地DELTA 阶段调用apiCall(delta, ...)分页获取远端变更列表然后远端存在而本地不存在 →CreateLocal远端标记为已删除而本地存在 →DeleteLocal远端updated_time新于本地 →UpdateLocal并重新读取最新的本地updated_time做二次比较避免一次耗时较长的 delta 过程中远端新变更被本地旧版本覆盖下载通过TaskQueuesyncDownload队列并发执行可随时取消。对于没有原生 delta 能力的同步目标文件系统、Nextcloud 等没有 delta API而 OneDrive、Dropbox 有FileApi提供了basicDelta()兜底算法file-api.ts以时间戳为游标记录上一轮扫描时的时间戳 恰好落在这个时间戳上的文件列表以处理同一毫秒内的并发修改对删除则用远端文件列表与本地已同步 ID 集合做差集得到远端已删除的对象。这里还有一个重要的防误删设计// 若超过 90% 的对象将被删除很可能是配置错误或 bug // 例如用户移动了 Nextcloud 目录或网络驱动器断开后返回空目录。 // 此时不删除用户数据除非用户在同步设置中关闭了 fail-safe。 if (options.wipeOutFailSafe percentDeleted 0.90) throw new JoplinError(..., failSafe);见 file-api.ts。配合sync.wipeOutFailSafe设置与checkSyncTargetIsValid()每轮 delta 分页后检查info.json是否仍然存在见 syncInfoUtils.tsJoplin 在同步目标目录被外部清空/移动这类事故下会中断同步而不是抹掉本地数据。Sync Target 属性info.json 与冲突协调同步目标的属性保存在名为info.json的文件中用于保证所有客户端使用同一套同步设置。规格文档给出的接口定义为interface SyncTargetInfo { // 同步目标的版本号。 version: number; // 同步目标上是否启用了 E2EE e2ee: { value: boolean; updatedTime: number; } // 当前活跃的加密主密钥 activeMasterKeyId: { value: string; updatedTime: number; } // 已知的加密/解密密钥 masterKeys: Key[]; // 公钥/私钥对 ppk: { value: { id: string; keySize: number; privateKey: Key; // 使用用户密码加密 publicKey: string; // 明文 createdTime: number; } } // 与该同步目标同步所需的最小应用版本 appMinVersion: string; }仓库中的实际实现是 syncInfoUtils.ts 里的SyncInfo类除规格文档列出的字段外还包含noteLockKey笔记锁密钥、revisionServiceEnabled与revisionServiceTtlDays修订服务开关与保留天数且每个可冲突属性都以{ value, updatedTime }形式存储。基于 updatedTime 的冲突协调两个客户端修改同一属性时比较各自的updatedTime保留较新者。mergeSyncInfos()syncInfoUtils.ts实现了这套启发式e2ee、ppk、revisionServiceEnabled等按时间戳取大者masterKeys做并集并按updated_time保留较新副本appMinVersion用版本号比较本地优先。针对activeMasterKeyId还有专门逻辑即使时间戳更旧已被使用过hasBeenUsed的主密钥优先保持活跃避免第二个客户端开启加密时误换主密钥导致数据不可解。同步引擎在每次start()中都会拉取远端info.jsonfetchSyncInfo与本地缓存保存在syncInfoCache设置中比对若不一致则在排他锁保护下mergeSyncInfos并上传合并结果Synchronizer.ts如果合并结果改变了 E2EE 开关还会调用setupAndEnableEncryption/setupAndDisableEncryption切换本地加密状态。版本兼容闸门appMinVersion决定与目标同步所需的最小客户端版本。当前仓库中该值为3.7.0syncInfoUtils.ts并设有前向兼容逻辑3.6 稳定版也能与使用 3.7.0 同步格式的客户端互通forwardCompatibleAppMinVersion。checkIfCanSync()在版本不足时抛出MustUpgradeApp错误Synchronizer捕获后向 UI 派发升级提示。旧目标迁移与兜底fetchSyncInfo()在info.json缺失时会退而读取.sync/version.txt判断是否为老版本目标并标记需要升级若两者都缺失且这不是首次同步则抛出failSafe错误syncInfoUtils.ts。测试内存目标与真实目标切换规格文档说明单元测试默认使用内存同步目标in-memory sync target速度快且足以验证绝大多数行为但测试也可以配置为针对真实同步目标运行。源码与文档一致见 test-utils.tsfunction setSyncTargetName(name: string) { syncTargetName name; } setSyncTargetName(memory); // setSyncTargetName(filesystem); // setSyncTargetName(nextcloud); // setSyncTargetName(dropbox); // setSyncTargetName(onedrive); // setSyncTargetName(amazon_s3); // setSyncTargetName(joplinServer); // setSyncTargetName(joplinCloud);修改setSyncTargetName()的实参即可切换目标必要时还需在~/joplin-credentials/目录下补充或修改对应凭据文件——具体读取逻辑见同文件的initFileApi()方法test-utils.ts。这解释了SyncTargetMemory.ts存在的意义它是专为测试准备的同步目标让数千个同步测试用例无需真实网络即可完成。延伸阅读仓库中与同步直接相关的其他规格文档可作为继续深入的入口同步锁机制说明Synchronizer使用的 Sync/Exclusive 锁类型及其语义E2EE 技术规格 与 E2EE 工作流解释info.json中masterKeys/activeMasterKeyId/ppk字段的加密学含义Synchronizer 主流程、FileApi 与 basicDelta、syncInfoUtils 三个源文件是规格文档中代码架构一节所列条目最核心的实现载体。【免费下载链接】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），仅供参考
Joplin 同步机制技术解析：Synchronizer 三步流程、Sync Target 架构与 info.json 冲突协调
Joplin 同步机制技术解析Synchronizer 三步流程、Sync Target 架构与 info.json 冲突协调【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplinJoplin 是一款离线优先offline-first的笔记应用数据保存在各设备本地多设备间的数据一致性依赖一套通用的同步过程每个设备把笔记、笔记本、标签、附件等对象上传到同步目标sync target同时下载自己没有的对象和最新变更本地删除的对象也会被删除到同步目标并最终传播到所有设备。本文基于仓库中的同步规格文档 sync.md 及其对应的核心实现完整梳理 Joplin 同步体系的术语、通用流程、分层代码架构、三步同步算法、info.json同步目标属性以及测试配置方式读完后你将能够理解Synchronizer、SyncTarget、FileApi三层之间如何协作并具备阅读和调试 Joplin 同步代码的能力。核心术语理解同步代码之前需要先统一三个概念Clients同步客户端即 Joplin 的各个应用本体——桌面版、移动版和终端CLI应用。所有客户端共用packages/lib中同一套同步逻辑。Sync targets同步目标数据最终被保存的位置例如 Joplin Server、Nextcloud 实例或 WebDAV 服务器。它是同步数据的中转存储各客户端围绕它进行上传与下载。Items条目需要被同步的对象包括笔记notes、笔记本notebooks、标签tags和附件资源resources。从 SyncTargetRegistry.ts 的实现看每种同步目标在注册时都会暴露一组元数据id、name、label、description以及能力开关supportsSelfHosted、supportsConfigCheck、supportsRecursiveLinkedNotes、supportsShare这正对应规格文档中暴露名称、描述、支持的选项等元数据的描述。通用同步流程按照规格文档的定义Joplin 的同步由两条时间线索驱动即时上传只要用户对某个对象做了修改它会在几秒内被上传到同步目标。尽早上传可以显著减少冲突概率——这样任何后续连接同步目标的客户端都更有可能拿到该对象的最新版本周期轮询每隔几分钟客户端会轮询同步目标下载最新变更并应用到本地数据集合。即时上传的具体入口可以从 registry.ts 中同步调度相关方法reg.scheduleSync(reg.syncAsYouTypeInterval(), ...)等印证Synchronizer在收尾阶段如果发现仍有未上传的变更会再次调度一次同步见 Synchronizer.ts把同步刚完成时又产生的变更尽快补传出去。代码架构四层结构同步规格文档把整个实现划分为若干文件类别以下逐层对照源码说明。Synchronizer主同步过程packages/lib/Synchronizer.ts 负责主同步过程下载变更、上传变更、应用删除操作。该类相对通用接收一个SyncTarget提供的FileApi对象来处理与具体同步目标相关的操作当启用 E2EE端到端加密时Synchronizer 还负责对对象做加解密。从 Synchronizer.ts 的源码注释可以直接看到主流程被定义为三个主要步骤// 1. UPLOAD: 把自上次同步以来变更的对象发送到同步目标。 // 2. DELETE_REMOTE: 在同步目标上删除已在本地删除的对象。 // 3. DELTA: 在同步目标上找出被修改或删除的对象并把变更应用到本地。start()方法通过syncSteps选项控制执行哪些步骤默认值为[update_remote, delete_remote, delta]Synchronizer.ts。同步过程中的每个动作都会通过logSyncOperation()记录并汇总到ProgressReport创建/更新/删除的本地与远端对象计数、错误列表等该报告最终以SYNC_COMPLETED等形式派发给 UI。同步开始前Synchronizer会通过LockHandler获取同步锁见 Synchronizer.ts并在同步期间自动刷新锁防止多个客户端同时写坏同一个同步目标——这是规格文档中提及的锁机制在代码中的落点。SyncTarget*.ts各同步目标的入口packages/lib下与SyncTarget对应的文件是各同步目标的入口。它们暴露名称、描述、支持的选项等元数据部分实现还提供配置检查函数供配置界面验证当前配置是否可用这类文件的核心职责是初始化一个FileApi实例。以最简单的 SyncTargetNone.ts 为例export default class SyncTargetNone extends BaseSyncTarget { public static id() { return 0; } public static targetName() { return none; } public static label() { return _((None)); } public async fileApi(): PromiseFileApi { return null; } ... }而 SyncTargetRegistry.ts 是所有SyncTarget类的注册表通过addClass()按id登记、通过nameToId()/infoByName()查询元数据供配置界面和同步引擎按名称找到目标。仓库中实际存在的目标包括SyncTargetJoplinCloud.ts、SyncTargetJoplinServer.ts、SyncTargetWebDAV.ts、SyncTargetNextcloud.ts、SyncTargetOneDrive.ts、SyncTargetFilesystem.ts、SyncTargetMemory.ts、SyncTargetDropbox.ts、SyncTargetAmazonS3.js、SyncTargetJoplinServerSAML.ts等均位于 packages/lib 目录。file-api-driver-*.ts文件式抽象这一层必须实现创建、更新、删除、列出文件等通用文件操作。同步引擎正是通过这套文件 API 来完成对象的创建、更新和删除。对应基类是 packages/lib/file-api.ts 中的FileApi它把底层 driver 统一封装为一组语义化方法get(path, options)/put(path, content, options)读取与写入put支持source: file从本地文件直接上传list(path, options)/stat(path)/delete(path)/mkdir(path)目录与文件操作delta(path, options)增量变更查询这是三步流程中 DELTA 步骤的核心调用supportsAccurateTimestamp、supportsMultiPut、supportsLocks等能力标志让Synchronizer能按目标能力走不同分支。每个 driver 负责把上述调用落到真实介质上file-api-driver-local用fs读写文件file-api-driver-amazon-s3调用 S3 APIfile-api-driver-webdav.js、file-api-driver-dropbox.js、file-api-driver-onedrive.ts等则分别对接对应云服务。*Api.ts低层服务 API当不存在现成的低层文件 API 时仓库会单独创建一个*Api.ts文件供 file-api-driver 调用。例如 JoplinServerApi.ts 用于连接 Joplin Serveronedrive-api.ts、WebDavApi.ts 等也是同一模式的产物。BaseModel / BaseItem 与 sync_items 表数据库中的每个对象对应一个BaseModel子类而可同步的对象则对应继承自BaseModel的BaseItem类BaseItem.ts。大量同步相关的工具方法都集中在这里BaseItem.itemsThatNeedSync()找出需要同步的对象——UPLOAD 步骤的主循环就是反复调用它每批 100 条见 Synchronizer.ts直到返回没有更多BaseItem.syncedItemIds()/remoteItemMetadata()供 delta 阶段比对本地与远端状态BaseItem.pathToId()/systemPath()对象 ID 与同步目标上系统路径如note/id.md之间的互相转换启用 E2EE 时对对象做加密的方法。每个对象的同步状态保存在sync_items表中关键字段sync_time对象最后一次成功同步的时间是判断哪些对象需要同步的主要依据sync_disabled用于对象完全无法同步的少数情形例如被 Dropbox 以受限内容版权拒绝或在 Joplin Cloud 上超过大小限制。Synchronizer中handleCannotSyncItem()会调用ItemClass.saveSyncDisabled()写入该标记避免同一个坏对象反复阻塞同步sync_target每条sync_items记录都绑定一个具体的同步目标 ID。这意味着同一份数据理论上可以同时同步到多个同步目标各目标的状态互相隔离。三步同步流程的源码细节start()的实际执行顺序是先做delete_remote把本地已删除的对象从目标上删掉再进入update_remote上传本地变更最后是delta拉取远端变更并应用到本地。三个步骤各有明确的算法依据。DELETE_REMOTE该步骤被抽取为独立函数syncDeleteStepsyncDeleteStep.ts遍历本地标记为已删除的对象调用FileApi.delete()将其从同步目标上移除并更新sync_items状态。UPDATE_REMOTE上传与冲突判定上传主循环Synchronizer.ts对每个待同步对象做如下决策先stat远端路径远端不存在且本地sync_time为空则执行CreateRemote远端已被删除但本地又有新变更则记为冲突NoteConflict/ResourceConflict/ItemConflict若远端存在会拉取并反序列化远端内容比较内容中的updated_time与本地sync_time远端更新时间晚于本地最后同步时间说明两端都改过判定为冲突否则执行UpdateRemote。源码注释解释了为什么必须读内容而不是只看文件时间戳——同步目标上的文件时间戳精度不够例如 OneDrive 的lastModifiedDateTime可能比实际设置值快几秒而对象内的updated_time由客户端管理始终准确资源附件上传时会比较blob_updated_time与sync_time如果数据块没变仅元信息变化就跳过 blob 上传只更新元数据文件上传成功后调用ItemClass.saveSyncTime()把sync_time设为updated_time并把当前正文/标题记为冲突基准base_body/base_title供后续冲突三方合并使用。代码中还处理了一个隐蔽的竞态同步运行期间用户仍在编辑同一对象时同一path可能在两轮循环中再次出现。Synchronizer通过donePaths检测重复处理并抛出带明确错误码的异常processingPathTwice、changedDuringSync其中changedDuringSync会重新触发一次同步而非报错Synchronizer.ts防止同步刚完成时又产生了新变更的窗口被遗漏。DELTA拉取远端变更并应用本地DELTA 阶段调用apiCall(delta, ...)分页获取远端变更列表然后远端存在而本地不存在 →CreateLocal远端标记为已删除而本地存在 →DeleteLocal远端updated_time新于本地 →UpdateLocal并重新读取最新的本地updated_time做二次比较避免一次耗时较长的 delta 过程中远端新变更被本地旧版本覆盖下载通过TaskQueuesyncDownload队列并发执行可随时取消。对于没有原生 delta 能力的同步目标文件系统、Nextcloud 等没有 delta API而 OneDrive、Dropbox 有FileApi提供了basicDelta()兜底算法file-api.ts以时间戳为游标记录上一轮扫描时的时间戳 恰好落在这个时间戳上的文件列表以处理同一毫秒内的并发修改对删除则用远端文件列表与本地已同步 ID 集合做差集得到远端已删除的对象。这里还有一个重要的防误删设计// 若超过 90% 的对象将被删除很可能是配置错误或 bug // 例如用户移动了 Nextcloud 目录或网络驱动器断开后返回空目录。 // 此时不删除用户数据除非用户在同步设置中关闭了 fail-safe。 if (options.wipeOutFailSafe percentDeleted 0.90) throw new JoplinError(..., failSafe);见 file-api.ts。配合sync.wipeOutFailSafe设置与checkSyncTargetIsValid()每轮 delta 分页后检查info.json是否仍然存在见 syncInfoUtils.tsJoplin 在同步目标目录被外部清空/移动这类事故下会中断同步而不是抹掉本地数据。Sync Target 属性info.json 与冲突协调同步目标的属性保存在名为info.json的文件中用于保证所有客户端使用同一套同步设置。规格文档给出的接口定义为interface SyncTargetInfo { // 同步目标的版本号。 version: number; // 同步目标上是否启用了 E2EE e2ee: { value: boolean; updatedTime: number; } // 当前活跃的加密主密钥 activeMasterKeyId: { value: string; updatedTime: number; } // 已知的加密/解密密钥 masterKeys: Key[]; // 公钥/私钥对 ppk: { value: { id: string; keySize: number; privateKey: Key; // 使用用户密码加密 publicKey: string; // 明文 createdTime: number; } } // 与该同步目标同步所需的最小应用版本 appMinVersion: string; }仓库中的实际实现是 syncInfoUtils.ts 里的SyncInfo类除规格文档列出的字段外还包含noteLockKey笔记锁密钥、revisionServiceEnabled与revisionServiceTtlDays修订服务开关与保留天数且每个可冲突属性都以{ value, updatedTime }形式存储。基于 updatedTime 的冲突协调两个客户端修改同一属性时比较各自的updatedTime保留较新者。mergeSyncInfos()syncInfoUtils.ts实现了这套启发式e2ee、ppk、revisionServiceEnabled等按时间戳取大者masterKeys做并集并按updated_time保留较新副本appMinVersion用版本号比较本地优先。针对activeMasterKeyId还有专门逻辑即使时间戳更旧已被使用过hasBeenUsed的主密钥优先保持活跃避免第二个客户端开启加密时误换主密钥导致数据不可解。同步引擎在每次start()中都会拉取远端info.jsonfetchSyncInfo与本地缓存保存在syncInfoCache设置中比对若不一致则在排他锁保护下mergeSyncInfos并上传合并结果Synchronizer.ts如果合并结果改变了 E2EE 开关还会调用setupAndEnableEncryption/setupAndDisableEncryption切换本地加密状态。版本兼容闸门appMinVersion决定与目标同步所需的最小客户端版本。当前仓库中该值为3.7.0syncInfoUtils.ts并设有前向兼容逻辑3.6 稳定版也能与使用 3.7.0 同步格式的客户端互通forwardCompatibleAppMinVersion。checkIfCanSync()在版本不足时抛出MustUpgradeApp错误Synchronizer捕获后向 UI 派发升级提示。旧目标迁移与兜底fetchSyncInfo()在info.json缺失时会退而读取.sync/version.txt判断是否为老版本目标并标记需要升级若两者都缺失且这不是首次同步则抛出failSafe错误syncInfoUtils.ts。测试内存目标与真实目标切换规格文档说明单元测试默认使用内存同步目标in-memory sync target速度快且足以验证绝大多数行为但测试也可以配置为针对真实同步目标运行。源码与文档一致见 test-utils.tsfunction setSyncTargetName(name: string) { syncTargetName name; } setSyncTargetName(memory); // setSyncTargetName(filesystem); // setSyncTargetName(nextcloud); // setSyncTargetName(dropbox); // setSyncTargetName(onedrive); // setSyncTargetName(amazon_s3); // setSyncTargetName(joplinServer); // setSyncTargetName(joplinCloud);修改setSyncTargetName()的实参即可切换目标必要时还需在~/joplin-credentials/目录下补充或修改对应凭据文件——具体读取逻辑见同文件的initFileApi()方法test-utils.ts。这解释了SyncTargetMemory.ts存在的意义它是专为测试准备的同步目标让数千个同步测试用例无需真实网络即可完成。延伸阅读仓库中与同步直接相关的其他规格文档可作为继续深入的入口同步锁机制说明Synchronizer使用的 Sync/Exclusive 锁类型及其语义E2EE 技术规格 与 E2EE 工作流解释info.json中masterKeys/activeMasterKeyId/ppk字段的加密学含义Synchronizer 主流程、FileApi 与 basicDelta、syncInfoUtils 三个源文件是规格文档中代码架构一节所列条目最核心的实现载体。【免费下载链接】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），仅供参考
