运营后台指南

运营后台（/admin/）面向平台运营角色，提供跨应用的用户、聊天室、消息审计、回调推送与运营看板。页面下半部分为由 Admin API 契约生成的参考。

应用总览​

展示应用数、用户数、消息量、在线峰值；点击应用行查看详情与实时统计。

用户管理​

• 查询用户资料与在线状态；
• 封禁/解封用户；
• 查看用户标签与所属群组。

聊天室治理​

• 查看在线聊天室与成员；
• 封禁聊天室成员、踢出成员；
• 销毁违规聊天室（仅运营角色）。

消息审计​

按应用、用户、会话、关键字与时间检索消息；支持导出审计结果。

回调与推送通道​

配置离线推送 Webhook 与通用回调，查看投递日志与失败重试；支持按事件类型开启/关闭。

运营看板​

消息量、DAU、在线峰值趋势图；数据源为 Admin API 统计接口。

Admin API 参考​

共 85 个管理接口，全部由 IDL 中的 operationId / method / path / 参数 / 响应 schema 生成；接口清单与实现零漂移。基础路径为 /api/admin。

GET /api/admin/apps​

应用列表（含用户/消息/在线统计）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps​

创建应用，返回 appkey/appSecret（仅本次返回 secret）。

GET /api/admin/apps/{appkey}​

应用详情（secret 脱敏）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/secret/reset​

重置 AppSecret（旧签名立即失效）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/users​

用户列表（含在线状态/封禁），?keyword&offset&limit。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/users​

注册测试用户（幂等）。

POST /api/admin/apps/{appkey}/users/{userId}/token​

为测试用户签发 token（控制台复制用）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/users/{userId}/ban​

封禁/解封用户。

GET /api/admin/apps/{appkey}/users/{userId}​

用户详情（在线/封禁/禁言/token 版本）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/users/{userId}/mute​

全应用禁言/解禁用户（mutedUntil=0 解禁；与群禁言独立）。

POST /api/admin/apps/{appkey}/users/{userId}/token/reset​

吊销并重置用户 token 版本（旧 JWT 立即失效）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/metrics/overview​

应用运营指标概览：DAU/消息量/在线峰值/错误率（今日+近 7 天）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/groups​

群/超级群列表（?keyword&offset&limit）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/chatrooms​

聊天室列表（在线数/存活状态）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/messages​

消息查询：?userId&conversationType&targetId&keyword&from&to&offset&limit。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/messages/{messageId}/trace​

消息投递轨迹。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/messages​

以系统/指定用户身份发消息（控制台调试）。

GET /api/admin/apps/{appkey}/connections​

在线连接明细：userId/sessionId/connectedAt/lastHeartbeat/device。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/connections/stats​

在线用户数/会话数/峰值。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/services​

服务开通项与配额。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/services​

更新服务开通项/配额。

GET /api/admin/apps/{appkey}/callbacks​

回调配置（secret 脱敏）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/callbacks​

设置回调配置。

GET /api/admin/apps/{appkey}/callbacks/deliveries​

回调投递日志（?eventType&status&from&to&offset&limit）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/callbacks/deliveries/{deliveryId}/retry​

手动重试投递。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/push​

离线推送通道配置。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/push​

设置离线推送 webhook。

GET /api/admin/apps/{appkey}/sensitive-words​

敏感词配置。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/sensitive-words​

设置敏感词与处置动作。

GET /api/admin/stats​

全局统计。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/stats/trend​

运营趋势（按天，?days&appkey）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/api-metadata​

API 调试器元数据：可选接口列表（operationId/method/path/params），由服务端从 Open API IDL 派生。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/callbacks/test​

发送回调测试事件（按当前回调配置投递一次，返回投递结果；用于控制台“测试回调”）。

POST /api/admin/apps/{appkey}/users/batch​

批量注册用户（上限 100，逐条幂等；返回 created 与 failed 明细）。

GET /api/admin/apps/{appkey}/messages/export​

导出消息为 CSV（查询参数 limit 默认 1000、beforeSeq 可选；返回 csv 文本供控制台下载）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/chatrooms/{chatroomId}/destroy​

销毁聊天室：踢出在线成员、广播 destroyed、回调 chatroom.destroyed；body {reason?}（默认 admin_destroy）。不存在 1012 / 已销毁 1013。

