突破多人协作瓶颈：Docmost中Yjs与HocusPocus实时同步架构详解

【免费下载链接】docmost Docmost is an open source collaborative documentation and wiki software. It is an open-source alternative to the likes of Confluence and Notion. 项目地址: https://gitcode.com/GitHub_Trending/do/docmost

你是否经历过多人同时编辑文档时的内容冲突？是否因网络延迟导致辛苦编辑的内容丢失？Docmost的实时协作技术通过Yjs与HocusPocus的深度整合，彻底解决了这些痛点。本文将从架构设计到代码实现，全面解析Docmost如何实现毫秒级的多人实时协作，以及在高并发场景下的性能优化策略。

实时协作技术栈概览

Docmost采用业界领先的"Yjs+WebSocket+Redis"三层架构实现实时协作，其核心组件包括：

• Yjs：负责文档状态的分布式数据结构同步
• HocusPocus：作为WebSocket服务器处理协作通信
• Redis：实现多服务器实例间的状态共享
• NestJS：提供模块化的协作服务封装

核心实现位于apps/server/src/collaboration/collaboration.gateway.ts，该文件定义了协作网关的初始化与连接处理逻辑。

HocusPocus服务器配置解析

HocusPocus作为Docmost实时协作的通信中枢，其配置直接影响系统的稳定性和性能。以下是关键配置分析：

this.hocuspocus = HocuspocusServer.configure({
  debounce: 10000,          // 10秒防抖延迟，减少高频更新
  maxDebounce: 45000,       // 最大防抖延迟45秒
  unloadImmediately: false, // 不立即卸载文档
  extensions: [
    this.authenticationExtension, // 身份验证扩展
    this.persistenceExtension,    // 持久化扩展
    this.loggerExtension,         // 日志扩展
    // Redis扩展用于多服务器同步
    new Redis({
      host: this.redisConfig.host,
      port: this.redisConfig.port,
      options: {
        password: this.redisConfig.password,
        retryStrategy: createRetryStrategy(), // 自定义重试策略
      },
    }),
  ],
});

上述配置通过防抖机制平衡了实时性与服务器负载，而Redis扩展则确保了多节点部署时的状态一致性。

文档状态持久化机制

Docmost的持久化策略是保证数据安全的关键，实现在apps/server/src/collaboration/extensions/persistence.extension.ts中。其核心流程包括三个阶段：

1. 文档加载阶段

当用户打开文档时，系统优先从数据库加载Yjs状态：

async onLoadDocument(data: onLoadDocumentPayload) {
  const { documentName, document } = data;
  const pageId = getPageId(documentName);
  
  // 从数据库获取页面
  const page = await this.pageRepo.findById(pageId, {
    includeContent: true,
    includeYdoc: true,
  });
  
  if (page.ydoc) {
    // 应用数据库中的Yjs状态
    const doc = new Y.Doc();
    const dbState = new Uint8Array(page.ydoc);
    Y.applyUpdate(doc, dbState);
    return doc;
  }
  
  // 如无Yjs状态，转换历史JSON内容
  if (page.content) {
    return TiptapTransformer.toYdoc(page.content, 'default', tiptapExtensions);
  }
  
  // 创建新文档
  return new Y.Doc();
}

2. 变更处理阶段

用户编辑触发的变更通过onChange事件记录贡献者信息：

async onChange(data: onChangePayload) {
  const documentName = data.documentName;
  const userId = data.context?.user.id;
  if (!userId) return;
  
  // 记录文档贡献者
  if (!this.contributors.has(documentName)) {
    this.contributors.set(documentName, new Set());
  }
  this.contributors.get(documentName).add(userId);
}

3. 文档存储阶段

定时将文档状态持久化到数据库：

async onStoreDocument(data: onStoreDocumentPayload) {
  const { documentName, document } = data;
  const pageId = getPageId(documentName);
  
  // 转换Yjs状态为Tiptap JSON
  const tiptapJson = TiptapTransformer.fromYdoc(document, 'default');
  // 编码Yjs状态为二进制
  const ydocState = Buffer.from(Y.encodeStateAsUpdate(document));
  
  // 提取文本内容用于搜索
  const textContent = jsonToText(tiptapJson);
  
  // 事务更新数据库
  await executeTx(this.db, async (trx) => {
    await this.pageRepo.updatePage(
      {
        content: tiptapJson,
        textContent: textContent,
        ydoc: ydocState,
        lastUpdatedById: context.user.id,
        contributorIds: Array.from(contributorSet),
      },
      pageId,
      trx
    );
  });
}

冲突解决与并发控制

Docmost采用Yjs的CRDT(无冲突复制数据类型)算法自动解决冲突。其核心原理是为每个变更分配唯一的时间戳和用户标识，通过数学特性保证合并结果的一致性。

Yjs冲突解决示例

当两个用户同时编辑同一文本段落时：

1. 用户A在位置10插入"hello"
2. 用户B在位置10插入"world"

Yjs会自动合并为"helloworld"或"worldhello"，具体取决于系统生成的唯一操作ID，而不会像传统版本控制那样产生冲突提示。

性能优化策略

为应对高并发场景，Docmost实现了多层次优化：

• 批量更新：通过10秒防抖延迟合并微小更新
• 增量存储：仅保存变更部分而非完整文档
• 内存缓存：活跃文档状态常驻内存减少数据库访问
• Redis集群：支持水平扩展以处理更多并发连接

生产环境部署最佳实践

基于Docmost的架构特性，推荐以下部署策略：

部署规模	架构方案	关键配置
小型团队	单服务器 + Redis	禁用Redis集群，简化配置
中型企业	多服务器 + Redis集群	启用Redis扩展，配置retryStrategy
大型组织	负载均衡 + 分片存储	按空间ID分片，优化数据库负载

未来演进方向

Docmost的协作引擎正在向三个方向演进：

1. 实时评论系统：基于Yjs实现评论的实时同步
2. 离线编辑支持：结合ServiceWorker实现断网重连后的数据恢复
3. 操作历史优化：实现更细粒度的版本控制和时间线管理

相关开发正在ee/comment/目录下进行，将进一步增强协作体验。

通过Yjs与HocusPocus的深度整合，Docmost实现了媲美商业产品的实时协作体验，同时保持了开源软件的灵活性和可扩展性。无论是小型团队知识库还是大型企业文档系统，Docmost的协作架构都能提供稳定高效的支持。

更多技术细节可参考：

• 官方文档：README.md
• 协作模块：apps/server/src/collaboration/
• 前端实现：apps/client/src/features/editor/

【免费下载链接】docmost Docmost is an open source collaborative documentation and wiki software. It is an open-source alternative to the likes of Confluence and Notion. 项目地址: https://gitcode.com/GitHub_Trending/do/docmost