跳到主要内容
版本:Dev

典型访问场景

本页介绍用基于规则的角色划分组织内访问权限的九种常见方式。每个场景给出目标,在控制台和 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 绑定到团队,或绑定到团队并以自己为成员。
  • 日志 和 用量 显示每个 payments Key 的请求,模型 列出带 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 可以把所有者以外的任何角色(包括管理员)授予任何人,包括她自己。请只把这个角色交给你愿意授予管理员权限的人。参见谁可以改变访问权限。

下一步​

完整的规则模型和资源类型见角色与权限;成员可以自己创建 Key 时仍然有效的上限见预算。