企业官网建设流程全解析

简介：这是一套面向即时通讯与音视频开发者的 Web 端开源方案，适合需要快速搭建 IM、群聊、聊天室、一对一视频、直播连麦、白板协作及多人视频会议的前后端工程师与产品团队。资源以 Web 前端工程为主体，兼容 WebRTC 并支持 P2P 高清传输，可实现安卓、iOS 与 Web 三端互通，同时覆盖门禁、电视盒子、树莓派等终端场景，并支持私有云部署。压缩包共 38 个文件，约 827KB，包含 7 个 js 脚本、2 个 css 样式、1 个 html 入口及 1 个 md 说明文档，另有 18 张 png 与 9 张 jpg 界面素材，涵盖通话、白板、屏幕共享等交互图标与预览图。目前已有 606 人学习下载。借助其中的 SDK 脚本、消息弹窗插件与页面结构，读者可快速理解音视频通话与消息模块的集成方式，并在此基础上完成私有化部署与二次开发。

1. 从 starrtc-web 看私有云 IM 与 WebRTC 的落地边界

如果你正在找一个能跑在自己服务器上的即时通讯底座，同时还要把群聊、聊天室、一对一视频、直播连麦、白板、多人视频会议全部塞进浏览器里，那 starrtc-web 这个方向大概率已经被你翻到过。它本质上是一套基于 WebRTC 的 Web 端即时通讯与实时音视频方案，把信令、房间管理、媒体协商、私有化部署这几件事打包在一起，让你不用从零去啃 janus、coturn、webrtc 这些底层组件。很多人第一次接触时会被“免费”“全功能”吸引，但真正决定能不能用的，是私有云部署时信令和媒体链路怎么走、NAT 穿透怎么配、浏览器端 WebRTC 怎么关闭或限制以避免泄露。这篇笔记按“先理解它是什么、再动手搭最小可用、最后看坑和进阶”的顺序展开，适合想自建 IM 和视频会议的中小团队后端或全栈工程师，也适合已经用过云视频会议、现在想迁到私有环境的运维同学。

2. starrtc-web 的模块拆解与私有云选型理由

2.1 信令、媒体、房间：三块必须分开看

starrtc-web 这类方案在浏览器端跑的是 WebRTC，但 WebRTC 本身只负责媒体采集、编码、传输和渲染，它不定义信令。信令负责的是“谁在哪个房间、谁要跟谁通话、SDP 怎么交换、ICE 候选怎么传”。starrtc-web 把信令服务、房间管理、用户状态这些逻辑放在服务端，浏览器通过 WebSocket 或 HTTP 长连接跟服务端交互。媒体流则走 WebRTC 的 PeerConnection，理想情况下是端到端直连，但在私有云里往往需要 coturn 做中继。

群聊和聊天室在实现上是两套不同的模型。群聊通常是固定成员列表，消息广播到群成员；聊天室更偏向大房间、成员动态进出、消息频率高。一对一视频聊天和多人视频会议的区别在于 PeerConnection 的数量和拓扑：一对一就是一条 PeerConnection，多人会议要么走 Mesh（每个端跟其他端都建一条），要么走 SFU（选一个中间服务器转发）。starrtc-web 在 Web 端通常对多人会议做了一定封装，但底层仍然绕不开这些拓扑选择。

白板功能一般不是 WebRTC 标准的一部分，而是基于 Canvas 或 SVG 的协同绘制，通过信令通道同步笔迹和图形数据。直播连麦则是把“直播推流”和“连麦互动”结合，通常一路走 RTMP 或 WebRTC 推流，另一路走低延迟连麦。私有云部署的核心诉求是数据不出自己机房，所以信令服务、turn 服务、媒体转发服务都要能独立部署，并且能配置内网地址和公网映射。

2.2 为什么选私有云而不是直接用云视频会议

云视频会议开箱即用，但数据经过第三方服务器，且并发和功能受套餐限制。私有云部署 starrtc-web 的吸引力在于：第一，用户账号、聊天记录、白板数据都在自己数据库里；第二，可以根据内网带宽和并发数自己扩容；第三，能跟内部 OA、工单系统做深度集成。代价是你要自己维护 coturn 的证书、端口、NAT 映射，还要处理浏览器对 WebRTC 的权限限制和泄露防护。

从选型角度看，如果团队规模在几十人以内、并发会议不超过 10 路，Mesh 拓扑加一台中等配置的 coturn 就能跑。如果要做直播连麦或百人会议，就必须上 SFU，常见做法是引入 janus 或 mediasoup 作为媒体服务器，starrtc-web 的信令层去对接它们。私有云部署时，coturn 的配置直接决定能不能穿透对称 NAT，很多“能登录但看不到画面”的问题都出在这里。

