PlayCanvas Editor中继功能完全指南：从零构建高效多人协作环境

2026-03-10 04:52:23作者：廉彬冶Miranda

引言：当3D协作遇上"不同步"难题

想象这样一个场景：你和团队正在开发一款复杂的3D游戏场景，你刚刚调整了关键光源参数，准备向团队展示效果，却发现同事看到的还是5分钟前的版本；或者两位设计师同时修改同一个模型，结果辛辛苦苦的工作因为同步问题付诸东流。这些问题不仅浪费时间，更严重打击团队协作效率。

在多人协作的3D项目开发中，实时同步和低延迟通信是提升团队效率的核心要素。PlayCanvas Editor的中继（Relay）功能通过WebSocket协议为开发团队提供了稳定的实时协作环境，让多人同时编辑3D场景成为可能。本文将通过"问题引入→核心原理→实践步骤→场景拓展"四个阶段，帮助你从零开始配置中继功能，构建高效的多人协作工作流。

一、核心原理：中继功能如何实现"无缝同步"？

学习目标

理解中继功能的基本工作原理
掌握WebSocket在实时协作中的应用方式
了解PlayCanvas中继系统的关键组件

1.1 从"对讲机"到"电话会议"：中继功能的本质

简单来说，中继功能就像是为你的3D编辑器安装了一套实时通信系统。如果把传统的文件共享比作"对讲机"（一次只能一人发言，信息传递有延迟），那么中继功能就像是"电话会议系统"（多人实时交流，信息即时同步）。

在技术实现上，中继功能基于WebSocket协议（一种在单个TCP连接上进行全双工通信的协议）构建，这使得编辑器可以在用户之间建立持久连接，实现即时的数据交换。

1.2 中继系统的"四大金刚"：核心组件解析

PlayCanvas中继系统包含四个关键组件，它们协同工作确保实时协作的顺畅进行：

🔧 连接管理器：就像一位细心的接线员，负责维护WebSocket连接的稳定性，处理网络波动时的自动重连。

🛠️ 房间路由器：类似会议组织者，为不同项目创建独立的"虚拟房间"，确保消息不会发送到错误的项目中。

🔐 权限验证器：作为安保人员，检查每个用户的权限，确保只有授权人员才能参与协作。

📡 事件分发器：好比快递分拣中心，将收到的消息准确分发给对应的编辑器模块（如场景、属性面板等）。

1.3 数据同步的"魔法"：中继通信流程

中继功能的数据同步过程可以分为三个阶段：

捕获变更：当用户在编辑器中进行操作（如移动模型、修改属性），系统捕获这些变更
编码传输：将变更数据编码为轻量级消息，通过WebSocket发送
解码应用：接收方解码消息并应用到本地编辑器，实现界面同步

这个过程通常在毫秒级完成，用户几乎感觉不到延迟。

关键收获

中继功能通过WebSocket实现实时双向通信
四大核心组件（连接管理器、房间路由器、权限验证器、事件分发器）协同工作
数据同步经历捕获、编码传输、解码应用三个阶段

二、实施步骤：三步打造高效协作环境

学习目标

掌握中继功能的完整配置流程
学会优化连接参数以适应不同网络环境
能够监控和诊断中继连接问题

模块一：环境准备与服务初始化

准备工作

在启用中继功能前，需要确保开发环境满足以下条件：

依赖检查：验证项目package.json中是否包含WebSocket相关依赖

// package.json中应包含类似依赖
"dependencies": {
  "@playcanvas/observer": "^1.0.0",
  "ws": "^8.0.0"
}

权限配置：确保用户具有"协作编辑"权限，权限检查逻辑在编辑器启动时自动执行
服务器确认：确认已部署中继服务器，默认连接地址通过项目配置文件设置

操作流程

权限验证与连接建立

// 权限验证通过后建立中继连接
// 检查用户是否有读取权限
if (editor.call('permissions:read')) {
  // 从配置中获取中继服务器地址
  const relayServerUrl = config.url.relay.ws;
  // 建立连接
  relay.connect(relayServerUrl);
  console.log('中继连接请求已发送');
} else {
  console.warn('无中继服务访问权限，协作功能已禁用');
}

连接状态事件监听

// 监听连接成功事件
editor.on('relay:connected', () => {
  // 更新UI显示连接状态
  updateConnectionStatus('已连接', 'success');
  // 连接成功后加入项目房间
  joinProjectRoom(currentProjectId);
});

// 监听连接断开事件
editor.on('relay:disconnected', (reason) => {
  // 显示断开连接原因
  updateConnectionStatus(`已断开: ${reason}`, 'error');
  // 自动尝试重连
  scheduleReconnection();
});

验证方法

查看编辑器右下角状态栏，确认显示"已连接"状态
打开浏览器开发者工具（F12），切换到"网络"标签，过滤WebSocket连接，确认状态为"101 Switching Protocols"
查看控制台输出，确认没有连接相关错误信息

模块二：连接优化与状态监控

准备工作

了解团队成员的网络环境（如办公室局域网、家庭宽带、移动网络等）
准备网络性能测试工具（如ping、traceroute或浏览器网络性能面板）

操作流程

连接参数优化配置

// 中继连接参数优化配置
const relayConfig = {
  // 重连延迟策略：采用指数退避算法
  reconnectDelay: {
    initial: 1000,    // 初始延迟1秒
    max: 8000,        // 最大延迟8秒
    factor: 2         // 每次失败后延迟翻倍
  },
  // 心跳检测机制
  heartbeat: {
    interval: 10000,  // 每10秒发送一次心跳包
    timeout: 5000     // 5秒内未收到响应则认为连接超时
  },
  // 消息传输配置
  message: {
    maxSize: 1024 * 16, // 单条消息最大16KB
    compress: true      // 启用消息压缩
  }
};

// 应用配置
relay.configure(relayConfig);

连接状态可视化实现

// 创建连接状态监控组件
class ConnectionMonitor {
  constructor() {
    this.statusElement = document.createElement('div');
    this.statusElement.className = 'relay-status';
    document.body.appendChild(this.statusElement);
    
    // 初始化状态显示
    this.updateStatus('connecting', '连接中...');
    
    // 绑定事件监听
    this.bindEvents();
  }
  
  bindEvents() {
    // 监听连接事件
    editor.on('relay:connected', () => {
      this.updateStatus('connected', '中继服务已连接');
    });
    
    // 监听断开事件
    editor.on('relay:disconnected', (reason) => {
      this.updateStatus('disconnected', `已断开: ${reason}`);
    });
    
    // 监听错误事件
    editor.on('relay:error', (error) => {
      this.updateStatus('error', `错误: ${error.message}`);
    });
  }
  
