Netcatty Convergent Sync Protocol v2:SSH 工作区 CRDT 收敛同步协议与迁移机制深度解析
Netcatty Convergent Sync Protocol v2:SSH 工作区 CRDT 收敛同步协议与迁移机制深度解析
本文以 docs/designs/convergent-sync-protocol-v2.md 设计文档为骨架,结合
domain/convergentSync目录下的 TypeScript 实现源码,完整解析 Netcatty(SSH workspace、SFTP、terminal 一体化工区)v2 收敛同步协议:它在保留旧客户端可读性的前提下引入 CRDT 收敛数据结构,处理 v1 旧数据迁移、本地持久化与密钥轮换、备份恢复、Provider 收敛状态机以及冲突解决与显式降级。读者将理解 v2 云文件的结构契约、迁移算法与状态机每轮读-合并-写-验证的工程细节,并能在阅读源码时快速定位关键实现文件。
兼容性契约:v2 云文件如何保持旧客户端可读
明文只增加一个版本号,其余全部留在密文内
v2 协议的第一条铁律是兼容性契约:一个 v2 云文件仍然是普通的 SyncedFile,其明文元数据只额外增加 syncSchemaVersion: 2 一个字段;完整的、物化后的 v1 SyncPayload、CRDT 元数据、冲突集合与候选值,全部保留在既有的 AES-256-GCM 密文内部。
这意味着解密后的 payload 依然包含全部 v1 字段——hosts、keys、snippets、settings 以及其他被同步的集合——旧版 Netcatty 客户端不需要任何新解析器即可读取这些数据。这一点在源码中有明确的类型佐证:domain/convergentSync/types.ts 中定义了加密信封的顶层结构:
export interface ConvergentSyncEnvelopeV2 {
schemaVersion: 2;
encoding: 'materialized-winner-v1';
state: ConvergentEnvelopeStateV2;
}
encoding: 'materialized-winner-v1' 正是文档所说的“相邻的 convergentSync 信封记录因果元数据与并发候选值”的实现形态:信封(envelope)与物化 v1 快照并排放置,各自承担不同职责。
赢家值可省略,结构值必须内联
对于一个可见实体字段或 settings 叶子节点,被选中的赢家(winner)通常不出现在信封中,而是在水合(hydration)时从相邻的物化 v1 字段重建。这由 domain/convergentSync/types.ts 中的 ConvergentEnvelopeCandidate 体现:
export type ConvergentEnvelopeCandidate<T extends JsonValue = JsonValue> =
| RegisterTombstoneCandidate
| (Omit<RegisterValueCandidate<T>, 'value'> & {
value?: T;
materialized?: true;
});
候选值可以用 materialized: true 标记替代真实 value,让信封变“紧凑”。而结构性存在(presence)与位置(position)值则始终内联在信封中——它们是 CRDT 元数据而非重复的用户记录,必须自描述。对应地,payload.ts 的 compactRegister 只在“该候选是赢家且其值与物化快照一致”时才省略 value,否则仍然完整写入;payload.ts 的 hydrateConvergentSyncEnvelope 则在反向方向上对带 materialized 标记的候选从物化快照重建值。
失败关闭(fail closed):水合的一切错误都是异常
文档明确列出了水合失败关闭的五个条件,全部能在源码中找到对应检查:
- 明文元数据声明未知或畸形 schema:
runtimeSchema(见 migration.ts)会把大于 2 的整数值判为'future',非整数判为'invalid',两者都会阻塞迁移。 - 元数据与加密信封不一致:
hydrateConvergentSyncEnvelope在水合后调用assertMaterializedPayloadMatchesState(payload.ts),对物化结果与 payload 做规范化指纹比对,不一致即抛错。 - 物化赢家无法重建:
hydrateRegister对标记为materialized但拿不到合法 JSON 值的候选直接抛出cannot reconstruct its materialized value。 - 信封违反 dot、context、origin、vector 或 HLC 不变式:
assertValidConvergentSyncState(serialization.ts)与mergeDotOrigins(state.ts,dot 来源冲突时抛出Dot origin mismatch)负责这类校验。 - 当前物化器会丢弃未知集合:
requireKnownCollections(payload.ts)对集合白名单之外的名字抛Unsupported convergent entity collection。
所有这类错误统一收敛为 ConvergentSyncInvariantError(types.ts),而不是静默降级为 null——这正是“失败关闭”的工程含义。
v2 目前覆盖的同步集合范围定义在 payload.ts:实体集合 hosts、keys、identities、proxyProfiles、snippets、notes、portForwardingRules、groupConfigs,以及字符串集合 customGroups、snippetPackages、noteGroups。
旧版导入:从 v1-only 到单一 CRDT 谱系
v1-only 初始迁移:每个 Provider 各跑一次智能合并
当一个设备只有 v1 数据时,初始迁移会下载每一个已连接的 Provider,并针对各 Provider 的可信基线(trusted base)运行既有的智能合并(smart merge)。整体编排在 migration.ts 的 planConvergentSyncMigration 中实现,其关键决策规则是:
- 没有可信基线的 Provider:要么被采纳为“新设备种子”(fresh-device seed),要么在其数据与当前合并结果完全一致时被接受;
- 与基线存在分歧的数据:直接阻塞(block),而不是去猜测“某个缺失的实体是否是被删除的”——文档明确反对在无证据时猜删除;
- 任何未解决的实体/settings 冲突、不可用的 Provider、或可疑收缩守卫(suspicious-shrink guard) 都会阻塞初始化。
只有全部通过后,成功结果才成为一个 v2 CRDT 谱系(lineage),并写回两样东西:一个完整的 v1 物化快照 + 一个紧凑信封(由 payload.ts 的 withConvergentSyncEnvelope 完成)。
已有 v2 时的混合加入:独立合成设备 ID 上的分支写入
如果一个或多个 Provider 已经包含 v2 数据,其状态用 CRDT join 合并;此时一个旧版本地或 Provider 快照只有在存在可信物化基线时才允许贡献写入。基线与快照的字段 diff 被应用在一条独立分支上,使用稳定的合成设备 ID(synthetic device ID),然后 join 进主状态。这样多个旧版写入者彼此保持并发,而不是被 Provider 的迭代顺序强加先后——对应 legacy.ts 的 applyLegacySyncPayload(state, baseline, legacy, syntheticDeviceId, now)。
若没有可信基线,上传被阻塞,而不是猜测“缺失字段是否意味着删除”。
undefined 集合与显式空集合的语义区分
这是一个容易出错的细节,文档与源码都做了精确区分(legacy.ts):
- 旧客户端未提供的可选顶层集合(或仅以内存中
undefined属性存在的集合)被视为“该客户端不支持”,保持原样、不写入; - 显式存在的空集合则是真实的删除;
- settings 内部的数组保持原子性(整体作为一个值),与 CRDT 核心一致。
hasDefinedOwnProperty 用 hasOwnProperty && value !== undefined 双重判断来实现这一语义。每个 legacy 分支在写入既有 v2 状态前都要通过可疑收缩守卫;该客户端省略的字段会从可信基线继承(inheritOmittedLegacySyncFields,legacy.ts),以保证安全校验的完整性。
全新安装与空快照的边界
- 设备没有任何云实体、也没有可信本地基线:视为全新安装,v1 与 v2 迁移都从云端 seed,而不会把本地首次启动的默认 settings 变成编辑(migration.ts 的
shouldIncludeLegacyLocalSource正是这个逻辑:无基线时只有含实体数据才纳入本地源); - 有可信基线时,空的本地快照就是一次因果删除,必须如实记录;
- 被选为 fresh-device seed 的 v1 Provider 在初始化 v2 前仍要过同一道可疑收缩守卫。
可疑收缩检测来自 domain/syncGuards.ts 的 detectSuspiciousShrink(其测试见 domain/syncGuards.test.ts),迁移中对每个输入源都会调用并记录 shrinkFindings。
本地持久化与主密钥轮换
规范副本与 Provider 基线:同密钥、严格加载
- 规范副本(canonical replica)与各 Provider 专属的 v2 基线,使用与既有 sync base、sync snapshot 相同的主密钥派生 AES-GCM 密钥加密。
- 加载既有 v2 记录是严格的:损坏数据与不支持的 schema 一律视为错误,绝不回退为
null。这与水合的失败关闭原则一脉相承——宁可报错,不可悄悄丢数据。 - 失效时机:当账号、endpoint、bucket 或连接被替换时,Provider 专属 v2 基线会与既有的 merge base、remote anchor 一起失效,确保新远程身份永远不会继承旧身份的可信度。
主密钥轮换:先准备、再验证、后提交
文档描述了严格的轮换事务协议:
- 在写任何内容之前,为所有派生密钥 sync 记录准备替换密文;
- 对既有记录和“缺失的 key”都做快照;
- 验证准备期间两者均未发生变化;
- 只有此时才提交新密文并发布新的主配置。
若写入失败,则恢复完全相同的先前密文与配置。这种“prepare → verify → commit”三步式设计保证了轮换要么原子完成、要么分毫不动。
experimental 开关是设备本地的
v2 的 enabled/paused 标志是设备本地(device-local)的,刻意不放进 SyncPayload.settings。禁用已初始化的副本只是暂停它,不删除本地或云元数据;要真正清除 v2 存储,必须经过显式的降级确认。这一点与后文“显式降级”一节相互呼应。
备份与恢复
本地 vault 备份不携带活动副本
本地 vault 备份始终是物化快照(materialized snapshots),永远不会携带活动的 CRDT 副本(active replica)。恢复场景下的因果历史与墓碑(tombstones)会随恢复保留下来,而不是被备份中一份无关的副本整体替换。
迁移初始化:受保护应用事务(protected-apply transaction)
迁移初始化复用既有的 protected-apply 事务,其流程在文档中描述得非常具体:
- 在 convergent Web Lock 下重建当前 cloud-sync payload,并与预览所用的快照比对;
- 任何插进来的本地编辑都会中止初始化并要求重新生成预览;
- 若 vault 未变化:先做一次加密安全备份(必须),然后持有跨窗口恢复屏障,应用预览过的物化 payload,持久化规范副本,最后才标记 v2 已初始化;
- 在释放同一把 Web Lock 之前,强制跑一轮 convergent read/merge/write/verify 循环,让即使未变化的 v1 物化数据也在每个已连接 Provider 上获得 v2 信封;
- 该循环发现的并发 Provider 编辑受保护并被应用到本地;部分发布(partial publication)会以 Provider 错误 + pending sync 的形式可见;
- sync manager 必须在事务开始前立即解锁,否则初始化会在任何备份、哨兵或本地变更之前就失败;
- 一旦变更开始后发生崩溃或失败,既有的 apply sentinel 会保持设置,使 auto-sync 无法发布部分迁移。
备份恢复:先验证、后提交
本地备份恢复的时序同样严谨:
- 在恢复快照改变本地数据之前,先把 restored snapshot 与当前物化副本做 diff,并准备为普通设备写入(不持久化);
- 因此副本加载在防护备份与部分应用哨兵之前就完成了验证,而准备好的写入只有在每个本地导入步骤成功后才提交;
- 准备失败不留哨兵(vault 尚未被动过);导入失败则副本保持原样;后续副本提交失败则留下 protected-apply sentinel,防止部分恢复被发布。
纯重排编辑与内存实体规范化
两个易被忽视的细节值得注意:
- 可信 legacy diff 也比较集合位置:纯重排(reorder-only)编辑会转换为实体/字符串集合的 position-register 写入,而不会因为值本身没变就消失——legacy.ts 的
diffLegacySyncPayload对每个实体/字符串条目同时比对值指纹(fingerprint)与位置索引(beforePositions.get(id) !== afterPositions.get(id)); - 内存实体在验证前用与加密 payload 相同的 JSON 序列化语义规范化(
normalizeJsonValue),使可选undefined模型字段被省略而非阻塞迁移。
Provider 收敛状态机
单一规范副本 + 独占 Web Lock
已初始化的设备持有一个规范副本(canonical replica),被所有 Provider 共享。每次同步都必须获取独占的 Web Lock;不支持 Web Lock 的环境失败关闭,防止两个渲染窗口同时分配并上传相互竞争的本地状态。关闭 experimental 开关会暂停 v2 路径,且永远不会落到旧版写入器(no fall-through)。
三选一的传出走法
运行时先下载每个已连接 Provider,再选择传出状态,三种策略语义在文档中定义清晰:
smartMerge:join 本地写入与所有远端分支;preferLocal:先 join,再创建支配被合并寄存器的因果本地写入;preferCloud:直接采纳无序远端 join。
包含本地生成 dot 的规范状态会先加密持久化,再上传到 Provider——这是“本地因果写入先落盘”的关键保证。下载到的 remote-only dot 只有在至少一个 Provider 验证了 join 后状态之后才会提交到本地副本;因此,即使网络完全失败,持久化副本仍与未变的本地 vault 对齐,远端分支可以安全地稍后重试。
在 smartMerge / preferLocal 把本地快照变成写入之前,既有的 suspicious-shrink guard 会将其与物化副本比对:大规模删除在分配或持久化任何 dot 之前就被拦截,除非用户执行既有的一次性强制操作(one-shot force)。
每轮 read-merge-write-verify
Provider 至多运行三轮 read-merge-write-verify,每轮:
- 下载并 join 自初始读取以来新出现的任何状态(内存中);
- 向可用 Provider 上传相同的预期向量(expected vector);
- 逐个读回,仅当返回向量支配预期向量时才接受写入;
- join 已验证的远端超集,若其中含新的并发状态则重复。
“支配”(dominates)的精确含义在 clock.ts 的 versionVectorDominates 中实现:候选向量在每个设备 ID 上的计数器都不小于预期向量,允许存在额外计数器——那表示远端超集,需要被 join 并传播,而非视为写失败。
重试延迟使用短全抖动(short full jitter)。一个不可用 Provider 记为一个错误并使本地同步保持 pending,但不会回滚已经验证成功的 Provider。因为本地生成的因果写入在网络 I/O 之前就已持久化,应用重启会重试同一批 dot 而不是重新生成。Provider 基线与 join 后的规范副本,都只在读回验证之后推进。
CRDT 状态合并的核心实现在 state.ts 的 mergeConvergentSyncStates:递归合并 collections/settings/stringCollections 下的多值寄存器,向量取逐设备最大值(mergeVersionVectors),HLC 取 maxHybridLogicalClock,dot 来源冲突即抛错;写入路径则由 state.ts 的 applyConvergentMutations 统一执行——单次结构克隆即可批量应用上千个寄存器(迁移场景的规模需求)。
冲突解决与显式降级
按寄存器地址暴露冲突,选择即支配
物化过程按寄存器地址暴露保留的冲突(retained conflicts)。选择一个候选值会写入一个新设备值,其上下文观察(context observes)每个候选——因此该解决结果会支配所有陈旧副本,并通过正常的 Provider 状态机传播。这一点在 conflicts.ts 的 resolveConvergentFieldConflict 中实现:根据候选 dot 定位候选,构造 resolve-register 变更(tombstone 与 value 互斥校验),再经 applyConvergentMutations 落盘。
若传播过程中发现额外的并发 Provider 写入,Netcatty 会在释放同一把 Web Lock 之前,先在本地应用最终的 canonical 物化结果。
秘密字段:只渲染“set”或“empty”
冲突候选值可能携带凭据。秘密字段的检测依据地址与嵌套字段名——包括原子数组内嵌套的对象。实现见 conflicts.ts:正则 SECRET_SEGMENT = /(?:password|passphrase|privatekey|secret|token|api[_-]?key|access[_-]?key)/i 匹配实体字段名、setting 路径段以及候选值内部的嵌套键名;命中者,其 UI 只渲染“set”或“empty”,值永不被格式化、记录日志或插入 DOM 文本。
显式降级:同一把锁,全量验证后才清除
显式降级同样持有同一把 Web Lock,并在写任何内容之前下载每个已连接 Provider:
- 先把 v2 暂停期间产生的编辑转换为本地副本之上的因果写入;
- 把这些写入与每个远端状态 join;
- 在防护备份(protective backup)之后应用 joined payload,并阻塞降级直到任何新发现的字段冲突被解决;
- 把 joined 物化 v1 快照写到每个 Provider,再次下载,并验证两件事:v2 元数据不存在且云数据相等(对应 payload.ts 的
stripConvergentSyncEnvelope,以及 legacy.ts 的cloudSyncPayloadsEqual指纹比对); - 只有所有 Provider 都验证通过后,才在同一把 Web Lock 内清除本地副本、Provider 基线与 experimental 配置。
一个部分降级(partial downgrade)会保留 joined 本地 v2 状态与刷新后的 Provider 基线,让用户能够安全重试而不丢失 remote-only dot。
结语
Netcatty 的 convergent sync protocol v2 是一套把 CRDT 收敛语义嵌入既有加密云同步管道的完整方案:以 syncSchemaVersion: 2 一个明文字段为入口,用 materialized-winner-v1 紧凑信封承载因果元数据,让旧客户端零解析成本继续工作;迁移、备份、密钥轮换、Provider 收敛状态机与降级流程全部围绕“失败关闭 + 先持久化后验证 + 独占 Web Lock”三条主线展开。
如果希望深入验证协议的代数性质与边界行为,可阅读 domain/convergentSync/convergentSync.property.test.ts(属性测试)与 domain/convergentSync/conflicts.test.ts;若关注迁移决策与旧数据路径,domain/convergentSync/payloadMigration.test.ts 与 convergentSyncMigration.test.ts 提供了最直接的对照用例。从 domain/convergentSync/index.ts 出发,可以沿着 clock / register / state / payload / legacy / migration 的模块划分,逐步走通整套协议。