跳到主要内容

limit-count

limit-count 插件使用固定窗口算法，根据给定时间间隔内的请求数量来限制请求速率。超过配置配额的请求将被拒绝。

你可能会在响应中看到以下限速响应头：

  • X-RateLimit-Limit: 总配额
  • X-RateLimit-Remaining: 剩余配额
  • X-RateLimit-Reset: 计数器重置前的剩余秒数

如果你使用的是 API7 企业版，可以通过插件元数据自定义这些响应头的名称。

备注

自 API7 企业版 version 3.9.14 起，高级限速能力已直接内置于 limit-count，包括用于高可用的 redis-sentinel 策略、在窗口边界处实施更平滑的 sliding window_type、通过 sync_interval 实现的延迟同步、通过 rules 数组配置多条限速规则，以及从请求变量派生 count。独立的 limit-count-advanced 插件仍保留以实现向后兼容。

示例​

以下示例展示了如何在不同场景下配置 limit-count。

根据远程地址进行限速​

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

创建一个使用 limit-count 插件的路由，允许每个远程地址在 30 秒窗口内请求 1 次：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route",
    "uri": "/get",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "key_type": "var",
        "key": "remote_addr"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

发送请求以验证：

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

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

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

使用滑动窗口进行限速​

以下示例演示了如何通过将 window_type 设置为 sliding 来使用滑动窗口算法（自 API7 企业版 version 3.9.14 起可用）。与默认的固定窗口相比，滑动窗口在计算当前请求计数时对上一个窗口进行加权，从而平滑窗口边界处的突发流量。

创建一个使用 limit-count 插件的路由，允许每个远程地址在 30 秒滑动窗口内请求 10 次：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route",
    "uri": "/get",
    "plugins": {
      "limit-count": {
        "count": 10,
        "time_window": 30,
        "rejected_code": 429,
        "key_type": "var",
        "key": "remote_addr",
        "policy": "local",
        "window_type": "sliding"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

发送请求以验证：

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

你应该会看到 HTTP/1.1 200 OK 响应。当你持续发送请求时，滑动窗口会在连续窗口的边界处比固定窗口更均匀地实施配额。

根据远程地址和消费者名称进行限速​

以下示例演示了如何通过变量组合 remote_addr 和 consumer_name 对请求进行限速。它允许每个远程地址和每个 Consumer 在 30 秒窗口内请求 1 次。

创建一个消费者 john：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_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_API_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_API_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_API_KEY}" \
  -d '{
    "id": "cred-jane-key-auth",
    "plugins": {
      "key-auth": {
        "key": "jane-key"
      }
    }
  }'

创建一个启用 key-auth 和 limit-count 插件的路由：

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

❶ key-auth: 在路由上启用密钥认证。

❷ key_type: 设置为 var_combination 以将 key 解释为变量组合。

❸ key: 设置为 $remote_addr $consumer_name 以根据远程地址和消费者应用限速配额。

以消费者 jane 的身份发送请求：

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

你应该会看到带有相应响应体的 HTTP/1.1 200 OK 响应。

此请求已消耗了该时间窗口的所有配额。如果你在同一个 30 秒时间间隔内再次以消费者 jane 的身份发送相同的请求，应该会收到 HTTP/1.1 429 Too Many Requests 响应，表明请求超过了配额阈值。

在同一个 30 秒时间间隔内以消费者 john 的身份发送相同的请求：

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

你应该会看到带有相应响应体的 HTTP/1.1 200 OK 响应，表明该请求未被限速。

在同一个 30 秒时间间隔内再次以消费者 john 的身份发送相同的请求，你应该会收到 HTTP/1.1 429 Too Many Requests 响应。

这验证了插件根据变量组合 remote_addr 和 consumer_name 进行限速。

在路由间共享配额​

以下示例演示了如何通过配置 limit-count 插件的 group 来在多个路由之间共享限速配额。