  updateStatus(status, message) {
    // 更新状态文本
    this.statusElement.textContent = message;
    
    // 更新状态样式
    this.statusElement.className = `relay-status status-${status}`;
  }
}

// 初始化连接监控
new ConnectionMonitor();

验证方法

故意断开网络再恢复，观察是否能自动重连
监控不同网络环境下的连接稳定性（可记录重连次数和延迟）
使用网络节流工具模拟弱网环境，测试系统表现

模块三：房间管理与消息配置

准备工作

确定项目协作的房间划分策略（如按项目、按功能模块或按团队划分）
了解不同类型消息的传输需求（如场景更新、属性修改、聊天消息等）

操作流程

房间管理功能实现

// 房间管理服务
class RoomService {
  constructor() {
    this.currentRoom = null;
    this.roomUsers = new Map(); // 使用Map存储房间用户，确保操作原子性
  }
  
  // 加入房间
  async joinRoom(roomId, metadata) {
    try {
      // 离开当前房间（如果已加入）
      if (this.currentRoom) {
        await this.leaveRoom();
      }
      
      // 发送加入房间请求
      const result = await relay.sendRequest('room:join', {
        roomId,
        metadata  // 包含项目ID、用户权限等信息
      });
      
      if (result.success) {
        this.currentRoom = roomId;
        this.updateRoomUsers(result.users);
        console.log(`成功加入房间: ${roomId}`);
        return true;
      } else {
        console.error('加入房间失败:', result.error);
        return false;
      }
    } catch (error) {
      console.error('加入房间时发生错误:', error);
      return false;
    }
  }
  
  // 离开房间
  async leaveRoom() {
    if (!this.currentRoom) return true;
    
    try {
      await relay.sendRequest('room:leave', {
        roomId: this.currentRoom
      });
      
      this.currentRoom = null;
      this.roomUsers.clear();
      console.log('已离开房间');
      return true;
    } catch (error) {
      console.error('离开房间时发生错误:', error);
      return false;
    }
  }
  
  // 更新房间用户列表
  updateRoomUsers(users) {
    this.roomUsers.clear();
    users.forEach(user => {
      this.roomUsers.set(user.id, user);
    });
    
    // 触发用户列表更新事件
    editor.emit('room:users:updated', Array.from(this.roomUsers.values()));
  }
}

// 初始化房间服务
const roomService = new RoomService();
// 加入项目房间
roomService.joinRoom('project-123', {
  projectId: 123,
  accessLevel: 'developer'
});

消息系统配置

// 消息服务
class MessageService {
  constructor() {
    this.registerMessageHandlers();
  }
  
  // 注册消息处理器
  registerMessageHandlers() {
    // 注册广播消息处理器
    relay.on('message:broadcast', (data) => {
      this.handleBroadcastMessage(data);
    });
    
    // 注册定向消息处理器
    relay.on('message:direct', (data) => {
      this.handleDirectMessage(data);
    });
  }
  
  // 发送广播消息（房间内所有用户可见）
  sendBroadcastMessage(type, payload) {
    if (!roomService.currentRoom) {
      console.error('未加入房间，无法发送广播消息');
      return;
    }
    
    relay.sendMessage({
      type: 'broadcast',
      roomId: roomService.currentRoom,
      data: {
        messageType: type,
        payload: payload
      }
    });
  }
  
  // 发送定向消息（仅指定用户可见）
  sendDirectMessage(userId, type, payload) {
    relay.sendMessage({
      type: 'direct',
      targetUserId: userId,
      data: {
        messageType: type,
        payload: payload
      }
    });
  }
  
  // 处理广播消息
  handleBroadcastMessage(data) {
    switch (data.messageType) {
      case 'entity:transform':
        // 处理实体变换消息
        editor.call('entities:update:transform', data.payload);
        break;
      case 'asset:updated':
        // 处理资源更新消息
        editor.call('assets:update', data.payload.assetId, data.payload.changes);
        break;
      // 其他消息类型处理...
    }
  }
  
  // 处理定向消息
  handleDirectMessage(data) {
    switch (data.messageType) {
      case 'code:review':
        // 处理代码审查请求
        editor.call('ui:show:code-review', data.payload);
        break;
      case 'chat:message':
        // 处理聊天消息
        editor.call('chat:add', {
          user: data.sender,
          message: data.payload.text,
          timestamp: new Date()
        });
        break;
      // 其他消息类型处理...
    }
  }
}

// 初始化消息服务
new MessageService();

验证方法

邀请团队成员加入同一房间，验证是否能看到彼此的编辑操作
测试不同类型消息的传输效果：广播消息（如移动模型）和定向消息（如发送聊天）
检查房间用户列表是否能正确更新（用户加入/离开时）

关键收获

中继功能配置分为环境准备、连接优化和房间管理三个核心模块
连接参数优化需要根据网络环境调整重连策略和心跳机制
房间管理实现项目隔离和用户权限控制
消息系统支持广播和定向两种通信模式

三、实战技巧：让协作更顺畅的7个秘诀

学习目标

掌握中继功能的高级使用技巧
学会诊断和解决常见的中继连接问题
了解性能优化的具体方法和量化指标

3.1 断线重连：智能恢复连接的艺术

场景案例：团队成员小王正在地铁上远程工作，网络信号时断时续。当中继连接断开时，系统能够自动尝试重连，并且在重连成功后恢复他的编辑状态。

// 智能重连实现
class ReconnectionManager {
  constructor() {
    this._connectAttempts = 0;
    this._reconnectTimer = null;
  }
  
  // 安排重连
  scheduleReconnection() {
    // 如果已有重连定时器，清除它
    if (this._reconnectTimer) {
      clearTimeout(this._reconnectTimer);
    }
    
    // 达到最大尝试次数，停止重连
    if (this._connectAttempts >= 8) {
      editor.emit('relay:reconnect:failed');
      console.error('已达到最大重连尝试次数');
      return;
    }
    
    // 计算重连延迟（指数退避算法）
    const delay = Math.min(
      1000 * Math.pow(2, this._connectAttempts), 
      8000 // 最大延迟8秒
    );
    
    console.log(`将在 ${delay}ms 后尝试重连（第 ${this._connectAttempts + 1} 次）`);
    
    // 设置重连定时器
    this._reconnectTimer = setTimeout(() => {
      this._connectAttempts++;
      this._attemptReconnection();
    }, delay);
  }
  
