P2P 实时协作系统

模块概述

版本: v1.0.0 状态: ✅ 已实现 IPC处理器: 21个 最后更新: 2026-03-05

基于 Yjs CRDT 和 libp2p 的 P2P 实时协作系统。支持多人实时编辑、光标感知、区域锁定、冲突解决、行内评论和版本快照，提供完整的协作编辑体验。

核心特性

Yjs CRDT: 无冲突复制数据类型，自动合并并发编辑
libp2p 同步: P2P 网络实时广播文档更新和感知状态
区域锁定: 支持全文/段落/区域级别的锁定机制
冲突解决: 检测并提供手动/自动冲突解决
行内评论: 支持线程化评论和解决跟踪
版本快照: Yjs 快照保存和历史版本恢复
组织知识同步: 跨组织 P2P 知识库同步

1. 架构设计

1.1 整体架构图

┌──────────────────────────────────────────────────────────────────┐
│                        前端 (Vue3)                                │
├──────────────────────────────────────────────────────────────────┤
│             Pinia Store: collab.ts (1,245行)                      │
│  ┌─────────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌────────┐ ┌────────┐  │
│  │ 文档编辑 │ │ 锁定  │ │ 评论  │ │ 版本  │ │ Yjs桥  │ │ 协作房间│  │
│  └─────────┘ └──────┘ └──────┘ └──────┘ └────────┘ └────────┘  │
└──────────────────────────────────────────────────────────────────┘
                              ↕ IPC (21个通道)
┌──────────────────────────────────────────────────────────────────┐
│                        主进程 (Electron)                          │
├──────────────────────────────────────────────────────────────────┤
│              realtime-collab-ipc.js (663行)                       │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  RealtimeCollabManager (1,329行)                            │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │  │
│  │  │ 锁定管理      │  │ 冲突解决      │  │ 评论系统      │     │  │
│  │  └──────────────┘  └──────────────┘  └──────────────┘     │  │
│  └────────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  YjsCollabManager (676行)        │ OrgKnowledgeSyncManager │  │
│  │  Yjs CRDT + libp2p 同步          │ 组织知识P2P同步 (937行)  │  │
│  └────────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  PermissionManager (683行)  │  SQLite Database              │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
                              ↕ libp2p
┌──────────────────────────────────────────────────────────────────┐
│                         P2P 网络                                  │
│  协议: /chainlesschain/yjs-sync/1.0.0                            │
│  协议: /chainlesschain/yjs-awareness/1.0.0                       │
└──────────────────────────────────────────────────────────────────┘

1.2 数据流

用户编辑 → Yjs Y.Doc → Y.applyUpdate()
    ↓ collab:yjs-update IPC
YjsCollabManager → 广播到 libp2p peers
    ↓ /chainlesschain/yjs-sync/1.0.0
远端 peer → Y.applyUpdate(doc, update, 'peer')
    ↓ collab:yjs-remote-update
前端 → 更新编辑器内容

1.3 核心组件

组件	文件	行数	说明
RealtimeCollabManager	`realtime-collab-manager.js`	1,329	协作核心 (锁/冲突/评论)
YjsCollabManager	`yjs-collab-manager.js`	676	Yjs CRDT + P2P同步
OrgKnowledgeSyncManager	`org-knowledge-sync-manager.js`	937	组织知识同步
PermissionManager	`permission-manager.js`	683	协作权限管理
RealtimeCollabIPC	`realtime-collab-ipc.js`	663	21个IPC处理器
Pinia Store	`collab.ts`	1,245	前端状态管理

2. 核心模块

2.1 RealtimeCollabManager

协作核心管理器，处理文档打开/关闭、锁定、冲突和评论。

核心方法:

javascript

class RealtimeCollabManager extends EventEmitter {
  // 文档操作
  async openDocument(docId, userDid, userName, orgId?)
  async closeDocument(docId, userDid)

  // Yjs同步桥接
  async syncUpdate(docId, update, userDid, version)
  async receiveUpdate(docId, fromVersion)

  // 感知 (光标/选区)
  async getAwareness(docId)
  async updateCursor(docId, userDid, userName, cursor, selection?)

