诊断 SFU 集成时,把应用请求、WebRTC 连接状态和媒体投递分开。后端响应成功本身并不能证明媒体已到达。
若返回了 API 错误,请使用错误代码参考解读响应并选择下一步。
记录操作、UTC 时间戳、App ID、目标 SFU 会话或适配器 ID、HTTP 状态、cf-ray 响应标头以及各项错误代码。在端点上记录信令、连接和 DataChannel 状态转换。
不要把 App Secret、端点令牌、SDP、ICE 凭据和媒体载荷写入日志。向不受信任的客户端返回错误前先做脱敏。
根据症状选择下一步观测:
| 症状 | 检查 |
|---|---|
| 应用请求被拒绝 | 身份、成员资格、所有权,以及已部署后端的认证配置 |
| SFU 请求失败 | HTTP 状态、顶层错误、逐项结果,以及 API schema 中的必填字段 |
HTTP 200 但缺少轨道 |
逐轨道错误字段、发布发现、发布者会话 ID 和轨道名称 |
协商持续不稳定,或重叠拉取返回 406 |
公开错误、未完成的 offer,以及按会话排序 |
| 已连接但没有入站媒体 | 源发布、已订阅轨道、接收端统计和浏览器播放状态 |
| 视频正常但音频无声 | 麦克风权限、静音状态、音频轨道统计和自动播放要求 |
| 发布者消息未到达订阅者 | 检查每个端点是否使用自己的已分配通道 ID、匹配的投递设置,以及任何必需的就绪消息。 |
| 订阅者控制未到达发布者 | 检查该订阅者是否持有回复权限。使用 waitForAck 时,其第一条消息会被当作就绪确认消费;之后再发送命令。 |
| 适配器无法连接 | 检查服务的 WebSocket 升级、可达性和认证。 |
使用 RTCPeerConnection.getStats() 观察入站流量。随时间比较样本;单次累计字节数无法证明媒体仍在流动。
在此浏览器片段中,pc 是接收端 PeerConnection:
const report = await pc.getStats();
for (const stat of report.values()) {
if (stat.type === "inbound-rtp") {
console.log({
id: stat.id,
kind: stat.kind,
bytesReceived: stat.bytesReceived,
packetsLost: stat.packetsLost,
jitter: stat.jitter,
});
}
}在应用可见的播放状态之外,检查已接收字节是否在增加。如果数据包到达但元素保持静音,检查播放权限和音频输出。如果数据包停止,检查发布、订阅和连接状态。
用应用状态和资源结果区分这些失败:
| 症状 | 检查与下一步 |
|---|---|
| 媒体失败后成员资格仍在 | 比较应用成员资格与 PeerConnection 状态。使用应用的连接恢复策略。 |
| API 响应丢失或超时 | 记录被中断的操作和已知资源标识符。在下一次变更前遵循按操作恢复。 |
| 重连恢复了错误的轨道 | 将当前会话 ID 和连接尝试 ID 与正在应用的响应比较。参见替换连接。 |
| 离开或停止永远无法完成 | 检查待处理的轨道、通道和适配器关闭及其逐项错误。重试失败项时保留清理状态。 |
| 轨道在不活动后消失 | 检查源的最后入站媒体和不活动超时。 |
| 断连后适配器停止投递 | 检查其方向,以及流重连窗口是否已过期。重新创建已终态关闭的适配器。 |
视频房间故障排除指南 ↗把认证、媒体和房间生命周期症状对应到检查项。云游戏指南 ↗区分 Container 启动、发布端就绪、媒体和控制权归属。
设备设置和浏览器恢复请使用 Pocket Radio 故障排除 ↗。WebSocket 适配器参考说明了其公开错误和媒体格式检查。