  // 执行重连
  async _attemptReconnection() {
    try {
      // 尝试重新连接
      await relay.reconnect();
      
      // 重连成功，重置尝试次数
      this._connectAttempts = 0;
      console.log('重连成功');
      editor.emit('relay:reconnected');
    } catch (error) {
      console.error('重连尝试失败:', error);
      // 安排下一次重连
      this.scheduleReconnection();
    }
  }
  
  // 手动触发重连
  triggerReconnection() {
    this._connectAttempts = 0;
    this.scheduleReconnection();
  }
}

// 初始化重连管理器
const reconnectionManager = new ReconnectionManager();
// 当连接断开时触发重连
editor.on('relay:disconnected', () => {
  reconnectionManager.scheduleReconnection();
});

量化指标：

初始重连延迟：1秒
最大重连延迟：8秒
最大重连尝试次数：8次
预期恢复率：在网络不稳定环境下>90%的连接可自动恢复

3.2 批量更新：减少网络传输的"交通拥堵"

场景案例：设计师小李正在调整多个灯光参数，如果每次微调都立即发送更新消息，会造成网络拥堵和性能问题。使用批量更新策略，可以显著减少消息数量。

// 批量更新管理器
class BatchUpdateManager {
  constructor() {
    this._batchQueue = new Map(); // 使用Map存储不同类型的更新
    this._batchTimer = null;
    this._defaultBatchDelay = 300; // 默认批量延迟300ms
  }
  
  // 添加更新到批处理队列
  queueUpdate(type, id, data) {
    // 如果不存在该类型的队列，创建一个
    if (!this._batchQueue.has(type)) {
      this._batchQueue.set(type, new Map());
    }
    
    const typeQueue = this._batchQueue.get(type);
    // 存储或合并更新数据
    typeQueue.set(id, {
      ...typeQueue.get(id), // 合并已有数据
      ...data              // 新数据覆盖旧数据
    });
    
    // 启动批处理定时器
    this._startBatchTimer();
  }
  
  // 启动批处理定时器
  _startBatchTimer() {
    // 如果定时器已存在，清除它
    if (this._batchTimer) {
      clearTimeout(this._batchTimer);
    }
    
    // 设置定时器，延迟发送批量更新
    this._batchTimer = setTimeout(() => {
      this._sendBatchUpdates();
    }, this._defaultBatchDelay);
  }
  
  // 发送批量更新
  _sendBatchUpdates() {
    // 如果队列为空，直接返回
    if (this._batchQueue.size === 0) {
      return;
    }
    
    // 准备批量更新数据
    const batchData = {};
    this._batchQueue.forEach((typeQueue, type) => {
      batchData[type] = Array.from(typeQueue.entries()).map(([id, data]) => ({
        id,
        data
      }));
    });
    
    // 发送批量更新消息
    messageService.sendBroadcastMessage('batch:update', batchData);
    
    // 清空队列
    this._batchQueue.clear();
    this._batchTimer = null;
    
    console.log(`发送批量更新，包含 ${Object.keys(batchData).length} 种类型，共 ${
      Object.values(batchData).reduce((sum, items) => sum + items.length, 0)
    } 条更新`);
  }
  
  // 立即发送批处理（用于紧急更新）
  flush() {
    if (this._batchTimer) {
      clearTimeout(this._batchTimer);
      this._sendBatchUpdates();
    }
  }
}

// 初始化批量更新管理器
const batchUpdateManager = new BatchUpdateManager();

// 使用示例：调整多个灯光参数
function updateLightProperties(lightId, properties) {
  // 将更新添加到批处理队列
  batchUpdateManager.queueUpdate('light', lightId, properties);
}

// 连续调整参数
updateLightProperties('light-1', { intensity: 2.5 });
updateLightProperties('light-1', { color: [1, 0.8, 0.6] });
updateLightProperties('light-2', { intensity: 1.8 });
// 这些更新将在300ms后合并为一个批量消息发送

量化指标：

默认批量延迟：300ms
预期消息减少率：在频繁编辑场景下减少60-80%的消息数量
性能提升：编辑器响应速度提升约30%

3.3 冲突解决：当多人编辑同一对象时

场景案例：开发人员小张和设计师小陈同时修改同一个模型的属性，小张调整了位置，小陈修改了材质。冲突解决机制需要智能合并这些变更，避免一方的修改被覆盖。

// 冲突解决服务
class ConflictResolutionService {
  constructor() {
    // 本地变更队列
    this._localChangeQueue = [];
    // 远程变更队列
    this._remoteChangeQueue = [];
    // 是否正在处理冲突
    this._isProcessing = false;
  }
  
  // 添加本地变更
  addLocalChange(objectType, objectId, property, value, timestamp) {
    this._localChangeQueue.push({
      source: 'local',
      objectType,
      objectId,
      property,
      value,
      timestamp
    });
    
    // 尝试处理变更
    this._processChanges();
  }
  
  // 添加远程变更
  addRemoteChange(objectType, objectId, property, value, timestamp, userId) {
    this._remoteChangeQueue.push({
      source: 'remote',
      userId,
      objectType,
      objectId,
      property,
      value,
      timestamp
    });
    
    // 尝试处理变更
    this._processChanges();
  }
  
  // 处理变更并解决冲突
  _processChanges() {
    // 如果正在处理，或没有变更，直接返回
    if (this._isProcessing || 
        this._localChangeQueue.length === 0 && 
        this._remoteChangeQueue.length === 0) {
      return;
    }
    
    this._isProcessing = true;
    
    // 合并所有变更
    const allChanges = [
      ...this._localChangeQueue,
      ...this._remoteChangeQueue
    ];
    
    // 按对象类型和ID分组
    const groupedChanges = {};
    
    allChanges.forEach(change => {
      const key = `${change.objectType}:${change.objectId}`;
      if (!groupedChanges[key]) {
        groupedChanges[key] = {};
      }
      
      if (!groupedChanges[key][change.property]) {
        groupedChanges[key][change.property] = [];
      }
      
      groupedChanges[key][change.property].push(change);
    });
    
    // 处理每个属性的变更
    Object.values(groupedChanges).forEach(properties => {
      Object.values(properties).forEach(changeList => {
        this._resolvePropertyChanges(changeList);
      });
    });
    
    // 清空队列
    this._localChangeQueue = [];
    this._remoteChangeQueue = [];
    this._isProcessing = false;
  }
  
