版本：3.10.x

创建自定义角色

API7 网关仅内置 Super Admin 一个角色，用于初始设置和紧急恢复。对于日常操作，请创建自定义角色，仅授予每个用户或团队实际需要的权限。

本指南说明一种常见模式：

对生产网关组的只读访问。
对测试网关组的完全访问。
创建一个组合这两项权限策略的自定义角色。

前置条件

开始前，请确保：

API7 网关正在运行，且控制台可访问。
你拥有能够管理角色和权限策略的用户 Token。该 Token 可按照从控制台获取 Token中的步骤创建。
至少拥有两个网关组，例如 test 和 production。
已知目标网关组 ID，或者拥有可在权限策略中使用的标签。

有关策略语法的详情，请参见权限策略和权限边界。

第 1 步：为生产环境创建只读策略

创建一个权限策略，允许只读访问生产网关组及其服务。

控制台
Admin API

在控制台中，进入组织 -> 权限策略。
点击 新增权限策略。
输入名称，例如 production-readonly。
在策略编辑器中粘贴类似下方的策略，并将网关组 ID 替换为生产组 ID。
保存策略。

{
  "statement": [
    {
      "resources": [
        "arn:api7:gateway:gatewaygroup/<production-gateway-group-id>"
      ],
      "actions": [
        "<.*>Get<.*>"
      ],
      "effect": "allow"
    },
    {
      "resources": [
        "arn:api7:gateway:gatewaygroup/<production-gateway-group-id>/service/<.*>"
      ],
      "actions": [
        "<.*>Get<.*>"
      ],
      "effect": "allow"
    }
  ]
}

curl -k "https://localhost:7443/api/permission_policies" -X POST \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-readonly",
    "desc": "Read-only access to the production gateway group",
    "policy_document": {
      "statement": [
        {
          "resources": [
            "arn:api7:gateway:gatewaygroup/<production-gateway-group-id>"
          ],
          "actions": [
            "<.*>Get<.*>"
          ],
          "effect": "allow"
        },
        {
          "resources": [
            "arn:api7:gateway:gatewaygroup/<production-gateway-group-id>/service/<.*>"
          ],
          "actions": [
            "<.*>Get<.*>"
          ],
          "effect": "allow"
        }
      ]
    }
  }'

第 2 步：为测试环境创建完全访问策略

创建第二项策略，允许完全访问测试网关组及其服务。

控制台
Admin API

在组织 -> 权限策略 中再次点击 新增权限策略。
输入名称，例如 test-full-access。
粘贴类似下方的策略，并将网关组 ID 替换为测试组 ID。
保存策略。

{
  "statement": [
    {
      "resources": [
        "arn:api7:gateway:gatewaygroup/<test-gateway-group-id>"
      ],
      "actions": [
        "<.*>"
      ],
      "effect": "allow"
    },
    {
      "resources": [
        "arn:api7:gateway:gatewaygroup/<test-gateway-group-id>/service/<.*>"
      ],
      "actions": [
        "<.*>"
      ],
      "effect": "allow"
    }
  ]
}

curl -k "https://localhost:7443/api/permission_policies" -X POST \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-full-access",
    "desc": "Full access to the test gateway group",
    "policy_document": {
      "statement": [
        {
          "resources": [
            "arn:api7:gateway:gatewaygroup/<test-gateway-group-id>"
          ],
          "actions": [
            "<.*>"
          ],
          "effect": "allow"
        },
        {
          "resources": [
            "arn:api7:gateway:gatewaygroup/<test-gateway-group-id>/service/<.*>"
          ],
          "actions": [
            "<.*>"
          ],
          "effect": "allow"
        }
      ]
    }
  }'

第 3 步：创建自定义角色

创建一个组合上述两项权限策略的角色。

控制台
Admin API

进入组织 -> 角色。
点击 新增自定义角色。
输入名称，例如 Development Team Member。
添加描述，例如 Read-only access to production and full access to test。
附加 production-readonly 和 test-full-access 权限策略。
保存角色。

创建角色：

curl -k "https://localhost:7443/api/roles" -X POST \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development Team Member",
    "desc": "Read-only access to production and full access to test"
  }'

然后使用 API 返回的角色和策略 ID，将权限策略附加到角色：

curl -k "https://localhost:7443/api/roles/<role-id>/attach_permission_policies" -X POST \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '[
    "<production-policy-id>",
    "<test-policy-id>"
  ]'

第 4 步：将角色分配给用户

将新自定义角色分配给非 root 用户。

控制台
Admin API

进入组织 -> 用户。
选择现有用户或邀请新用户。
附加 Development Team Member 角色。
保存更改。

使用目标角色 ID 更新用户已分配的角色：

curl -k "https://localhost:7443/api/users/<user-id>/assigned_roles" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "roles": [
      "<role-id>"
    ]
  }'

第 5 步：验证角色

以获得新角色的用户身份登录，并验证预期访问权限：

在生产网关组中，用户可以查看资源，但不能修改资源。
在测试网关组中，用户可以创建、更新和删除资源。
在这些范围以外，用户不会获得意外权限。

如果倾向使用 Admin API 验证，请以该用户身份登录，生成 Token，并对生产和测试资源发送测试请求。

常见模式

按环境划分的运维人员：生产环境只读，非生产环境可写。
角色管理员：管理用户、角色和权限策略，但无流量配置访问权。
审计员：对审计日志、网关配置和凭证具有只读访问权。
团队负责人：仅管理标记为特定团队的资源。

更多示例请参见权限策略示例。

后续步骤

基于角色的访问控制（RBAC）——了解角色、用户和策略如何协同工作。
权限策略和权限边界——了解 JSON 语法和评估模型。
权限策略操作和资源——查看支持的操作和资源模式。
设计自定义角色体系——为较大型组织规划可扩展的角色模型。

前置条件​

第 1 步：为生产环境创建只读策略​

第 2 步：为测试环境创建完全访问策略​

第 3 步：创建自定义角色​

第 4 步：将角色分配给用户​

第 5 步：验证角色​

常见模式​

后续步骤​