🚀 多人协同编辑系统

📋 1. 项目概述

1.1 核心功能

• 实时协同编辑：多用户同时编辑同一文档，毫秒级同步
• 冲突自动解决：基于 CRDT 算法自动合并冲突，无需人工干预
• 光标位置同步：实时显示其他用户的 cursor 位置和选区
• 在线用户列表：显示当前正在编辑文档的所有用户
• 版本历史：完整的操作日志和版本回溯能力
• 离线编辑：支持离线编辑，网络恢复后自动同步
• 权限管理：细粒度的文档访问和编辑权限控制
• 评论批注：支持对文档内容进行评论和批注

1.2 技术指标

🏗️ 2. 系统架构设计

2.1 整体架构图

2.2 架构分层说明

2.3 核心模块划分

🛠️ 3. 技术选型

3.1 前端技术栈

3.2 后端技术栈

3.3 数据库选型

3.4 基础设施

• 容器化：Docker + Kubernetes
• 服务网格：Istio（可选）
• 监控告警：Prometheus + Grafana
• 日志系统：ELK Stack（Elasticsearch + Logstash + Kibana）
• 链路追踪：Jaeger / OpenTelemetry
• CI/CD：GitHub Actions + ArgoCD

📊 4. 数据模型设计

4.1 核心实体关系图

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│    User     │      │   Document   │      │  Workspace  │
├─────────────┤      ├──────────────┤      ├─────────────┤
│ id          │◄────►│ id           │◄────►│ id          │
│ email       │      │ title        │      │ name        │
│ username    │      │ workspace_id │      │ owner_id    │
│ avatar      │      │ created_by   │      │ created_at  │
│ created_at  │      │ created_at   │      └─────────────┘
└─────────────┘      │ updated_at   │
                     │ content      │
                     └──────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │   Operation  │
                     ├──────────────┤
                     │ id           │
                     │ document_id  │
                     │ user_id      │
                     │ type         │
                     │ data         │
                     │ timestamp    │
                     │ version      │
                     └──────────────┘

4.2 MongoDB Schema 设计

Document 集合

{
  "_id": "ObjectId",
  "title": "String",
  "workspaceId": "ObjectId",
  "createdBy": "ObjectId",
  "updatedAt": "Date",
  "createdAt": "Date",
  "content": {
    "type": "Binary",  // Yjs 二进制更新数据
    "encoding": "UInt8Array"
  },
  "snapshot": {
    "type": "Binary",  // 定期快照
    "version": "Number",
    "createdAt": "Date"
  },
  "metadata": {
    "tags": ["String"],
    "color": "String",
    "icon": "String"
  },
  "settings": {
    "allowComments": "Boolean",
    "allowSuggestions": "Boolean",
    "lockEditing": "Boolean"
  },
  "stats": {
    "viewCount": "Number",
    "editCount": "Number",
    "collaboratorCount": "Number"
  },
  "version": "Number",  // 当前版本号
  "isDeleted": "Boolean",
  "deletedAt": "Date"
}

Operation 集合（操作日志）

{
  "_id": "ObjectId",
  "documentId": "ObjectId",
  "userId": "ObjectId",
  "username": "String",
  "type": "String",  // insert, delete, update, format
  "data": {
    "position": "Number",
    "length": "Number",
    "content": "String",
    "attributes": "Object"
  },
  "timestamp": "Date",
  "version": "Number",
  "clientId": "String",  // 客户端唯一标识
  "siteId": "Number",    // CRDT site ID
  "lamport": "Number",   // Lamport 时间戳
  "vectorClock": "Object"
}

User 集合

{
  "_id": "ObjectId",
  "email": "String",
  "username": "String",
  "passwordHash": "String",
  "avatar": "String",
  "role": "String",  // admin, member, guest
  "workspaces": ["ObjectId"],
  "preferences": {
    "theme": "String",
    "language": "String",
    "notifications": "Object"
  },
  "lastActiveAt": "Date",
  "createdAt": "Date",
  "isVerified": "Boolean",
  "isOnline": "Boolean"
}

4.3 PostgreSQL Schema 设计