  // 解决属性变更冲突
  _resolvePropertyChanges(changeList) {
    // 按时间戳排序，最新的变更排在后面
    changeList.sort((a, b) => a.timestamp - b.timestamp);
    
    // 简单策略：最后一次变更获胜
    // 更复杂的策略可以根据属性类型和内容进行智能合并
    const finalChange = changeList[changeList.length - 1];
    
    // 应用最终变更
    this._applyChange(finalChange);
    
    // 如果有冲突（即不止一个变更），记录冲突解决情况
    if (changeList.length > 1) {
      console.log(`解决冲突: ${finalChange.objectType}:${finalChange.objectId}.${finalChange.property}, ` +
                `应用了 ${finalChange.source === 'local' ? '本地' : '远程用户#' + finalChange.userId} 的变更`);
      
      // 可以在这里添加UI通知，告知用户冲突已解决
      editor.call('ui:notify', {
        type: 'info',
        message: `已解决冲突，应用了最新变更`,
        duration: 3000
      });
    }
  }
  
  // 应用变更
  _applyChange(change) {
    switch (change.objectType) {
      case 'entity':
        editor.call('entities:set', change.objectId, change.property, change.value);
        break;
      case 'asset':
        editor.call('assets:set', change.objectId, change.property, change.value);
        break;
      // 其他对象类型处理...
    }
  }
}

// 初始化冲突解决服务
const conflictResolutionService = new ConflictResolutionService();

3.4 网络状态自适应：根据网络情况调整同步策略

场景案例：团队成员分布在不同地区，有的在高速网络环境，有的在较差的网络环境。中继系统可以根据实时网络状况调整同步策略。

// 网络状态监控服务
class NetworkMonitor {
  constructor() {
    this._networkQuality = 'excellent'; // 网络质量：excellent, good, fair, poor
    this._lastReportedQuality = 'excellent';
    this._monitorInterval = null;
    this._samples = [];
    this._sampleWindow = 10; // 采样窗口大小
    
    // 初始化网络监控
    this.startMonitoring();
    // 监听浏览器网络状态事件
    window.addEventListener('online', () => this._handleNetworkChange(true));
    window.addEventListener('offline', () => this._handleNetworkChange(false));
  }
  
  // 开始网络监控
  startMonitoring() {
    // 每5秒评估一次网络质量
    this._monitorInterval = setInterval(() => {
      this._assessNetworkQuality();
    }, 5000);
  }
  
  // 停止网络监控
  stopMonitoring() {
    if (this._monitorInterval) {
      clearInterval(this._monitorInterval);
      this._monitorInterval = null;
    }
  }
  
  // 处理网络连接状态变化
  _handleNetworkChange(isOnline) {
    if (isOnline) {
      console.log('网络已恢复连接');
      this._networkQuality = 'fair'; // 刚恢复连接时假设为一般质量
      editor.emit('network:reconnected');
    } else {
      console.log('网络连接已断开');
      this._networkQuality = 'poor';
      editor.emit('network:disconnected');
    }
    this._notifyQualityChange();
  }
  
  // 评估网络质量
  _assessNetworkQuality() {
    // 创建性能测试
    const testStart = performance.now();
    const testDataSize = 1024; // 1KB测试数据
    const testData = new Array(testDataSize).fill('x').join('');
    
    // 通过中继发送测试消息并测量往返时间
    relay.sendRequest('network:ping', { data: testData })
      .then(response => {
        const roundTripTime = performance.now() - testStart;
        
        // 存储采样（往返时间，单位ms）
        this._samples.push(roundTripTime);
        
        // 保持采样窗口大小
        if (this._samples.length > this._sampleWindow) {
          this._samples.shift();
        }
        
        // 计算平均往返时间
        const avgRtt = this._samples.reduce((sum, sample) => sum + sample, 0) / this._samples.length;
        
        // 根据平均往返时间评估网络质量
        if (avgRtt < 100) {
          this._networkQuality = 'excellent';
        } else if (avgRtt < 300) {
          this._networkQuality = 'good';
        } else if (avgRtt < 600) {
          this._networkQuality = 'fair';
        } else {
          this._networkQuality = 'poor';
        }
        
        console.log(`网络质量评估: ${this._networkQuality} (平均往返时间: ${avgRtt.toFixed(2)}ms)`);
        
        // 如果质量变化，通知系统
        this._notifyQualityChange();
        
        // 根据网络质量调整系统行为
        this._adjustSystemForNetworkQuality();
      })
      .catch(error => {
        console.error('网络质量测试失败:', error);
        this._networkQuality = 'poor';
        this._notifyQualityChange();
      });
  }
  
  // 通知网络质量变化
  _notifyQualityChange() {
    if (this._networkQuality !== this._lastReportedQuality) {
      this._lastReportedQuality = this._networkQuality;
      editor.emit('network:quality:change', this._networkQuality);
    }
  }
  
  // 根据网络质量调整系统行为
  _adjustSystemForNetworkQuality() {
    switch (this._networkQuality) {
      case 'excellent':
        // 优秀网络：启用全部功能，最小批量延迟
        batchUpdateManager._defaultBatchDelay = 100;
        messageService.setCompression(false);
        editor.call('render:quality:set', 'high');
        break;
      case 'good':
        // 良好网络：正常批量延迟
        batchUpdateManager._defaultBatchDelay = 200;
        messageService.setCompression(false);
        editor.call('render:quality:set', 'medium');
        break;
      case 'fair':
        // 一般网络：增加批量延迟，启用压缩
        batchUpdateManager._defaultBatchDelay = 400;
        messageService.setCompression(true);
        editor.call('render:quality:set', 'medium');
        break;
      case 'poor':
        // 较差网络：最大批量延迟，启用压缩，降低渲染质量
        batchUpdateManager._defaultBatchDelay = 800;
        messageService.setCompression(true);
        editor.call('render:quality:set', 'low');
        // 减少更新频率
        editor.call('viewport:update:rate', 15); // 15 FPS
        break;
    }
  }
  
  // 获取当前网络质量
  getCurrentQuality() {
    return this._networkQuality;
  }
}

// 初始化网络监控
const networkMonitor = new NetworkMonitor();

量化指标：

网络质量评估间隔：5秒
采样窗口大小：10个样本
网络质量分类阈值：<100ms(优秀)，<300ms(良好)，<600ms(一般)，≥600ms(较差)
批量延迟范围：100ms(优秀)至800ms(较差)

3.5 常见误区解析：避开配置陷阱

误区一：忽视权限配置

错误表现：中继连接始终失败，但没有明确错误提示。 原因分析：用户没有"协作编辑"权限，导致中继服务初始化失败。 解决方案：

