# 典型访问场景

本页介绍用[基于规则的角色](https://docs.apiseven.com/ai-gateway/cloud/custom-roles.md)划分组织内访问权限的九种常见方式。每个场景给出目标，在控制台和 Admin API 请求体两种形式下定义角色，说明分配给谁，并描述此人之后能看到什么。

所有场景共用一个示例组织，可以并排配置、互相对照。基于规则的角色从控制面 1.11.0 起在 AISIX Enterprise 和 AISIX Cloud 中提供。

## 示例组织[​](#the-example-organization "示例组织的直接链接")

各场景假定以下配置：

* 两个环境：`test` 和 `prod`。
* 在 **标签键** 页面声明的标签键 `dept`、`tier` 和 `vendor`。参见[声明标签键](https://docs.apiseven.com/ai-gateway/cloud/cost-attribution-tags.md#declare-tag-keys)。
* 两个团队：`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` 是[成本归属标签](https://docs.apiseven.com/ai-gateway/cloud/cost-attribution-tags.md#set-tags-on-api-keys-teams-and-members)。模型和 Provider Key 的标签在其创建和编辑表单的 **访问控制标签** 中设置。

场景中的每个人都是以默认角色受限成员受邀加入的。

### 创建并分配角色[​](#create-and-assign-a-role "创建并分配角色的直接链接")

在控制台中，打开 **角色**，选择 **新建角色**，输入角色的 **名称**，按场景规则表的每一行添加一张规则卡片，然后选择 **创建角色**。之后在 **成员** 页面该成员所在行通过 **角色** 和 **添加角色** 分配，或在团队的 **团队角色** 卡片中分配。

使用 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](#9-delegate-role-assignment) 那样持有 `role_assignments` 的成员。定义角色需要内置的管理员或所有者。

## 1. 新成员默认受限[​](#1-new-members-start-restricted "1. 新成员默认受限的直接链接")

**目标**：新受邀的成员在有人决定其所需权限之前没有任何访问权限。

**角色**：内置的受限成员。它只读取分配给本人、本人所在团队和本人负责的团队的 API Key，以及这些 Key 的用量，无需额外定义。

**分配给**：`dev-new`，通过保留预选 **受限成员** 角色的邀请加入。

**能看到什么**：受限成员无法读取任何环境，所以 `dev-new` 登录后环境切换器为空，提示其还没有任何环境的访问权限、请联系管理员，并链接到 **我的权限**，其中列出受限成员的那一条规则。各配置页面都被隐藏，**用量** 页面也一样，因为它还需要环境读取权限；**成本分析** 会显示其 Key 跨环境的用量。场景 2 补充了浏览自己 Key 所需的权限。

## 2. 普通用户只看到自己的 Key、模型和用量[​](#2-regular-users-see-only-their-own-keys-models-and-usage "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[​](#3-self-service-developers-manage-their-own-keys "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[​](#4-team-leads-manage-their-teams-keys "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. 在共用环境中隔离部门[​](#5-isolate-departments-that-share-environments "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` 标签同时驱动[成本归属](https://docs.apiseven.com/ai-gateway/cloud/cost-attribution-tags.md)，所以同一个标签既划分访问也划分成本。

## 6. 委托一个环境[​](#6-delegate-one-environment "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. 财务查看用量和成本[​](#7-finance-reviews-usage-and-cost "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[​](#8-manage-one-vendors-provider-keys "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. 委托角色分配[​](#9-delegate-role-assignment "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 可以把所有者以外的任何角色（包括管理员）授予任何人，包括她自己。请只把这个角色交给你愿意授予管理员权限的人。参见[谁可以改变访问权限](https://docs.apiseven.com/ai-gateway/cloud/custom-roles.md#who-can-change-access)。

## 下一步[​](#next-steps "下一步的直接链接")

完整的规则模型和资源类型见[角色与权限](https://docs.apiseven.com/ai-gateway/cloud/custom-roles.md)；成员可以自己创建 Key 时仍然有效的上限见[预算](https://docs.apiseven.com/ai-gateway/traffic-controls/budgets.md)。
