典型访问场景
本页介绍用基于规则的角色划分组织内访问权限的九种常见方式。每个场景给出目标,在控制台和 Admin API 请求体两种形式下定义角色,说明分配给谁,并描述此人之后能看到什么。
所有场景共用一个示例组织,可以并排配置、互相对照。基于规则的角色从控制面 vNEXT 起在 AISIX Enterprise 和 AISIX Cloud 中提供。
示例组织
各场景假定以下配置:
- 两个环境:
test和prod。 - 在 标签键 页面声明的标签键
dept、tier和vendor。参见声明标签键。 - 两个团队:
payments的负责人是lead-payments,成员有dev-alice;search的成员有dev-carol。 - 两个环境中都有调用方 API Key:有的分配给个人成员,有的绑定到团队但不指定成员,有的带有标签
dept=payments或dept=search。 - 两个环境中都有模型,有的带访问控制标签
tier=public,有的带dept=payments或dept=search。 - 带访问控制标签
vendor=openai或vendor=anthropic的 Provider Key。
API Key 上的 dept 是成本归属标签。模型和 Provider Key 的标签在其创建和编辑表单的 访问控制标签 中设置。
场景中的每个人都是以默认角色受限成员受邀加入的。
创建并分配角色
在控制台中,打开 角色,选择 新建角色,输入角色的 名称,按场景规则表的每一行添加一张规则卡片,然后选择 创建角色。之后在 成员 页面该成员所在行通过 角色 和 添加角色 分配,或在团队的 团队角色 卡片中分配。
使用 Admin API 时,把场景中的请求体发送到 POST /roles,然后按 user_id 分配给成员,或按 team_id 分配给团队。请把请求体中的 TEST_ENV_ID 替换为 test 环境的 ID。
# AISIX_CP 包含 /api,且末尾不带斜杠。
# 本地 AISIX Enterprise 快速开始使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
# 先把场景的请求体保存为 role.json。
curl -sS -X POST "${AISIX_CP}/roles" \
-H "Authorization: Bearer ${AISIX_TOKEN}" \
-H "Content-Type: application/json" \
-d @role.json
# 分配给成员。
curl -sS -X POST "${AISIX_CP}/members/${USER_ID}/roles" \
-H "Authorization: Bearer ${AISIX_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"role": "ROLE_NAME"}'
# 或分配给团队。
curl -sS -X POST "${AISIX_CP}/teams/${TEAM_ID}/roles" \
-H "Authorization: Bearer ${AISIX_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"role": "ROLE_NAME"}'
分配角色需要所有者,或像场景 9 那样持有 role_assignments 的成员。定义角色需要内置的管理员或所有者。
1. 新成员默认受限
目标:新受邀的成员在有人决定其所需权限之前没有任何访问权限。
角色:内置的受限成员。它只读取分配给本人 、本人所在团队和本人负责的团队的 API Key,以及这些 Key 的用量,无需额外定义。
分配给:dev-new,通过保留预选 受限成员 角色的邀请加入。
能看到什么:受限成员无法读取任何环境,所以 dev-new 登录后环境切换器为空,提示其还没有任何环境的访问权限、请联系管理员,并链接到 我的权限,其中列出受限成员的那一条规则。各配置页面都被隐藏,用量 页面也一样,因为它还需要环境读取权限;成本分析 会显示其 Key 跨环境的用量。场景 2 补充了浏览自己 Key 所需的权限。
2. 普通用户只看到自己的 Key、模型和用量
目标:开发者在所有环境中使用分配给自己的 API Key 及其产生的用量,但看不到别人的 Key,也看不到网关配置。
角色:受限成员已把 Key 和用量限定在本人及其团队。自定义角色 environment-viewer 再加上环境列表,让开发者可以在控制台中打开各个环境:
| 资源类型 | 操作 | 环境 | 对象 |
|---|---|---|---|
| 环境 | 读取 | 不适用 | 全部对象 |
{
"name": "environment-viewer",
"description": "Environment Viewer: read every environment",
"rules": [
{
"resources": ["environments"],
"actions": ["read"]
}
]
}
分配给:dev-alice,保留受限成员,同时获得 environment-viewer。
能看到什么:
- 环境切换器中出现
test和prod。 - API 密钥 列出分配给 Alice 的 Key,以及绑定到
payments团队且未指定成员的 Key。队友的个人 Key(即使绑定到payments)和search的所有 Key 都不出现,Admin API 对它们返回404。 - 日志、用量 和 成本分析 只显示这些 Key 的请求。
- 她的 Key 可以调用的模型在每个 Key 上以名称加锁形图标显示:Alice 能看到 Key 可以使用哪些模型,但打不开模型配置。模型 页面和其他所有配置页面都被隐藏。
- 创建、编辑和轮换 Key 的操作被禁用,提示中写明缺少的权限。
3. 自助开发者管理自己的 Key
目标:开发者在测试环境中创建、轮换和删除自己的 Key,只能选择经过批准的模型,并且无法访问生产环境。
角色:自定义角色 self-service-developer:
| 资源类型 | 操作 | 环境 | 对象 |
|---|---|---|---|
| 环境 | 读取 | 不适用 | 指定对象:test |
| API 密钥 | 全部操作 | 指定环境:test | 按分配关系:本人 |
| 用量 | 读取 | 指定环境:test | 按分配关系:本人 |
| 模型 | 读取 | 指定环境:test | 按标签:tier=public |
{
"name": "self-service-developer",
"description": "Self-service Developer: own keys and public models in test",
"rules": [
{
"resources": ["environments"],
"actions": ["read"],
"selector": {"ids": ["TEST_ENV_ID"]}
},
{
"resources": ["api_keys"],
"actions": ["read", "create", "update", "delete"],
"environments": {"ids": ["TEST_ENV_ID"]},
"selector": {"assigned_to": ["self"]}
},
{
"resources": ["usage"],
"actions": ["read"],
"environments": {"ids": ["TEST_ENV_ID"]},
"selector": {"assigned_to": ["self"]}
},
{
"resources": ["models"],
"actions": ["read"],
"environments": {"ids": ["TEST_ENV_ID"]},
"selector": {"tags": {"tier": "public"}}
}
]
}
分配给:dev-bob,直接分配。
能看到什么:
- 环境切换器 中只有
test。prod不出现,其页面会被拒绝。 - API 密钥 列出 Bob 自己的 Key。他可以创建 Key,但每个新 Key 都必须以他为成员,否则请求以
400被拒绝。他可以轮换、编辑和删除自己的 Key,但不能把 Key 转给别人,因为编辑后 Key 必须仍然分配给他。 - Key 的模型选择器只提供带
tier=public标签的模型,模型 也只列出这些模型。为 Key 开启全部模型会被拒绝,因为那需要读取该环境中的所有模型。 - 日志 和 用量 只显示他的 Key 的请求。
4. 团队负责人管理团队的 Key
目标:团队负责人在所有环境中管理其负责的团队的每个 API Key,并查看这些 Key 的用量和团队的模型。
角色:自定义角色 team-lead,与受限成员一起持有:
| 资源类型 | 操作 | 环境 | 对象 |
|---|---|---|---|
| 环境 | 读取 | 不适用 | 全部对象 |
| API 密钥 | 全部操作 | 全部环境 | 按分配关系:本人负责的团队 |
| 用量 | 读取 | 全部环境 | 按分配关系:本人负责的团队 |
| 模型 | 读取 | 全部环境 | 按标签:dept=payments |
{
"name": "team-lead",
"description": "Team Lead: every key of the teams I lead",
"rules": [
{
"resources": ["environments"],
"actions": ["read"]
},
{
"resources": ["api_keys"],
"actions": ["read", "create", "update", "delete"],
"environments": "all",
"selector": {"assigned_to": ["led_teams"]}
},
{
"resources": ["usage"],
"actions": ["read"],
"environments": "all",
"selector": {"assigned_to": ["led_teams"]}
},
{
"resources": ["models"],
"actions": ["read"],
"environments": "all",
"selector": {"tags": {"dept": "payments"}}
}
]
}
分配给:payments 的负责人 lead-payments,直接分配。
能看到什么:
- API 密钥 列出两个环境中绑定到
payments的每个 Key,包括团队成员绑定到该团队的个人 Key,以及通过受限成员看到的自己的 Key。 - 可以创建绑定到
payments的 Key,并轮换、编辑、禁用或删除团队的 Key,但不能把 Key 移出该团队。为新 Key 指定其他成员还需要成员的读取权限,因此负责人创建的新 Key 绑定到团队,或绑定到团队并以自己为成员。 - 日志 和 用量 显示每个
paymentsKey 的请求,模型 列出带dept=payments标签的模型。 - 规则跟随团队名单:如果不再负责
payments,团队的 Key 就从其视图中消失。
5. 在共用环境中隔离部门
目标:两个部门在同样的 test 和 prod 环境中工作,各自只看到自己的 Key、用量和模型。
角色:自定义角色 search-department,分配给该部门的团队:
| 资源类型 | 操作 | 环境 | 对象 |
|---|---|---|---|
| 环境 | 读取 | 不适用 | 全部对象 |
| API 密钥、用量 | 读取 | 全部环境 | 按标签:dept=search |
| 模型 | 读取 | 全部环境 | 按标签:dept=search |
{
"name": "search-department",
"description": "Search Department: objects tagged dept=search",
"rules": [
{
"resources": ["environments"],
"actions": ["read"]
},
{
"resources": ["api_keys", "usage"],
"actions": ["read"],
"environments": "all",
"selector": {"tags": {"dept": "search"}}
},
{
"resources": ["models"],
"actions": ["read"],
"environments": "all",
"selector": {"tags": {"dept": "search"}}
}
]
}
分配给:search 团队,在其 团队角色 卡片中分配。dev-carol 作为 search 的成员获得它,之后加入该团队的人也一样。再用一个 dept=payments 的 payments-department 角色分配给 payments,就完成了拆分。
能看到什么:
- 两个环境的 API 密钥 都列出带
dept=search标签的 Key,不论归属谁。 - 日志、用量 和 成本分析 显示这些 Key 的请求,模型 列出带
dept=search标签的模型。 - 任何带
dept=payments标签的东西都不会出现:它的 Key、用量和模型都看不到,Admin API 对它们返回404。 - 我的权限 中这些规则的来源显示为 search-department,来自团队 search。
部门边界就是标签,因此请给部门拥有的每个 Key 和模型打上标签,并明确谁可以修改标签。Key 的 dept 标签同时驱动成本归属,所以同一个标签既划分访问也划分成本。
6. 委托一个环境
目标:运维人员管理 test 环境内的一切,但看不到 prod,也看不到组织设置。
角色:自定义角色 test-environment-admin。在控制台中,一次选中 环境内资源 下的全部类型;保存时会展开为当时存在的类型列表:
| 资源类型 | 操作 | 环境 | 对象 |
|---|---|---|---|
| 环境 | 读取 | 不适用 | 指定对象:test |
| 全部环境内资源 | 全部操作 | 指定环境:test | 全部对象 |
| 服务商密钥 | 读取 | 不适用 | 全部对象 |
{
"name": "test-environment-admin",
"description": "Test Environment Admin: everything inside test",
"rules": [
{
"resources": ["environments"],
"actions": ["read"],
"selector": {"ids": ["TEST_ENV_ID"]}
},
{
"resources": [
"models", "api_keys", "usage", "guardrails", "cache_policies",
"rate_limits", "observability_exporters", "passthrough_routes",
"oidc_providers", "claim_mappings", "mcp_policy",
"gateway_certificates", "dp_nodes", "playground"
],
"actions": ["read", "create", "update", "delete"],
"environments": {"ids": ["TEST_ENV_ID"]}
},
{
"resources": ["provider_keys"],
"actions": ["read"]
}
]
}
需要 Provider Key 规则,是因为环境管理员必须能读取它用来构建模型的 Provider Key:模型只能指向创建者可以读取的 Provider Key。
分配给:ops-dan,直接分配。
能看到什么:
- 环境切换器中只有
test,其中的一切都可以配置:模型、Key、护栏、各类策略、网关证书和数据面、调试台,以及它的用量。 prod不可见,test环境本身也不能重命名或删除,因为那需要环境的update和delete。- 服务商密钥 可读但不可编辑。团队、成员、预算 等其他组织页面被隐藏。
环境内资源的角色只能通过引用触及组织级资源,所以该角色需要读取 Provider Key。如需把 Dan 限定在部分厂商,用标签收窄这条规则。同理,除非角色还能读取成员和团队,新 Key 只能以 Dan 本人或他所在的团队为归属。
7. 财务查看用量和成本
目标:财务查看者可以看到整个组织的用量、成本、预算和定价,但不能访问任何配置。
角色:自定义角色 finance-viewer:
| 资源类型 | 操作 | 环境 | 对象 |
|---|---|---|---|
| 环境 | 读取 | 不适用 | 全部对象 |
| 用量 | 读取 | 全部环境 | 全部对象 |
| 预算、模型定价 | 读取 | 不适用 | 全部对象 |
{
"name": "finance-viewer",
"description": "Finance Viewer: all usage, budgets, and pricing",
"rules": [
{
"resources": ["environments"],
"actions": ["read"]
},
{
"resources": ["usage"],
"actions": ["read"],
"environments": "all"
},
{
"resources": ["budgets", "model_pricing"],
"actions": ["read"]
}
]
}
分配给:finance-eve,直接分配。
能看到什么:
- 用量 和 成本分析 覆盖所有环境,包括 目标模型 视图以及团队和标签分组上的预算数据,因为 Eve 不带对象范围地读取全部用量,并且可以读取预算。
- 每个环境的 日志 显示每个请求的全部字段。
- 预算 和 模型定价 可读但不可编辑。
- 用量中引用的 API Key、成员和模型以名称加锁形图标显示。Eve 打不开它们,其配置页面也被隐藏。
8. 管理某一厂商的 Provider Key
目标:厂商对接人维护 OpenAI 的 Provider Key,但看不到其他任何 Provider Key。
角色:自定义角色 openai-key-manager:
| 资源类型 | 操作 | 环境 | 对象 |
|---|---|---|---|
| 服务商密钥 | 读取、更新 | 不适用 | 按标签:vendor=openai |
{
"name": "openai-key-manager",
"description": "OpenAI Key Manager: provider keys tagged vendor=openai",
"rules": [
{
"resources": ["provider_keys"],
"actions": ["read", "update"],
"selector": {"tags": {"vendor": "openai"}}
}
]
}
分配给:vendor-frank,直接分配。
能看到什么:
- 服务商密钥 只列出带
vendor=openai标签的 Key,Frank 可以编辑它们。带vendor=anthropic标签的 Key 不出现,Admin API 对它返回404。 - 去掉或修改
vendor=openai标签的编辑会被拒绝,因为修改后 Key 必须仍在范围内。他不能创建或删除 Provider Key。 - 他无法读取任何环境,所以环境切换器为空。
9. 委托角色分配
目标:访问管理员为成员和团队分配角色并维护团队名单,但不是所有者。
角色:自定义角色 access-manager:
| 资源类型 | 操作 | 环境 | 对象 |
|---|---|---|---|
| 角色分配 | 创建、删除 | 不适用 | 全部对象 |
| 成员、角色 | 读取 | 不适用 | 全部对象 |
| 团队 | 读取、更新 | 不适用 | 全部对象 |
{
"name": "access-manager",
"description": "Access Manager: assigns roles and maintains team rosters",
"rules": [
{
"resources": ["role_assignments"],
"actions": ["create", "delete"]
},
{
"resources": ["members", "roles"],
"actions": ["read"]
},
{
"resources": ["teams"],
"actions": ["read", "update"]
}
]
}
定义该角色时,团队规则会显示警告:更新团队包括修改团队成员,持有者因此可以把这些团队的角色交给任何人。
分配给:it-grace,直接分配。
能看到什么:
- 在 成员 页面,Grace 可以添加和移除每位成员的手动角色,并查看每位成员的 生效权限。不会提供所有者角色,SSO 或 SCIM 分配的角色仍然锁定。
- 在 团队 页面,她可以添加和移除团队成员,并在 团队角色 中管理团队的角色。
- 在 角色 页面,她可以读取所有角色,并在 持有者 标签页中移除持有者,但不能创建或编辑角色:定义角色只限内置的所有者和管理员。
- 她不能邀请或移除成员。
分配角色等同于管理员。Grace 可以把所有者以外的任何角色(包括管理员)授予任何人,包括她自己。请只 把这个角色交给你愿意授予管理员权限的人。参见谁可以改变访问权限。