feat(phase2e-2): media-server Task 0/1/2 落地 + 代码审查修复

本次提交一次性落盘 Phase 2e-2 的 Task 0（PoC Spike）、Task 1（骨架 + Fastify 5 升级）和 Task 2（9 个内部 REST API + code-reviewer 审查修复），覆盖 media-server 子项目从零到可用的全部工作。【Task 0 - PoC Spike】 - media-server/poc/：Node + mediasoup + fastify-websocket + 前端 mediasoup-client - Playwright 双 tab 自动化验证 2 人会议：4 transports / 4 producers / 4 consumers / RSS 61MB - media-server/docs/poc-notes.md 归档 7 项关键坑 + 启动步骤 + Task 1/2/9 复用映射 - 锁定技术栈：mediasoup + fastify + mediasoup-client，不改用 livekit-server 【Task 1 - 骨架 + Fastify 5 升级】 - 依赖版本：mediasoup@3.19.0 + fastify@5.8.5 + fastify-plugin@5.1.0 + @fastify/sensible@6.0.4 + @fastify/websocket@11.2.0 + pino@9.3.2 + zod@3.23.8 - src 五件套：app.ts / config.ts / utils/logger.ts / mediasoup/worker.ts / middlewares/internal-auth.ts - /healthz + /readyz + /internal/info 三端点实测通过 - X-Internal-Token 鉴权用 timingSafeEqual 防侧信道 - mediasoup Worker died 指数退避自愈通过 kill -9 验证 - 多阶段 Dockerfile：非 root + curl HEALTHCHECK + 暴露 40000-40199 UDP/TCP - Fastify 4 → 5 升级：loggerInstance: logger 消灭两个 pino 实例【Task 2 - 9 个内部 REST API + 审查修复】接口全部挂 /internal/v1/* 前缀，覆盖 Router/Transport/Producer/Consumer 完整生命周期： - POST /routers, DELETE /routers/:id - POST /transports, POST /transports/:id/connect - POST /producers, DELETE /producers/:id - POST /consumers, POST /consumers/:id/resume, DELETE /consumers/:id 工程特性： - zod 手动 parse + 全局 errorHandler（不引入 fastify-type-provider-zod 避免 zod v4 依赖冲突） - AppError 统一错误码（NOT_FOUND/CONFLICT/CAN_NOT_CONSUME/ROUTER_LIMIT_EXCEEDED /MEDIASOUP_ERROR/VALIDATION_ERROR/UNAUTHORIZED/INTERNAL_ERROR） - 所有资源用 Map + observer.once('close') 自清理，Consumer 监听 producerclose 级联关闭 - Consumer 强制 paused:true 创建，/resume 独立接口 - Transport direction 强约束：recv 拒 produce、send 拒 consume code-reviewer 子代理审查"有条件通过"，同步修复： - M1 _clearXxxMap 新增 src/utils/test-guard.ts#assertTestOnly 守卫（生产误调用抛错） - M2 新增 src/schemas/rtp.ts 对 rtpParameters / rtpCapabilities 做 codecs 浅层校验（mimeType/clockRate/payloadType 必填、codecs ≥1），消除 as unknown as 双跳断言 - m1 connectTransport 改乐观锁：先置位再 await，失败回退 - m2 改读 consumer.producerPaused（更符合 mediasoup 语义） - m3 producerclose 改为 once（风格一致） - m5 internal-auth 改为反向白名单 PRIVATE_PATH_PREFIXES = ['/internal/'] 验证： - typecheck / lint 0 错误 - vitest：65 passed / 8 spec 文件 - 覆盖率 stmts 82.87% / branches 75.83% / funcs 91.3% / lines 82.87% - 9 接口 happy path + 6 类错误路径 curl 手测全部按预期返回【文档同步】 - CURRENT_STATUS.md +232 行：新增 Task 0/1/2 完整记录 + 代码审查修复章节 + 延后清单 - project-context.mdc：Task 0/1/2 状态同步 - phase2e-2-design.md +20 行：Fastify 5 升级相关决策记录 - phase2e-2-implementation.plan.md +117 行：Task 0/1/2 实际产出 + 修复记录余下 Minor/Nits（m4/m6~m10/n1~n10）登记至 Task 16 收尾清单一次性清扫。 Made-with: Cursor
2026-04-21 15:31:01 +08:00
parent df538e8df6
commit 6e2e792db0
56 changed files with 11123 additions and 51 deletions
--- a/media-server/poc/.gitignore
+++ b/media-server/poc/.gitignore
@@ -0,0 +1,4 @@
+node_modules/
+.DS_Store
+npm-debug.log*
+poc-*.log
--- a/media-server/poc/README.md
+++ b/media-server/poc/README.md
@@ -0,0 +1,30 @@
+# mediasoup PoC Spike
+
+Phase 2e-2 Task 0 产物，用于验证 mediasoup + Fastify + mediasoup-client 技术栈。
+
+**这不是正式 media-server**，正式实现详见 Task 1-2，目录位于 [`../src/`](../src)（Task 1 完成时创建）。
+
+## 快速启动
+
+```bash
+npm install
+node server.mjs
+```
+
+浏览器访问 `http://localhost:3300/`，打开两个窗口各自点击「加入并推流」即可互通。
+
+## 结论
+
+技术栈可用性验证通过，详见 [`../docs/poc-notes.md`](../docs/poc-notes.md)。
+
+## 目录
+
+```
+poc/
+├── server.mjs            # Node 侧：Fastify + WS 信令 + mediasoup Worker/Router
+├── public/
+│   ├── index.html        # 浏览器侧极简 UI
+│   └── client.mjs        # 浏览器侧：mediasoup-client 完整流程
+├── package.json          # 依赖清单（固定版本号）
+└── .gitignore
+```
--- a/media-server/poc/package-lock.json
+++ b/media-server/poc/package-lock.json
--- a/media-server/poc/package.json
+++ b/media-server/poc/package.json
@@ -0,0 +1,23 @@
+{
+  "name": "echochat-media-server-poc",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Phase 2e-2 Task 0: mediasoup PoC Spike (2 browsers <-> Node <-> mediasoup)",
+  "main": "server.mjs",
+  "scripts": {
+    "start": "node server.mjs",
+    "dev": "node --watch server.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "fastify": "4.28.1",
+    "@fastify/static": "7.0.4",
+    "@fastify/websocket": "10.0.1",
+    "mediasoup": "3.14.11",
+    "pino": "9.3.2",
+    "pino-pretty": "11.2.2"
+  }
+}
--- a/media-server/poc/public/client.mjs
+++ b/media-server/poc/public/client.mjs
@@ -0,0 +1,347 @@
+// PoC 浏览器端：mediasoup-client + 原生 WebSocket
+// 通过 esm.sh CDN 加载 mediasoup-client，保持 PoC 零构建步骤。
+// 正式 media-server 落地时会改为 frontend 侧 npm 依赖 + vite 打包。
+// esm.sh 自动解析到最新 3.x（本 PoC 验证时为 3.19.0）；正式 media-server 落地会用 npm + vite 打包
+import { Device } from 'https://esm.sh/mediasoup-client@3';
+
+const logEl = document.getElementById('log');
+const statusEl = document.getElementById('status');
+const videosEl = document.getElementById('videos');
+const btnJoin = document.getElementById('btnJoin');
+const btnLeave = document.getElementById('btnLeave');
+
+function log(msg, level = 'info') {
+  const ts = new Date().toLocaleTimeString();
+  const line = document.createElement('div');
+  line.className = `log-${level}`;
+  line.textContent = `[${ts}] ${msg}`;
+  logEl.appendChild(line);
+  logEl.scrollTop = logEl.scrollHeight;
+  console[level === 'err' ? 'error' : 'log'](msg);
+}
+
+// ---------------- WS 信令包装（Promise-based） ----------------
+
+class SignalClient {
+  constructor(url) {
+    this.url = url;
+    this.ws = null;
+    this.pending = new Map(); // reqId → {resolve, reject}
+    this.listeners = new Map();
+  }
+
+  connect() {
+    return new Promise((resolve, reject) => {
+      this.ws = new WebSocket(this.url);
+      this.ws.onopen = () => resolve();
+      this.ws.onerror = (e) => reject(e);
+      this.ws.onclose = () => {
+        this.emit('__close__', {});
+      };
+      this.ws.onmessage = (ev) => this._onMessage(ev);
+    });
+  }
+
+  _onMessage(ev) {
+    let msg;
+    try { msg = JSON.parse(ev.data); } catch { return; }
+    const { type, data, reqId } = msg;
+    if (reqId && this.pending.has(reqId)) {
+      const { resolve, reject } = this.pending.get(reqId);
+      this.pending.delete(reqId);
+      if (type === 'error') reject(new Error(data?.message || 'signal error'));
+      else resolve(data);
+      return;
+    }
+    this.emit(type, data);
+  }
+
+  request(type, data = {}) {
+    const reqId = Math.random().toString(36).slice(2);
+    return new Promise((resolve, reject) => {
+      this.pending.set(reqId, { resolve, reject });
+      this.ws.send(JSON.stringify({ type, data, reqId }));
+      setTimeout(() => {
+        if (this.pending.has(reqId)) {
+          this.pending.delete(reqId);
+          reject(new Error(`request ${type} timeout`));
+        }
+      }, 10_000);
+    });
+  }
+
+  on(type, fn) {
+    if (!this.listeners.has(type)) this.listeners.set(type, new Set());
+    this.listeners.get(type).add(fn);
+  }
+
+  emit(type, data) {
+    const set = this.listeners.get(type);
+    if (set) for (const fn of set) fn(data);
+  }
+
+  close() {
+    if (this.ws) this.ws.close();
+  }
+}
+
+// ---------------- App 状态 ----------------
+
+const state = {
+  signal: null,
+  device: null,
+  sendTransport: null,
+  recvTransport: null,
+  myPeerId: null,
+  localStream: null,
+  producers: { audio: null, video: null },
+  consumers: new Map(), // producerId → {consumer, peerId}
+};
+
+function setStatus(text) {
+  statusEl.textContent = text;
+}
+
+function addVideoTile(id, stream, label, isSelf = false) {
+  let box = document.getElementById(`tile-${id}`);
+  if (!box) {
+    box = document.createElement('div');
+    box.id = `tile-${id}`;
+    box.className = 'video-box' + (isSelf ? ' self' : '');
+    const v = document.createElement('video');
+    v.autoplay = true;
+    v.playsInline = true;
+    if (isSelf) v.muted = true;
+    v.srcObject = stream;
+    box.appendChild(v);
+    const lab = document.createElement('div');
+    lab.className = 'label';
+    lab.textContent = label;
+    box.appendChild(lab);
+    videosEl.appendChild(box);
+  } else {
+    const v = box.querySelector('video');
+    // 将新的 track 合并进已有 stream
+    for (const t of stream.getTracks()) {
+      if (!v.srcObject) v.srcObject = new MediaStream();
+      v.srcObject.addTrack(t);
+    }
+  }
+}
+
+function removeVideoTile(id) {
+  const box = document.getElementById(`tile-${id}`);
+  if (box) box.remove();
+}
+
+// ---------------- 关键流程 ----------------
+
+async function join() {
+  btnJoin.disabled = true;
+  setStatus('connecting WS...');
+  const proto = location.protocol === 'https:' ? 'wss' : 'ws';
+  const signal = new SignalClient(`${proto}://${location.host}/ws`);
+  state.signal = signal;
+
+  signal.on('welcome', ({ peerId }) => {
+    state.myPeerId = peerId;
+    log(`WS connected as peer ${peerId.slice(0, 8)}`, 'ok');
+  });
+
+  signal.on('newProducer', async ({ peerId, producerId, kind }) => {
+    log(`remote producer: peer=${peerId.slice(0, 8)} kind=${kind}`, 'info');
+    await consumeRemote(peerId, producerId, kind);
+  });
+
+  signal.on('peerLeft', ({ peerId }) => {
+    log(`peer left: ${peerId.slice(0, 8)}`, 'info');
+    removeVideoTile(peerId);
+    // 清理该 peer 的 consumers
+    for (const [pid, entry] of state.consumers) {
+      if (entry.peerId === peerId) {
+        entry.consumer.close();
+        state.consumers.delete(pid);
+      }
+    }
+  });
+
+  signal.on('consumerClosed', ({ consumerId }) => {
+    for (const [pid, entry] of state.consumers) {
+      if (entry.consumer.id === consumerId) {
+        entry.consumer.close();
+        state.consumers.delete(pid);
+      }
+    }
+  });
+
+  signal.on('__close__', () => {
+    setStatus('disconnected');
+    log('WS closed', 'err');
+  });
+
+  await signal.connect();
+
+  // 1. Device
+  setStatus('loading device...');
+  const rtpCapabilities = await signal.request('getRtpCapabilities');
+  const device = new Device();
+  await device.load({ routerRtpCapabilities: rtpCapabilities });
+  state.device = device;
+  log('mediasoup Device loaded', 'ok');
+
+  // 2. getUserMedia
+  setStatus('requesting media...');
+  let localStream;
+  try {
+    localStream = await navigator.mediaDevices.getUserMedia({
+      audio: true,
+      video: { width: { ideal: 640 }, height: { ideal: 360 } },
+    });
+  } catch (e) {
+    log(`getUserMedia failed: ${e.message}`, 'err');
+    setStatus('media denied');
+    btnJoin.disabled = false;
+    return;
+  }
+  state.localStream = localStream;
+  addVideoTile('local', localStream, '本地（你自己）', true);
+
+  // 3. SendTransport
+  setStatus('creating send transport...');
+  const sendInfo = await signal.request('createTransport', { direction: 'send' });
+  const sendTransport = device.createSendTransport({
+    id: sendInfo.id,
+    iceParameters: sendInfo.iceParameters,
+    iceCandidates: sendInfo.iceCandidates,
+    dtlsParameters: sendInfo.dtlsParameters,
+  });
+  state.sendTransport = sendTransport;
+
+  sendTransport.on('connect', ({ dtlsParameters }, cb, errb) => {
+    signal
+      .request('connectTransport', { transportId: sendTransport.id, dtlsParameters })
+      .then(() => cb())
+      .catch(errb);
+  });
+
+  sendTransport.on('produce', ({ kind, rtpParameters }, cb, errb) => {
+    signal
+      .request('produce', { transportId: sendTransport.id, kind, rtpParameters })
+      .then(({ producerId }) => cb({ id: producerId }))
+      .catch(errb);
+  });
+
+  sendTransport.on('connectionstatechange', (s) => {
+    log(`sendTransport ICE: ${s}`, s === 'failed' ? 'err' : 'info');
+  });
+
+  // 4. produce audio + video
+  const audioTrack = localStream.getAudioTracks()[0];
+  const videoTrack = localStream.getVideoTracks()[0];
+  if (audioTrack) {
+    state.producers.audio = await sendTransport.produce({ track: audioTrack });
+    log(`local audio producer: ${state.producers.audio.id.slice(0, 8)}`, 'ok');
+  }
+  if (videoTrack) {
+    state.producers.video = await sendTransport.produce({
+      track: videoTrack,
+      encodings: [
+        { maxBitrate: 150_000, scaleResolutionDownBy: 4 },
+        { maxBitrate: 400_000, scaleResolutionDownBy: 2 },
+        { maxBitrate: 1_000_000 },
+      ],
+      codecOptions: { videoGoogleStartBitrate: 1000 },
+    });
+    log(`local video producer: ${state.producers.video.id.slice(0, 8)}`, 'ok');
+  }
+
+  // 5. RecvTransport
+  setStatus('creating recv transport...');
+  const recvInfo = await signal.request('createTransport', { direction: 'recv' });
+  const recvTransport = device.createRecvTransport({
+    id: recvInfo.id,
+    iceParameters: recvInfo.iceParameters,
+    iceCandidates: recvInfo.iceCandidates,
+    dtlsParameters: recvInfo.dtlsParameters,
+  });
+  state.recvTransport = recvTransport;
+
+  recvTransport.on('connect', ({ dtlsParameters }, cb, errb) => {
+    signal
+      .request('connectTransport', { transportId: recvTransport.id, dtlsParameters })
+      .then(() => cb())
+      .catch(errb);
+  });
+
+  recvTransport.on('connectionstatechange', (s) => {
+    log(`recvTransport ICE: ${s}`, s === 'failed' ? 'err' : 'info');
+  });
+
+  // 6. 拉取当前已在房间的其他 peers
+  const { items } = await signal.request('getPeers');
+  log(`existing remote producers: ${items.length}`, 'info');
+  for (const it of items) {
+    await consumeRemote(it.peerId, it.producerId, it.kind);
+  }
+
+  setStatus('in room');
+  btnLeave.disabled = false;
+}
+
+async function consumeRemote(peerId, producerId, kind) {
+  if (!state.recvTransport) return;
+  try {
+    const data = await state.signal.request('consume', {
+      transportId: state.recvTransport.id,
+      producerId,
+      rtpCapabilities: state.device.rtpCapabilities,
+    });
+    const consumer = await state.recvTransport.consume({
+      id: data.id,
+      producerId: data.producerId,
+      kind: data.kind,
+      rtpParameters: data.rtpParameters,
+    });
+    await state.signal.request('resumeConsumer', { consumerId: consumer.id });
+    state.consumers.set(producerId, { consumer, peerId });
+
+    const stream = new MediaStream([consumer.track]);
+    addVideoTile(peerId, stream, `远端 ${peerId.slice(0, 8)} · ${kind}`);
+    log(`consuming ${kind} from ${peerId.slice(0, 8)}`, 'ok');
+
+    consumer.on('transportclose', () => state.consumers.delete(producerId));
+  } catch (e) {
+    log(`consume failed: ${e.message}`, 'err');
+  }
+}
+
+async function leave() {
+  btnLeave.disabled = true;
+  setStatus('leaving...');
+  try {
+    for (const { consumer } of state.consumers.values()) consumer.close();
+    state.consumers.clear();
+    if (state.producers.audio) state.producers.audio.close();
+    if (state.producers.video) state.producers.video.close();
+    if (state.sendTransport) state.sendTransport.close();
+    if (state.recvTransport) state.recvTransport.close();
+    if (state.localStream) state.localStream.getTracks().forEach((t) => t.stop());
+    if (state.signal) state.signal.close();
+  } catch (e) {
+    log(`leave error: ${e.message}`, 'err');
+  }
+  videosEl.innerHTML = '';
+  setStatus('idle');
+  btnJoin.disabled = false;
+}
+
+btnJoin.addEventListener('click', () => {
+  join().catch((e) => {
+    log(`join error: ${e.message}`, 'err');
+    setStatus('error');
+    btnJoin.disabled = false;
+  });
+});
+btnLeave.addEventListener('click', () => leave());
+
+log('PoC client ready. 点击「加入并推流」，授权摄像头/麦克风后可与其他窗口互通。', 'info');
--- a/media-server/poc/public/index.html
+++ b/media-server/poc/public/index.html
@@ -0,0 +1,91 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>EchoChat mediasoup PoC</title>
+    <style>
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+        background: #0f172a;
+        color: #e2e8f0;
+        padding: 16px;
+      }
+      header {
+        display: flex;
+        justify-content: space-between;
+        align-items: center;
+        margin-bottom: 16px;
+      }
+      h1 { font-size: 18px; margin: 0; color: #fbbf24; }
+      .controls button {
+        background: #2563eb;
+        color: white;
+        border: none;
+        padding: 8px 16px;
+        margin-left: 8px;
+        border-radius: 6px;
+        cursor: pointer;
+        font-size: 14px;
+      }
+      .controls button:hover { background: #1d4ed8; }
+      .controls button:disabled { background: #475569; cursor: not-allowed; }
+      #log {
+        background: #1e293b;
+        padding: 8px 12px;
+        border-radius: 6px;
+        font-family: ui-monospace, SFMono-Regular, monospace;
+        font-size: 12px;
+        max-height: 140px;
+        overflow-y: auto;
+        margin-bottom: 16px;
+      }
+      #log div { line-height: 1.5; }
+      .log-info { color: #93c5fd; }
+      .log-ok { color: #86efac; }
+      .log-err { color: #fca5a5; }
+      #videos {
+        display: grid;
+        grid-template-columns: repeat(auto-fill, minmax(360px, 1fr));
+        gap: 12px;
+      }
+      .video-box {
+        position: relative;
+        background: #1e293b;
+        border-radius: 8px;
+        overflow: hidden;
+        aspect-ratio: 16 / 9;
+      }
+      .video-box video {
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+      }
+      .video-box .label {
+        position: absolute;
+        bottom: 8px;
+        left: 8px;
+        background: rgba(0,0,0,0.6);
+        padding: 4px 10px;
+        border-radius: 4px;
+        font-size: 12px;
+      }
+      .self { outline: 2px solid #f59e0b; }
+    </style>
+  </head>
+  <body>
+    <header>
+      <h1>EchoChat mediasoup PoC（Phase 2e-2 Task 0）</h1>
+      <div class="controls">
+        <span id="status" style="margin-right:12px; color:#94a3b8;">idle</span>
+        <button id="btnJoin">加入并推流</button>
+        <button id="btnLeave" disabled>离开</button>
+      </div>
+    </header>
+    <div id="log"></div>
+    <div id="videos"></div>
+    <script type="module" src="./client.mjs"></script>
+  </body>
+</html>
--- a/media-server/poc/server.mjs
+++ b/media-server/poc/server.mjs
@@ -0,0 +1,348 @@
+// Phase 2e-2 Task 0: mediasoup PoC Server
+// 架构：Fastify 提供静态资源 + WS 信令 + mediasoup 单 Worker 单 Router
+// 仅用于验证技术栈，PoC 结束后可删除或演化为正式 media-server
+
+import Fastify from 'fastify';
+import fastifyStatic from '@fastify/static';
+import fastifyWebsocket from '@fastify/websocket';
+import * as mediasoup from 'mediasoup';
+import pino from 'pino';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import os from 'node:os';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const logger = pino({
+  transport: {
+    target: 'pino-pretty',
+    options: { colorize: true, translateTime: 'SYS:HH:MM:ss.l' },
+  },
+});
+
+// ---------------- Config ----------------
+
+const HTTP_PORT = Number(process.env.HTTP_PORT ?? 3300);
+const LISTEN_IP = process.env.MEDIASOUP_LISTEN_IP ?? '0.0.0.0';
+const ANNOUNCED_IP = process.env.MEDIASOUP_ANNOUNCED_IP ?? ''; // 本机留空走 iceCandidates 自动
+const RTC_MIN_PORT = Number(process.env.MEDIASOUP_RTC_MIN_PORT ?? 40000);
+const RTC_MAX_PORT = Number(process.env.MEDIASOUP_RTC_MAX_PORT ?? 40099);
+
+// 媒体编解码（Router 创建时注入）
+const mediaCodecs = [
+  {
+    kind: 'audio',
+    mimeType: 'audio/opus',
+    clockRate: 48000,
+    channels: 2,
+  },
+  {
+    kind: 'video',
+    mimeType: 'video/VP8',
+    clockRate: 90000,
+    parameters: { 'x-google-start-bitrate': 1000 },
+  },
+  {
+    kind: 'video',
+    mimeType: 'video/H264',
+    clockRate: 90000,
+    parameters: {
+      'packetization-mode': 1,
+      'profile-level-id': '42e01f',
+      'level-asymmetry-allowed': 1,
+    },
+  },
+];
+
+// ---------------- Mediasoup 全局资源 ----------------
+
+let worker;
+let router;
+
+// peers：peerId → { ws, transports: Map, producers: Map, consumers: Map }
+const peers = new Map();
+
+async function initMediasoup() {
+  worker = await mediasoup.createWorker({
+    rtcMinPort: RTC_MIN_PORT,
+    rtcMaxPort: RTC_MAX_PORT,
+    logLevel: 'warn',
+  });
+
+  worker.on('died', (err) => {
+    logger.error({ err }, 'mediasoup worker died, exiting');
+    process.exit(1);
+  });
+
+  router = await worker.createRouter({ mediaCodecs });
+
+  logger.info(
+    {
+      workerPid: worker.pid,
+      routerId: router.id,
+      rtcPortRange: `${RTC_MIN_PORT}-${RTC_MAX_PORT}`,
+      listenIp: LISTEN_IP,
+      announcedIp: ANNOUNCED_IP || '(unset, use local LAN ip)',
+    },
+    'mediasoup worker + router ready',
+  );
+}
+
+// ---------------- Transport 创建辅助 ----------------
+
+async function createWebRtcTransport() {
+  const listenIps = [{ ip: LISTEN_IP, announcedIp: ANNOUNCED_IP || undefined }];
+  const transport = await router.createWebRtcTransport({
+    listenIps,
+    enableUdp: true,
+    enableTcp: true,
+    preferUdp: true,
+    initialAvailableOutgoingBitrate: 1_000_000,
+  });
+  return transport;
+}
+
+// ---------------- WS 信令 ----------------
+
+function send(ws, type, data = {}, reqId) {
+  if (ws.readyState !== 1) return;
+  const msg = { type, data };
+  if (reqId) msg.reqId = reqId;
+  ws.send(JSON.stringify(msg));
+}
+
+function broadcast(excludeId, type, data) {
+  for (const [pid, peer] of peers) {
+    if (pid === excludeId) continue;
+    send(peer.ws, type, data);
+  }
+}
+
+async function handleMessage(peerId, peer, raw) {
+  let msg;
+  try {
+    msg = JSON.parse(raw);
+  } catch {
+    logger.warn({ peerId, raw: String(raw).slice(0, 80) }, 'invalid json');
+    return;
+  }
+  const { type, data = {}, reqId } = msg;
+
+  try {
+    switch (type) {
+      case 'getRtpCapabilities': {
+        send(peer.ws, 'rtpCapabilities', router.rtpCapabilities, reqId);
+        break;
+      }
+      case 'createTransport': {
+        const transport = await createWebRtcTransport();
+        peer.transports.set(transport.id, transport);
+        send(
+          peer.ws,
+          'transportCreated',
+          {
+            direction: data.direction,
+            id: transport.id,
+            iceParameters: transport.iceParameters,
+            iceCandidates: transport.iceCandidates,
+            dtlsParameters: transport.dtlsParameters,
+          },
+          reqId,
+        );
+        break;
+      }
+      case 'connectTransport': {
+        const { transportId, dtlsParameters } = data;
+        const transport = peer.transports.get(transportId);
+        if (!transport) throw new Error(`transport ${transportId} not found`);
+        await transport.connect({ dtlsParameters });
+        send(peer.ws, 'transportConnected', { transportId }, reqId);
+        break;
+      }
+      case 'produce': {
+        const { transportId, kind, rtpParameters } = data;
+        const transport = peer.transports.get(transportId);
+        if (!transport) throw new Error(`transport ${transportId} not found`);
+        const producer = await transport.produce({ kind, rtpParameters });
+        peer.producers.set(producer.id, producer);
+
+        producer.on('transportclose', () => {
+          peer.producers.delete(producer.id);
+        });
+
+        send(peer.ws, 'produced', { producerId: producer.id, kind }, reqId);
+
+        // 广播给其他 peer
+        broadcast(peerId, 'newProducer', {
+          peerId,
+          producerId: producer.id,
+          kind,
+        });
+        logger.info({ peerId, producerId: producer.id, kind }, 'peer produced');
+        break;
+      }
+      case 'consume': {
+        const { transportId, producerId, rtpCapabilities } = data;
+        const transport = peer.transports.get(transportId);
+        if (!transport) throw new Error(`transport ${transportId} not found`);
+        if (!router.canConsume({ producerId, rtpCapabilities })) {
+          throw new Error(`router cannot consume producer ${producerId}`);
+        }
+        const consumer = await transport.consume({
+          producerId,
+          rtpCapabilities,
+          paused: true, // 先暂停，客户端确认后再 resume
+        });
+        peer.consumers.set(consumer.id, consumer);
+
+        consumer.on('transportclose', () => {
+          peer.consumers.delete(consumer.id);
+        });
+        consumer.on('producerclose', () => {
+          peer.consumers.delete(consumer.id);
+          send(peer.ws, 'consumerClosed', { consumerId: consumer.id });
+        });
+
+        send(
+          peer.ws,
+          'consumed',
+          {
+            id: consumer.id,
+            producerId,
+            kind: consumer.kind,
+            rtpParameters: consumer.rtpParameters,
+          },
+          reqId,
+        );
+        break;
+      }
+      case 'resumeConsumer': {
+        const { consumerId } = data;
+        const consumer = peer.consumers.get(consumerId);
+        if (!consumer) throw new Error(`consumer ${consumerId} not found`);
+        await consumer.resume();
+        send(peer.ws, 'consumerResumed', { consumerId }, reqId);
+        break;
+      }
+      case 'getPeers': {
+        // 返回当前其他 peers 正在 produce 的 producerId 列表
+        const others = [];
+        for (const [pid, p] of peers) {
+          if (pid === peerId) continue;
+          for (const producer of p.producers.values()) {
+            others.push({ peerId: pid, producerId: producer.id, kind: producer.kind });
+          }
+        }
+        send(peer.ws, 'peers', { items: others }, reqId);
+        break;
+      }
+      default:
+        send(peer.ws, 'error', { message: `unknown type: ${type}` }, reqId);
+    }
+  } catch (err) {
+    logger.error({ peerId, type, err: err.message }, 'handle message failed');
+    send(peer.ws, 'error', { message: err.message }, reqId);
+  }
+}
+
+function cleanupPeer(peerId) {
+  const peer = peers.get(peerId);
+  if (!peer) return;
+  for (const p of peer.producers.values()) p.close();
+  for (const c of peer.consumers.values()) c.close();
+  for (const t of peer.transports.values()) t.close();
+  peers.delete(peerId);
+  broadcast(peerId, 'peerLeft', { peerId });
+  logger.info(
+    {
+      peerId,
+      remaining: peers.size,
+      routerStats: { producers: [...peers.values()].reduce((n, p) => n + p.producers.size, 0) },
+    },
+    'peer cleaned up',
+  );
+}
+
+// ---------------- Fastify 启动 ----------------
+
+async function main() {
+  await initMediasoup();
+
+  const app = Fastify({ logger: false });
+
+  await app.register(fastifyWebsocket);
+  await app.register(fastifyStatic, {
+    root: path.join(__dirname, 'public'),
+    prefix: '/',
+  });
+
+  app.get('/healthz', async () => ({
+    ok: true,
+    workerPid: worker.pid,
+    routerId: router.id,
+    peers: peers.size,
+  }));
+
+  app.get('/stats', async () => {
+    // 基础压测观测：peer 数 + producer/consumer 总数 + 内存
+    let totalProducers = 0;
+    let totalConsumers = 0;
+    let totalTransports = 0;
+    for (const p of peers.values()) {
+      totalProducers += p.producers.size;
+      totalConsumers += p.consumers.size;
+      totalTransports += p.transports.size;
+    }
+    const mem = process.memoryUsage();
+    return {
+      peers: peers.size,
+      transports: totalTransports,
+      producers: totalProducers,
+      consumers: totalConsumers,
+      memoryMB: {
+        rss: Math.round(mem.rss / 1024 / 1024),
+        heapUsed: Math.round(mem.heapUsed / 1024 / 1024),
+      },
+      loadavg: os.loadavg(),
+      uptime: Math.round(process.uptime()),
+    };
+  });
+
+  app.register(async function (f) {
+    f.get('/ws', { websocket: true }, (socket, req) => {
+      const peerId = randomUUID();
+      const peer = {
+        ws: socket,
+        transports: new Map(),
+        producers: new Map(),
+        consumers: new Map(),
+      };
+      peers.set(peerId, peer);
+
+      logger.info({ peerId, total: peers.size, ua: req.headers['user-agent'] }, 'peer connected');
+      send(socket, 'welcome', { peerId });
+
+      socket.on('message', (raw) => {
+        handleMessage(peerId, peer, raw.toString());
+      });
+
+      socket.on('close', () => {
+        logger.info({ peerId }, 'ws closed');
+        cleanupPeer(peerId);
+      });
+
+      socket.on('error', (err) => {
+        logger.warn({ peerId, err: err.message }, 'ws error');
+      });
+    });
+  });
+
+  await app.listen({ port: HTTP_PORT, host: '0.0.0.0' });
+  logger.info(`PoC ready: http://localhost:${HTTP_PORT}  (open in 2 browser windows)`);
+}
+
+main().catch((err) => {
+  logger.error({ err }, 'poc server failed to start');
+  process.exit(1);
+});