-- 工作空间表
CREATE TABLE workspaces (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    description TEXT,
    owner_id UUID NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 文档权限表
CREATE TABLE document_permissions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    document_id UUID NOT NULL,
    user_id UUID NOT NULL,
    role VARCHAR(50) NOT NULL,  -- owner, editor, commenter, viewer
    granted_by UUID,
    granted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    expires_at TIMESTAMP,
    UNIQUE(document_id, user_id)
);

-- 评论表
CREATE TABLE comments (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    document_id UUID NOT NULL,
    parent_comment_id UUID,
    user_id UUID NOT NULL,
    content TEXT NOT NULL,
    position_start INTEGER,
    position_end INTEGER,
    status VARCHAR(20) DEFAULT 'active',  -- active, resolved, deleted
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 索引优化
CREATE INDEX idx_document_permissions_doc ON document_permissions(document_id);
CREATE INDEX idx_document_permissions_user ON document_permissions(user_id);
CREATE INDEX idx_comments_document ON comments(document_id);
CREATE INDEX idx_operations_document_version ON operations(document_id, version);

4.4 Redis 数据结构

# 在线用户集合
SET workspace:{workspaceId}:users {userId}
EXPIRE workspace:{workspaceId}:users 300

# 文档活跃用户
HSET doc:{docId}:presence {userId} "{jsonUserData}"
EXPIRE doc:{docId}:presence 60

# 用户光标位置
HSET doc:{docId}:cursors {userId} "{cursorData}"
EXPIRE doc:{docId}:cursors 30

# 会话 Token
SETEX session:{sessionId} 86400 "{sessionData}"

# 速率限制计数器
INCR rate_limit:{userId}:{endpoint}
EXPIRE rate_limit:{userId}:{endpoint} 60

# 发布订阅频道
PUBLISH doc:{docId}:updates "{updateMessage}"

⚡ 5. 协同算法设计

5.1 CRDT vs OT 对比

5.2 Yjs CRDT 实现原理

核心概念

• YDoc：文档根对象，包含所有共享类型
• YText：协同文本类型，支持插入、删除
• YMap：协同 Map 类型
• YArray：协同数组类型
• Client ID：每个客户端的唯一标识
• State Vector：记录每个 client 的最新操作序号

操作流程示例

// 客户端 A 操作
const ydoc = new Y.Doc();
const ytext = ydoc.getText('content');

// 用户输入 "Hello"
ytext.insert(0, 'Hello');

// 生成更新
const update = Y.encodeStateAsUpdate(ydoc);

// 发送到服务端和其他客户端
websocket.send(update);

// 客户端 B 接收更新
const remoteUpdate = websocket.receive();
Y.applyUpdate(ydoc, remoteUpdate);

// 自动合并，保证一致性

5.3 冲突解决策略

文本插入冲突

if (lamportA !== lamportB) {
    return lamportA < lamportB ? -1 : 1;
} else {
    return clientIdA < clientIdB ? -1 : 1;
}

格式化冲突

// 格式属性合并策略
const mergedAttributes = {
    ...baseAttributes,
    ...newAttributes,
    timestamp: Math.max(timestampA, timestampB)
};

5.4 性能优化策略

• 增量更新：只传输变化的 binary update
• 压缩传输：使用 gzip 压缩更新数据
• 批量处理：短时间内的操作合并发送（16ms 窗口）
• 快照机制：定期生成快照减少重放成本
• 垃圾回收：清理已确认的历史操作
• 分片加载：大文档按需加载可见区域

🔌 6. RESTful API 接口文档

6.1 认证授权接口

{
  "email": "user@example.com",
  "username": "string (3-20 字符)",
  "password": "string (最少 8 位)",
  "inviteCode": "string (可选)"
}

{
  "success": true,
  "data": {
    "userId": "uuid",
    "email": "user@example.com",
    "username": "username",
    "accessToken": "jwt_token",
    "refreshToken": "refresh_token"
  },
  "message": "注册成功"
}

{
  "email": "user@example.com",
  "password": "string"
}

{
  "success": true,
  "data": {
    "userId": "uuid",
    "accessToken": "jwt_token",
    "refreshToken": "refresh_token",
    "expiresIn": 3600
  }
}

Authorization: Bearer {refreshToken}

{
  "success": true,
  "data": {
    "accessToken": "new_jwt_token",
    "expiresIn": 3600
  }
}

6.2 文档管理接口

{
  "workspaceId": "uuid (可选)",
  "page": "number (默认 1)",
  "limit": "number (默认 20)",
  "sortBy": "updatedAt|createdAt|title",
  "order": "asc|desc",
  "search": "string (可选)"
}

{
  "success": true,
  "data": {
    "documents": [
      {
        "id": "uuid",
        "title": "文档标题",
        "workspaceId": "uuid",
        "createdBy": {"id": "uuid", "name": "用户名"},
        "updatedAt": "ISO8601",
        "collaborators": 5,
        "preview": "文档预览内容..."
      }
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 20,
      "totalPages": 5
    }
  }
}

{
  "title": "新文档",
  "workspaceId": "uuid",
  "content": "初始内容 (可选)",
  "templateId": "uuid (可选)",
  "visibility": "private|workspace|public"
}

{
  "success": true,
  "data": {
    "id": "uuid",
    "title": "新文档",
    "createdAt": "ISO8601",
    "accessUrl": "/docs/uuid/edit"
  }
}

documentId: string (required)

{
  "includeContent": "boolean (默认 true)",
  "version": "number (可选，获取历史版本)"
}

{
  "success": true,
  "data": {
    "id": "uuid",
    "title": "文档标题",
    "content": "完整内容",
    "createdBy": {...},
    "collaborators": [...],
    "permissions": "owner|editor|viewer",
    "version": 42,
    "updatedAt": "ISO8601"
  }
}

{
  "title": "新标题 (可选)",
  "workspaceId": "uuid (可选)",
  "settings": {
    "allowComments": true,
    "lockEditing": false
  }
}

{
  "success": true,
  "message": "文档已移至回收站"
}

6.3 工作空间接口

{
  "success": true,
  "data": {
    "workspaces": [
      {
        "id": "uuid",
        "name": "工作空间名称",
        "role": "owner|member",
        "documentCount": 25,
        "memberCount": 10
      }
    ]
  }
}

{
  "name": "工作空间名称",
  "description": "描述 (可选)",
  "visibility": "private|public"
}

6.4 权限管理接口

{
  "userId": "uuid",
  "role": "editor|commenter|viewer",
  "expiresIn": 86400 (可选，秒)
}

6.5 版本历史接口

{
  "limit": "number (默认 50)",
  "before": "ISO8601 (可选)"
}

{
  "success": true,
  "data": {
    "versions": [
      {
        "version": 42,
        "timestamp": "ISO8601",
        "userId": "uuid",
        "username": "用户名",
        "operationCount": 15,
        "summary": "添加了第三章内容"
      }
    ]
  }
}

6.6 评论接口

{
  "content": "评论内容",
  "positionStart": 100,
  "positionEnd": 150,
  "parentCommentId": "uuid (可选，回复评论)"
}

6.7 错误响应格式

// 标准错误响应
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "人类可读的错误描述",
    "details": {}  // 可选的详细错误信息
  }
}

