跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

可观测性

最后更新 查看 MarkdownAgent 设置

诊断 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 适配器参考说明了其公开错误和媒体格式检查。

这篇文档对您有帮助吗?