3.3 动手搭建信令服务

3.3 动手搭建信令服务

本节摘要：这一节把前两节的模型与文本落地为可运行的代码：一个支持房间、四类消息转发、心跳保活与断线清理的 WebSocket 信令服务，外加与之配套的客户端封装。代码刻意保持零依赖、单文件可跑，内网环境直接可用；每一段实现都对应一条设计决策，读完你就有了评估与改造任何信令方案的能力。

本节的学习收获

阅读完本节，你应当能够：

1. 设计信令消息协议，区分连接生命周期消息与协商转发消息；
2. 用 Node.js 实现房间管理与消息按房间转发的信令服务；
3. 实现心跳保活与僵尸连接清理，避免房间被断开的连接占位；
4. 写出与该服务配套的客户端信令封装，并保持协商层不感知传输细节；
5. 说明信令服务的安全边界：鉴权、消息校验与生产化的扩展方向。

一、问题与直觉：邮局的营业规则

信令服务是个邮局，但邮局也有营业规则。没有规则的信令服务在演示里活得好好的，上线第一天就出事：断网的客户端没被踢出，房间计数虚高；恶意客户端乱发消息，把别人的协商搅乱；服务重启后所有通话的信令全断，客户端却不知道该重连还是该放弃。所以动笔之前，先定三条营业规则——房间隔离（消息只在本房间转发）、消息校验（不认识的类型丢弃并记日志）、生命周期管理（心跳探活、退出广播、房间清空即解散）。

消息协议设计先行。约定全部消息为 JSON，必带 type 字段：

表格里埋着一个多人场景的关键决策：转发消息带目标标识。两人房间服务端无脑转发即可；三人以上就必须知道「这条 offer 是发给谁的」，否则房间里的协商会互相踩踏。本节的实现按「带目标标识」设计，两人与多人通吃。

二、核心实现：服务端与客户端

先写服务端（Node.js，使用 ws 库，零框架）：

// 信令服务端：房间管理 + 按房间转发 + 心跳清理
const { WebSocketServer } = require('ws');
const wss = new WebSocketServer({ port: 8080 });
const rooms = new Map();   // roomId -> Map(ws -> peerId)

function safeSend(ws, msg) {
  if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(msg));
}

wss.on('connection', (ws) => {
  ws.isAlive = true;
  ws.on('pong', () => { ws.isAlive = true; });
  ws.on('message', (raw) => {
    let msg;
    try { msg = JSON.parse(raw); } catch { return; }   // 非 JSON 直接丢弃
    const { type, room, to, payload } = msg;

    if (type === 'join') {
      if (!rooms.has(room)) rooms.set(room, new Map());
      rooms.get(room).set(ws, msg.peerId || Math.random().toString(36).slice(2));
      ws.room = room;
      safeSend(ws, { type: 'joined', peers: [...rooms.get(room).values()] });
      broadcast(room, { type: 'peer-joined', peerId: rooms.get(room).get(ws) }, ws);
      return;
    }
    if (type === 'ping') return safeSend(ws, { type: 'pong' });
    if (['offer', 'answer', 'candidate', 'bye'].includes(type)) {
      // 找到目标：同一房间内、peerId 匹配
      const peers = rooms.get(ws.room);
      if (!peers) return;
      for (const [peerWs, peerId] of peers) {
        if (peerId === to) return safeSend(peerWs, { type, from: peers.get(ws), payload });
      }
      return;   // 目标不在房内，静默丢弃（可扩展为错误回执）
    }
    // 未知类型：记录后忽略，协议演进的安全垫
  });
  ws.on('close', () => leaveRoom(ws));
});

function broadcast(room, msg, exclude) {
  const peers = rooms.get(room);
  if (!peers) return;
  for (const peerWs of peers.keys()) {
    if (peerWs !== exclude) safeSend(peerWs, msg);
  }
}

function leaveRoom(ws) {
  const peers = rooms.get(ws.room);
  if (!peers) return;
  const id = peers.get(ws);
  peers.delete(ws);
  broadcast(ws.room, { type: 'peer-left', peerId: id });
  if (peers.size === 0) rooms.delete(ws.room);   // 房间清空即解散
}

