多人实时协同文档：Tiptap + Yjs 协作编辑方案
DocFlow 提供基于 Tiptap、Yjs 与 Hocuspocus 的多人实时协同文档方案，覆盖在线状态、离线缓存、自动重连、修订追踪和私有化扩展。
这套方案解决什么问题？
DocFlow 将富文本编辑、CRDT 协同状态、在线成员感知和离线持久化放在同一文档协作空间中。团队成员可以同时编辑同一份文档；网络中断时，本地内容继续保留，恢复连接后再同步。需要长期保存的文档、权限和审计数据仍由服务端数据库负责。
适合哪些团队
从真实业务边界判断是否适合采用或二次开发。
- 需要多人同时撰写、评审和修订制度、方案或知识文档的团队
- 计划在自有系统中集成 Tiptap、Yjs 或 Hocuspocus 的研发团队
- 对文档权限、数据隔离、离线编辑和私有化部署有明确要求的企业
快速判断这套方案是否适合
DocFlow 的多人实时协同文档方案是什么？
它是基于 Tiptap、Yjs、Hocuspocus、awareness 和 IndexedDB 的协同编辑方案，用于让团队在同一份文档中实时编辑、离线恢复和追踪修订。
这套方案适合私有化部署吗？
适合。DocFlow 的协同编辑能力可以作为私有化文档协作平台的基础，但部署时仍需要结合企业认证、权限、审计、存储和网络环境做安全配置。
DocFlow 如何处理协同编辑状态？
正文和可合并协同状态进入 Y.Doc；在线用户、光标和临时选区进入 awareness；权限、审计、评论和长期业务数据由数据库保存。
从功能名称落到可验证的实现边界
多人同步编辑
Yjs 负责可合并的协同文档状态，Hocuspocus 负责连接和文档同步，避免依赖脆弱的本地文本索引。
离线缓存与自动重连
IndexedDB 保留本地 Y.Doc 状态；网络恢复后，客户端重新连接协同服务并继续同步。
在线状态与选区感知
awareness 只承载在线用户、光标和临时选区等瞬时信息，不用于保存需要长期持久化的业务数据。
修订与审阅
编辑建议以结构化修订进入文档，审阅者可以定位、接受或拒绝变更，保留清晰的人机协作边界。
关键步骤与错误边界保持清楚
- 1
加载文档与权限
服务端根据已认证用户、工作区和文档标识校验访问边界，再加载对应协作文档。
- 2
初始化本地与远端状态
客户端创建 Y.Doc，并同时连接 IndexedDB 持久化与 Hocuspocus Provider。
- 3
同步正文和临时在线状态
正文通过 Yjs update 合并；在线成员、光标和选区通过 awareness 单独同步。
- 4
持久化快照与业务数据
文档快照、元信息、权限、评论和审计记录按职责进入数据库，而不是混入 awareness。
技术与数据职责
明确每一层负责什么，避免把临时状态、权限和持久业务数据混在一起。
- Tiptap：富文本编辑器和文档 schema
- Yjs：正文与可合并协同状态
- Hocuspocus：WebSocket 协同服务和房间隔离
- IndexedDB：离线编辑状态与恢复
- Database：权限、文档元信息、审计和长期业务数据
常见问题
DocFlow 的协同编辑为什么使用 Yjs？+
Yjs 提供 CRDT 数据结构和增量更新机制，适合多人并发编辑与离线合并。DocFlow 用它承载文档协同状态，而不是把普通 React state 当成协同数据源。
断网后还能继续编辑文档吗？+
可以。客户端通过 IndexedDB 保留本地协同状态；网络恢复后会重新连接并同步更新。具体冲突结果由 Yjs 合并语义决定。
是否适合私有化文档协作平台？+
适合以 DocFlow 的产品能力为基础进行私有化扩展。企业部署仍需结合现有身份认证、网络、存储、审计和运维要求完成配置与安全评估。
awareness 是否保存评论和审批数据？+
不保存。awareness 只适合在线用户、光标、选区等临时状态；评论、权限、审批和审计应持久化到数据库。
继续了解相关方案
基于 DocFlow 评估你的文档协作与 AI 工作流
可以先查看项目说明和实现边界；需要企业知识库、认证、内部工具或私有化环境集成时，再根据实际需求设计交付范围。