诊断与日志

排查问题时，先确认失败发生在哪个阶段，再收集相应证据。

阶段	现象	优先检查
获取连接参数	业务服务端不返回 peer_id 或 Token	业务权限、服务名、设备 ID、签发错误
TiRTC 建连	设备未向 WHIP Service 发起 POST	设备凭据、设备注册、Region 服务配置、Token 有效期、设备网络
WHIP HTTP	返回 401/403/415/5xx	Header、Query、Token、公钥、入口代理、服务日志
WebRTC 建连	已返回 201 但连接回调失败	SDP、Candidate、DNS、防火墙、UDP/NAT
媒体传输	连接成功但没有媒体或发生丢帧	事件缓冲、消费速度、订阅状态、编解码格式
断开清理	活跃会话持续增长	DELETE、断开事件、超时和幂等清理

建议收集

• 发生时间、Region、服务版本和 TiRTC SDK 版本。
• 脱敏后的设备 ID、服务名和会话 ID。
• HTTP 状态码、请求路径和响应耗时。
• 建连错误码、断开原因及 EventStats()。
• 网络入口、Candidate、公网 UDP 和防火墙配置。

不要收集或传递完整私钥、Device Secret Key、Bearer Token。需要关联 Token 时，只记录不可逆摘要或末尾少量字符。

Echo 基线

先使用快速开始示例和 tirn_probe_device connect 验证基础建连，再用 media 验证双向音视频。Echo 可以成功而业务服务失败时，重点检查业务服务的认证组合、会话注册表、事件处理和资源管理。

Echo 服务可通过 HTTPAdapter.Stats() 检查活跃会话、接受失败、建连失败、超时、发送失败和事件丢弃。需要实时指标时，使用 Echo Observer 接收 Echo 会话和媒体事件，使用 tirtcxauth.AuthObserver 接收认证结果；指标标签只能使用 SDK 提供的有限枚举，不能使用设备 ID 或会话 ID。