// 心跳：每半分钟探一轮，两轮无响应判死
setInterval(() => {
  for (const ws of wss.clients) {
    if (!ws.isAlive) { ws.terminate(); leaveRoom(ws); continue; }
    ws.isAlive = false;
    ws.ping();
  }
}, 30000);
​

客户端封装坚持一个原则：协商层只认事件，不认 WebSocket。

// 客户端信令封装：连上、发消息、按类型派发
class Signaling {
  constructor(url) {
    this.handlers = new Map();
    this.connect(url);
  }
  connect(url) {
    this.ws = new WebSocket(url);
    this.ws.onopen = () => this.emit('open');
    this.ws.onmessage = (e) => {
      const msg = JSON.parse(e.data);
      if (msg.type === 'pong') return this.markAlive();
      this.emit(msg.type, msg);
    };
    this.ws.onclose = () => {
      // 指数退避重连：1 秒起，翻倍封顶 30 秒
      this.retry = Math.min((this.retry || 1000) * 2, 30000);
      setTimeout(() => this.connect(url), this.retry);
    };
  }
  on(type, fn) { this.handlers.set(type, fn); }
  emit(type, msg) { this.handlers.get(type)?.(msg); }
  send(obj) { if (this.ws.readyState === 1) this.ws.send(JSON.stringify(obj)); }
  join(room, peerId) { this.send({ type: 'join', room, peerId }); }
}
​

重连逻辑里那个指数退避不是装饰：信令服务器重启的窗口期里，所有客户端同时重连会形成惊群，退避把冲击摊平。重连成功后客户端要重新 join，并依据 3.1 节的协商代数决定是否发起新一轮 offer。

图：一次完整信令会话的消息流

三、工程实践要点：安全边界与扩展方向

内网 demo 与公网生产之间隔着安全边界，三条必守：鉴权前置——join 必须携带业务签发的票据（一次性的房间口令或签名），服务器校验后才分配房间，否则任何人可探测任意房间；消息限额——对单连接的消息频率设上限，防止恶意客户端灌爆转发循环；传输加密——公网信令必须是 wss，信令内容里虽然没有媒体数据，但候选地址与房间结构本身就是有价值的信息。

完整案例：信令服务重启引发的「僵尸房间」

背景：某团队把信令服务灰度上线后重启了一次实例，随后用户反馈「房间人数显示正确，但呼叫永远无人接听」。

操作：排查发现，重启后原连接全部断开，客户端的重连逻辑把旧 WebSocket 对象替换成了新连接，但服务端房间表里的旧映射（指向已死连接）没有被清干净——心跳清理只遍历 clients 集合，而旧房间表里的死连接引用成了孤儿，join 时房间看似有成员，消息转发却石沉大海。

结果：修复两处：leaveRoom 与 terminate 严格成对，心跳循环里对每个死连接也执行一次 leaveRoom；房间表改为弱引用风格的结构，连接销毁必然触发清理。另加了一层保险：服务器每次启动用新的实例代数标记，客户端重连后发现代数变化就强制重走 join。

解读：这个案例的教训是「转发逻辑的正确性依赖房间表与连接集合的一致性」，而连接的生死事件分散在 close、error、心跳三处，任何一处漏清理都会积累出幽灵成员。把「连接销毁必触发房间清理」做成单点函数、三处事件都调它，是一致性的最低保障。

变式：规模再往上走，单机 Map 撑不住房间与连接的规模时，常见演进是把房间状态外置到 Redis、信令节点变成无状态转发层，节点间用发布订阅同步消息。协议本身（消息类型与字段）不需要变——这正是消息协议先行的红利：传输层随便重构，协商层无感。

本节要点回顾

• 协议先行：四类转发消息加生命周期消息，type 字段统一，未知类型丢弃并记录，为演进留安全垫。
• 房间是转发的基本单位：转发消息带目标标识，两人与多人房间共用一套逻辑。
• 心跳与清理必须成对：探活、判死、leaveRoom 三件事在 close、error、心跳三处都要执行，防幽灵成员。
• 客户端封装屏蔽传输细节：协商层只认事件，换信令通道零改动；重连用指数退避防惊群。
• 安全三条线：join 鉴权、消息限额、wss 加密，一条都不能省到公网上去。