Skip to main content
Version: 3.17

limit-req

描述#

limit-req 插件使用漏桶算法来限制请求的数量并允许节流。

本地 vs Redis 速率限制#

limit-req 插件支持两种速率限制模式：

  • 本地速率限制：限制在每个网关实例上独立执行。每个实例维护自己的计数器，因此当流量分布在多个实例之间时，有效限制大约为（限制 × 实例数量）。当未设置 policy 或 policy 为 local 时，这是默认模式。
  • 基于 Redis 的速率限制：限制通过 Redis 在所有网关实例之间共享。所有实例共享相同的配额，因此配置的限制适用于所有网关实例。

属性#

名称类型必选项默认值有效值描述
ratenumber是> 0每秒允许的最大请求数。超过速率且低于突发的请求将被延迟。
burstnumber是>= 0每秒允许延迟的请求数，以进行节流。超过速率和突发的请求将被拒绝。
key_typestring否var["var", "var_combination"]key 的类型。如果 key_type 为 var，则 key 将被解释为变量。如果 key_type 为 var_combination，则 key 将被解释为变量的组合。
keystring是用于计数请求的 key。如果 key_type 为 var，则 key 将被解释为变量。变量不需要以美元符号（$）为前缀。如果 key_type 为 var_combination，则 key 会被解释为变量的组合。所有变量都应该以美元符号（$）为前缀。例如，要配置 key 使用两个请求头 custom-a 和 custom-b 的组合，则 key 应该配置为 $http_custom_a $http_custom_b。
rejected_codeinteger否503[200,...,599]请求因超出阈值而被拒绝时返回的 HTTP 状态代码。
rejected_msgstring否非空请求因超出阈值而被拒绝时返回的响应主体。
nodelayboolean否false如果为 true，则不延迟突发阈值内的请求。
allow_degradationboolean否false如果为 true，则允许 APISIX 在插件或其依赖项不可用时继续处理没有插件的请求。
policystring否local["local", "redis", "redis-cluster"]速率限制计数器的策略。如果是 local，则计数器存储在本地内存中。如果是 redis，则计数器存储在 Redis 实例上。如果是 redis-cluster，则计数器存储在 Redis 集群中。
redis_hoststring否Redis 节点的地址。当 policy 为 redis 时必填。
redis_portinteger否6379[1,...]当 policy 为 redis 时，Redis 节点的端口。
redis_usernamestring否如果使用 Redis ACL，则为 Redis 的用户名。如果使用旧式身份验证方法 requirepass，则仅配置 redis_password。当 policy 为 redis 时使用。
redis_passwordstring否当 policy 为 redis 或 redis-cluster 时，Redis 节点的密码。
redis_sslboolean否false如果为 true，则在 policy 为 redis 时使用 SSL 连接到 Redis。
redis_ssl_verifyboolean否false如果为 true，则在 policy 为 redis 时验证服务器 SSL 证书。
redis_databaseinteger否0>= 0当 policy 为 redis 时，Redis 中的数据库编号。
redis_timeoutinteger否1000[1,...]当 policy 为 redis 或 redis-cluster 时，Redis 超时值（以毫秒为单位）。
redis_keepalive_timeoutinteger否10000≥ 1000当 policy 为 redis 或 redis-cluster 时，与 Redis 的空闲连接超时时间，单位为毫秒。
redis_keepalive_poolinteger否100≥ 1当 policy 为 redis 或 redis-cluster 时，与 Redis 的连接池最大连接数。
redis_cluster_nodesarray[string]否具有至少一个地址的 Redis 集群节点列表。当 policy 为 redis-cluster 时必填。
redis_cluster_namestring否Redis 集群的名称。当 policy 为 redis-cluster 时必须使用。
redis_cluster_sslboolean否false如果为 true，当 policy 为 redis-cluster 时，使用 SSL 连接 Redis 集群。
redis_cluster_ssl_verifyboolean否false如果为 true，当 policy 为 redis-cluster 时，验证服务器 SSL 证书。

示例#

以下示例演示了如何在不同场景中配置 limit-req。

note

你可以这样从 config.yaml 中获取 admin_key 并存入环境变量：

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

按远程地址应用速率限制#

以下示例演示了通过单个变量 remote_addr 对 HTTP 请求进行速率限制。

