版本：3.10.x

教程：通过插件代理和管理 API 请求

本教程以快速开始为基础，带你完成一个贴近实际的场景：通过 API7 网关代理 API 请求，并使用插件实施身份认证和限流。

你将学到：

为后端 API 创建服务和路由
添加 key-auth 插件以要求 API Key（API 密钥）身份认证
创建带有凭证的消费者
添加 limit-count 插件以实施限流
测试完整配置

预计用时：约 15 分钟

前置条件：已运行的 API7 网关实例。如果尚未设置，请先完成快速开始。如果要跟随 Admin API 示例，请在开始前阅读从控制台获取 Token。

第 1 步：创建服务和路由

创建一个将请求代理到 httpbin.org 的服务。你可以手动添加，也可以导入 OpenAPI 规范来创建服务及其路由。

控制台
Admin API
ADC

在控制台侧边栏中进入默认网关组，然后点击 Services。
点击 Add Service，再点击 Add Manually。
配置服务：

字段	值
名称	`demo-api`
服务类型	`HTTP(Layer 7 protocol)`
上游协议	`HTTP`
如何查找上游	`Use Nodes`

点击 Add Node，并进行如下配置：

字段	值
主机	`httpbin.org`
端口	`80`
权重	`100`

点击 Add 创建服务。
点击 demo-api 服务，然后点击 Add Route。
配置路由：

字段	值
名称	`get-request`
路径	`/get`
方法	`GET`

点击 Add。

# 创建包含上游的服务
curl -k "https://localhost:7443/apisix/admin/services/demo-api?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "demo-api",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        { "host": "httpbin.org", "port": 80, "weight": 100 }
      ]
    }
  }'

# 在该服务下创建路由
curl -k "https://localhost:7443/apisix/admin/routes/get-request?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get-request",
    "service_id": "demo-api",
    "paths": ["/get"],
    "methods": ["GET"]
  }'

如果不是在本地运行，请将 localhost 替换为你的 Admin API 主机。若 Admin API 使用自签名 TLS 证书，则必须使用 -k 标志。将 {gateway_group_id} 替换为网关组 ID：对于快速开始创建的网关组，请使用 default；也可从控制台的 Gateway Groups 页面复制该 ID。

adc.yaml
services:
  - name: demo-api
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: get-request
        uris:
          - /get
        methods:
          - GET

adc sync -f adc.yaml

导入 OpenAPI 规范

控制台支持通过 OpenAPI 3.0 或 3.1 规范创建服务及其路由。例如，将以下内容保存为 openapi.yaml：

openapi.yaml
openapi: 3.0.0
info:
  title: demo-api
  version: 1.0.0
paths:
  /get:
    get:
      operationId: get-request
      responses:
        "200":
          description: Successful response

在控制台中：

在默认网关组中，进入 Services 并点击 Add Service。
选择 Import OpenAPI，在 OpenAPI Specification 字段中上传 openapi.yaml。
将 Service Type 保持为 HTTP(Layer 7 protocol)，将 Scheme 设为 HTTP，并在 How to find the upstream 中选择 Use Nodes。
点击 Add Node，填写上游主机、端口和权重。本教程使用 httpbin.org、80 和 100。
点击 Next，检查根据规范生成的服务和路由，然后点击 Add。

规范中的路径会生成该服务下的路由。接着按照第 2 步验证 /get 路由，再为导入的服务配置插件。

第 2 步：验证代理

在添加插件前，测试路由以验证基本配置：

curl -i "http://localhost:9080/get"

你应收到包含 HTTPBin 响应正文的 200 OK 响应，这表示代理工作正常。

第 3 步：启用 `key-auth` 插件

key-auth 插件要求消费者提供有效的 API Key。

控制台
Admin API
ADC

在默认网关组中，进入 Services 并点击 demo-api 服务。
点击 Plugins，再点击 Enable Plugin。
搜索 key-auth 并启用它。
使用默认配置并点击 Submit。

# 替换服务定义并启用 key-auth
curl -k "https://localhost:7443/apisix/admin/services/demo-api?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "demo-api",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        { "host": "httpbin.org", "port": 80, "weight": 100 }
      ]
    },
    "plugins": {
      "key-auth": {}
    }
  }'