  // 区域锁定
  async acquireLock(docId, userDid, userName, lockType, sectionStart, sectionEnd, durationMs?)
  async releaseLock(lockId, userDid)
  async releaseUserLocks(docId, userDid)

  // 冲突解决
  async requestConflictResolution(docId, conflictData)
  async resolveConflict(conflictId, resolverDid, resolution)

  // 行内评论
  async addInlineComment(docId, comment)
  async resolveComment(commentId, resolverDid)
  async getComments(docId, options?)

  // 版本历史
  async getDocumentHistory(docId, options?)
  async restoreVersion(docId, versionId, userDid)

  // 导出
  async exportWithComments(docId, format?)
}

2.2 YjsCollabManager

Yjs CRDT 集成和 libp2p P2P 同步。

javascript

class YjsCollabManager extends EventEmitter {
  // 文档管理
  getDocument(docId)                      // 获取/创建 Y.Doc
  async openDocument(docId, orgId?)       // 打开文档 + 连接peer
  async closeDocument(docId)              // 关闭文档

  // 光标跟踪
  async updateCursor(docId, cursor, selection?)
  getActiveUsers(docId)

  // 版本管理
  async createSnapshot(docId, metadata?)  // 创建快照
  async restoreSnapshot(docId, snapshotId) // 恢复快照
  async getVersionHistory(docId, limit?)  // 版本列表
}

libp2p 协议:

/chainlesschain/yjs-sync/1.0.0 — 文档更新同步
/chainlesschain/yjs-awareness/1.0.0 — 感知状态 (lib0 编码)

2.3 锁定机制

锁定类型: full | section | paragraph

获取锁定:
  1. 检查是否存在冲突锁 (区域重叠)
  2. 冲突 → 返回 { success: false, error: "LOCK_CONFLICT", conflictingLocks }
  3. 无冲突 → 创建锁记录, 设置过期定时器 (默认5分钟)
  4. 过期 → 自动释放并通知 lock_expired 事件

释放锁定:
  1. 验证释放者身份 (必须是锁拥有者)
  2. 删除锁记录, 清除定时器
  3. 通知 lock_released 事件

3. 数据模型

3.1 collaboration_sessions

字段	类型	说明
id	TEXT PK	会话ID
knowledge_id	TEXT	文档ID
org_id	TEXT	组织ID
user_did	TEXT	用户DID
user_name	TEXT	用户名
user_color	TEXT	用户颜色
last_activity	INTEGER	最后活动时间
status	TEXT	状态 (active)
created_at	INTEGER	创建时间

3.2 collab_document_locks

字段	类型	说明
id	TEXT PK	锁ID
knowledge_id	TEXT	文档ID
locked_by_did	TEXT	锁定者DID
locked_by_name	TEXT	锁定者名称
lock_type	TEXT	锁类型 (full/section/paragraph)
section_start	INTEGER	区域起始位置
section_end	INTEGER	区域结束位置
expires_at	INTEGER	过期时间
created_at	INTEGER	创建时间

3.3 knowledge_comments

字段	类型	说明
id	TEXT PK	评论ID
knowledge_id	TEXT	文档ID
author_did	TEXT	作者DID
content	TEXT	评论内容
position_start	INTEGER	起始位置
position_end	INTEGER	结束位置
thread_id	TEXT	线程ID
parent_comment_id	TEXT	父评论ID
status	TEXT	状态 (open/resolved)
created_at	INTEGER	创建时间

3.4 其他表

collab_cursor_positions — 光标/选区感知
collab_conflict_history — 冲突解决历史
knowledge_yjs_updates — Yjs 更新持久化
knowledge_snapshots — Yjs 快照版本
collab_stats — 协作统计
org_knowledge_folders — 组织文件夹层级
org_knowledge_items — 组织知识条目
knowledge_activities — 活动审计日志

4. IPC接口 (21个)

4.1 文档操作 (2个)

通道	说明	参数
`collab:open-document`	打开文档	docId, userDid, userName, orgId?
`collab:close-document`	关闭文档	docId, userDid

4.2 同步操作 (2个)

通道	说明	参数
`collab:sync-update`	同步更新	docId, update, userDid, version?
`collab:receive-update`	接收更新	docId, fromVersion?

4.3 感知 (2个)

