控制台任务手册

控制台模块按“对象”组织（应用、用户、群组、聊天室、推送、回调、审核、统计…），而日常工作是按“任务”组织的。本页把常见任务拆成可执行步骤，并给出每一步对应的控制台页面与管理接口，便于交接与自动化。

使用前提

管理接口前缀 /api/admin，请求头 X-Admin-Secret（本地默认 dev-admin，生产必须替换）；子账号使用 X-Admin-Account + X-Admin-Token。

响应统一为 { code, data } / { code, msg }；code=0 成功。

控制台页面入口：服务端根路径下的 /console/。

任务 → 模块 → 接口对照​

任务控制台页面主要管理接口
创建/配置应用、重置密钥应用与密钥POST /apps、POST /apps/{appkey}/secret/reset
注册用户、签发 Token、封禁/禁言用户管理 · 封禁用户POST /apps/{appkey}/users、POST /apps/{appkey}/users/{userId}/ban
群组资料、成员、禁言、解散群组管理GET /apps/{appkey}/groups、POST /apps/{appkey}/groups/{groupId}/dismiss
聊天室在线、禁言、销毁聊天室管理POST /apps/{appkey}/chatrooms/{chatroomId}/destroy
消息追踪与导出消息追踪 · 数据导出GET /apps/{appkey}/messages、GET /apps/{appkey}/messages/export
连接与在线排查连接明细GET /apps/{appkey}/connections、GET /apps/{appkey}/connections/stats
回调配置、投递日志与重试回调服务POST /apps/{appkey}/callbacks/config、GET /apps/{appkey}/callbacks/deliveries
敏感词与内容审核敏感词 · 内容审核POST /apps/{appkey}/sensitive-words、POST /apps/{appkey}/moderation/tasks/{taskId}/decide
统计与趋势统计维度GET /apps/{appkey}/stats/dimensions
限频与配额接口调频 · 配额POST /apps/{appkey}/ratelimit
操作审计操作日志GET /apps/{appkey}/audit
子账号与权限子账号与 RBACPOST /accounts、POST /accounts/{accountId}

任务一：新应用接入到第一条消息​

  1. 创建应用并保存 AppSecret

    控制台「应用与密钥」创建应用，或调用 POST /api/admin/apps。响应里的 appSecret 只返回这一次，立即写入密钥管理系统。

    验证：GET /api/admin/apps/{appkey} 能读到应用信息（不返回 secret 明文）。

  2. 注册测试用户并签发 Token

    管理端注册用户（POST /api/admin/apps/{appkey}/users），或由业务后端在登录流程里注册。

    服务端用签名调用 POST /im/v2/user/token/issue 签发用户 Token（7 天有效），返回给客户端。

  3. 客户端建连并收发第一条消息

    按 Quick Start 初始化 SDK、connect、发送文本消息，并在另一端确认收到。

    在「连接明细」确认两个用户的会话数；在「消息追踪」按 userId 查消息记录。

  4. 配置回调与验证签名

    控制台「回调服务」或 POST /apps/{appkey}/callbacks/config 配置回调地址与密钥。

    用「回调服务 → 测试」发一条测试事件，确认接收端验签通过、eventId 幂等生效。

    投递失败可在「投递日志」查看并按 POST /apps/{appkey}/callbacks/deliveries/{deliveryId}/retry 重试。

  5. 设置限频与配额，准备上线

    按上线检查清单逐项确认；为高流量接口设置接口级 QPS 覆盖，避免被整体限频误伤。

任务二：排查“收不到消息”​

按“连接 → 消息投递 → 客户端渲染”的顺序排查，每一步都能在控制台看到证据。

顺序检查项控制台位置判定
1用户是否在线连接明细无在线会话 ⇒ 消息走离线补发（依赖再次上线）
2是否被封禁/禁言封禁用户封禁期间不能建连；禁言只影响发送
3消息是否入库消息追踪按 userId/会话/时间查；无记录 ⇒ 发送端失败或未发送
4是否被审核拦截内容审核blocked 消息有阻塞标记与原因
5是否在聊天室聊天室管理聊天室消息不持久化、不补发
6客户端是否去重/排序错误客户端日志收到但未渲染 ⇒ 去重集合或 seq 排序问题

任务三：内容安全处置​

  1. 在「敏感词」配置词条与处置动作（block/replace），或调用 POST /apps/{appkey}/sensitive-words；批量导入用 sensitiveword.batch.add。
  2. 命中后消息被拦截（1010）或掩码；审核模式下生成审核任务，在「内容审核」逐条裁决：POST /apps/{appkey}/moderation/tasks/{taskId}/decide（approve/reject）。
  3. reject 会把消息标记为 blocked 并通知发送者；需要留证时导出审核记录。
  4. 对反复违规用户执行封禁（POST /apps/{appkey}/users/{userId}/ban），并在「操作日志」确认动作已记录。

任务四：容量与性能巡检​

指标位置关注点
用户/群/消息/在线总量与趋势统计维度聊天室消息为 ephemeral，统计返回 0 属预期
连接数与会话数连接明细在线会话突增/突降通常对应故障或发版
推送投递结果推送统计sent 恒为 0 表示无厂商通道投递能力
限频命中接口调频429/1008 比例升高说明需要扩容或合并请求
告警规则监控与告警阈值告警 webhook 是否可达

常用管理接口速查​

Shell
# 1) 应用与密钥
curl -sS http://127.0.0.1:8080/api/admin/apps -H 'X-Admin-Secret: dev-admin'
curl -sS -X POST http://127.0.0.1:8080/api/admin/apps/demo/secret/reset -H 'X-Admin-Secret: dev-admin'

# 2) 用户：注册 / 签发 Token / 封禁
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":"spam"}'

# 3) 消息与连接排查
curl -sS 'http://127.0.0.1:8080/api/admin/apps/demo/messages?userId=alice&limit=20' -H 'X-Admin-Secret: dev-admin'
curl -sS 'http://127.0.0.1:8080/api/admin/apps/demo/connections?userId=alice' -H 'X-Admin-Secret: dev-admin'

# 4) 回调投递日志与重试
curl -sS 'http://127.0.0.1:8080/api/admin/apps/demo/callbacks/deliveries?status=failed' -H 'X-Admin-Secret: dev-admin'
curl -sS -X POST http://127.0.0.1:8080/api/admin/apps/demo/callbacks/deliveries/1/retry -H 'X-Admin-Secret: dev-admin'

# 5) 审计日志
curl -sS 'http://127.0.0.1:8080/api/admin/apps/demo/audit?action=apps.secret.reset&limit=20' -H 'X-Admin-Secret: dev-admin'

相关链接​