2.3 最小私有云部署的目录与端口规划

在动手之前，先规划好服务器角色。我一般会分三台或三个容器：一台跑信令和 Web 静态资源，一台跑 coturn，一台跑媒体服务器（如果上 SFU）。如果只是验证，可以全部挤在一台机器上，但端口不能冲突。

HTTPS 是硬性要求，浏览器只在安全上下文里允许 getUserMedia。私有云里可以用自签证书，但要在客户端导入信任，否则连摄像头都打不开。coturn 的 TLS 端口需要配置证书路径，且证书域名要跟 turn 服务对外暴露的域名一致。

2.4 用 Docker 跑通信令加 coturn 的最小命令

下面这段 bash 是我在测试环境里常用的启动方式，把信令服务和 coturn 分别拉起来。注意 coturn 的 external-ip 要填公网 IP，如果是内网测试就填内网 IP。

# 启动 coturn，映射 3478 UDP/TCP 和 5349 TLS docker run -d --name coturn \ --network host \ -v /etc/coturn/turnserver.conf:/etc/turnserver.conf \ coturn/coturn -c /etc/turnserver.conf # turnserver.conf 关键项 # listening-port=3478 # tls-listening-port=5349 # external-ip=你的公网IP # realm=your.domain.com # cert=/etc/ssl/turn.crt # pkey=/etc/ssl/turn.key # fingerprint # lt-cred-mech # user=test:test123

# 启动信令服务，假设二进制为 starrtc-signal，监听 8080 ./starrtc-signal --port 8080 --turn turn:your.domain.com:3478 --turn-user test --turn-pass test123

第一段命令用 host 网络是为了避免 UDP 端口映射的麻烦，coturn 对 NAT 环境比较敏感，host 模式最省事。turnserver.conf 里 external-ip 必须写对，否则 ICE 候选里会填错地址。lt-cred-mech 和 user 是长期凭证机制，测试时可以用固定用户名密码，生产环境建议用动态凭证。第二段信令服务启动时把 turn 地址和凭证传进去，前端拿到配置后就能在 RTCPeerConnection 里设置 iceServers。

2.5 前端建立一对一视频的最小代码

前端这部分是 starrtc-web 的核心交互，下面用原生 WebRTC API 演示一对一视频的建立过程，实际项目里 starrtc-web 会封装得更厚，但底层逻辑一致。

// 获取本地媒体流 const localStream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true }); document.getElementById('localVideo').srcObject = localStream; // 创建 PeerConnection，配置 turn const pc = new RTCPeerConnection({ iceServers: [ { urls: 'turn:your.domain.com:3478', username: 'test', credential: 'test123' } ] }); // 把本地流加进去 localStream.getTracks().forEach(track => pc.addTrack(track, localStream)); // 收到远端流时渲染 pc.ontrack = (event) => { document.getElementById('remoteVideo').srcObject = event.streams[0]; }; // 通过信令通道交换 SDP const offer = await pc.createOffer(); await pc.setLocalDescription(offer); // 这里把 offer 通过 WebSocket 发给对方 ws.send(JSON.stringify({ type: 'offer', sdp: offer })); // 收到 answer 后设置远端描述 ws.onmessage = async (msg) => { const data = JSON.parse(msg.data); if (data.type === 'answer') { await pc.setRemoteDescription(new RTCSessionDescription(data.sdp)); } else if (data.type === 'candidate') { await pc.addIceCandidate(new RTCIceCandidate(data.candidate)); } }; // 收集 ICE 候选并发送 pc.onicecandidate = (event) => { if (event.candidate) { ws.send(JSON.stringify({ type: 'candidate', candidate: event.candidate })); } };

这段代码里 getUserMedia 必须在 HTTPS 下调用，否则返回 undefined。iceServers 里只配了 turn，实际生产建议同时配 stun，但私有云里 stun 可以用 coturn 自己兼。createOffer 之后要等 setLocalDescription 完成再发送，否则 SDP 不完整。onicecandidate 是异步收集的，要持续发送直到 candidate 为 null。收到远端 candidate 时要判断 setRemoteDescription 是否已完成，否则会报错，稳妥做法是先把 candidate 存队列，等 remote description 设置好再逐个添加。

3. 群聊、聊天室与多人会议的信令设计

3.1 群聊和聊天室的消息模型差异

