⚡ 多人协同编辑系统

// Yjs 核心数据类型
import { Y } from 'yjs'

// 文档类型定义
interface DocumentContent {
  content: Y.Text          // 富文本内容
  cursors: Y.Map<Cursor>   // 用户光标位置
  awareness: Y.Map<Awareness> // 用户状态感知
  metadata: Y.Map<any>     // 文档元数据
}

// 光标信息结构
interface Cursor {
  userId: string
  userName: string
  color: string
  position: number
  selection: { start: number, end: number } | null
  timestamp: number
}

// 场景：两个用户同时在位置 5 插入不同文本
// 用户 A 插入 "Hello"，用户 B 插入 "World"

// Yjs 会自动为每个操作分配唯一的 Lamport 时间戳和客户端 ID
// 根据 ID 和时间戳确定操作顺序，保证所有客户端结果一致

const ydoc = new Y.Doc()
const ytext = ydoc.getText('content')

// 用户 A 的操作
ytext.insert(5, 'Hello', clientA_ID)

// 用户 B 的操作 (同时发生)
ytext.insert(5, 'World', clientB_ID)

// CRDT 会根据客户端 ID 字典序决定顺序
// 假设 clientA_ID < clientB_ID，则结果为 "...HelloWorld..."
// 所有客户端都会得到相同的结果

// 使用 Yjs Awareness 实现光标和状态同步
import { Awareness } from 'y-protocols/awareness'

const awareness = new Awareness(ydoc)

// 设置本地用户状态
awareness.setLocalStateField('user', {
  name: '张三',
  color: '#FF6B6B',
  cursorPosition: 125,
  selection: { start: 120, end: 130 }
})

// 监听其他用户状态变化
awareness.on('change', ({ added, updated, removed }) => {
  added.forEach(id => {
    const state = awareness.getState(id)
    showRemoteCursor(id, state.user)
  })
  updated.forEach(id => {
    const state = awareness.getState(id)
    updateRemoteCursor(id, state.user)
  })
  removed.forEach(id => {
    removeRemoteCursor(id)
  })
})

{
  "_id": ObjectId,
  "doc_id": UUID,
  "user_id": UUID,
  "operation_type": "insert" | "delete" | "update",
  "operation_data": {
    "insert": { "position": Number, "content": String },
    "delete": { "position": Number, "length": Number }
  },
  "timestamp": ISODate,
  "vector_clock": { "client_id": Number },
  "sequence_num": Number,
  "yjs_update": BinData  // Yjs 增量更新二进制
}

// 客户端发送编辑操作
{
  "type": "update",
  "data": Uint8Array,  // Yjs 编码的二进制更新
  "clientId": "client-abc123",
  "timestamp": 1710259200000
}

// 服务器广播给其他客户端
{
  "type": "update",
  "data": Uint8Array,
  "originClientId": "client-abc123",
  "timestamp": 1710259200000
}

// 客户端上报状态
{
  "type": "awareness",
  "clientId": "client-abc123",
  "state": {
    "user": {
      "userId": "user-001",
      "userName": "zhangsan",
      "color": "#FF6B6B",
      "avatarUrl": "https://oss.example.com/avatars/xxx.png"
    },
    "cursor": {
      "position": 125,
      "selection": {
        "start": 120,
        "end": 130
      }
    },
    "status": "editing"  // editing | viewing | away
  }
}

// 服务器广播状态变化
{
  "type": "awareness",
  "changes": {
    "added": [],
    "updated": ["client-abc123"],
    "removed": []
  },
  "states": {
    "client-abc123": { ... }  // 完整状态
  }
}

// 用户加入
{
  "type": "user-join",
  "user": {
    "userId": "user-002",
    "userName": "lisi",
    "color": "#4ECDC4",
    "avatarUrl": "https://oss.example.com/avatars/yyy.png"
  }
}

// 用户离开
{
  "type": "user-leave",
  "userId": "user-002",
  "reason": "disconnect"  // disconnect | timeout | kicked
}

// 客户端每 30 秒发送 ping
{
  "type": "ping",
  "timestamp": 1710259200000
}

// 服务器响应 pong
{
  "type": "pong",
  "timestamp": 1710259200000,
  "serverTime": 1710259200050
}

// 90 秒无活动自动断开连接

{
  "algorithm": "RS256",
  "accessTokenExpiry": "2h",
  "refreshTokenExpiry": "7d",
  "issuer": "collab-system",
  "audience": "collab-client",
  "claims": {
    "userId": "user-001",
    "email": "user@example.com",
    "roles": ["user"],
    "permissions": {
      "doc-001": "editor",
      "doc-002": "viewer"
    }
  }
}

{
  "logId": "log-001",
  "timestamp": "2026-03-12T16:00:00.000Z",
  "userId": "user-001",
  "action": "document.update",
  "resource": "doc-001",
  "ipAddress": "192.168.1.100",
  "userAgent": "Mozilla/5.0...",
  "requestId": "req-abc123",
  "status": "success",
  "metadata": {
    "changeCount": 5,
    "duration": 120
  }
}

// 使用 gzip 压缩 Yjs Update 消息
import { gzip, ungzip } from 'pako'

// 发送前压缩
const compressed = gzip(updateData)
ws.send(compressed)

// 接收后解压
ws.onmessage = async (event) => {
  const data = await event.arrayBuffer()
  const decompressed = ungzip(data)
  applyUpdate(decompressed)
}

// 压缩率：通常可减少 60-80% 的数据量

// 合并短时间内的多个操作
const BATCH_INTERVAL = 50 // ms
let batchQueue = []
let batchTimer = null

function enqueueOperation(op) {
  batchQueue.push(op)
  if (!batchTimer) {
    batchTimer = setTimeout(flushBatch, BATCH_INTERVAL)
  }
}

function flushBatch() {
  const mergedUpdate = mergeUpdates(batchQueue)
  broadcast(mergedUpdate)
  batchQueue = []
  batchTimer = null
}

// 光标更新使用节流 (100ms)
const throttledSendCursor = throttle(sendCursor, 100)

// 自动保存使用防抖 (2s)
const debouncedSave = debounce(saveToStorage, 2000)

editor.on('cursorChange', throttledSendCursor)
editor.on('contentChange', debouncedSave)

# 多阶段构建
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package.json ./

ENV NODE_ENV=production
EXPOSE 3000

CMD ["node", "dist/server.js"]

version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://user:pass@db:5432/collab
      - REDIS_URL=redis://redis:6379
    depends_on:
      - db
      - redis
    deploy:
      replicas: 3

  db:
    image: postgres:15
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=collab
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass

  redis:
    image: redis:7-alpine
    volumes:
      - redisdata:/data

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - app

volumes:
  pgdata:
  redisdata:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: collab-app
spec:
  replicas: 5
  selector:
    matchLabels:
      app: collab
  template:
    metadata:
      labels:
        app: collab
    spec:
      containers:
      - name: app
        image: collab-app:latest
        ports:
        - containerPort: 3000
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: url
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "1Gi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 5