// 正确的权限检查方式
async function initRelayService() {
  try {
    // 明确请求权限检查
    const hasPermission = await editor.call('permissions:check', 'collaboration:edit');
    
    if (hasPermission) {
      // 有权限，初始化中继服务
      relay.initialize(config.url.relay.ws);
    } else {
      // 无权限，显示友好提示
      editor.call('ui:show:dialog', {
        title: '协作功能不可用',
        message: '您没有协作编辑权限，请联系项目管理员获取权限。',
        buttons: ['确定']
      });
    }
  } catch (error) {
    console.error('权限检查失败:', error);
  }
}

误区二：使用默认连接参数应对所有网络环境

错误表现：在网络不稳定的环境下频繁断开连接或重连失败。 原因分析：默认连接参数可能不适合较差的网络环境。 解决方案：根据目标用户的网络环境调整重连策略：

// 针对较差网络环境的参数配置
const poorNetworkConfig = {
  reconnectDelay: {
    initial: 2000,   // 更长的初始延迟
    max: 10000,      // 更长的最大延迟
    factor: 1.5      // 较慢的增长因子
  },
  heartbeat: {
    interval: 15000, // 减少心跳频率
    timeout: 10000   // 更长的超时时间
  }
};

// 根据用户位置选择配置
if (user.region === 'low-bandwidth') {
  relay.configure(poorNetworkConfig);
}

误区三：不限制消息大小

错误表现：大型资产更新导致连接断开或消息丢失。 原因分析：单个消息过大，超出服务器或网络的处理能力。 解决方案：实现消息分片和大小限制：

// 消息分片发送
function sendLargeAsset(assetId, assetData) {
  const MAX_CHUNK_SIZE = 8192; // 8KB每片
  const dataBuffer = new TextEncoder().encode(JSON.stringify(assetData));
  const totalChunks = Math.ceil(dataBuffer.length / MAX_CHUNK_SIZE);
  
  // 发送总片数和资产ID
  messageService.sendBroadcastMessage('asset:large:start', {
    assetId,
    totalChunks,
    totalSize: dataBuffer.length
  });
  
  // 分片发送数据
  for (let i = 0; i < totalChunks; i++) {
    const start = i * MAX_CHUNK_SIZE;
    const end = Math.min(start + MAX_CHUNK_SIZE, dataBuffer.length);
    const chunk = dataBuffer.subarray(start, end);
    
    // 发送分片
    messageService.sendBroadcastMessage('asset:large:chunk', {
      assetId,
      chunkIndex: i,
      data: btoa(String.fromCharCode.apply(null, chunk))
    });
    
    // 控制发送速度，避免网络拥塞
    await new Promise(resolve => setTimeout(resolve, 50));
  }
  
  // 发送完成通知
  messageService.sendBroadcastMessage('asset:large:complete', {
    assetId
  });
}

关键收获

断线重连采用指数退避算法，平衡重连效率和资源消耗
批量更新策略可显著减少网络传输量，提升性能
冲突解决机制确保多人编辑时的数据一致性
网络状态自适应根据实时网络状况调整系统行为
常见误区包括忽视权限配置、使用默认参数和不限制消息大小

四、场景拓展：中继功能的创新应用

学习目标

了解中继功能在不同协作场景中的应用
掌握中继功能与其他工具的集成方法
学会扩展中继功能实现自定义协作需求

4.1 跨团队协作最佳实践

在大型项目中，往往需要多个团队协同工作（如设计团队、开发团队、测试团队）。中继功能可以通过精细化的房间管理实现高效的跨团队协作。

团队隔离与信息共享策略：

为每个团队创建独立的基础房间（如"design-team"、"dev-team"）
创建跨团队项目房间（如"project-alpha"）
实现基于角色的消息过滤机制

// 跨团队协作房间管理
class TeamRoomManager {
  constructor() {
    this.rooms = new Map();
    this.userRoles = new Map();
  }
  
  // 设置用户角色
  setUserRoles(userId, roles) {
    this.userRoles.set(userId, roles);
  }
  
  // 加入团队房间
  joinTeamRooms(userId) {
    const roles = this.userRoles.get(userId) || [];
    
    // 为每个角色加入相应的团队房间
    roles.forEach(role => {
      const roomId = `team-${role}`;
      this.joinRoom(roomId, { role });
    });
    
    // 如果是项目负责人，加入所有项目房间
    if (roles.includes('project-lead')) {
      this.joinAllProjectRooms();
    }
  }
  
  // 发送团队消息
  sendTeamMessage(team, messageType, payload) {
    const roomId = `team-${team}`;
    if (this.rooms.has(roomId)) {
      messageService.sendBroadcastMessage(messageType, payload, {
        roomId: roomId
      });
    } else {
      console.error(`团队房间不存在: ${roomId}`);
    }
  }
  
  // 发送跨团队消息（带过滤）
  sendCrossTeamMessage(projectId, messageType, payload, targetRoles = []) {
    const roomId = `project-${projectId}`;
    
    // 如果指定了目标角色，只发送给特定角色的用户
    if (targetRoles.length > 0) {
      const targetUsers = [];
      
      // 找出房间中具有目标角色的用户
      this.rooms.get(roomId)?.users.forEach(userId => {
        const userRoles = this.userRoles.get(userId) || [];
        if (userRoles.some(role => targetRoles.includes(role))) {
          targetUsers.push(userId);
        }
      });
      
      // 向目标用户发送定向消息
      targetUsers.forEach(userId => {
        messageService.sendDirectMessage(userId, messageType, payload);
      });
    } else {
      // 没有指定角色，发送广播消息
      messageService.sendBroadcastMessage(messageType, payload, {
        roomId: roomId
      });
    }
  }
}

真实项目案例分析：

案例一：大型游戏开发团队协作 某游戏工作室使用PlayCanvas开发多人在线游戏，团队分布在三个不同地区。通过中继功能实现了：

实时场景编辑，设计师在上海调整模型，旧金山的开发团队立即看到效果
基于角色的权限控制，美术团队只能编辑视觉资源，无法修改游戏逻辑
自动冲突解决，当两个设计师同时修改同一模型时，系统智能合并变更
结果：团队协作效率提升40%，沟通成本降低60%，项目按时交付率从65%提升到90%

案例二：远程教学场景应用 一所设计学院使用PlayCanvas进行3D设计教学：

教师可以实时看到所有学生的操作
教师可以向特定学生发送指导消息或直接示范操作
学生可以请求帮助，系统自动通知教师
结果：学生学习效率提升35%，教师指导效率提升50%，学生作品质量平均提高25%

4.2 中继功能与其他协作工具的集成

中继功能可以与多种协作工具集成，打造无缝的工作流。

与版本控制系统集成：

// 中继与Git集成
class RelayGitIntegration {
  constructor() {
    this._setupEventListeners();
  }
  