群聊的消息通常是“发给群 ID”，服务端查群成员列表，然后推给在线成员。聊天室更接近“房间广播”，成员进出频繁，消息不保证持久化，但要求低延迟。starrtc-web 在信令层一般用不同的消息类型区分：群聊消息带 groupId，聊天室消息带 roomId，并且聊天室会额外处理成员列表变更事件。

私有云部署时，群聊消息可以落库，聊天室消息可以只走内存加 Redis 发布订阅。如果聊天室人数上千，WebSocket 连接数会成为瓶颈，常见做法是引入网关层做连接收敛，或者用 SSE 降级。但 WebRTC 的媒体通道不受这个影响，聊天室里的连麦仍然是独立的 PeerConnection。

3.2 多人视频会议的 Mesh 与 SFU 选择

多人会议如果走 Mesh，每个参与者要跟其他所有人建 PeerConnection，上行带宽是 N-1 倍。4 人以内还能接受，6 人以上上行就会爆。SFU 模式下，每个参与者只跟媒体服务器建一条 PeerConnection，上行 1 路，下行 N-1 路，服务器负责转发。starrtc-web 如果自带媒体服务器，通常就是 SFU 模式；如果只是信令层，就需要对接 janus 或 mediasoup。

选择依据很简单：并发人数少、不想维护媒体服务器，就用 Mesh；要支持 10 人以上或者直播连麦，就上 SFU。私有云里 SFU 的部署成本主要是 UDP 端口段和带宽，一台 4 核 8G 的机器跑 20 路 720p 转发问题不大，但要注意网卡和内核参数调优。

3.3 用 janus 做 SFU 时 starrtc-web 信令怎么对接

janus 是常见的 WebRTC 媒体服务器，它有自己的插件体系，视频会议一般用 VideoRoom 插件。starrtc-web 的信令服务需要跟 janus 的 API 对接，把房间创建、加入、发布、订阅这些操作翻译成 janus 的请求。

# janus 启动示例，开启 VideoRoom 插件 janus --configs-folder=/opt/janus/etc/janus \ --plugins-folder=/opt/janus/lib/janus/plugins \ --debug-level=4

janus 启动后监听 8188 端口，starrtc-web 信令服务通过 HTTP 或 WebSocket 跟它通信。创建房间时调用 VideoRoom 的 create 请求，加入房间时调用 join，发布流时调用 publish。每个参与者拿到 janus 分配的 publisher id 后，前端用这个 id 创建 PeerConnection。janus 的 SDP 交换跟原生 WebRTC 略有不同，它会在 answer 里带上自己的 ICE 候选，前端要正确处理。

私有云里 janus 的 nat-1-1 配置要填公网 IP，否则它通告的候选地址是内网，外部用户连不上。如果 janus 和 coturn 在同一台机器，注意端口不要冲突，janus 默认用 8188 和 7088/8088/8089，coturn 用 3478/5349。

3.4 白板同步的数据通道设计

白板一般不走 WebRTC 的媒体通道，而是走 DataChannel 或 WebSocket。DataChannel 的好处是跟媒体流共享同一条连接，延迟低；坏处是如果 PeerConnection 断了，白板也断。WebSocket 更独立，但多一次网络往返。

我一般会白板走 WebSocket，因为白板数据量小但要求可靠，WebSocket 的 TCP 重传更省心。笔迹数据用 JSON 或二进制数组，按操作类型（画线、擦除、清空）同步。私有云里白板数据可以落库做回放，但要注意频率，每秒几十条笔迹点的话，批量发送比逐条发送更划算。

4. 私有云部署的避坑与排查记录

4.1 能登录但看不到画面，ICE 状态一直 checking

现象：用户能进房间，信令也通了，但视频黑屏，chrome://webrtc-internals 里 ICE 状态卡在 checking。

原因：coturn 的 external-ip 没配或配错，导致 ICE 候选里只有内网地址，外部用户连不上。或者防火墙没放行 UDP 3478。

解决：检查 turnserver.conf 的 external-ip 是否等于公网 IP，用 turnutils_uclient 测试 turn 服务是否可达。防火墙要同时放行 UDP 和 TCP 的 3478，TLS 的 5349 也要放行。

4.2 HTTPS 下摄像头权限被拒

现象：页面能打开，但 getUserMedia 报 NotAllowedError 或 NotFoundError。

原因：私有云用了自签证书，浏览器不信任，安全上下文不成立。或者用户之前拒绝了权限，浏览器记住了。

