版本：3.10.x

API7 网关 AI Agent Skill：多租户方案

概览

API7 企业版中的多租户由三层组成：

使用网关组实现运行时隔离。
用于租户身份的消费者和凭证。
使用基于服务的路由承载租户 API。

对于路由流量，请使用当前版本的 a7 服务关联路由模型：

创建包含上游节点的服务。
使用 paths 和 service_id 创建路由。
分别创建消费者和凭证。

适用场景

分离 dev、staging 和 prod 网关配置。
为 SaaS 租户提供不同的限制或身份认证策略。
通过网关组隔离受监管或高优先级租户。
由平台团队维护共享路由，由应用团队维护服务目标。

方案 A：使用网关组隔离

网关组是主要隔离边界。安装 jq 后，创建网关组并保存 API7 企业版返回的 ID：

PREMIUM_GROUP_ID=$(a7 gateway-group create --name premium-tier --description "High-performance tier for paid customers" --output json | jq -r '.id')
STANDARD_GROUP_ID=$(a7 gateway-group create --name standard-tier --description "Standard tier for free and trial users" --output json | jq -r '.id')
PLATFORM_GROUP_ID=$(a7 gateway-group create --name platform --description "Shared platform gateway group for tenant consumers and routes" --output json | jq -r '.id')

API7 企业版会生成网关组 ID。请在当前 shell 中保留这些变量，并向运行时资源命令传入生成的 ID，而不是显示名称。

每个网关组都可以拥有自己的全局策略：

a7 global-rule create -g "$STANDARD_GROUP_ID" -f - <<'EOF'
{
  "plugins": {
    "limit-count": {
      "count": 5000,
      "time_window": 3600,
      "rejected_code": 429
    }
  }
}
EOF

方案 B：使用消费者和凭证

当前 API7 企业版不通过 Admin API 暴露消费者组管理能力。请将租户建模为消费者，在需要时为每个消费者关联插件，并使用 a7 credential create 创建凭证。

a7 consumer create -g "$PLATFORM_GROUP_ID" -f - <<'EOF'
{
  "username": "startup-xyz",
  "desc": "Free tier tenants",
  "plugins": {
    "limit-count": {
      "count": 100,
      "time_window": 86400,
      "key_type": "var",
      "key": "consumer_name",
      "rejected_code": 429,
      "rejected_msg": "Free tier quota exceeded"
    }
  }
}
EOF

a7 credential create startup-xyz-key-auth -g "$PLATFORM_GROUP_ID" --consumer startup-xyz --plugins-json '{"key-auth":{"key":"startup-xyz-key"}}'

a7 consumer create -g "$PLATFORM_GROUP_ID" -f - <<'EOF'
{
  "username": "acme-corp",
  "desc": "Pro tier tenants",
  "plugins": {
    "limit-count": {
      "count": 10000,
      "time_window": 86400,
      "key_type": "var",
      "key": "consumer_name",
      "rejected_code": 429,
      "rejected_msg": "Pro tier quota exceeded"
    }
  }
}
EOF

a7 credential create acme-corp-key-auth -g "$PLATFORM_GROUP_ID" --consumer acme-corp --plugins-json '{"key-auth":{"key":"acme-secret-key"}}'

方案 C：租户感知的服务路由

先创建后端服务：

a7 service create -g "$PLATFORM_GROUP_ID" -f - <<'EOF'
{
  "id": "tenant-api-service",
  "name": "tenant-api-service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [
      {"host": "internal-service", "port": 8080, "weight": 1}
    ]
  }
}
EOF

使用 paths 和 service_id 创建租户路由：

a7 route create -g "$PLATFORM_GROUP_ID" -f - <<'EOF'
{
  "id": "multi-tenant-api",
  "name": "multi-tenant-api",
  "paths": ["/service/*"],
  "service_id": "tenant-api-service",
  "plugins": {
    "key-auth": {},
    "proxy-rewrite": {
      "headers": {
        "set": {
          "X-Tenant-ID": "$consumer_name",
          "X-User-ID": "$consumer_name",
          "X-Gateway-Group": "platform"
        }
      }
    }
  }
}
EOF

按网关组进行声明式管理

每个网关组使用一个声明式文件，并通过 -g 应用。这与当前 a7 config sync 工作流一致。

version: "1"
services:
  - id: tenant-api-service
    name: tenant-api-service
    upstream:
      type: roundrobin
      nodes:
        - host: internal-service
          port: 8080
          weight: 1
routes:
  - id: multi-tenant-api
    name: multi-tenant-api
    paths:
      - /service/*
    service_id: tenant-api-service
    plugins:
      key-auth: {}
      proxy-rewrite:
        headers:
          set:
            X-Tenant-ID: "$consumer_name"
            X-User-ID: "$consumer_name"
            X-Gateway-Group: platform

应用配置：

a7 config sync -g "$PLATFORM_GROUP_ID" -f platform-tenants.yaml --delete=false

该文件只包含租户服务和路由。禁用删除可保留网关组中单独管理的消费者及其他资源。

使用 a7 consumer create -f 和 a7 credential create 管理租户身份和密钥材料。

验证

a7 consumer list -g "$PLATFORM_GROUP_ID"
a7 credential list -g "$PLATFORM_GROUP_ID" --consumer startup-xyz
a7 service get tenant-api-service -g "$PLATFORM_GROUP_ID" -o json
a7 route get multi-tenant-api -g "$PLATFORM_GROUP_ID" -o json

流量验证需要已部署的网关：

curl -i -H "apikey: startup-xyz-key" https://gateway.example.com/service/resource
curl -i -H "apikey: acme-secret-key" https://gateway.example.com/service/resource

身份认证成功后，后端应收到 X-Tenant-ID、X-User-ID 和 X-Gateway-Group 请求头。

重要注意事项

使用不同网关组实现严格运行时隔离。
在同一网关组内使用消费者级插件实现租户特定策略。
将凭证放在 a7 credential 中，不要直接嵌入消费者中。
a7 config sync -g 每次管理一个网关组。
对于没有专用 CLI 参数的字段，请使用原始消费者请求体。

本页面由 api7/a7 仓库中的 a7-recipe-multi-tenant/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。

概览​

适用场景​

方案 A：使用网关组隔离​

方案 B：使用消费者和凭证​

方案 C：租户感知的服务路由​

按网关组进行声明式管理​

验证​

重要注意事项​

概览