WebRTC

WebRTC 在 SyncTV 中做什么？

WebRTC 用于客户端之间的实时音视频或低延迟通信能力。SyncTV 负责信令、权限检查和 ICE server 下发。

webrtc.mode

可选值：

• signaling_only
• peer_to_peer

signaling_only

只使用 SyncTV 做信令转发，不提供内置 STUN。

适合：

• 你已有完整 WebRTC 基础设施。
• 只想保留信令，不希望服务监听 UDP STUN 端口。

peer_to_peer

启用 P2P 模式，并可使用内置 STUN 和外部 ICE servers。

默认推荐：

webrtc:
  mode: "peer_to_peer"

webrtc.enable_builtin_stun

默认值：false。

作用：是否启动 SyncTV 内置 STUN server。

STUN 帮助客户端发现自己的公网映射地址，是 NAT 穿透的一部分。

关闭场景：

• 你使用外部 STUN/TURN。
• 当前部署环境不能暴露 UDP 端口。
• 只使用 signaling_only。

webrtc.stun_port

默认值：3478。

这是 STUN 常用端口。

Kubernetes 或云服务器上要确保 UDP 3478 能被客户端访问。

webrtc.stun_host

默认值：

webrtc:
  stun_host: "0.0.0.0"

作用：STUN server 绑定的本地地址。容器和服务器部署通常保持默认。

webrtc.stun_external_addr

作用：告诉客户端 STUN server 的外部可达地址。

如果留空，SyncTV 会尝试 server.advertise_host:stun_port、STUN_EXTERNAL_IP 和云厂商 metadata。只有找到公网可路由地址时才会启动内置 STUN；否则会跳过内置 STUN。

NAT 或 Kubernetes 环境建议显式设置为客户端可访问的公网 ip:port 或域名，例如 LoadBalancer IP、节点公网 IP 或 STUN 域名。不要使用 Pod IP 或 ClusterIP Service IP。

webrtc:
  stun_external_addr: "203.0.113.10:3478"

或使用域名：

webrtc:
  stun_external_addr: "stun.example.com:3478"

webrtc.filter_private_ice_candidates

默认值：false。

作用：过滤私网、回环、链路本地 ICE candidates，减少内部网络信息泄露。

默认配置允许同机和局域网客户端直接连接，适合自包含部署。所有客户端均可获得有效的公网 STUN 或 TURN candidate，且部署需要隐藏本地网络地址时可以开启过滤。

外部 ICE servers

外部 ICE servers 不在 YAML 里静态配置，而是通过运行时设置管理：

webrtc.external_ice_servers

值是 ICE server 对象数组，例如：

[
  { "urls": ["stun:stun.l.google.com:19302"] },
  {
    "urls": ["turn:turn.example.com:3478"],
    "username": "user",
    "credential": "pass"
  }
]

为什么放到运行时设置：

• TURN 凭据可能需要更新。
• 管理员可能希望不重启服务就调整 ICE servers。
• 多节点需要统一动态下发。

语音通话容量

当前语音通话使用房间内 WebRTC Mesh。每个参与者会与其余 N-1 个参与者建立 PeerConnection，因此客户端上行和房间总连接数会随人数快速增长。webrtc.maxVoiceParticipantsPerRoom 默认限制为 8 人，可在 runtime settings 中动态设置为 2 到 32。

服务端在语音 join 时原子占用席位。降低上限只影响后续 join；当前通话继续保持，leave、断线和会话过期会释放席位。多副本部署使用 Redis 协调同一房间的全局人数。

面向超大房间的语音应使用 SFU：每个客户端向服务端发送一路 Opus，SFU 根据活跃说话人和订阅优先级转发有限数量的下行音轨。该模型将客户端上行固定为一路，也能集中实施带宽、发言权限和房间容量策略。

房间动态开关

房间管理员通过 voiceChatEnabled 和 p2pMediaEnabled 独立控制语音与媒体 P2P。设置更新沿现有房间设置版本化 fanout 传播到所有副本和客户端。关闭后服务端立即释放当前连接登记的语音席位与媒体 swarm；新 join、offer、answer、ICE 和 swarm join 返回权限类错误。客户端观察 room_settings，收到关闭状态后销毁本地 PeerConnection、音轨、DataChannel 和 P2P gateway，并隐藏相关入口。

部署检查清单

如果 WebRTC 连接失败，按顺序检查：

1. 客户端是否能访问 SyncTV HTTP/gRPC API。
2. UDP 3478 是否开放。
3. stun_external_addr 是否是客户端可达地址。 这个地址不能是 Pod IP、ClusterIP、回环地址或私网地址，除非你完全使用外部 ICE/TURN 并关闭内置 STUN。
4. 反向代理是否只代理了 HTTP，而没有开放 UDP。
5. 如果客户端在严格 NAT 后面，是否配置了 TURN。
6. filter_private_ice_candidates 是否符合你的网络环境。