用户管理

控制台的用户管理面向联调与运营处置：注册测试用户、查看在线会话数、签发 Token 给客户端、对违规用户封禁或禁言。用户数据按 appkey 隔离。

概念​

  • Token 为 JWT，有效期 7 天；同一用户重复签发得到不同 token，旧 token 在过期前仍有效（除非 token/reset）。
  • token/reset 递增 tokenVersion，旧 JWT 立即失效，并向该用户在线连接推送 kick（code=1002）。
  • 封禁（banned=true）会踢掉在线连接（code=1016），且签发 Token 返回 403。
  • 禁言（mutedUntil，epoch 毫秒，0=解除）只影响发送，连接保持；发送返回 1009。

前置条件​

  • 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#users。
  • 已设置 X-Admin-Secret（默认 dev-admin；控制台会保存在浏览器 localStorage 的 im.admin.secret）。
  • 已创建应用并在控制台顶部选中应用（模块接口路径都带 {appkey}）。
  • 用户 ID 1-64 字符；批量导入单次上限 100。

步骤​

  1. 注册用户

    幂等：已存在则返回现有用户，不覆盖昵称（更新资料请用 Open API user.update）。

  2. 签发 Token

    把返回的 data.token 交给客户端 connect(token)；客户端不需要 AppSecret。

  3. 封禁 / 解封

    封禁立即踢下线；解封后需重新签发 Token 或等待客户端重连（旧 Token 仍有效，除非同时 reset）。

  4. 禁言 / 解除
    mutedUntil 用毫秒时间戳；传 0 解除。禁言不影响收发历史与在线状态。
  5. 批量导入
    users/batch 逐条幂等注册，返回每条结果。

参数表​

操作方法与路径请求体 / 参数
用户列表GET /api/admin/apps/{appkey}/userskeyword、offset、limit（≤500）
注册用户POST /api/admin/apps/{appkey}/users{userId,name?,avatarUrl?}
用户详情GET /api/admin/apps/{appkey}/users/{user_id}—（含 online/sessionCount/banned/mutedUntil/tokenVersion）
签发 TokenPOST /api/admin/apps/{appkey}/users/{user_id}/token—
吊销 TokenPOST /api/admin/apps/{appkey}/users/{user_id}/token/reset—
禁言POST /api/admin/apps/{appkey}/users/{user_id}/mute{mutedUntil}
封禁POST /api/admin/apps/{appkey}/users/{user_id}/ban{banned,reason?}
批量注册POST /api/admin/apps/{appkey}/users/batch{users:[{userId,name?,avatarUrl?}]}（≤100）

示例​

注册 → 签发 Token → 封禁 → 解封​

Shell
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/users" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"userId":"alice","name":"Alice"}'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/users/alice/token" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/users/alice/ban" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"banned":true,"reason":"abuse"}'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/users/alice/ban" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"banned":false}'

禁言 10 分钟后解除​

mutedUntil 是绝对时间戳（毫秒），示例值请按当前时间 + 600000 计算。

Shell
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/users/alice/mute" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"mutedUntil":1750000600000}'

# 解除
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/users/alice/mute" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"mutedUntil":0}'

常见问题​

封禁后客户端一直重连？​

服务端在封禁时发送 kick（code=1016）并关闭连接；SDK 收到 kick 后停止重连。若客户端仍重连，检查是否用了旧 SDK 或自定义重连逻辑。

签发的 Token 有效期多久？​

7 天（TOKEN_TTL_MS）；过期后建连返回 1002，需要重新签发。

禁言用户还能调用 Open API 发消息吗？​

会返回 1009（被禁言），与客户端发送同一校验。

相关链接​