实时协同
通过 OT 协调并发编辑,结合 HTTP、WebSocket、持久化与应用部署,让用户和 Agent 共同操作同一份内容。
实时协同使多个用户和接入协同的 Agent 可以操作同一份文档。编辑先在本地生效,服务端随后确定这些编辑的顺序,再将其分发给其他参与者。用户因此能立即获得反馈,所有参与者最终看到的内容保持一致。
并发编辑与冲突处理
Univer 使用 OT(操作转换)协调并发编辑。客户端将编辑操作组织为 changeset,服务端在提交前按已确认的 revision 转换 changeset。各客户端在收到彼此的修改后收敛到同一份内容。
例如,Alice 正在编辑 C2,Bob 同时在 B 列之前插入一列,转换后的编辑位置会随单元格移动到 D2。撤销和重做同样会考虑远端操作。OT 力求保留用户意图,但无法自动解决所有业务冲突。
如果某个操作既无法转换也无法执行,客户端会进入冲突状态,并停止该文档的编辑。CollaborationConflict 会给出原因以及尚未得到确认的本地修改。应用可以据此恢复,或先保存用户的工作,但在重新加载之前必须保留本地数据。详见冲突恢复,原理见 OT 算法与协同编辑设计。
HTTP、WebSocket 与断线恢复
| 通道 | 职责 |
|---|---|
| HTTP | 加载快照和 changeset、获取 Session Ticket、提交 changeset。 |
| WebSocket | 维持协同 Session 和文档 Room,接收 ACK、远端修改及在线状态通知。 |
客户端用一次性 Session Ticket 换取一条 WebSocket 连接,然后加入对应文档的 Room。Presence 通过这条连接同步在线成员、光标和选区。服务端每确认一个 revision,客户端的状态就向前推进。连接正常或 HTTP 请求成功,并不代表修改已经保存。 保存状态应结合 ACK、协同状态和待确认的修改来判断。
断线期间,客户端可以缓存尚未确认的修改。重新连接后,它按 revision 取回缺失的修改,并重发待确认的提交。服务端会对提交去重,重试不会被执行两次。见同步状态与重发和 Presence。
内容持久化与版本快照
协同服务保存已确认的 changeset 和 revision,并按自身策略生成版本快照。加载文档时,先从快照恢复内容,再应用之后的修改。并非每次编辑都需要重新生成快照。
快照生成期间的计算,见无头与服务端计算。历史面板、评论和 Agent 草稿审阅属于独立的协同扩展模块,可按需接入。
部署架构
- 单节点:在 Node.js 应用中组装 Transport、Endpoint、Service 和 Database Adapter。Memory 可用于临时验证,SQLite 适合本地和小规模部署,其他数据库通过应用提供的 Adapter 接入。
- 扩容设计:仅共享持久化并不足够。跨节点的文档广播、Presence、Session Ticket 验证和存储一致性都需要一并处理,仅增加服务进程无法解决。具体方案以所集成版本的部署设计为准。
- 拆分重任务:文件转换这类 CPU 密集型任务可单独部署,以减少对协同响应的影响。
完整组装见模块分工,部署步骤见部署指引,也可参考多节点示例。
性能与容量
当前版本的性能基准测试与容量数据待补充。 实际容量和协同延迟取决于文档大小、编辑频率、单文档的协作者数量以及部署环境。
评估系统时,应关注提交确认耗时、远端修改显示耗时、每秒 changeset 数、广播量以及活跃文档占用的内存。
接入方式
先阅读协同总览了解各模块之间的关系,再按快速开始运行双浏览器示例,验证编辑、确认和广播。身份与授权通过应用的 Middleware 接入。如需长期保存数据,应选择持久化的 Database Adapter,并验证服务重启后内容仍然保留。
适用边界
核心服务支持 Sheet、Doc、Slide、Canvases 和 Relational Table,PDF 不在这五个产品的核心协同范围内。身份、授权、文件管理和存储策略由应用提供;历史记录、评论和 Worktree 属于独立扩展。
你觉得这篇文档如何?