  _setupEventListeners() {
    // 监听重要编辑事件，自动创建提交点
    editor.on('scene:save', async (sceneId) => {
      // 获取当前中继房间中的用户
      const users = roomService.getRoomUsers();
      const userNames = Array.from(users.values()).map(u => u.name).join(', ');
      
      // 创建自动提交
      await executeGitCommand(`commit -m "Auto-commit after scene save by ${userNames}"`);
      
      // 广播提交信息
      messageService.sendBroadcastMessage('git:commit', {
        message: `场景已保存并提交，协作编辑者: ${userNames}`,
        commitHash: await executeGitCommand('rev-parse HEAD'),
        timestamp: new Date().toISOString()
      });
    });
    
    // 监听Git事件，通知中继房间
    this._setupGitHooks();
  }
  
  _setupGitHooks() {
    // 设置Git钩子，当有外部提交时通知编辑器
    // 实际实现会涉及设置.git/hooks/post-merge等钩子脚本
    setupGitHook('post-merge', (data) => {
      messageService.sendBroadcastMessage('git:merge', {
        branch: data.branch,
        commitHash: data.commitHash,
        author: data.author,
        message: data.message
      });
    });
  }
}

与项目管理工具集成：

// 中继与项目管理工具集成
class RelayProjectManagementIntegration {
  constructor() {
    this._taskStatus = new Map();
    this._setupIntegration();
  }
  
  async _setupIntegration() {
    // 从项目管理工具加载任务列表
    const tasks = await fetchProjectTasks();
    tasks.forEach(task => {
      this._taskStatus.set(task.id, task.status);
    });
    
    // 设置UI面板显示任务
    editor.call('ui:panel:create', 'project-tasks', {
      title: '项目任务',
      content: this._renderTaskPanel()
    });
    
    // 监听中继消息，更新任务状态
    messageService.on('task:status:change', (data) => {
      this._taskStatus.set(data.taskId, data.status);
      editor.call('ui:panel:update', 'project-tasks', {
        content: this._renderTaskPanel()
      });
    });
  }
  
  _renderTaskPanel() {
    // 渲染任务面板HTML
    let html = '<div class="task-panel">';
    
    this._taskStatus.forEach((status, taskId) => {
      const task = this._getTaskById(taskId);
      html += `
        <div class="task-item status-${status}">
          <h4>${task.title}</h4>
          <p>${task.description}</p>
          <div class="task-actions">
            <button class="task-btn" data-task-id="${taskId}">更新状态</button>
          </div>
        </div>
      `;
    });
    
    html += '</div>';
    return html;
  }
  
  // 更新任务状态并广播
  updateTaskStatus(taskId, newStatus) {
    this._taskStatus.set(taskId, newStatus);
    
    // 通知项目管理工具
    updateProjectTask(taskId, { status: newStatus });
    
    // 广播任务状态变更
    messageService.sendBroadcastMessage('task:status:change', {
      taskId,
      status: newStatus,
      updatedBy: editor.call('user:id')
    });
    
    // 更新UI
    editor.call('ui:panel:update', 'project-tasks', {
      content: this._renderTaskPanel()
    });
  }
}

4.3 进阶功能扩展开发指南

扩展一：操作历史回放功能

基于中继消息日志实现操作历史回放，支持查看任意时间点的场景状态。

// 操作历史回放服务
class OperationHistoryService {
  constructor() {
    this._history = []; // 存储操作历史
    this._recording = true; // 是否记录操作
    this._playbackActive = false; // 是否正在回放
    
    // 监听所有中继消息
    relay.on('message', (message) => {
      if (this._recording && !this._playbackActive && message.type === 'broadcast') {
        // 记录广播消息（用户操作）
        this._history.push({
          timestamp: Date.now(),
          message: message.data
        });
        
        // 限制历史记录大小（保留最近1小时）
        this._trimHistory();
      }
    });
  }
  
  // 修剪历史记录，只保留最近1小时
  _trimHistory() {
    const oneHourAgo = Date.now() - (60 * 60 * 1000);
    const index = this._history.findIndex(entry => entry.timestamp > oneHourAgo);
    
    if (index > 0) {
      this._history = this._history.slice(index);
    }
  }
  
  // 开始回放
  startPlayback(startTime, speed = 1.0) {
    if (this._playbackActive) {
      this.stopPlayback();
    }
    
    this._playbackActive = true;
    this._recording = false; // 回放期间停止记录
    
    // 找到起始时间点的操作
    const startIndex = this._history.findIndex(
      entry => entry.timestamp >= startTime
    );
    
    if (startIndex === -1) {
      console.error('找不到起始时间点的操作记录');
      this._playbackActive = false;
      this._recording = true;
      return;
    }
    
    // 创建临时场景用于回放
    editor.call('scene:create:temporary', 'playback-scene');
    
    // 回放开始事件
    editor.emit('playback:start', { startTime, speed });
    
    // 执行回放
    this._executePlayback(startIndex, speed);
  }
  
  // 执行回放
  async _executePlayback(startIndex, speed) {
    const playbackStartTime = Date.now();
    
    for (let i = startIndex; i < this._history.length && this._playbackActive; i++) {
      const entry = this._history[i];
      
      // 计算相对于回放开始的延迟
      const originalTime = entry.timestamp - this._history[startIndex].timestamp;
      const adjustedTime = originalTime / speed;
      const playbackElapsed = Date.now() - playbackStartTime;
      const sleepTime = adjustedTime - playbackElapsed;
      
      // 如果需要，等待适当的时间
      if (sleepTime > 0) {
        await new Promise(resolve => setTimeout(resolve, sleepTime));
      }
      
      // 应用操作
      this._applyOperation(entry.message);
    }
    
    // 回放结束
    this.stopPlayback();
  }
  
  // 应用操作
  _applyOperation(message) {
    switch (message.messageType) {
      case 'entity:transform':
        editor.call('entities:update:transform', message.payload, { playback: true });
        break;
      case 'asset:updated':
        editor.call('assets:update', message.payload.assetId, message.payload.changes, { playback: true });
        break;
      // 处理其他操作类型...
    }
  }
  
  // 停止回放
  stopPlayback() {
    if (this._playbackActive) {
      this._playbackActive = false;
      this._recording = true;
      editor.emit('playback:stop');
      // 恢复原始场景
      editor.call('scene:restore:original');
    }
  }
}

扩展二：协作编辑热力图

可视化显示团队成员的编辑活动分布，帮助识别协作热点和潜在冲突点。

