跳到主要内容

角色与自定义角色

每个组织成员都持有一个角色，该角色决定其可以在 AISIX Cloud 控制面和 AISIX Cloud Admin API 中执行的操作。三个内置角色覆盖常见场景；需要更细粒度控制的组织可以定义自定义角色，即基于 API 所执行的同一组资源术语定义的命名权限集合。

角色管理的是控制面（谁可以配置网关）。API Key 可以发送哪些流量（模型、工具和预算）由 API Key 自身的设置决定，而不是由成员角色决定。

内置角色​

角色访问权限
owner完全控制，包括账单、成员角色变更、移除成员和管理 Admin Token。
admin对所有资源具有读写权限，但不能执行仅 owner 可执行的操作，例如变更角色、移除成员和创建 Admin Token。
member对组织资源具有只读权限，不能读取审计事件。

Roles 页面会列出每个角色实际执行的精确权限。该页面展示的权限目录与 API 每次请求检查的目录相同，因此页面中的内容就是实际生效的权限。

自定义角色​

自定义角色是针对资源类型（环境、模型、API Key、安全护栏、预算、审计事件等）定义的 read / write 权限集合。持有自定义角色的成员只能执行角色授予的操作；自定义角色会替换内置基线，而不是在内置基线上扩展。例如，只对 environments 授予 read 的角色不能列出团队或查看用量。

常见用途包括：

  • 只读审计记录和用量、但不配置任何内容的 auditor 角色；
  • 管理模型、服务提供方密钥和安全护栏、但不能操作成员或账单的 gateway-operator 角色；
  • 以只读为主、仅对一种资源（例如预算）授予写权限的角色。

创建和分配​

  1. 打开 Roles，选择 New role（组织管理员和 owner 可执行）。
  2. 选择名称，例如小写 slug auditor。名称是永久的：成员按名称引用角色，因此重命名会使引用失效。请改为创建新角色。
  3. 选择角色授予的权限并保存。
  4. 在 Members 页面分配角色（仅组织 owner 可执行），或将目录组映射到该角色，请参阅目录同步。

自定义角色也可以作为 SCIM 组到角色映射和目录同步默认角色的目标。

环境范围访问​

成员的组织角色适用于整个组织。环境访问授权会在组织角色之上，为成员在单个环境内额外授予一个角色，但不能缩小组织角色的权限。

例如，成员可以保留组织范围的只读访问权限，同时获得生产环境的 admin 授权。该授权会增加对生产环境内资源的写权限，但不会移除成员在其他位置的组织级访问权限。如需降低适用于整个组织的基础权限，请使用自定义组织角色。

  • 成员对环境资源的最终访问权限是组织角色与该环境授权的并集（取权限更宽的一方）。
  • 授权在其所属环境之外不生效：组织级资源（成员、团队、设置、账单和自定义角色）以及其他环境仍只使用组织角色判断权限。
  • 授权只覆盖环境内部的资源，不包含环境对象本身；环境范围的 admin 不能重命名或删除环境。
  • 授权可以指向 admin、member 或任意自定义角色，但不能指向 owner。
  • owner 无法获得授权（因为其已经拥有全部权限），且只有 owner 可以编辑成员的授权。
  • 删除环境时，指向该环境的授权也会被删除；被授权引用的自定义角色不能删除。

在 Members 页面管理授权：展开成员行中的 Environment access，添加环境和角色，然后保存。也可以通过 API 管理：

# 读取成员授权（成员 ID 来自 GET /api/members）
curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://<your-host>/api/members/<member_id>/role_bindings"

# 替换整个授权集合（仅 Owner）
curl -sS -X PUT "https://<your-host>/api/members/<member_id>/role_bindings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bindings":[{"env_id":"<environment-uuid>","role":"admin"}]}'

规则和限制​

  • 管理员和 owner 可以创建、编辑和删除自定义角色。向成员分配任何角色仍仅限 owner 执行。
  • 自定义角色不能授予超过内置 admin 角色的权限。仅限 owner 的操作不能授予，目录同步也不能分配 owner。
  • 仍有成员持有的角色不能删除，请先为这些成员重新分配角色。
  • 角色权限变更会在数秒内应用到组织中持有该角色的所有成员。

API​

使用 Admin Token 通过程序管理角色：

# 列出角色（内置和自定义）
curl -sS -H "Authorization: Bearer $TOKEN" "https://<your-host>/api/roles"

# 创建自定义角色
curl -sS -X POST "https://<your-host>/api/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"auditor","description":"Read-only audit access","permissions":[{"action":"read","resource":"audit"},{"action":"read","resource":"usage"}]}'

# 更新角色权限
curl -sS -X PATCH "https://<your-host>/api/roles/auditor" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"permissions":[{"action":"read","resource":"audit"}]}'

# 删除角色
curl -sS -X DELETE "https://<your-host>/api/roles/auditor" \
  -H "Authorization: Bearer $TOKEN"

如果删除仍有成员持有的角色，API 会返回 409 ROLE_IN_USE。

下一步​

如需由身份提供方管理成员和角色分配，请继续阅读 SCIM 目录同步。如需连接为环境资源提供服务的网关，请参阅连接 AISIX 网关。