// 常见错误码
{
  "UNAUTHORIZED": "未授权访问",
  "FORBIDDEN": "权限不足",
  "NOT_FOUND": "资源不存在",
  "VALIDATION_ERROR": "参数验证失败",
  "RATE_LIMIT_EXCEEDED": "请求频率超限",
  "DOCUMENT_LOCKED": "文档已被锁定",
  "VERSION_CONFLICT": "版本冲突"
}

📡 7. WebSocket 实时通信协议

7.1 连接建立

连接 URL 格式

wss://ws.collab-doc.com/v2/ws?token={jwt_token}&documentId={doc_id}&clientId={client_id}

握手响应

// 服务端发送的欢迎消息
{
  "type": "welcome",
  "data": {
    "clientId": "assigned_client_id",
    "documentId": "doc_id",
    "serverTime": "ISO8601",
    "protocolVersion": "2.0"
  }
}

7.2 消息协议格式

通用消息结构

{
  "type": "message_type",
  "requestId": "uuid (可选，用于请求 - 响应配对)",
  "timestamp": "number (毫秒时间戳)",
  "data": {}
}

7.3 客户端 → 服务端消息

{
  "type": "join-document",
  "requestId": "uuid",
  "data": {
    "documentId": "uuid",
    "lastSyncedVersion": "number (可选)"
  }
}

// 响应
{
  "type": "document-state",
  "requestId": "uuid",
  "data": {
    "documentId": "uuid",
    "content": "binary_update",
    "version": 42,
    "collaborators": [...],
    "cursors": {...}
  }
}

