子账号与 RBAC

子账号用于把控制台访问拆给多人：创建 accountId 并分配 owner/admin/operator/viewer 角色，鉴权使用 X-Admin-Account + X-Admin-Token。根凭据 X-Admin-Secret 仍可全量读写，且不出现在账号列表中。

概念​

角色能力约束
owner全部权限，含创建/变更 owner不可停用/降级最后一个启用中的 owner
admin管理应用与运营对象、管理低阶账号不能改 owner 账号
operator日常运营写操作不能管理账号与高危配置（由能力矩阵约束）
viewer只读写接口返回 403 / 1003
  • 账号上限 200；Token 只在创建与 rotateToken=true 时返回一次，服务端只存 SHA-256 摘要。
  • Token 轮换后旧 Token 立即失效；删除账号需 role ≥ admin，owner 账号仅 owner 可删。
  • 角色变更受层级约束：admin 不能修改 owner；owner 角色变更需 owner 操作。
  • 控制台把账号与 Token 保存在本机会话中；不要把 Token 写进前端代码或仓库。

前置条件​

  • 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#accounts（tab #accounts：成员与权限）。
  • 请求头 X-Admin-Secret 与服务端 IM_ADMIN_SECRET 一致（本地默认 dev-admin）。
  • 已在控制台选中应用；带 {appkey} 的接口都按应用隔离。
  • 自托管版无购买、计费、套餐、续费与发票流程（不适用项）；本页只覆盖配置、查询与治理接口。
  • 建议先创建一个备用 owner，避免唯一 owner 丢失导致无法管理账号。

步骤​

  1. 创建子账号

    提交 {accountId,name?,role}；响应中的 token 仅本次可见，立即交付给使用者。

  2. 分配最小角色

    只读同学给 viewer；日常运营给 operator；需要改配置/账号再给 admin。

  3. 轮换或停用

    怀疑泄露时 rotateToken=true；离职立即 disabled=true 或删除。

  4. 验证权限

    用 X-Admin-Account + X-Admin-Token 调一个写接口；viewer 应返回 403/1003。

参数表​

操作方法与路径请求体 / 参数
账号列表GET /api/admin/accounts—（不含 Token 摘要）
创建账号POST /api/admin/accounts{accountId,name?,role}
更新账号POST /api/admin/accounts/{accountId}{name?,role?,disabled?,rotateToken?}
删除账号DELETE /api/admin/accounts/{accountId}—
子账号鉴权所有 /api/admin/** 请求X-Admin-Account + X-Admin-Token

示例​

创建 viewer → 用子账号只读 → 轮换 Token​

Shell
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-li","name":"李运营","role":"viewer"}'

# 用返回的 token（仅本次可见）
curl -sS "http://127.0.0.1:8080/api/admin/apps" \
  -H 'X-Admin-Account: ops-li' \
  -H 'X-Admin-Token: <token>'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/accounts/ops-li" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"rotateToken":true}'

curl -sS -X DELETE "http://127.0.0.1:8080/api/admin/accounts/ops-li" \
  -H 'X-Admin-Secret: dev-admin'

常见问题​

Token 丢了怎么办？​

无法找回，只能 rotateToken=true 重新签发；旧 Token 立即失效。

为什么 viewer 也能看到应用列表？​

viewer 是只读角色，读接口允许；写接口返回 403/1003。

可以删除最后一个 owner 吗？​

不可以。服务端拒绝停用/降级/删除最后一个启用中的 owner，避免失去管理入口。

根密钥还要保留吗？​

建议保留在密钥管理系统作为应急入口，但日常操作使用子账号以便审计到人。

相关链接​