IM 在线统计

1. 接口定位

• 接口名称: IM 在线统计
• 所属域: admin/statistic
• 业务目标: 获取当前 IM 在线用户数、在线设备数及平台分布

2. 请求定义

• Method: POST
• Path: /adminx/statistic/im_online_count
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 幂等

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	管理员 token

Body 参数

该接口无需业务参数，建议传空对象：

{}

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	object	业务数据

data 字段

字段	类型	说明
onlineUserCount	int64	当前在线用户数（按 userID 去重）
onlineDeviceCount	int64	当前在线设备数（按 userID+platform）
platformCount	map<string, int64>	按平台聚合的当前在线用户数

5. 业务规则

• chat 回调接收 callbackAfterUserOnlineCommand/callbackAfterUserOfflineCommand 后，会通过 admin 统计链路更新在线状态。
• 统计查询由统计 RPC 从 Redis 实时读取并返回。
• platformCount 的 key 为平台名称，value 为该平台在线用户数；值为 0 的平台不会出现在返回 map 中。

6. 错误码与失败场景

错误码	场景	典型报错
-	Redis 客户端未初始化	adminx redis client is nil
-	查询在线集合失败	由 Redis 客户端返回

7. 示例

fetch 请求示例

fetch("http://localhost:10011/adminx/statistic/im_online_count", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440206",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "onlineUserCount": 128,
    "onlineDeviceCount": 176,
    "platformCount": {
      "iOS": 48,
      "Android": 62,
      "Windows": 18
    }
  }
}

8. 时序流程

1. 中间件校验管理员 token。
2. API 层转发到统计 RPC GetIMOnlineCount。
3. RPC 从 Redis 读取在线用户集合、在线设备集合与平台集合。
4. 组装统计结果并返回。

9. 变更记录

• 2026-04-07: 首版发布，新增 IM 在线统计接口文档。