{
  "type": "sync-update",
  "data": {
    "update": "base64_encoded_binary",
    "version": 43,
    "clientId": "client_id"
  }
}

{
  "type": "cursor-update",
  "data": {
    "selection": {
      "anchor": {"pos": 100, "offset": 0},
      "head": {"pos": 150, "offset": 5}
    },
    "scrollPosition": {"top": 500},
    "userColor": "#FF5733"
  }
}

{
  "type": "awareness-update",
  "data": {
    "status": "active|idle|offline",
    "typing": true,
    "metadata": {
      "browser": "Chrome 120",
      "platform": "Windows"
    }
  }
}

{
  "type": "request-snapshot",
  "requestId": "uuid",
  "data": {
    "version": 40
  }
}

7.4 服务端 → 客户端消息

{
  "type": "sync-update",
  "data": {
    "update": "base64_encoded_binary",
    "version": 43,
    "clientId": "other_client_id",
    "userId": "user_id"
  }
}

{
  "type": "cursor-broadcast",
  "data": {
    "clientId": "client_id",
    "userId": "user_id",
    "username": "用户名",
    "selection": {...},
    "color": "#FF5733"
  }
}

{
  "type": "user-joined",
  "data": {
    "userId": "uuid",
    "username": "用户名",
    "avatar": "url",
    "color": "#FF5733",
    "role": "editor"
  }
}

{
  "type": "user-left",
  "data": {
    "userId": "uuid",
    "username": "用户名"
  }
}

{
  "type": "awareness-change",
  "data": {
    "clientId": "client_id",
    "userId": "user_id",
    "status": "idle",
    "typing": false
  }
}

{
  "type": "version-created",
  "data": {
    "version": 43,
    "timestamp": "ISO8601",
    "userId": "uuid",
    "operationCount": 10
  }
}

{
  "type": "error",
  "requestId": "uuid (如果是对请求的响应)",
  "data": {
    "code": "SYNC_VERSION_MISMATCH",
    "message": "版本不匹配",
    "expectedVersion": 42,
    "receivedVersion": 40
  }
}

7.5 心跳与连接维护

// 客户端发送心跳
{
  "type": "ping",
  "timestamp": 1234567890
}

// 服务端响应
{
  "type": "pong",
  "timestamp": 1234567890,
  "serverTime": 1234567895
}

// 超时断开：90 秒无通信自动断开

7.6 断线重连流程

🔒 8. 安全设计

8.1 认证安全

• JWT Token: RS256 签名，有效期 1 小时
• Refresh Token: 有效期 7 天，存储在 HttpOnly Cookie
• 密码加密: bcrypt + salt (cost=12)
• 双因素认证: TOTP (可选)
• 会话管理: 单设备登录，异地登录提醒

8.2 授权控制

8.3 数据安全

• 传输加密: TLS 1.3
• 静态加密: AES-256-GCM
• 端到端加密: 可选，使用 Signal Protocol
• 数据备份: 每日自动备份，保留 30 天
• 审计日志: 所有敏感操作记录日志

8.4 防护措施

• 速率限制: 每用户 100 请求/分钟
• XSS 防护: 内容过滤 + CSP 策略
• CSRF 防护: SameSite Cookie + CSRF Token
• SQL 注入: 参数化查询 + ORM
• DDoS 防护: Cloudflare + 限流

🚀 9. 部署方案

9.1 生产环境架构

9.2 Kubernetes 资源配置

apiVersion: apps/v1
kind: Deployment
metadata:
  name: collab-ws-service
spec:
  replicas: 5
  selector:
    matchLabels:
      app: collab-ws
  template:
    spec:
      containers:
      - name: ws-server
        image: collab-doc/ws-server:v2.0
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "1Gi"
            cpu: "1000m"
        ports:
        - containerPort: 8080
        env:
        - name: REDIS_URL
          valueFrom:
            secretKeyRef:
              name: app-secrets
              key: redis-url
---
apiVersion: v1
kind: Service
metadata:
  name: ws-service
spec:
  selector:
    app: collab-ws
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer

9.3 扩缩容策略

• HPA 配置: CPU > 70% 或 内存 > 80% 时扩容
• 最大副本数: 20
• 最小副本数: 3
• 冷却时间: 300 秒

9.4 监控指标