1. 从一次无声崩溃说起为什么业务类初始化值得单独拎出来讲如果你正在用 mediasoup 做流媒体服务端开发大概率经历过这样的场景Worker 起来了Router 也创建了信令通道看起来一切正常但客户端就是拉不到流或者推流推到一半突然断掉日志里干干净净什么错误都没有。这种无声崩溃十有八九不是媒体协商的问题而是业务类在初始化阶段就埋了雷。mediasoup 本身是一个偏底层的 SFU 库它只负责媒体转发这一件事至于房间怎么管、参与者怎么映射、Transport 什么时候创建、Producer 和 Consumer 怎么关联这些统统属于业务类的范畴。很多教程讲到 mediasoup 的初始化往往只讲到 Worker 和 Router 就停了剩下的全丢给读者自己悟。但实际项目里真正决定系统稳不稳的恰恰是这些业务类的初始化顺序和状态管理。这篇内容适合两类人一类是刚接触 mediasoup、已经能跑通官方 demo 但不知道如何组织业务代码的开发者另一类是做了一段时间、系统开始出现各种诡异问题、想回头梳理初始化链路的老手。我会围绕业务类初始化的核心逻辑展开把顺序、依赖、状态、常见坑都拆开讲清楚尽量做到你看完就能对照自己的代码改。需要先说明一点mediasoup 的版本迭代比较快不同版本 API 有差异下面讲到的思路和结构是通用的具体方法名请以你所用版本的文档为准。我这边主要以 v3 系列的常见实践为参考。2. 业务类初始化的整体分层谁先谁后不是随便定的2.1 三层结构进程级、房间级、参与者级在动手写代码之前先把业务类的层次理清楚否则很容易写成一锅粥。我习惯把 mediasoup 相关的业务类分成三层进程级Worker 层整个服务进程共享的 Worker 池负责 CPU 资源的分配。这一层通常在服务启动时初始化一次生命周期跟进程一致。房间级Router 层每个房间对应一个 RouterRouter 承载了这个房间里所有参与者的媒体转发逻辑。房间创建时初始化房间销毁时释放。参与者级Transport / Producer / Consumer 层每个加入房间的用户都有自己的 Transport推流产生 Producer拉流产生 Consumer。用户加入时初始化离开时清理。这三层的初始化顺序是严格自上而下的。Worker 没起来Router 创建会直接抛错Router 没创建Transport 无从谈起。听起来是废话但实际项目里我见过不少人在房间还没完全初始化完就把用户塞进去结果就是各种空指针和超时。2.2 为什么不能用到再创建有人会想何必这么麻烦等真正需要的时候再懒加载不就行了比如用户要推流的时候再创建 Transport。这个思路在小规模场景下能跑但一旦并发上来就会出问题。原因在于 mediasoup 的很多操作是异步的创建 Transport 需要跟底层 Worker 通信这个往返是有延迟的。如果等到用户点击推流按钮才开始创建用户会明显感觉到卡顿。更麻烦的是如果多个操作并发触发可能出现重复创建或者状态竞争。所以我的做法是在用户加入房间的信令处理阶段就把该用户需要的 Transport 全部创建好等真正推拉流时直接复用。2.3 初始化失败的兜底策略初始化链路一长失败点就多。Worker 可能因为资源不足起不来Router 可能因为参数错误创建失败Transport 可能因为网络问题超时。每一层都要有兜底。我的经验是进程级初始化失败直接让服务启动失败因为 Worker 都起不来这个进程留着也没用不如让编排系统重新拉起。房间级初始化失败要回滚把已经创建的资源释放掉避免内存泄漏。参与者级初始化失败要通知客户端让客户端知道是哪一步出了问题而不是干等。这里有个细节mediasoup 的资源释放是异步的close() 调用之后不代表资源立刻回收。所以在回滚逻辑里不要假设 close() 之后对象就没了该置空的引用还是要置空。3. Worker 层的初始化别小看这几行代码3.1 Worker 数量怎么定Worker 是 mediasoup 的媒体处理进程每个 Worker 是一个独立的子进程。Worker 数量直接决定了这个服务能榨干多少 CPU。官方建议是每个 CPU 核心对应一个 Worker。但这个建议有个前提你的服务是独占这台机器的。如果是容器化部署容器本身有 CPU limit那就不能按物理核心数来算要按 limit 来算。比如容器限制 2 核你起 8 个 Worker结果就是互相抢 CPU性能反而下降。我一般的做法是const os require(os); const numWorkers process.env.WORKER_COUNT ? parseInt(process.env.WORKER_COUNT) : Math.min(os.cpus().length, 4);用环境变量覆盖默认取 CPU 核心数和 4 的较小值。为什么封顶 4因为大多数中小规模场景 4 个 Worker 已经够用起太多反而增加调度开销和内存占用。等真的压测发现不够再往上调。3.2 Worker 的创建参数创建 Worker 时可以传一些参数最常用的是rtcMinPort和rtcMaxPort指定 WebRTC 使用的 UDP/TCP 端口范围。这个范围要跟你的防火墙规则对齐否则媒体流会被挡在外面。const worker await mediasoup.createWorker({ logLevel: warn, rtcMinPort: 40000, rtcMaxPort: 40100, });端口范围给多大每个 Transport 会占用端口具体占用多少跟 ICE 候选有关。保守估计每个参与者可能占用 2 到 4 个端口。如果你预计单机最多 100 个参与者那至少准备 400 个端口。我一般会留一倍余量所以上面例子里给了 100 个端口是远远不够的实际项目里我会开到 40000 到 41000 这样的范围。注意端口范围不是越大越好。范围太大防火墙规则不好写排查问题也麻烦。够用就行留点余量。3.3 Worker 异常退出的监听Worker 是子进程子进程是会挂的。挂的原因可能是内存溢出、可能是底层崩溃、也可能是被系统 kill 掉。如果不监听Worker 挂了你的服务还在傻跑新来的请求全部失败。worker.on(died, (error) { console.error(worker died, error); // 标记该 worker 不可用从池子里移除 // 如果池子里没有可用 worker考虑重启服务 });这里有个坑Worker 挂掉之后绑定在它上面的 Router、Transport 全部失效。如果你有房间映射到这些 Router需要把这些房间标记为异常通知里面的用户重新加入。这个逻辑不做用户就会卡在一个永远连不上的房间里。4. Router 层的初始化房间的真正起点4.1 Router 与 Worker 的绑定关系Router 必须创建在某个 Worker 上。一个 Worker 可以承载多个 Router一个 Router 只能属于一个 Worker。这个绑定关系在创建时就确定了之后不能改。所以创建 Router 的时候要先从 Worker 池里挑一个。挑的策略有几种轮询简单均匀但没考虑负载。最少 Router 数挑当前承载 Router 最少的 Worker相对均衡。按房间 ID 哈希同一个房间总是落到同一个 Worker方便调试但可能不均。我一般用最少 Router 数这个策略实现简单效果也还行。如果你的场景对房间和 Worker 的绑定有特殊要求再考虑哈希。function pickWorker(workers) { return workers.reduce((min, w) w.routerCount min.routerCount ? w : min ); }4.2 Router 的 RTP 能力配置创建 Router 时需要指定这个 Router 支持哪些 RTP 能力codec、header extension 等。这个配置决定了房间里能用什么编码格式。const router await worker.createRouter({ mediaCodecs: [ { kind: audio, mimeType: audio/opus, clockRate: 48000, channels: 2, }, { kind: video, mimeType: video/VP8, clockRate: 90000, }, ], });这里的关键是Router 的 mediaCodecs 必须跟客户端的能力有交集。如果 Router 只支持 VP8客户端只会 H264那协商就会失败。实际项目里我一般会同时支持 VP8、H264、VP9让客户端去选。还有一个容易忽略的点Router 创建后mediaCodecs 不能改。所以如果你有不同编码需求的房间要么创建不同的 Router要么一开始就把所有可能用到的 codec 都配上。4.3 房间与 Router 的生命周期管理房间创建时创建 Router房间销毁时关闭 Router。听起来简单但房间什么时候算销毁这个问题很微妙。是最后一个用户离开就销毁吗不一定。如果用户只是临时断线马上重连你把房间销毁了他重连回来发现房间没了体验很差。所以通常会给房间加一个空置超时最后一个用户离开后等一段时间比如 30 秒如果没人回来再销毁。function onUserLeave(room) { if (room.users.size 0) { room.emptyTimer setTimeout(() { room.router.close(); rooms.delete(room.id); }, 30000); } } function onUserJoin(room) { if (room.emptyTimer) { clearTimeout(room.emptyTimer); room.emptyTimer null; } }这个空置超时的时长要权衡太短用户重连来不及太长资源回收慢。30 秒是个比较稳妥的值你可以根据自己场景调整。5. 参与者级初始化Transport、Producer、Consumer 的创建顺序5.1 Transport 的两种类型与创建时机mediasoup 里有两种 TransportWebRtcTransport和PlainTransport。前者用于浏览器等 WebRTC 客户端后者用于跟其他媒体系统对接比如跟 FFmpeg、跟其他 SFU。大多数场景用的是 WebRtcTransport。每个参与者通常需要两个 Transport一个用于发送推流一个用于接收拉流。也可以只用一个双向 Transport但我不推荐因为分开更清晰权限控制也更容易。创建 WebRtcTransport 时需要指定监听 IPconst transport await router.createWebRtcTransport({ listenIps: [ { ip: 0.0.0.0, announcedIp: 你的公网IP } ], enableUdp: true, enableTcp: true, preferUdp: true, });announcedIp这个参数是坑最多的地方。它告诉客户端你应该连我这个地址。如果你填的是内网地址客户端在外网就连不上。如果你不填mediasoup 会用 listenIp那多半也是内网地址。所以生产环境一定要显式指定 announcedIp 为公网地址。5.2 Transport 创建后要立刻做的事Transport 创建出来只是第一步接下来还要获取 ICE 候选和 DTLS 参数发给客户端。客户端用这些信息建立连接。监听 dtlsstatechangeDTLS 连接建立成功才算 Transport 真正可用。监听 closeTransport 关闭时清理相关资源。const { id, iceParameters, iceCandidates, dtlsParameters } transport; transport.on(dtlsstatechange, (state) { if (state closed) { transport.close(); } });这里有个经验不要假设 Transport 创建成功就一定能连上。DTLS 握手可能因为各种原因失败证书问题、网络问题、防火墙问题。所以要有超时机制比如 10 秒内没收到 dtlsstatechange 为 connected就认为这个 Transport 有问题通知客户端重试。5.3 Producer 的创建与暂停恢复用户开始推流时客户端会发一个 produce 请求服务端据此创建 Producer。const producer await transport.produce({ kind: video, rtpParameters: clientRtpParameters, });创建 Producer 之后要把它跟这个用户的会话关联起来方便后续管理。同时要监听 Producer 的事件transportcloseTransport 关了Producer 也就没了。pause / resume用户暂停或恢复推流。closeProducer 被关闭。Producer 的暂停恢复是个容易被忽略的功能。用户可能想临时关掉摄像头但保持连接这时候用 pause 比关闭再重建要高效得多。但要注意pause 之后 Producer 还在只是不发送媒体数据资源占用会降低但不会归零。5.4 Consumer 的创建与层级选择拉流时创建 Consumer。创建 Consumer 需要指定一个 Producer 作为源还要指定 RTP 能力通常从客户端的 recvTransport 拿。const consumer await transport.consume({ producerId: producer.id, rtpCapabilities: clientRtpCapabilities, paused: true, // 先暂停等客户端准备好再恢复 });这里有个关键点Consumer 创建时先设为 paused。为什么因为创建 Consumer 是异步的创建完成到客户端真正准备好接收之间有时间差。如果不暂停媒体数据可能在这段时间里发出去然后丢掉造成花屏或者卡顿。等客户端确认准备好了再调用 resume。Consumer 还有层级的概念consumer.setPreferredLayers用于 simulcast 场景。如果 Producer 推了多个分辨率的流Consumer 可以根据自己的网络情况选择拉哪个层级。这个功能在弱网环境下特别有用但配置起来有点绕后面有机会单独讲。6. 初始化链路的常见坑与排查思路6.1 坑一Worker 端口范围与防火墙不匹配这个坑的典型表现是信令一切正常ICE 候选也交换了但媒体就是不通。看日志发现 ICE 一直处于 checking 状态最后超时。原因通常是 Worker 的 rtcMinPort/rtcMaxPort 指定的端口范围跟服务器防火墙放行的范围不一致。mediasoup 会在这个范围里随机选端口如果选中的端口被防火墙挡了媒体就通不了。排查方法先确认 Worker 的端口范围然后在服务器上检查防火墙规则确保这个范围是放行的。如果是云服务器还要检查安全组规则。6.2 坑二announcedIp 配置错误这个坑的表现是内网测试一切正常一上外网就拉不到流。原因就是 announcedIp 填了内网地址。客户端拿到 ICE 候选后尝试连内网地址当然连不上。排查方法检查创建 WebRtcTransport 时的 announcedIp 参数。如果是动态获取公网 IP要确保获取逻辑正确并且在 IP 变化时能更新。6.3 坑三Router 的 mediaCodecs 与客户端不匹配表现是produce 请求被拒绝错误信息里提到 codec 不支持。原因是 Router 配置的 mediaCodecs 跟客户端想推的编码格式没有交集。比如客户端想推 H264但 Router 只配了 VP8。排查方法打印 Router 的 rtpCapabilities跟客户端的 rtpCapabilities 对比看有没有交集。如果没有要么改 Router 配置要么让客户端换编码。6.4 坑四资源释放不彻底导致内存泄漏表现是服务跑一段时间后内存持续上涨最后 OOM。原因是各种 close() 调用不完整。比如用户离开时只关了 Transport没关 Producer 和 Consumer或者房间销毁时只关了 Router没清理房间内的其他资源。排查方法给每个资源都加上 close 监听在监听里做级联清理。同时用工具比如 clinic、heapdump定期检查内存快照看有没有异常增长的对象。7. 一套可复用的初始化流程模板把上面的内容串起来一个完整的初始化流程大概是这样服务启动阶段根据 CPU 配置创建 Worker 池。为每个 Worker 注册 died 事件监听。启动信令服务等待客户端连接。用户加入房间阶段查找或创建房间。房间不存在则创建 Router配置 mediaCodecs。为用户创建 sendTransport 和 recvTransport。把 ICE 参数和 DTLS 参数返回给客户端。等待客户端确认 Transport 连接成功。用户推流阶段客户端发送 produce 请求。服务端在 sendTransport 上创建 Producer。关联 Producer 到用户会话。通知房间内其他用户有新的流可用。用户拉流阶段客户端发送 consume 请求。服务端在 recvTransport 上创建 Consumer初始为 paused。返回 Consumer 参数给客户端。客户端准备好后服务端 resume Consumer。用户离开阶段关闭该用户的所有 Producer 和 Consumer。关闭该用户的 Transport。从房间用户列表移除。如果房间空了启动空置超时。这套流程我在几个项目里用过基本能覆盖大多数场景。当然具体实现要根据你的信令协议和业务需求调整但大框架是通用的。8. 关于状态同步的一点个人体会最后聊一个容易被忽略但很重要的话题状态同步。mediasoup 的服务端状态和客户端状态是两套东西。服务端认为某个 Producer 存在不代表客户端也认为它存在。网络抖动、页面刷新、进程崩溃都可能导致两边状态不一致。我的做法是服务端维护一份权威状态客户端定期同步。客户端加入房间时服务端把当前房间的所有 Producer 列表发过去客户端拉流时以服务端的列表为准。如果客户端发现本地状态跟服务端不一致以服务端为准重建。这个机制听起来简单但能避免很多诡异问题。比如用户 A 的 Producer 因为网络问题在服务端被关闭了但用户 B 的客户端还认为这个 Producer 存在尝试拉流就会失败。有了状态同步用户 B 下次同步时就会发现这个 Producer 没了主动清理本地状态。状态同步的频率要权衡太频繁浪费带宽太稀疏发现问题慢。我一般用 30 秒一次的心跳同步加上关键操作加入、离开、推流、停止推流时的即时同步。这样既能及时发现问题又不会给服务端太大压力。这套东西没有标准答案每个项目的业务特点不同需要根据自己的情况调整。但核心思路是一致的服务端权威客户端跟随定期同步异常重建。把这十六个字记住大部分状态问题都能迎刃而解。