请注意，同一 group 的 limit-count 插件配置应完全相同。为了避免更新异常和重复配置，你可以创建一个包含 limit-count 插件和上游的 Service，供路由连接。

创建一个服务：

curl "http://127.0.0.1:9180/apisix/admin/services" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-service",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "group": "srv1"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

创建两个路由并将它们的 service_id 配置为 limit-count-service，以便它们共享插件和上游的相同配置：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route-1",
    "service_id": "limit-count-service",
    "uri": "/get1",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/get"
      }
    }
  }'
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route-2",
    "service_id": "limit-count-service",
    "uri": "/get2",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/get"
      }
    }
  }'
备注

proxy-rewrite 插件用于将 URI 重写为 /get，以便将请求转发到正确的端点。

向路由 /get1 发送请求：

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

你应该会看到带有相应响应体的 HTTP/1.1 200 OK 响应。

在同一个 30 秒时间间隔内向路由 /get2 发送相同的请求：

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

你应该会收到 HTTP/1.1 429 Too Many Requests 响应，这验证了两个路由共享相同的限速配额。

使用 Redis 服务器在 APISIX 节点间共享配额​

以下示例演示了如何使用 Redis 服务器在多个 APISIX 节点之间进行限速，以便不同的 APISIX 节点共享相同的限速配额。

在每个 APISIX 实例上，使用以下配置创建一个路由。请相应调整 Admin API 的地址。

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route",
    "uri": "/get",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "key": "remote_addr",
        "policy": "redis",
        "redis_host": "192.168.xxx.xxx",
        "redis_port": 6379,
        "redis_password": "p@ssw0rd",
        "redis_database": 1
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

❶ policy: 设置为 redis 以使用 Redis 实例进行限速。

❷ redis_host: 设置为 Redis 实例的 IP 地址。

❸ redis_port: 设置为 Redis 实例的监听端口。

❹ redis_password: 设置为 Redis 实例的密码（如果有）。

❺ redis_database: 设置为 Redis 实例中的数据库编号。

向一个 APISIX 实例发送请求：

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

你应该会看到带有相应响应体的 HTTP/1.1 200 OK 响应。

在同一个 30 秒时间间隔内向另一个 APISIX 实例发送相同的请求，你应该会收到 HTTP/1.1 429 Too Many Requests 响应，验证了在不同 APISIX 节点中配置的路由共享相同的配额。

使用 Redis 集群在 APISIX 节点间共享配额​

你还可以使用 Redis 集群在多个 APISIX 节点之间应用相同的配额，以便不同的 APISIX 节点共享相同的限速配额。

确保你的 Redis 实例以集群模式运行。limit-count 插件配置至少需要两个节点。

在每个 APISIX 实例上，使用以下配置创建一个路由。请相应调整 Admin API 的地址。

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route",
    "uri": "/get",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "key": "remote_addr",
        "policy": "redis-cluster",
        "redis_cluster_nodes": [
          "192.168.xxx.xxx:6379",
          "192.168.xxx.xxx:16379"
        ],
        "redis_password": "p@ssw0rd",
        "redis_cluster_name": "redis-cluster-1",
        "redis_cluster_ssl": true
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

❶ policy: 设置为 redis-cluster 以使用 Redis 集群进行限速。

❷ redis_cluster_nodes: 设置为 Redis 集群中的 Redis 节点地址。

❸ redis_password: 设置为 Redis 集群的密码（如果有）。

❹ redis_cluster_name: 设置为 Redis 集群名称。

❺ redis_cluster_ssl: 启用与 Redis 集群的 SSL/TLS 通信。

向一个 APISIX 实例发送请求：

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

你应该会看到带有相应响应体的 HTTP/1.1 200 OK 响应。

在同一个 30 秒时间间隔内向另一个 APISIX 实例发送相同的请求，你应该会收到 HTTP/1.1 429 Too Many Requests 响应，验证了在不同 APISIX 节点中配置的路由共享相同的配额。

使用 Redis Sentinel 在 APISIX 节点间共享配额​