// 协作编辑热力图服务
class CollaborationHeatmapService {
  constructor() {
    this._activityData = new Map(); // 存储活动数据：entityId -> { users: Map(userId -> count), lastUpdated }
    this._updateInterval = null;
    
    // 监听编辑操作
    messageService.on('entity:transform', this._handleEntityTransform.bind(this));
    messageService.on('asset:updated', this._handleAssetUpdate.bind(this));
    
    // 定期更新热力图
    this._updateInterval = setInterval(() => {
      this._updateHeatmapVisualization();
    }, 5000);
    
    // 创建热力图UI面板
    editor.call('ui:panel:create', 'collaboration-heatmap', {
      title: '协作热力图',
      width: 300,
      height: 400
    });
  }
  
  // 处理实体变换事件
  _handleEntityTransform(data) {
    const entityId = data.entityId;
    
    // 如果没有该实体的数据，创建一个
    if (!this._activityData.has(entityId)) {
      this._activityData.set(entityId, {
        users: new Map(),
        lastUpdated: Date.now()
      });
    }
    
    const entityData = this._activityData.get(entityId);
    const userId = data.userId || editor.call('user:id');
    
    // 更新用户活动计数
    entityData.users.set(userId, (entityData.users.get(userId) || 0) + 1);
    entityData.lastUpdated = Date.now();
  }
  
  // 处理资源更新事件
  _handleAssetUpdate(data) {
    // 类似实体处理...
  }
  
  // 更新热力图可视化
  _updateHeatmapVisualization() {
    // 准备热力图数据
    const heatmapData = [];
    const now = Date.now();
    
    this._activityData.forEach((data, entityId) => {
      // 获取实体位置
      const entity = editor.call('entities:get', entityId);
      if (!entity || !entity.get('position')) return;
      
      const position = entity.get('position');
      const userCount = data.users.size;
      const totalEdits = Array.from(data.users.values()).reduce((sum, count) => sum + count, 0);
      
      // 计算活跃度（最近10分钟内的编辑权重更高）
      const age = now - data.lastUpdated;
      const recencyFactor = Math.max(0, 1 - (age / (10 * 60 * 1000))); // 10分钟衰减
      const activityScore = totalEdits * recencyFactor;
      
      if (activityScore > 0) {
        heatmapData.push({
          x: position.x,
          y: position.y,
          z: position.z,
          value: activityScore,
          userCount: userCount
        });
      }
    });
    
    // 更新热力图UI
    editor.call('ui:panel:update', 'collaboration-heatmap', {
      content: this._renderHeatmap(heatmapData)
    });
    
    // 同时在视口中绘制热力图
    editor.call('viewport:draw:heatmap', heatmapData);
  }
  
  // 渲染热力图
  _renderHeatmap(data) {
    // 简化实现：渲染一个简单的热力图表格
    let html = '<div class="heatmap-panel">';
    
    // 按活跃度排序
    data.sort((a, b) => b.value - a.value);
    
    // 显示前10个最活跃的实体
    const topEntities = data.slice(0, 10);
    
    html += '<table class="heatmap-table">';
    html += '<tr><th>实体</th><th>位置</th><th>编辑次数</th><th>协作人数</th></tr>';
    
    topEntities.forEach(item => {
      html += `<tr>
        <td>Entity-${item.x.toFixed(1)},${item.y.toFixed(1)},${item.z.toFixed(1)}</td>
        <td>(${item.x.toFixed(1)}, ${item.y.toFixed(1)}, ${item.z.toFixed(1)})</td>
        <td>${item.value.toFixed(1)}</td>
        <td>${item.userCount}</td>
      </tr>`;
    });
    
    html += '</table></div>';
    return html;
  }
}

扩展三：语音协作集成

在中继功能基础上添加语音通话功能，实现边编辑边沟通。

// 语音协作服务
class VoiceCollaborationService {
  constructor() {
    this._mediaStream = null;
    this._peerConnections = new Map(); // userId -> RTCPeerConnection
    this._isMuted = false;
    this._isSpeaking = false;
    this._audioContext = null;
    this._analyser = null;
    
    // 初始化WebRTC相关组件
    this._initWebRTC();
    
    // 监听房间用户变化
    editor.on('room:users:updated', this._handleUserChange.bind(this));
  }
  
  // 初始化WebRTC
  _initWebRTC() {
    // 检查浏览器支持
    if (!navigator.mediaDevices || !window.RTCPeerConnection) {
      console.error('浏览器不支持WebRTC，语音功能不可用');
      return;
    }
    
    // 创建音频上下文用于音量分析
    this._audioContext = new AudioContext();
    this._analyser = this._audioContext.createAnalyser();
    this._analyser.fftSize = 256;
    
    // 设置语音状态UI
    editor.call('ui:toolbar:add', 'voice-controls', {
      icon: 'microphone',
      tooltip: '语音协作',
      controls: [
        { type: 'button', id: 'voice-toggle', icon: 'microphone' },
        { type: 'button', id: 'voice-mute', icon: 'microphone-slash' }
      ]
    });
    
    // 绑定UI事件
    editor.on('ui:toolbar:click', (id) => {
      if (id === 'voice-toggle') {
        this._toggleVoice();
      } else if (id === 'voice-mute') {
        this._toggleMute();
      }
    });
  }
  
  // 处理房间用户变化
  _handleUserChange(users) {
    const currentUser = editor.call('user:id');
    
    // 为每个其他用户创建或移除对等连接
    users.forEach(user => {
      if (user.id !== currentUser && !this._peerConnections.has(user.id)) {
        // 新用户加入，创建对等连接
        this._createPeerConnection(user.id);
      }
    });
    
    // 移除已离开房间的用户连接
    Array.from(this._peerConnections.keys()).forEach(userId => {
      if (!users.some(u => u.id === userId)) {
        this._closePeerConnection(userId);
      }
    });
  }
  
  // 创建对等连接
  async _createPeerConnection(userId) {
    try {
      // 创建RTCPeerConnection
      const pc = new RTCPeerConnection({
        iceServers: [
          { urls: 'stun:stun.l.google.com:19302' },
          { urls: 'stun:stun1.l.google.com:19302' }
        ]
      });
      
      // 存储连接
      this._peerConnections.set(userId, pc);
      
      // 如果有本地媒体流，添加到连接
      if (this._mediaStream) {
        this._mediaStream.getTracks().forEach(track => {
          pc.addTrack(track, this._mediaStream);
        });
      }
      
      // 设置ICE候选处理
      pc.onicecandidate = (event) => {
        if (event.candidate) {
          // 通过中继发送ICE候选
          messageService.sendDirectMessage(userId, 'webrtc:ice:candidate', {
            candidate: event.candidate
          });
        }
      };
      
      // 设置远程流处理
      pc.ontrack = (event) => {
        // 将远程音频流添加到音频元素
        this._addRemoteAudio(userId, event.streams[0]);
      };
      
      // 创建offer
      const offer = await pc.createOffer();
      await pc.setLocalDescription(offer);
      
      // 发送offer给远程用户
      messageService.sendDirectMessage(userId, 'webrtc:offer', {
        sdp: pc.localDescription
      });
      
      // 监听远程消息
      messageService.on(`webrtc:answer:${userId}`, this._handleAnswer.bind(this, userId));
      messageService.on(`webrtc:ice:candidate:${userId}`, this._handleIceCandidate.bind(this, userId));
      
    } catch (error) {
      console.error(`创建对等连接失败 (${userId}):`, error);
      this._peerConnections.delete(userId);
    }
  }
  
