连接常见问题

本页覆盖建连、掉线、重连与多端在线的常见问题。连接参数（心跳 30000ms、空闲超时 90000ms、退避 1000→30000ms）来自协议定义，排查时先对照这些值。

connect 返回 1002（Token 无效）怎么办？​

用户 Token 有效期 7 天，过期、被重置、或 appkey 与签发 Token 的应用不一致都会返回 1002。处理顺序：① 服务端重新签发 Token；② 客户端用新 Token 重连；③ 不要循环重试旧 Token（会持续失败并触发限频）。

connect 一直处于 CONNECTING 或报 3002（超时）？​

  • 检查服务端地址是否正确（协议 + 端口 + 是否有反向代理改写 WS 升级头）。
  • 检查网络是否允许 WebSocket（部分企业代理只放行 HTTPS）。
  • 检查服务端是否可达：先请求 HTTP 健康检查/文档页，再排查 WS 握手。
  • 确认客户端没有同时创建多个客户端实例重复建连。

为什么会进入 SUSPEND 状态？​

SUSPEND 表示“异常断开后 SDK 正在自动重连”。SDK 按指数退避（1000ms 起、上限 30000ms、最多 8 次）重试；期间请求会以 3001（长连接未就绪）失败。业务侧应暂停发送并等待 CONNECTED，不要自己再调 connect 竞争。

收到 KICKED 事件是什么原因？​

同账号在同类型端重复登录、或管理端强制下线时会收到 KICKED。正确做法是停止重连、提示用户“已在其他设备登录”，并按产品策略跳转登录页。不要用自动重连绕过踢下线。

多端能同时在线吗？​

可以。同一账号的 Web、移动端、桌面端各自维持一条连接，消息投递到全部在线会话；rev25 起离线消息按设备游标补发（A 设备确认不影响 B 设备补收），未读仍用户级。需要“新登录挤掉旧设备”时，Electron 的 connect 可显式开启 kickOtherDevice；其它端默认允许多端。

deviceId 需要业务传入吗？​

不需要，也没有新增公开 API：各端 SDK 首次连接自动生成随机 deviceId 并持久化（Web localStorage、Electron device.json、Android ImStore、Flutter device storage），之后重连复用；服务端按它记录每设备投递游标，hello 会回显。清缓存/换设备会生成新 deviceId，首次连接按新设备补收全部未 ack 消息。详见「多设备投递游标」。

重连成功后需要做什么？​

  • 收到 CONNECTED 后立刻刷新会话列表与未读数（离线期间可能变化）。
  • 补发队列里的待发消息：复用原 clientMsgId，保证幂等。
  • 对当前打开的会话做一次历史对齐（极端情况下本地可能缺消息）。

浏览器切到后台/休眠后连接断了算异常吗？​

不算。浏览器可能冻结标签页导致心跳停止，恢复后 SDK 会重连并补收。页面应在 visibilitychange 恢复时检查连接状态并刷新会话。

为什么移动端后台一段时间后消息不实时？​

移动系统会冻结后台进程，长连接无法维持；实时性依赖推送通道（本项目推送通道为规划中的能力）。业务上应接受“回到前台后再同步”的行为。

可以自己写心跳吗？​

不要。SDK 已按协议发送 ping 并处理 pong 与空闲超时；自建心跳会干扰 SDK 的状态机，且可能与服务端空闲判定冲突。

如何判断连接是否健康？​

  • getConnectionStatus() 返回当前状态；事件流提供状态变化。
  • 服务端“连接明细”可看最后心跳时间与会话数（管理端）。
  • 客户端侧可结合发送成功率与 3001/3002/3003 错误率判断。

相关链接​