连接明细

连接明细展示当前 WS 在线会话：sessionId、connectedAt、lastHeartbeatAt 与按用户的会话数。它是“收不到消息”排查的第一站——先确认接收方是否在线，再看消息轨迹。

概念​

字段含义备注
userId连接归属用户按应用隔离
sessionId连接会话 ID一次建连一个；多端并存时多个
connectedAt建连时间毫秒时间戳
lastHeartbeatAt最近心跳客户端 30s ping；服务端 60s 未收 pong 判定失活
device设备标识当前恒为空字符串（客户端未上报）
  • connections/stats 返回 onlineUsers（去重用户）、sessions（会话数）、peakToday（当日峰值）。
  • 连接是内存态，进程重启即断开并重建；历史断线原因不保留。
  • 强制下线通过封禁/Token reset 等动作触发，不是独立的踢人接口。

前置条件​

  • 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#connections（tab #connections：连接监控）。
  • 请求头 X-Admin-Secret 与服务端 IM_ADMIN_SECRET 一致（本地默认 dev-admin）。
  • 已在控制台选中应用；带 {appkey} 的接口都按应用隔离。
  • 自托管版无购买、计费、套餐、续费与发票流程（不适用项）；本页只覆盖配置、查询与治理接口。

步骤​

  1. 确认接收方是否在线

    按 userId 过滤连接；无结果说明当前没有 WS 会话。

  2. 核对心跳与会话数
    lastHeartbeatAt 停滞可能是弱网/挂起；多会话说明多端在线。
  3. 与统计对照

    用 connections/stats 判断是个体问题还是大面积掉线（配合告警 online_drop）。

  4. 处置

    封禁/注销会踢下线；Token reset 会让旧连接收到 kick(1002) 并断开。

参数表​

操作方法与路径参数
连接列表GET /api/admin/apps/{appkey}/connectionsuserId（可选）
连接统计GET /api/admin/apps/{appkey}/connections/stats—

示例​

查单个用户与全量在线​

Shell
curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/connections?userId=alice" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/connections/stats" \
  -H 'X-Admin-Secret: dev-admin'

常见问题​

为什么 device 都是空？​

客户端当前没有上报设备标识；字段保留但恒为空字符串，不能据此判断机型。

连接数为什么大于用户数？​

多端登录会产生多个 sessionId；onlineUsers 才是去重用户数。

能看到历史断线原因吗？​

不能。只保留当前会话；断线原因需结合客户端日志与告警事件。

踢下线有独立接口吗？​

没有。通过封禁、注销、Token reset 等业务动作触发 kick。

相关链接​