realtime-sync

实时同步

概述

设计分布式客户端与服务端之间的高并发、低于 50 毫秒延迟的同步方案。涵盖 WebTransport（HTTP/3）双向流、用于确保数据库与同步一致性的事务发件箱模式、用于协作编辑的 CRDT，以及 AI 令牌流编排。

核心原则：数据库是真实数据源（实时通道用于通知，而非持久化），CRDT 无需锁即可处理并发编辑，背压管理可避免高频流导致 UI 抖动。

适用场景： 实时协作 UI、发布/订阅消息、WebTransport/WebSocket 连接、实时 AI 令牌流、在线状态跟踪、使用 CRDT 解决冲突、多人游戏应用。

不适用场景： 批处理管道、静态内容交付、无实时需求的请求-响应 API、仅限离线的应用。

快速参考

模式	方法	关键要点
WebTransport	new WebTransport(url) + await ready	HTTP/3 多路复用；新项目可用其替代 WebSocket
双向流	transport.createBidirectionalStream()	返回 { readable, writable }，用于请求-响应
单向流	transport.createUnidirectionalStream()	直接返回用于单向推送的 WritableStream
数据报	transport.datagrams.writable	类似 UDP 的不可靠传输，适用于高频状态
连接统计信息	transport.getStats()	返回 smoothedRtt、bytesSent、packetsLost
事务发件箱	在同一事务中写入数据库并插入发件箱记录	CDC 工作进程推送到通道；防止状态漂移
序列跟踪	为每条消息添加序列 ID	重新连接时回溯以获取遗漏的消息
CRDT 协作	Yjs（文本）或 Automerge（JSON 状态）	无需锁即可实现无冲突的并发编辑
CRDT 感知	y-protocols/awareness 模块	跟踪光标、选区和用户在线状态
CRDT 撤销/重做	使用 trackedOrigins 的 Y.UndoManager	仅跟踪本地用户操作，以便选择性撤销
在线状态	基于心跳的用户跟踪	通过流行式广播可靠地清理僵尸状态
AI 流批处理	使用 requestAnimationFrame 渲染令牌	避免高频更新导致 UI 抖动
缓冲并批处理	使用 useTransition 处理同步触发的更新	同步突发期间延迟非紧急重新渲染
背压	限制缓冲区大小，必要时强制刷新	避免令牌产生速度超过渲染速度时内存不断增长
WebSocket 回退	先检测是否支持 WebTransport	企业防火墙可能会阻止 UDP/HTTP/3
序列化	Protocol Buffers 或 MessagePack	避免在 100Hz 及以上的流中使用 JSON.stringify
Web Worker 传输	在 Web Worker 中处理 WebTransport	避免阻塞 UI 线程
通道多路复用	通过一个套接字订阅多个通道	所有订阅共用一个传输连接

常见错误

错误	正确做法
将实时消息作为主要事实来源	状态存储在数据库中；实时消息用于通知状态变更
在高频流（100Hz 以上）中使用 JSON.stringify	使用 Protocol Buffers 或 MessagePack 进行序列化
客户端漏收消息时忽略序列偏移	实现序列 ID，并在客户端实现回退机制
为并发访问实现全局锁	使用 Optimistic UI 和 CRDT，实现无冲突协作
新项目需要多路复用时仍坚持使用 WebSockets	使用 WebTransport（HTTP/3）实现双向多路复用流
CRDT 文档因历史记录无限增长而臃肿	对不需要保留历史记录的字段使用快照（LWW）
卸载时未关闭 WebTransport 流	显式关闭流，以防传输崩溃
从 yjs 而不是 y-protocols 导入 Awareness	使用 import { Awareness } from 'y-protocols/awareness'
将 ydoc.clientID 用作 UndoManager 跟踪的来源	使用传递给 doc.transact() 的自定义事务来源
每收到一个 AI 令牌就触发一次 React 重渲染	使用 requestAnimationFrame 批量处理令牌，并在每帧刷新一次
未处理 WebTransport 的 closed promise	监控 transport.closed，以检测意外断开连接

委派

如果可以使用 local-first 技能，请将本地优先架构决策、同步引擎比较和客户端存储选择委派给它。 如果可以使用 electricsql 技能，请将基于形状的 ElectricSQL Postgres 同步模式委派给它。

• 探索传输协议选项和延迟基准：使用 Explore Agent 比较 WebTransport、SSE 和 WebSocket 的优缺点
• 实现带 CDC 流水线的事务发件箱模式：使用 Task Agent 设置数据库触发器、发件箱表和后台工作进程
• 设计协作编辑的实时架构：使用 Plan Agent 制定 CRDT 策略、在线状态管理和冲突解决流程
• 构建多流 AI 编排组件：使用 Task Agent 实现并行令牌流渲染和背压
• 审查实时连接生命周期管理：使用 Review Agent 检查流泄漏、缺少清理操作和重连处理

参考资料

• WebTransport 流式传输和工作进程模式
• 发布/订阅消息传递和可靠送达
• CRDT 和协作编辑
• AI 流编排模式
• 协作撤销和重做模式