把 CRDT 当成协议，而不是魔法：Go 服务接入 DarkInno/crdt 的完整路径

把 CRDT 当成协议而不是魔法Go 服务接入 darkInno-tech/crdt 的完整路径“CRDT 会自动合并冲突”这句话没有错但它只覆盖了系统中最窄的一段当一份已经被接受、已经被正确解码、语义已经匹配的变更抵达副本后如何在重复、乱序和延迟下收敛。在真实 Go 服务里麻烦恰恰发生在这句话之外谁能发消息一条超大帧会不会耗尽内存机器重启后还能不能沿用 replica ID客户端确认了什么才能删 tombstoneDarkInno/crdt 的推荐用法不是把这些问题藏起来而是把它们排列成可实现、可测试的接入流程。本文给出一条适合已有 Go 后端的路径。它面向协作清单、共享表单、文档元数据、设备离线状态和增量文本等“可最终一致”的状态不适用于余额、库存预留、排他预约和权限判定。先定义四个不变量在写任何 handler 之前让产品、后端和安全评审对以下不变量达成一致。不变量要回答的问题失败时的后果合并语义并发 add/remove、并发写、并发文本插入分别如何呈现“收敛”了但收敛成错误业务结果协议身份哪个 group、schema、epoch、frame pair 和语义版本能互发跨版本或跨租户数据被错误合并资源上限请求、帧、元素、字符串、actor、pending work 各自上限多少恶意或异常输入占满内存、CPU 或队列恢复单元哪些状态必须原子保存才能复用 replica ID重启后产生重复 tag、漏投递或不安全压缩这四项不是文档作业而是实施顺序。它们把“可以收敛”升级为“在我们的服务里可以安全地收敛”。第一步按业务含义选 profile不要让调用者散落着手写 frame ID。先查询库内的 replication profile再让 profile 驱动协议配置profile,ok:crdt.ReplicationProfileFor(text/run-v2)if!ok{returnerrors.New(unknown CRDT profile)}builder,err:replica.NewSessionBuilderForFrameType(notes-42,// 应用组example.com/notes/plain-text/v1,// 应用 schema1,// membership / contract epochprofile.FrameType,,// profile 要求 codec 时传入已版本化 codec IDcrdt.ProtocolPolicy{},)iferr!nil{returnfmt.Errorf(create manifest: %w,err)}manifest:builder.Manifest()这个 Manifest 不会自动认证任何人它表达的是双方完成认证后要精确比较的契约。把 group、schema 和 epoch 纳入契约使得“同一个 WebSocket 已连上”不再被误认为“可以向任意文档写入”。第二步在解码前拒绝不应进入 Go 的数据接收顺序应当固定认证 → 授权 group/schema/操作 → 传输层 body 限额 → 带限额解码 → 应用 delta → 持久化 receipt 与状态。校验和、TypeID 和一次成功 decode 都不是身份验证。失败通过失败通过失败通过失败通过畸形或资源超限合法 delta提交失败提交成功收到网络 frame认证对端拒绝并记录低基数原因授权 group / schema / 操作精确 Manifest 匹配传输 body 未超限UnmarshalWithLimitsApplyDelta原子持久化 state clock frontier receipt/outbox不确认恢复后安全重试确认接收并异步投递 outbox图中最容易被省掉的节点是“原子持久化”。只有状态、生成下一次操作所需的 clock/因果信息和交付进度一起提交服务重启后才可以安全地继续使用同一个 replica ID。if!authenticatedPeerCanWrite(peer,manifest){returnerrUnauthorized}iflen(body)limits.MaxFrameBytes{// 在 decode 前完成传输限制returnerrTooLarge}delta,err:text.UnmarshalRGARunDeltaWithLimits(body,limits)iferr!nil{returnbadRequest(err)// 拒绝时本地 CRDT 状态不能改变}iferr:document.ApplyDelta(delta);err!nil{returnapplyFailure(err)}这里limits不是示例常量。它应从真实单次操作反推允许多大的粘贴、一个文档可保留多少节点、一个客户端离线多久、并发多少 actor、pending 依赖最多可以堆积多少。对共享文档而言输出帧预算也应约束本地变更超出预算的本地操作应该在状态和 HLC 前被拒绝而不是在 outbox 里留下一个永远发不出去的“幽灵更新”。第三步把本地变更和 outbox 放进同一提交边界CRDT 能容忍重复投递不代表可以随便丢投递。典型的本地写入事务包含业务命令 → 创建 CRDT delta → 持久化 CRDT 状态 / HLC(或因果状态) / frontier / outbox → 提交 → 异步发送 outbox → 收到明确确认后标记完成对 HLC 驱动的 RGA、LWW、OR-Tree 和附件引用只保存序列化状态并不足以安全地重用原 replica ID还需保存生成下一个唯一 tag 所需的 clock 状态以及交付 frontier 与 outbox。对 MV-Register 则需要保留因果上下文。DarkInno/crdt 的 checkpoint 与 durable relay 文档把这些字段作为一个恢复单元描述目的是阻止“重启后从旧时钟继续发新操作”这种很隐蔽的分叉。第四步选择 provider而不是让 provider 选择架构库提供的 WebSocket、耐久 relay、数据库 log、WebRTC 和本地 checkpoint 都是参考实现或可选模块不要求所有应用采用同一拓扑。选择时可以用下面这张工程矩阵需要解决的问题优先考虑仍由宿主负责单进程本地重启恢复bbolt/file checkpoint加密、备份、单进程约束与卷生命周期断线重连与有序回放durable relay 与 cursortoken 续期、持久化后端 HA、租户策略低延迟在线会话有界 WebSocket providerTLS、身份、origin、限流与背压P2P 或局域网直连WebRTC DataChannel bridge信令、NAT、身份、资源配额已有数据库或消息设施Redis/PostgreSQL/MySQL/SQLite durable-log 模块事务边界、索引、运维和成本这里的关键是“可选”而不是“缺失”。业务已有 Kafka、NATS、网关或数据库事务时核心 CRDT 不应迫使你绕开既有架构而使用参考 relay 时也不应把参考的 loopback 覆盖误报成生产容量验证。第五步把 tombstone 视作协议债务RGA、OR-Set 和树结构需要保留一部分删除信息以处理晚到或乱序更新。最危险的捷径是“我看见对端最大 tag 比这个更新所以可以删掉 tombstone。”最大 tag 不能证明中间没有缺口。正确的回收需要经过认证的权威成员视图、当前 membership epoch、每个应被确认 tag 的精确 acknowledgement、压缩后的耐久快照以及为旧客户端制定的重引导策略。也就是说GC 是成员关系协议的一部分不是一次本地内存优化。第六步用故障模型验收而不是只跑一次 merge建议将下列矩阵纳入 CI 和上线演练维度最小验收收敛两个或多个副本在重复、乱序、延迟投递后得到同一可见状态输入安全超大、畸形、未知类型、错误 codec 与越权帧在 mutation 前被拒绝恢复写后宕机、重启、重放 outbox 后不复用 tag、不漏掉已接收更新连接断线、重连、cursor catch-up、慢消费者和取消场景有明确行为保留tombstone 在成员退役、快照和精确确认下才能回收性能在目标 CPU、存储、网络和文档分布上分别测吞吐、p95/p99、峰值内存与队列长度make test、make race、模糊测试和 benchmark 是良好的库级证据生产验收还必须补齐目标部署的 TLS、鉴权链路、存储故障和真实负载。将这两类证据分开报告才能避免“单元测试绿了”被误解为“端到端已证明”。结语值得推荐的不是 API 数量而是可落地的约束DarkInno/crdt 的可贵之处是把 CRDT 放回它应在的位置它负责确定的合并与有界协议实现宿主负责身份、权限、业务不变量、耐久事务和运维。对于已有 Go 服务体系的团队这种分工意味着可以渐进引入复制状态而不必重写整个协作架构。第一周只选一个无争议的可最终一致事实确定 profile 与限额接入原子 outbox第二周模拟重复、乱序、重启和断网最后再引入 relay、跨端和 tombstone 生命周期。走完这条路径后CRDT 才真正成为可交付的能力。资料与口径库的具体 API 与接入边界见 darkinno-tech/crdt、按业务意图配置、端到端集成、provider 架构 与 checkpoint 参考。Yjs、Automerge 与 Loro 都有自身的同步协议和数据模型本库提供的 Yjs relay 是兼容 relay不将 Go RGA 与 Yjs 状态互译。Yjs 的 provider 模型可见 官方文档Automerge 的 storage/network adapter 结构可见 Repositories 文档。文中所有限额、SLO 和基准目标均应按目标工作负载确定没有把本地 loopback 或跨运行时对比写成生产容量结论。