adc.yaml
services:
  - name: demo-api
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: get-request
        uris:
          - /get
        methods:
          - GET
    plugins:
      key-auth: {}

adc sync 会以声明式方式替换全部资源，因此文件必须包含完整的目标状态；请保留第 1 步的上游和路由块，并添加新的 plugins 块。

adc sync -f adc.yaml

不带密钥测试

curl -i "http://localhost:9080/get"

预期响应：

HTTP/1.1 401 Unauthorized
{"message":"Missing API key in request"}

第 4 步：创建消费者

创建一个带有 API Key 凭证的消费者：

控制台
Admin API
ADC

在控制台侧边栏中进入 Consumers，然后点击 Create Consumer。
配置消费者：

字段	值
名称	`test-consumer`

点击 Submit 创建消费者。
点击 test-consumer 消费者以打开它，然后选择 Credentials 选项卡。
点击 Create Credential，并选择 key-auth 作为类型。
配置凭证：

字段	值
名称	`test-consumer-key`
密钥	`my-secret-api-key`

点击 Submit。

# 创建消费者
curl -k "https://localhost:7443/apisix/admin/consumers/test-consumer?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "test-consumer"
  }'

# 为消费者添加 key-auth 凭证
curl -k "https://localhost:7443/apisix/admin/consumers/test-consumer/credentials/test-consumer-key?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-consumer-key",
    "plugins": {
      "key-auth": {
        "key": "my-secret-api-key"
      }
    }
  }'

在 API7 企业版中，API Key 存放在附加到消费者的凭证资源中，而不是直接内联到消费者上。如果在消费者上内联配置 key-auth 插件，Admin API 会拒绝请求并返回错误 adding new key-auth plugin in consumer is not allowed, please use it in credential。

adc.yaml
consumers:
  - username: test-consumer
    credentials:
      - name: test-consumer-key
        type: key-auth
        config:
          key: my-secret-api-key

adc sync -f adc.yaml

使用 API Key 测试

curl -i "http://localhost:9080/get" -H "apikey: my-secret-api-key"

预期响应：200 OK。

第 5 步：启用限流

添加 limit-count 插件，以限制消费者可以发出的请求数量。

控制台
Admin API
ADC

在默认网关组中，进入 Services 并点击 demo-api 服务。
点击 Plugins，再点击 Enable Plugin。
搜索 limit-count 并按如下配置：

{
  "count": 5,
  "time_window": 60,
  "rejected_code": 429,
  "key_type": "var",
  "key": "consumer_name",
  "policy": "local"
}

点击 Submit。

# 替换服务定义并启用 key-auth 和 limit-count
curl -k "https://localhost:7443/apisix/admin/services/demo-api?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "demo-api",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        { "host": "httpbin.org", "port": 80, "weight": 100 }
      ]
    },
    "plugins": {
      "key-auth": {},
      "limit-count": {
        "count": 5,
        "time_window": 60,
        "rejected_code": 429,
        "key_type": "var",
        "key": "consumer_name",
        "policy": "local"
      }
    }
  }'

adc.yaml
services:
  - name: demo-api
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: get-request
        uris:
          - /get
        methods:
          - GET
    plugins:
      key-auth: {}
      limit-count:
        count: 5
        time_window: 60
        rejected_code: 429
        key_type: var
        key: consumer_name
        policy: local

adc sync -f adc.yaml

测试限流

快速连续发送多个请求：

for i in $(seq 1 6); do
  echo "Request $i:"
  curl -s -o /dev/null -w "HTTP %{http_code}\n" \
    http://localhost:9080/get -H "apikey: my-secret-api-key"
done

预期输出：

Request 1: HTTP 200
Request 2: HTTP 200
Request 3: HTTP 200
Request 4: HTTP 200
Request 5: HTTP 200
Request 6: HTTP 429

后续步骤

深入了解 API7 产品和 APISIX：了解完整的 API7 产品生态系统。
API7 网关控制面配置参考：为生产环境微调控制面。
监控指标：监控网关流量。

第 1 步：创建服务和路由​

导入 OpenAPI 规范​

第 2 步：验证代理​

第 3 步：启用 key-auth 插件​

不带密钥测试​

第 4 步：创建消费者​

使用 API Key 测试​

第 5 步：启用限流​

测试限流​

后续步骤​