  // 处理远程offer
  async _handleOffer(userId, data) {
    if (!this._peerConnections.has(userId)) {
      await this._createPeerConnection(userId);
    }
    
    const pc = this._peerConnections.get(userId);
    
    try {
      await pc.setRemoteDescription(new RTCSessionDescription(data.sdp));
      
      // 创建answer
      const answer = await pc.createAnswer();
      await pc.setLocalDescription(answer);
      
      // 发送answer
      messageService.sendDirectMessage(userId, 'webrtc:answer', {
        sdp: pc.localDescription
      });
    } catch (error) {
      console.error(`处理offer失败 (${userId}):`, error);
    }
  }
  
  // 处理answer
  async _handleAnswer(userId, data) {
    const pc = this._peerConnections.get(userId);
    if (pc) {
      try {
        await pc.setRemoteDescription(new RTCSessionDescription(data.sdp));
      } catch (error) {
        console.error(`处理answer失败 (${userId}):`, error);
      }
    }
  }
  
  // 处理ICE候选
  async _handleIceCandidate(userId, data) {
    const pc = this._peerConnections.get(userId);
    if (pc) {
      try {
        await pc.addIceCandidate(new RTCIceCandidate(data.candidate));
      } catch (error) {
        console.error(`处理ICE候选失败 (${userId}):`, error);
      }
    }
  }
  
  // 添加远程音频
  _addRemoteAudio(userId, stream) {
    // 创建音频元素
    const audioElement = document.createElement('audio');
    audioElement.id = `remote-audio-${userId}`;
    audioElement.srcObject = stream;
    audioElement.autoplay = true;
    audioElement.muted = false;
    
    // 添加到页面
    document.body.appendChild(audioElement);
    
    // 监听语音活动
    const source = this._audioContext.createMediaStreamSource(stream);
    source.connect(this._analyser);
    
    // 定期检查语音活动
    const checkSpeaking = () => {
      if (!this._peerConnections.has(userId)) {
        return;
      }
      
      const dataArray = new Uint8Array(this._analyser.frequencyBinCount);
      this._analyser.getByteFrequencyData(dataArray);
      const volume = dataArray.reduce((sum, value) => sum + value, 0) / dataArray.length;
      
      const isSpeaking = volume > 30; // 音量阈值
      if (isSpeaking !== this._isSpeaking) {
        this._isSpeaking = isSpeaking;
        // 更新用户语音状态
        editor.call('ui:user:update', userId, { speaking: isSpeaking });
      }
      
      requestAnimationFrame(checkSpeaking);
    };
    
    checkSpeaking();
  }
  
  // 切换语音开启/关闭
  async _toggleVoice() {
    if (this._mediaStream) {
      // 停止所有轨道
      this._mediaStream.getTracks().forEach(track => track.stop());
      this._mediaStream = null;
      
      // 关闭所有对等连接
      Array.from(this._peerConnections.keys()).forEach(userId => {
        this._closePeerConnection(userId);
      });
      
      // 更新UI
      editor.call('ui:toolbar:update', 'voice-toggle', { icon: 'microphone' });
      editor.emit('voice:disabled');
    } else {
      try {
        // 获取用户媒体设备
        this._mediaStream = await navigator.mediaDevices.getUserMedia({
          audio: true,
          video: false
        });
        
        // 更新UI
        editor.call('ui:toolbar:update', 'voice-toggle', { icon: 'microphone-slash' });
        editor.emit('voice:enabled');
        
        // 为现有房间用户创建对等连接
        const currentUsers = roomService.getRoomUsers();
        const currentUserId = editor.call('user:id');
        
        currentUsers.forEach(user => {
          if (user.id !== currentUserId) {
            this._createPeerConnection(user.id);
          }
        });
        
      } catch (error) {
        console.error('获取媒体设备失败:', error);
        editor.call('ui:notify', {
          type: 'error',
          message: '无法访问麦克风，请检查权限设置'
        });
      }
    }
  }
  
  // 切换静音
  _toggleMute() {
    this._isMuted = !this._isMuted;
    
    if (this._mediaStream) {
      this._mediaStream.getAudioTracks().forEach(track => {
        track.enabled = !this._isMuted;
      });
    }
    
    // 更新UI
    editor.call('ui:toolbar:update', 'voice-mute', {
      icon: this._isMuted ? 'volume-mute' : 'volume-up'
    });
  }
  
  // 关闭对等连接
  _closePeerConnection(userId) {
    const pc = this._peerConnections.get(userId);
    if (pc) {
      pc.close();
      this._peerConnections.delete(userId);
    }
    
    // 移除音频元素
    const audioElement = document.getElementById(`remote-audio-${userId}`);
    if (audioElement) {
      audioElement.remove();
    }
  }
}

4.4 问题排查决策树

当中继功能出现问题时，可以按照以下决策树进行排查：

中继连接无法建立
- 检查网络连接是否正常
- 验证中继服务器地址是否正确
- 检查用户是否有协作权限
- 确认服务器是否正常运行
连接不稳定，频繁断开
- 检查网络质量（使用网络监控工具）
- 调整重连参数（增加延迟和尝试次数）
- 检查防火墙设置是否阻止WebSocket连接
- 验证服务器负载是否过高
消息同步延迟或丢失
- 检查网络延迟和丢包率
- 启用消息压缩
- 实现消息确认机制
- 优化批量更新策略
多人编辑冲突
- 检查冲突解决策略是否正确实现
- 增加冲突提示和手动解决选项
- 实现更细粒度的变更跟踪
- 考虑使用操作转换(OT)或冲突无关复制数据类型(CRDT)
性能问题
- 检查消息数量是否过多
- 优化消息大小（减少不必要的数据）
- 实现消息节流和批量处理
- 检查客户端CPU/内存使用情况