联调与故障排查

按业务登录、IM Session、连接、消息同步和媒体链路分层定位问题，结合稳定错误码与追踪信息缩小排查范围。

按现象定位

现象	优先检查	下一步
业务登录成功但 IM 不可用	业务后端是否取得有效 IM Session	核对签名、账号状态与返回字段
REST 可用但 WebSocket 失败	WS 地址、代理 Upgrade、票据与证书	验证设备/平台绑定和入口配置
已连接但历史暂未出现	同步进度、会话范围、本地存储	查看同步错误，不重复创建 Socket
只有特定联系人或群发不出去	好友关系、群成员、禁言与限制	对照服务端业务拒绝
搜索结果少于另一台设备	当前设备已同步的本地索引范围	区分本地搜索与服务端历史
图片曾能打开，稍后失败	短效 URL、消息可见性和对象存储	验证一次授权刷新，避免无限重试
收到通话邀请但无声音	麦克风权限、媒体网络和实际音频路由	检查音视频媒体服务与真机设备
Webhook 重复触发业务	事件 ID 去重与消费事务	核对可靠落库后才返回成功

Flutter 连接诊断

SDK 提供 connectionDiagnostics 当前快照和 connectionDiagnosticsStream 后续变化，包含重试次数、下次重连时间、心跳及稳定错误信息。

final snapshot = sdk.connectionDiagnostics;
final subscription = sdk.connectionDiagnosticsStream.listen((diagnostics) {
  // 宿主可记录必要的状态与时间，不拼接 Token 或聊天正文。
});
// 持有订阅的组件释放时：await subscription.cancel();

自定义传输结合连接状态与其自身日志排查；诊断数据只记录定位问题所需的状态与标识。

五个常见误区

1. 业务 Token 当作 IM Token 使用。
2. 签名后再次格式化 JSON，导致发送字节与签名字节不同。
3. 切号只换页面资料，没有等待旧 SDK 状态释放。
4. 把附件 403 一律当作链接过期，忽略退出群或消息撤回后的权限变化。
5. 调整网络或媒体配置后，未同步更新应用权限、域名与设备路由。

提交问题前准备

记录客户端平台、SDK/服务端版本、发生时间、可复现步骤、期望结果、实际结果与稳定错误码。跨服务问题附脱敏追踪 ID；Webhook 附事件 ID；消息问题附经过脱敏的消息定位信息。

不要发送用户密码、完整 Token、签名密钥或真实聊天正文。使用独立测试账号复现同样问题，通常更容易定位。

上线检查

双账号互发消息、断网恢复、切号退出、设备撤销、历史与撤回同步、私有附件访问、群权限，以及目标真机上的推送和音视频。备份恢复和服务回退也应在实际部署流程中验证。

相关内容：连接生命周期、错误处理、通话权限。