权限模型与危险操作

控制台的权限是“RBAC-lite”：根凭据拥有 owner 权限，子账号分四档（owner > admin > operator > viewer）。本页说明每档能做什么、哪些操作不可逆、以及如何用审计日志追溯。

四档角色​

角色读取（GET）写入（POST 业务配置）特权（账号/密钥）典型用途
owner✅✅✅负责人：可管理子账号、重置密钥、删除应用
admin✅✅✅（不能改 owner 账号）运维主管：日常配置与应急处置
operator✅✅❌客服/运营：封禁、禁言、解散群、审核裁决
viewer✅❌❌只读：值班观察、数据核对

判定规则：读取接口任意角色可用；写入接口要求 operator 及以上；账号管理与密钥重置要求 admin 及以上；涉及 owner 账号本身的变更要求调用者为 owner。角色不足返回 403。

子账号管理​

操作接口约束
创建子账号POST /accounts字段 {accountId,name?,role}；创建 owner 需调用者自身为 owner；上限 200 个账号
更新/停用/轮换 tokenPOST /accounts/{accountId}rotateToken=true 立即失效旧 token；不可停用/降级最后一个启用中的 owner
列出账号GET /accounts只返回账号元数据，不返回 token
删除账号DELETE /accounts/{accountId}同样受 owner 保护规则约束
鉴权头—X-Admin-Account + X-Admin-Token；根凭据继续用 X-Admin-Secret
Shell
# 创建 operator 子账号（token 只在本次响应返回）
curl -sS -X POST http://127.0.0.1:8080/api/admin/accounts -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"accountId":"ops-1","name":"值班运营","role":"operator"}'

# 用子账号调用（只读接口）
curl -sS http://127.0.0.1:8080/api/admin/apps/demo/audit -H 'X-Admin-Account: ops-1' -H 'X-Admin-Token: <本次返回的 token>'

# 轮换子账号 token（旧 token 立即失效）
curl -sS -X POST http://127.0.0.1:8080/api/admin/accounts/ops-1 -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' -d '{"rotateToken":true}'

危险操作清单​

下面这些操作影响面大且多数不可逆，执行前必须确认影响范围、通知相关方，并在执行后核对审计日志。

操作接口 / 页面后果要求
重置 AppSecretPOST /apps/{appkey}/secret/reset · 应用与密钥旧签名立即失效，所有使用旧密钥的 Open API 调用返回 1018；不可回滚admin+；需密钥管理系统配合
删除应用DELETE /apps/{appkey}软删除：数据保留、默认列表隐藏，可恢复admin+
恢复应用POST /apps/{appkey}/restore恢复被软删的应用admin+
封禁用户POST /apps/{appkey}/users/{userId}/ban立即踢下线，封禁期间不能建连（1016）operator+
禁言用户POST /apps/{appkey}/users/{userId}/mute仅限制发送（1009），不影响接收operator+
解散群POST /apps/{appkey}/groups/{groupId}/dismiss移除群与群级附属状态，消息历史保留供审计，触发 group.destroyedoperator+
销毁聊天室POST /apps/{appkey}/chatrooms/{chatroomId}/destroy踢出在线成员并广播销毁，不可恢复operator+
清理历史消息POST /im/v2/message/history/clean（Open API）服务端历史与补发被清理，客户端本地库不受影响应用签名
更新回调配置POST /apps/{appkey}/callbacks/config密钥/地址变更立即生效，旧密钥签名验不过operator+
设置敏感词与拦截动作POST /apps/{appkey}/sensitive-words立即影响发送（1010/掩码），批量导入需谨慎operator+
设置接口限频POST /apps/{appkey}/ratelimit过低的 QPS 会导致业务 429/1008operator+
管理子账号/accounts/** · 子账号与 RBAC权限变更/停用/token 轮换立即生效admin+/owner（涉 owner）

审计与追溯​

管理端写操作会写入操作日志（环形上限 5000 条）：actor、action、object、result、timestamp。按应用查询：GET /api/admin/apps/{appkey}/audit?actor=&action=&object=&from=&to=&offset=&limit=，时间倒序。

Shell
# 查最近的重置密钥与封禁动作
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'
curl -sS 'http://127.0.0.1:8080/api/admin/apps/demo/audit?action=users.ban&from=1750000000000&limit=50' -H 'X-Admin-Secret: dev-admin'
审计不等于回滚

操作日志只记录“谁在什么时候做了什么”，不保存被覆盖前的配置快照。

危险操作前请先导出当前配置（例如回调配置、敏感词表、限频规则），或记录在变更单里。

环形上限 5000 条：高频写入会滚动覆盖旧记录，需要长期留存请定期导出。

最小权限落地建议​

  • 值班/观察：只给 viewer；需要处置时临时提升或使用专门的 operator 账号。
  • 日常运营：operator；不要给 admin（避免误重置密钥）。
  • 密钥与账号管理：admin 只给 1-2 人，owner 仅在需要转让/删除时使用。
  • 子账号 token 与根密钥分别存放在不同的密钥管理系统条目，轮换互不影响。
  • 每次危险操作后核对审计日志（actor/action/object/result）并记录变更单编号。

相关链接​