Netcatty Convergent Sync Protocol v2:SSH 工作区 CRDT 收敛同步协议与迁移机制深度解析

原创2026-10-08 21:37:572,257 阅读

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 一起失效,确保新远程身份永远不会继承旧身份的可信度。

主密钥轮换:先准备、再验证、后提交

文档描述了严格的轮换事务协议:

  1. 在写任何内容之前,为所有派生密钥 sync 记录准备替换密文;
  2. 对既有记录和“缺失的 key”都做快照;
  3. 验证准备期间两者均未发生变化;
  4. 只有此时才提交新密文并发布新的主配置。

若写入失败,则恢复完全相同的先前密文与配置。这种“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 事务,其流程在文档中描述得非常具体:

  1. 在 convergent Web Lock 下重建当前 cloud-sync payload,并与预览所用的快照比对;
  2. 任何插进来的本地编辑都会中止初始化并要求重新生成预览;
  3. 若 vault 未变化:先做一次加密安全备份(必须),然后持有跨窗口恢复屏障,应用预览过的物化 payload,持久化规范副本,最后才标记 v2 已初始化;
  4. 在释放同一把 Web Lock 之前,强制跑一轮 convergent read/merge/write/verify 循环,让即使未变化的 v1 物化数据也在每个已连接 Provider 上获得 v2 信封;
  5. 该循环发现的并发 Provider 编辑受保护并被应用到本地;部分发布(partial publication)会以 Provider 错误 + pending sync 的形式可见;
  6. sync manager 必须在事务开始前立即解锁,否则初始化会在任何备份、哨兵或本地变更之前就失败;
  7. 一旦变更开始后发生崩溃或失败,既有的 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,每轮:

  1. 下载并 join 自初始读取以来新出现的任何状态(内存中);
  2. 向可用 Provider 上传相同的预期向量(expected vector);
  3. 逐个读回,仅当返回向量支配预期向量时才接受写入;
  4. 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:

  1. 先把 v2 暂停期间产生的编辑转换为本地副本之上的因果写入;
  2. 把这些写入与每个远端状态 join;
  3. 在防护备份(protective backup)之后应用 joined payload,并阻塞降级直到任何新发现的字段冲突被解决;
  4. 把 joined 物化 v1 快照写到每个 Provider,再次下载,并验证两件事:v2 元数据不存在且云数据相等(对应 payload.ts 的 stripConvergentSyncEnvelope,以及 legacy.ts 的 cloudSyncPayloadsEqual 指纹比对);
  5. 只有所有 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 的模块划分,逐步走通整套协议。

登录后查看全文
Netcatty