使用 limit-req 插件创建允许每个远程地址 1 QPS 的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '
  {
    "id": "limit-req-route",
    "uri": "/get",
    "plugins": {
      "limit-req": {
        "rate": 1,
        "burst": 0,
        "key": "remote_addr",
        "key_type": "var",
        "rejected_code": 429,
        "policy": "local",
        "nodelay": true
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

❶ rate：将 QPS 限制为 1。

❷ key：设置为 remote_addr，以按远程地址应用速率限制配额。

❸ key_type：设置为 var，以将 key 解释为变量。

发送请求以验证：

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

你应该会看到一个 HTTP/1.1 200 OK 响应。

该请求已消耗了时间窗口允许的所有配额。如果你在同一秒内再次发送请求，你应该会收到 HTTP/1.1 429 Too Many Requests 响应，表示请求超出了配额阈值。

实现 API 节流#

以下示例演示了如何配置 burst 以允许超出配置值的速率限制阈值并实现请求节流。你还将看到与未实施节流时的比较。

使用 limit-req 插件创建一个路由，允许每个远程地址 1 QPS，并将 burst 设置为 1，以允许 1 个超过 rate 的请求延迟处理：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "limit-req-route",
    "uri": "/get",
    "plugins": {
      "limit-req": {
        "rate": 1,
        "burst": 1,
        "key": "remote_addr",
        "rejected_code": 429,
        "policy": "local"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

❶ burst：允许 1 个超过 rate 的请求延迟处理。

生成三个对路由的请求：

resp=$(seq 3 | xargs -I{} curl -i "http://127.0.0.1:9080/get" -o /dev/null -s -w "%{http_code}\n") && \
  count_200=$(echo "$resp" | grep "200" | wc -l) && \
  count_429=$(echo "$resp" | grep "429" | wc -l) && \
  echo "200 responses: $count_200 ; 429 responses: $count_429"

你可能会看到所有三个请求都成功：

200 responses: 3 ; 429 responses: 0

要查看没有 burst 的效果，请将 burst 更新为 0 或将 nodelay 设置为 true，如下所示：

curl "http://127.0.0.1:9180/apisix/admin/routes/limit-req-route" -X PATCH \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "plugins": {
      "limit-req": {
        "nodelay": true
      }
    }
  }'

再次向路由生成三个请求：

resp=$(seq 3 | xargs -I{} curl -i "http://127.0.0.1:9080/get" -o /dev/null -s -w "%{http_code}\n") && \
  count_200=$(echo "$resp" | grep "200" | wc -l) && \
  count_429=$(echo "$resp" | grep "429" | wc -l) && \
  echo "200 responses: $count_200 ; 429 responses: $count_429"

你应该会看到类似以下内容的响应，表明超出速率的请求已被拒绝：

200 responses: 1 ; 429 responses: 2

按远程地址和消费者名称应用速率限制#

以下示例演示了通过变量组合 remote_addr 和 consumer_name 来限制请求的速率。

使用 limit-req 插件创建一个路由，允许每个远程地址和每个消费者有 1 QPS。

创建消费者 john：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "username": "john"
  }'

为消费者创建 key-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "cred-john-key-auth",
    "plugins": {
      "key-auth": {
        "key": "john-key"
      }
    }
  }'

创建第二个消费者 jane：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "username": "jane"
  }'

为消费者创建 key-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/jane/credentials" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "cred-jane-key-auth",
    "plugins": {
      "key-auth": {
        "key": "jane-key"
      }
    }
  }'

创建一个带有 key-auth 和 limit-req 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "limit-req-route",
    "uri": "/get",
    "plugins": {
      "key-auth": {},
      "limit-req": {
        "rate": 1,
        "burst": 0,
        "key": "$remote_addr $consumer_name",
        "key_type": "var_combination",
        "rejected_code": 429,
        "policy": "local"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

❶ key-auth：在路由上启用 key 认证。

❷ key：设置为 $remote_addr $consumer_name，以按远程地址和消费者应用速率限制配额。

❸ key_type：设置为 var_combination，以将 key 解释为变量的组合。

同时发送两个请求，每个请求针对一个消费者：

curl -i "http://127.0.0.1:9080/get" -H 'apikey: jane-key' & \
curl -i "http://127.0.0.1:9080/get" -H 'apikey: john-key' &

你应该会收到两个请求的 HTTP/1.1 200 OK，表明请求未超过每个消费者的阈值。

如果你在同一秒内以任一消费者身份发送更多请求，应该会收到 HTTP/1.1 429 Too Many Requests 响应。

这验证了插件通过变量组合 remote_addr 和 consumer_name 进行速率限制。