POST /api/admin/apps/{appkey}/chatrooms/{chatroomId}/mute-all​

聊天室全体禁言/解除：{muted, durationSec?}；durationSec 1..=2592000（30 天），省略=持续禁言；muted=false 立即解除。与 Open API chatroom.mute-all 同源状态。

GET /api/admin/apps/{appkey}/audit​

操作日志查询（按应用；时间倒序）：?actor&action&object&from&to&offset&limit。记录管理端写操作（actor=admin、action、object、result、timestamp），环形上限 5000 条。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/features​

功能开关：friend/group/chatroom/push/sensitiveWord/messageCallbacks；mapping 字段说明各自映射到的既有数据源（ServiceActivation.services / app.pushEnabled）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/features​

更新功能开关（未传的开关保持原值）：body {features:{friend?,group?,chatroom?,push?,sensitiveWord?,messageCallbacks?}}；写穿到既有 services/push 配置，不新建第二份状态。

GET /api/admin/apps/{appkey}/ratelimit​

Open API 接口级调频配置（per operation QPS override；默认空=关闭不限频）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/ratelimit​

设置 Open API 接口级 QPS 覆盖：body {overrides:{operationId:qps}}（1..=10000，0/省略=该接口不限频，整体覆盖）。超限返回 HTTP 429 + code 1008 + Retry-After: 1，envelope 保留。

POST /api/admin/apps/{appkey}/push/test​

推送测试：{userId,title?,body?} 按当前推送配置真实投递一次 webhook 并返回投递尝试结果；推送未启用/webhook 为空返回 1021 SERVICE_NOT_ACTIVATED（不伪造成功）。

DELETE /api/admin/apps/{appkey}​

删除应用（软删除：保留用户/消息/配置，仅置生命周期 deleted + app.disabled）：body {confirmAppkey, reason?}，confirmAppkey 必须等于路径 appkey（二次确认，否则 1001）。删除后 Open API 与 WS 鉴权返回 1017 APP_DISABLED；admin.apps.list 默认隐藏，?includeDeleted=1 可见（带 deleted/deletedAt）。

POST /api/admin/apps/{appkey}/restore​

恢复已删除应用：清除 deleted 标记并解除 app.disabled（1017 立即消失）；数据原样保留。未删除应用返回 1001。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/accounts​

管理端子账号列表（accountId/name/role/disabled/createdAt/updatedAt/lastUsedAt；token 仅存 SHA-256 摘要，永不返回）。根凭据 X-Admin-Secret 不在此表内。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/accounts​

创建子账号 {accountId,name?,role}（role ∈ owner|admin|operator|viewer；创建 owner 需调用者自身为 owner）。响应 token 仅本次返回一次，后续鉴权用 X-Admin-Account + X-Admin-Token。上限 200 个账号。

POST /api/admin/accounts/{accountId}​

更新子账号 {name?,role?,disabled?,rotateToken?}：role 变更受层级约束（admin 不能改 owner 账号，owner 角色变更需 owner）；rotateToken=true 生成新 token 并在本次响应返回（旧 token 立即失效）；不可停用/降级最后一个启用中的 owner。

DELETE /api/admin/accounts/{accountId}​

删除子账号：需 role ≥ admin；owner 账号仅 owner 可删；不允许删除最后一个启用中的 owner。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/moderation/tasks​

内容审核任务列表（消息命中敏感词时由发送路径自动生成）：?status=pending|approved|rejected|all&offset&limit。任务环形上限 2000；字段含 messageId（replace 模式）/text/matchedWords/action/status/createdAt/decided*。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/moderation/tasks/{taskId}/decide​

审核决策 {decision:approve|reject, reason?}：approve 保留消息（replace 模式保留掩码正文）；reject 把已入库消息正文打上 moderation=blocked 标记并向发送者发送 message.blocked 系统通知（system_notification）。任务已决策返回 1001。

GET /api/admin/apps/{appkey}/alerts/rules​

告警规则与支持的指标：metric ∈ rate_limited|callback_failure|online_drop|error_5xx；字段 threshold/windowSec/webhookUrl/enabled。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/alerts/rules​