通道	说明	参数
`collab:get-awareness`	获取感知状态	docId
`collab:update-cursor`	更新光标	docId, userDid, cursor, selection?

4.4 锁定管理 (2个)

通道	说明	参数
`collab:acquire-lock`	获取锁	docId, userDid, lockType, sectionStart?, sectionEnd?
`collab:release-lock`	释放锁	lockId, userDid

4.5 冲突解决 (2个)

通道	说明	参数
`collab:request-conflict-resolution`	请求冲突解决	docId, conflictData
`collab:resolve-conflict`	解决冲突	conflictId, resolverDid, resolution

4.6 评论 (3个)

通道	说明	参数
`collab:add-inline-comment`	添加评论	docId, comment
`collab:resolve-comment`	解决评论	commentId, resolverDid
`collab:get-comments`	获取评论列表	docId, options?

4.7 版本历史 (2个)

通道	说明	参数
`collab:get-document-history`	获取版本历史	docId, options?
`collab:restore-version`	恢复版本	docId, versionId, userDid

4.8 统计/导出/订阅 (3个)

通道	说明	参数
`collab:get-stats`	获取协作统计	docId
`collab:export-with-comments`	导出含评论	docId, format?
`collab:subscribe-changes`	订阅变更事件	docId

4.9 Yjs CRDT 桥接 (3个)

通道	说明	参数
`collab:yjs-connect`	连接Yjs文档	documentId
`collab:yjs-update`	应用Yjs更新	documentId, update (Uint8Array)
`collab:yjs-disconnect`	断开Yjs	documentId

5. 前端页面

5.1 Pinia Store: collab.ts

typescript

interface CollabState {
  currentDocument: CollabDocument | null;
  collaborators: Collaborator[];
  cursorPositions: Record<string, CursorPosition>;
  locks: Lock[];
  pendingConflicts: Conflict[];
  comments: Comment[];
  versionHistory: Version[];
  connectionStatus: ConnectionStatus;
  yjsConnected: boolean;
  yjsSynced: boolean;
  activeCollaborators: ActiveCollaborator[];
  currentRoom: CollabRoom | null;
}

// Getters
hasUnresolvedConflicts; // 是否有未解决冲突
isDocumentLocked; // 文档是否被锁定
myLockedSections; // 我的锁定区域
onlineCollaboratorCount; // 在线协作者数量
isYjsReady; // Yjs 是否就绪

6. 文件结构

desktop-app-vue/src/main/collaboration/
├── realtime-collab-manager.js    # 协作核心 (1,329行)
├── realtime-collab-ipc.js        # 21个IPC处理器 (663行)
├── yjs-collab-manager.js         # Yjs CRDT + P2P (676行)
├── org-knowledge-sync-manager.js # 组织知识同步 (937行)
├── permission-manager.js         # 协作权限 (683行)
├── collaboration-manager.js      # 遗留ShareDB (889行)
└── collaboration-ipc.js          # 遗留IPC (190行)

desktop-app-vue/src/renderer/
└── stores/collab.ts              # 协作状态管理 (1,245行)

7. 相关文档

文档版本: 1.0 最后更新: 2026-03-05

P2P 实时协作系统 ​

模块概述 ​

核心特性 ​

1. 架构设计 ​

1.1 整体架构图 ​

1.2 数据流 ​

1.3 核心组件 ​

2. 核心模块 ​

2.1 RealtimeCollabManager ​

2.2 YjsCollabManager ​

2.3 锁定机制 ​

3. 数据模型 ​

3.1 collaboration_sessions ​

3.2 collab_document_locks ​

3.3 knowledge_comments ​

3.4 其他表 ​

4. IPC接口 (21个) ​

4.1 文档操作 (2个) ​

4.2 同步操作 (2个) ​

4.3 感知 (2个) ​

4.4 锁定管理 (2个) ​

4.5 冲突解决 (2个) ​

4.6 评论 (3个) ​

4.7 版本历史 (2个) ​

4.8 统计/导出/订阅 (3个) ​

4.9 Yjs CRDT 桥接 (3个) ​

5. 前端页面 ​

5.1 Pinia Store: collab.ts ​

6. 文件结构 ​

7. 相关文档 ​