解决：把自签证书导入系统信任区，或者用受信任的证书。Chrome 里可以在地址栏左侧站点设置里重置摄像头权限。另外注意，如果页面是 HTTP 而不是 HTTPS，getUserMedia 直接不可用。

4.3 多人会议时上行带宽跑满，画面卡顿

现象：4 人以上会议时，每个参与者的上行带宽接近满载，画面糊成马赛克。

原因：用了 Mesh 拓扑，每个端要发 N-1 路流。或者 SFU 的码率没限制，默认给了太高。

解决：切换到 SFU 模式，或者在 Mesh 下把视频分辨率降到 320p、码率限制到 300kbps。SFU 里可以在 janus 的 VideoRoom 配置里设置 bitrate 上限，也可以在前端用 RTCRtpSender.setParameters 限制。

4.4 WebRTC 泄露真实 IP 的顾虑

现象：用户担心 WebRTC 会暴露内网 IP 或真实公网 IP。

原因：WebRTC 的 ICE 候选里会包含本地 IP 和公网 IP，这是协议本身的行为。

解决：在私有云里，如果所有用户都在内网，泄露的是内网 IP，风险可控。如果要限制，可以在浏览器端通过策略关闭非代理 UDP，但这不是标准做法。更稳妥的是用 turn 强制中继，把 iceTransportPolicy 设为 relay，这样候选里只有 turn 服务器地址。代价是延迟增加，但隐私性更好。

4.5 聊天室消息丢失或乱序

现象：聊天室里消息偶尔丢失，或者顺序跟发送顺序不一致。

原因：WebSocket 断线重连时没有补发机制，或者服务端广播时没有按房间加锁。

解决：消息带自增序列号，客户端按序列号排序和去重。断线重连后拉取最近 N 条历史消息。服务端广播时用 Redis 的发布订阅，但要注意订阅者收到消息的顺序不保证，所以序列号是必须的。

5. 从能跑到好用：并发调优与验证技巧

5.1 用 webrtc-internals 看关键指标

chrome://webrtc-internals 是排查 WebRTC 问题的黑匣子。重点看几个指标：ICE 候选类型（host/srflx/relay）、码率（bitsSentPerSecond）、丢包率（packetsLost）、往返延迟（roundTripTime）。如果 relay 候选占比高，说明直连没成功，全走中继，延迟会大。如果 packetsLost 持续增长，检查网络抖动或带宽是否不足。

5.2 coturn 的并发连接数调优

coturn 默认的并发连接数可能不够，私有云里如果同时有几百路中继，需要调整配置。在 turnserver.conf 里加 max-bps 限制单用户带宽，total-quota 限制总配额，user-quota 限制单用户会话数。另外，coturn 的 relay-threads 可以调大，但不要超过 CPU 核数太多。

# turnserver.conf 调优片段 max-bps=1000000 total-quota=1000 user-quota=12 relay-threads=4

max-bps 是单会话最大比特率，1000000 约等于 1Mbps，够 720p。total-quota 是总配额，1000 路中继对一台机器来说已经很高，实际要看带宽。user-quota 限制同一用户名的并发会话，防止一个账号开太多。relay-threads 是转发线程数，一般设为 CPU 核数。

5.3 验证私有云是否真的不依赖外部服务

部署完之后，把服务器的外网出口断掉，只保留内网互通，看 IM 和会议是否还能用。如果断了外网就挂，说明还有组件在调外部 API，比如某些云服务的 STUN。检查前端配置里的 iceServers 是否只包含自己的 coturn，信令地址是否指向内网。另外，检查页面有没有加载外部 CDN 的 JS，私有云里最好把静态资源也本地化。

5.4 一个容易忽略的细节：时间同步

WebRTC 的 RTCP 和某些信令协议依赖时间戳，如果服务器时间偏差太大，会导致媒体同步问题。私有云里如果有多台服务器，建议都配 NTP。我遇到过因为 coturn 服务器时间比信令服务器慢了几分钟，导致 ICE 候选过期被丢弃的情况。这个坑很隐蔽，现象是偶尔能连上偶尔不能，排查时容易忽略。

5.5 我的习惯：先压测再上线

每次私有云部署完，我会先用脚本模拟 10 个并发用户进同一个会议，跑 10 分钟，看 CPU、内存、带宽和丢包。工具可以用 puppeteer 开多个无头浏览器，每个页面自动加入房间并开启假摄像头。压测通过后再逐步加人。这个习惯帮我提前发现过 coturn 端口耗尽和 janus 句柄泄漏的问题。希望帮到你。

本文还有配套的精品资源，点击获取