整体覆盖告警规则：body {rules:[{metric,threshold,windowSec,webhookUrl,enabled}]}（≤20 条，windowSec 1..=86400，同一 metric 后者覆盖前者）。评估在维护周期（IM_MAINTENANCE_MS，默认 5s）执行，触发后写事件并按 HMAC-SHA256 的 X-IM-Signature 投递 webhook（best-effort，1 次重试）。

GET /api/admin/apps/{appkey}/alerts/events​

告警事件（环形上限 1000，按时间倒序）：?metric&offset&limit；同时返回 counters（rate_limited/callback_failure/error_5xx 最近 300s 计数、online 当前值、online_drop 300s 回落）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/groups/{groupId}​

群详情（K09）：成员预览/管理员/禁言/全员禁言/扩展属性/群消息计数；群不存在 1012。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/groups/{groupId}/members​

群成员分页（K09）：?keyword&offset&limit，字段 userId/name/role/online/muted/mutedUntil/testUser；排序 owner→admin→member。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/groups/{groupId}/members/{userId}/mute​

群成员禁言/解禁（K09）：body {muted,durationSec?,reason?}；durationSec 1..=2592000（缺省 3600）；写入既有 Group.muted，群消息发送路径真实返回 1009；群主不可被禁言。

POST /api/admin/apps/{appkey}/groups/{groupId}/members/{userId}/remove​

踢出群成员（K09）：body {reason?}；群主需先转让（否则 4xx）；同步清理管理员/禁言/成员资料，回调 group.updated（members_removed）。

POST /api/admin/apps/{appkey}/groups/{groupId}/mute-all​

群全员禁言开关（K09）：body {muted,durationSec?}（durationSec 1..=2592000，缺省永久）；与 Open API group.mute-all 同一份 group_mute_all 状态，群主/管理员/白名单豁免。

POST /api/admin/apps/{appkey}/groups/{groupId}/dismiss​

解散群（K09）：body {reason?}；移除群与群级附属状态（禁言/白名单/成员资料/频道/扩展），消息历史保留供审计，回调 group.destroyed。

POST /api/admin/apps/{appkey}/groups/{groupId}/transfer​

转让群主（K09）：body {toUserId}；新群主必须是成员，旧群主保留为管理员，回调 group.updated（owner_transferred）。

POST /api/admin/apps/{appkey}/groups/{groupId}/profile​

群资料编辑（K09）：body {name?,notice?,joinPolicy?,ext?}；name 1..=64 字符、notice ≤1000、joinPolicy ∈ invite|open、ext ≤20 键（键 ≤32 / 值 ≤256）。

GET /api/admin/apps/{appkey}/bans​

封禁用户视图（K10）：?status=active|history|all&keyword&offset&limit；返回封禁名单（原因/时长/操作者/到期）、注销用户视图、封禁历史（环形 2000）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/bans​

封禁/解封/注销/恢复（K10）：body {userId,action:ban|unban|deactivate|restore,reason?,durationSec?,operator?}；写 User.banned / User.deactivated 并踢下线，durationSec 由维护周期到期自动解除，全程写审计。

GET /api/admin/apps/{appkey}/test-users​

测试用户列表（K13）：?keyword&offset&limit；返回已标记用户与配额（limitConfigured/limitDefault=100/limitMax/usage）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/users/{userId}/test-user​

标记/取消测试用户（K13）：body {testUser}；超过配置上限返回 4xx（1001），用户不存在 1004。

POST /api/admin/apps/{appkey}/test-users/limit​

设置测试用户上限（K13）：body {limit}（1..=100000，默认 100）；返回 usage/remaining。

GET /api/admin/apps/{appkey}/stats/dimensions​

统计维度扩展（K14）：?days（1..=90，默认 7）；返回用户/群组/群消息/聊天室/聊天室消息/消息/在线总量与按天趋势；聊天室消息为 ephemeral 不落盘，如实返回 0 并在 notes 标注。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/push/channels​

推送通道配置（K21）：APNs/FCM/华为/小米/OPPO/vivo；敏感字段（privateKey/serviceAccountJson/appSecret/masterSecret）脱敏，另返回 secretsSet/configured/missingFields；deliveryImplemented=false。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/push/channels​

按通道保存推送配置（K21）：body {channel,enabled,fields}；未知通道/未知字段/启用但缺必填 → 4xx；敏感字段传 **** 开头表示保持原值。仅存储，不包含厂商发送。

