诊断与日志

接入 Room 时，建议按「凭证签发 → TiRTC TiRtcWhipConnect 建连 → 连接结果 → 音频上下行 → 房间信令」的顺序定位问题。

常见问题

现象	诊断方向	排查建议
获取 token 失败	Token 服务返回 401 或 403。	检查 X-Tg-App-Id、Authorization 和设备入房权限。
TiRTC 建连返回鉴权失败	token 无效、过期，或未与本次 peer_id 配套使用。	重新申请凭证，并确认设备端原样传入业务服务端下发的 peer_id 和 token。
TiRTC 建连暂不可用	服务暂不可用或网络临时异常。	重新申请凭证后重试；如果持续出现，请携带时间、room_id、device_id 和请求信息联系技术支持。
连接无法完成	网络、NAT 或 UDP 连通异常。	检查设备网络和 TiRTC SDK 日志。
能入房但听不到声音	上行无音频、编码格式不一致或播放端未处理下行音频。	核对采样率、声道、codec 和下行播放缓冲。
成员列表不更新	未收到 room_snapshot，或命令通道处理失败。	检查命令通道 0x2200 是否收到合法 JSON-RPC 通知；必要时发送 get_room_snapshot 主动对齐状态。
麦克风状态不更新	未发送 set_mic_state，或未处理 participant_mic_state_changed。	确认本端麦克风开关和讲话检测会映射为 on、speaking、off，并检查其他成员是否收到状态变化通知。
离房后状态残留	本地资源未彻底释放，或房间状态未清理。	将主动离房、断网、超时统一到同一个清理流程。

排查时需要收集的信息

• 应用 ID、业务 room_id、设备 device_id 和问题发生时间。
• 脱敏后的 peer_id，不要提供完整 token。
• Token 服务 HTTP 状态码和错误响应。
• TiRTC TiRtcWhipConnect 的调用时间、返回码和错误信息。
• TiRTC SDK 建连、音频收发和命令通道日志。

日志脱敏

日志中可以保留定位字段，例如 room_id、device_id、session_id 和错误码。不要打印完整 token、完整应用密钥或包含敏感 query 的完整 URL。