自 API7 企业版 version 3.9.14 起，你还可以使用由 Redis Sentinel 管理的 Redis 节点在多个 APISIX 节点之间应用相同的配额，通过主节点自动故障转移实现高可用。

在每个 APISIX 实例上，使用以下配置创建一个路由。请相应调整配置细节。

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route",
    "uri": "/get",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "key": "remote_addr",
        "policy": "redis-sentinel",
        "redis_sentinels": [
          { "host": "192.168.xxx.xxx", "port": 26379 },
          { "host": "192.168.xxx.xxx", "port": 26380 }
        ],
        "redis_master_name": "mymaster",
        "sentinel_username": "sentinel-user",
        "sentinel_password": "p@ssw0rd",
        "redis_database": 1
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

其中：

  • policy 设置为 redis-sentinel 以使用由 Redis Sentinel 管理的 Redis 节点。
  • redis_sentinels 列出 Sentinel 节点，每个节点包含 host 和 port。
  • redis_master_name 是 Sentinel 监控的主节点名称。
  • sentinel_username 和 sentinel_password 用于向 Sentinel 节点进行身份验证（如有需要）。

向一个 APISIX 实例发送请求：

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

你应该会看到带有相应响应体的 HTTP/1.1 200 OK 响应。

在同一个 30 秒时间间隔内向另一个 APISIX 实例发送相同的请求，你应该会收到 HTTP/1.1 429 Too Many Requests 响应，验证了在不同 APISIX 节点中配置的路由共享相同的配额。

对匿名消费者进行限速​

以下示例演示了如何为常规消费者和匿名消费者配置不同的限速策略，其中匿名消费者不需要身份验证且配额较少。虽然此示例使用 key-auth 进行身份验证，但匿名消费者也可以通过 basic-auth、jwt-auth 和 hmac-auth 进行配置。

创建常规消费者 john 并配置 limit-count 插件，允许 30 秒窗口内有 3 次配额：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "john",
    "plugins": {
      "limit-count": {
        "count": 3,
        "time_window": 30,
        "rejected_code": 429
      }
    }
  }'

为消费者 john 创建 key-auth 凭据：

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

创建匿名用户 anonymous 并配置 limit-count 插件，允许 30 秒窗口内有 1 次配额：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "anonymous",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429
      }
    }
  }'

创建一个路由并配置 key-auth 插件，以接受匿名消费者 anonymous 绕过身份验证：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "key-auth-route",
    "uri": "/anything",
    "plugins": {
      "key-auth": {
        "anonymous_consumer": "anonymous"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

要进行验证，请使用 john 的密钥发送五个连续请求：

resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/anything" -H 'apikey: john-key' -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": $count_200, "429": $count_429

你应该会看到以下响应，显示在 5 个请求中，3 个请求成功（状态码 200），而其他请求被拒绝（状态码 429）。

200:    3, 429:    2

发送五个匿名请求：

resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/anything" -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": $count_200, "429": $count_429

你应该会看到以下响应，显示只有一个请求成功：

200:    1, 429:    4

自定义限速响应头​

以下示例演示了如何使用插件元数据自定义限速响应头名称，默认情况下为 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset。

配置此插件的插件元数据并更新响应头：

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/limit-count" -X PUT -d '
{
  "log_format": {
    "limit_header": "X-Custom-RateLimit-Limit",
    "remaining_header": "X-Custom-RateLimit-Remaining",
    "reset_header": "X-Custom-RateLimit-Reset"
  }
}'

创建一个使用 limit-count 插件的路由，允许每个远程地址在 30 秒窗口内请求 1 次：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route",
    "uri": "/get",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "key_type": "var",
        "key": "remote_addr"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

发送请求以验证：

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

你应该会收到 HTTP/1.1 200 OK 响应并看到以下响应头：

X-Custom-RateLimit-Limit: 1
X-Custom-RateLimit-Remaining: 0
X-Custom-RateLimit-Reset: 28