POST /api/admin/apps/{appkey}/push/channels/{channel}/test​

通道测试（K21）：诚实返回 {configured,enabled,missingFields,implemented:false,delivered:false,reason}；不伪造发送成功；离线推送测试仍用 POST /apps/{appkey}/push/test。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/push/stats​

推送统计（K22）：?date&days；按 push_logs 真实投递计数聚合 sent/delivered/failed 与按天趋势；无厂商通道级拆分（channelStatsAvailable=false）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/translation​

翻译配置（K24）：provider/sourceLang/targetLangs/endpoint/开关；返回 configured（以 IM_TRANSLATE_ENDPOINT 为准）、runtimeSource、mockDeprecated=true。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/translation​

保存翻译配置（K24）：body {enabled,provider:none|http,sourceLang?,targetLangs?,endpoint?}；provider=mock 已弃用（4xx）；enabled 需 provider=http 且端点或环境变量存在；仅存储 + 校验，运行时仍读环境变量。

GET /api/admin/apps/{appkey}/bots​

机器人列表（K24）：?offset&limit；bot 账号与回调配置合并视图（secretMasked/secretSet/callbackUrl/events/enabled/lastDelivery），并返回支持的事件枚举。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/bots​

创建机器人（K24）：body {botId,name,avatarUrl?,description?,callbackUrl?,events?,secret?,enabled?}；callbackUrl 须 http(s)，events ∈ BOT_EVENTS，secret 8..=128 字符（缺省生成）；重复 botId 返回 4xx。

POST /api/admin/apps/{appkey}/bots/{botId}​

更新机器人（K24）：body {name?,avatarUrl?,description?,callbackUrl?,events?,secret?,enabled?}；callbackUrl 为空串移除回调配置，非空且无配置时创建；机器人不存在 1004。

DELETE /api/admin/apps/{appkey}/bots/{botId}​

删除机器人（K24）：移除 bot 账号与回调配置；不存在返回 1004（不静默成功）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/embed/token​

签发一次性控制台嵌入令牌（K29）：body {scopes?,ttlSec?}；scopes ⊆ overview|stats|users|groups（缺省 overview+stats），ttlSec 30..=86400（缺省 900）；返回 token/expiresAt/embedUrl；兑换用公开 GET /api/embed/session?token=，一次性 + 过期即失效，失败 401。

GET /api/admin/apps/{appkey}/push/tokens​

设备 token 台账（C23/K21）：?userId&platform&active&offset&limit；platform ∈ ios|android|web|huawei|xiaomi|oppo|vivo|fcm，active 仅 true|false|1|0；返回 tokens/total/hasMore/perUserLimit（服务端状态，重启后仍在）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

DELETE /api/admin/apps/{appkey}/push/tokens/{tokenId}​

管理端注销设备 token（C23）：软删除 active=false 并写审计；不存在 404/1001（不静默成功）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/push/deliveries​

创建投递尝试记录（M14）：body {userIds|userId,title,body,extras?}（≤100 用户；title 1..=128、body 1..=2048、extras ≤4096 bytes）；每用户一条记录。无厂商凭据/适配器 → status=no_token（无活跃 token）或 not_configured（有 token 但适配器未配置），不发起网络请求、不伪造 sent。

GET /api/admin/apps/{appkey}/push/deliveries​

投递记录分页（M14）：?userId&status&offset&limit；status ∈ no_token|not_configured|queued|sent|failed；按 createdAt 倒序，附 counts 与 retryableStatuses（failed|not_configured）。

该接口无请求体参数（查询参数按路径与分页约定传递）。

GET /api/admin/apps/{appkey}/push/deliveries/{deliveryId}​

单条投递记录（M14）：含 attemptLog（每次尝试的 status/provider/error/at）；不存在 404/1001。

该接口无请求体参数（查询参数按路径与分页约定传递）。

POST /api/admin/apps/{appkey}/push/deliveries/{deliveryId}/retry​

重试投递（M14）：仅 failed|not_configured 可重试；生成新记录（新 deliveryId）、attempts+1、retryOf 指向旧记录；重新选择当前活跃 token（可能变为 no_token），仍不伪造 sent；其它状态返回 4xx/1001。

该接口无请求体参数（查询参数按路径与分页约定传递）。