limit-count插件
更新时间 2026-04-21 15:50:35
最近更新时间: 2026-04-21 15:50:35
本文将详细介绍limit-count插件功能、配置和使用。
功能说明
limit-count 插件使用固定时间窗口算法，主要用于限制单个客户端在指定的时间范围内对服务的总请求数，并且会在 HTTP 响应头中返回剩余可以请求的个数.
注意：limit-count 插件的速率限制策略默认是针对单个实例节点，即按照实例节点上的请求数来计数，当存在节点达到数量阈值后请求会被拒绝。如果想对实例集群限速，则policy需指定为redis，并填写redis相关配置信息。
配置字段
| 名称 | 类型 | 填写要求 | 默认值 | 有效值 | 描述 |
|---|---|---|---|---|---|
| count | integer | 必填 | count> 0 | 每个客户端在指定时间窗口内的总请求数量阈值。 | |
| time_window | integer | 必填 | time_window> 0 | 时间窗口的大小（以秒为单位）。超过该属性定义的时间，则会重新开始计数。 | |
| rejected_code | integer | 可选 | 429 | [200,599] | 当请求超过阈值被拒绝时，返回的 HTTP 状态码。 |
| key_type | string | 可选 | "var" | ["var", "var_combination", "constant"] | key 的类型。 |
| key | string | 可选 | "remote_addr" | 用来做请求计数的依据。如果 key_type 为 var，则 key 将被解释为变量。变量不需要以美元符号（$）为前缀。如果 key_type 为 var_combination，那么 key 会被当作变量组合，所有变量都应该以美元符号 ($) 为前缀。如 $remote_addr $consumer_name，插件会同时受 $remote_addr 和 $consumer_name 两个变量的约束；如果 key_type 为 constant，那么 key 会被当作常量。如果 key 的值为空，$remote_addr 会被作为默认 key。 | |
| rejected_msg | string | 可选 | 非空 | 当请求超过阈值被拒绝时，返回的响应体。 | |
| show_limit_quota_header | boolean | 可选 | true | 当设置为 true 时，在响应头中显示 X-RateLimit-Limit（限制的总请求数）和 X-RateLimit-Remaining（剩余还可以发送的请求数）字段。 | |
| group | string | 可选 | 非空 | 对多个API设置相同 group，则路由可以共享相同的速率限制计数器。注意同一个group下的插件配置值需相同。 | |
| policy | string | 可选 | "local" | ["local","redis"] | 速率限制计数器的策略。如果是 local，则计数器存储在本地内存中，按照单个实例节点计数。如果是 redis，则计数器存储在 Redis 实例上，按照实例集群计数。 |
| redis_host | string | 当 policy 为 redis 时必填 | Redis 节点的地址。 | ||
| redis_port | integer | 当 policy 为 redis 时必填 | 6379 | [1,65535] | Redis 节点的端口。 |
| redis_username | string | 可选 | 如果使用 Redis ACL，则为 Redis 的用户名。如果使用旧式身份验证方法 requirepass，则仅配置 redis_password。 | ||
| redis_password | string | 可选 | Redis 节点的密码。 |
配置示例
limit-count 使用示例
count: 2
time_window: 60
rejected_code: 429根据该配置场景，其限制了 60 秒内请求只能访问 2 次。请求以下路由
curl -i http://example.com/index.html在执行测试命令的前两次都会正常访问。其中响应头中包含了 X-RateLimit-Limit 和 X-RateLimit-Remaining 和 X-RateLimit-Reset 字段，分别代表限制的总请求数和剩余还可以发送的请求数以及计数器剩余重置的秒数：
HTTP/1.1 200 OK
......
X-RateLimit-Limit: 2
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 58当第三次进行测试访问时，会收到包含 503 HTTP 状态码的响应头，目前在拒绝的情况下，也会返回相关的头，表示插件生效：
HTTP/1.1 503 Service Temporarily Unavailable
......
X-RateLimit-Limit: 2
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 58配置模板
基础配置案例
# [必填]时间窗口内的请求数量阈值。
count: 30
# [必填]时间窗口的大小（以秒为单位）
time_window: 60
# [可选]请求超过阈值被拒绝时，返回的 HTTP 状态码
#rejected_code: 429
# [可选]当设置rejected_msg时，非空。默认可不填
# rejected_msg: "Requests are too frequent, please try again later."
