# Limit Count Advanced 配置选项

limit-count-advanced 插件使用固定窗口或滑动窗口算法实施 API 限速，在时间窗口内限制请求数量，并拒绝超出配额的请求。<!-- --> <!-- -->配置涵盖插件参数。

## 参数[​](#参数 "参数的直接链接")

有关所有插件均可使用的配置项，请参阅[插件通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md)。

该插件支持在字符串类型的配置字段中使用网关引用。使用 `$env://` 前缀引用环境变量中的值，或使用 `$secret://` 前缀引用密钥管理器中的值，例如 HashiCorp Vault 的 [KV 密钥引擎](https://developer.hashicorp.com/vault/docs/secrets/kv)。网关在运行时解析这些引用。ADC 的 `${NAME}` 插值有所不同：ADC 在同步前加载配置文件时解析插值。有关更多信息，请参阅[插件中的环境变量](https://docs.apiseven.com/apisix/reference/environment-variables.md#plugins)和[密钥](https://docs.apiseven.com/apisix/key-concepts/secrets.md)。

备注

在 API7 企业版 3.8.17 及更高版本中，请配置以下两组参数之一，不要同时配置：

* `count`, `time_window`
* `rules`

- count

  integer | string

  有效值：

  大于 0

  ***

  给定时间间隔内允许的最大请求数。

  在 API7 企业版（从 3.8.17 开始）中，此参数还支持字符串数据类型，并允许使用以美元符号（`$`）为前缀的[内置变量](https://docs.apiseven.com/api7-gateway/reference/built-in-variables.md)。

  未配置 `rules` 时，必须与 `time_window` 一起配置。不要将 `count` 或 `time_window` 与 `rules` 一起配置。

- time\_window

  integer | string

  有效值：

  大于 0

  ***

  与速率限制 `count` 对应的时间间隔，以秒为单位。

  在 API7 企业版（从 3.8.17 开始）中，此参数还支持字符串数据类型，并允许使用以美元符号（`$`）为前缀的[内置变量](https://docs.apiseven.com/api7-gateway/reference/built-in-variables.md)。

  未配置 `rules` 时，必须与 `count` 一起配置。不要将 `count` 或 `time_window` 与 `rules` 一起配置。

- window\_type

  string

  默认值：`fixed`

  有效值：

  `fixed` 或 `sliding`

  ***

  速率限制算法，固定窗口或滑动窗口。

- key\_type

  string

  默认值：`var`

  有效值：

  `var`、`var_combination` 或 `constant`

  ***

  键的类型。

  如果 `key_type` 为 `var`，则 `key` 被解释为变量。

  如果 `key_type` 为 `var_combination`，则 `key` 被解释为变量组合。

  如果 `key_type` 为 `constant`，则 `key` 被解释为常量。

- key

  string

  默认值：`remote_addr`

  ***

  用于计数请求的键。

  如果 `key_type` 为 `var`，则 `key` 被解释为变量。变量不需要以美元符号（`$`）作为前缀。查看[内置变量](https://docs.apiseven.com/api7-gateway/reference/built-in-variables.md)以获取可用变量。

  如果 `key_type` 为 `var_combination`，则 `key` 被解释为变量组合。所有变量都应以美元符号（`$`）作为前缀。例如，要将 `key` 配置为使用两个请求头 `custom-a` 和 `custom-b` 的组合，`key` 应配置为 `$http_custom_a $http_custom_b`。

  如果 `key_type` 为 `constant`，则 `key` 被解释为常量值。

- rejected\_code

  integer

  默认值：`503`

  有效值：

  介于 200 和 599 之间（含边界值）

  ***

  当请求因超过阈值而被拒绝时返回的 HTTP 状态码。

- rejected\_msg

  string

  有效值：

  任意非空字符串

  ***

  当请求因超过阈值而被拒绝时返回的响应体。

- policy

  string

  默认值：`local`

  有效值：

  `local`、`redis`、`redis-cluster` 或 `redis-sentinel`

  ***

  速率限制计数器的策略。

  设置为 `local` 以将计数器存储在本地内存中。

  设置为 `redis` 以将计数器存储在 Redis 实例中。

  设置为 `redis-cluster` 以将计数器存储在 Redis 集群中。

  设置为 `redis-sentinel` 以将计数器存储在由 Redis Sentinel 管理的 Redis 主节点上，这通过在故障时自动将副本提升为主节点来确保高可用性。当不使用 Redis Cluster 时，Redis Sentinel 为 Redis 提供高可用性。

- redis\_sentinels

  array\[object]

  ***

  Redis Sentinel 节点数组（主机和端口）。当 `policy` 为 `redis-sentinel` 时必填。

- redis\_master\_name

  string

  ***

  Sentinel 监控的 Redis 主组名称。当 `policy` 为 `redis-sentinel` 时必填。

- redis\_role

  string

  默认值：`master`

  有效值：

  `master` 或 `slave`

  ***

  要连接的 Redis 节点角色。当 `policy` 为 `redis-sentinel` 时可配置。设置为 `master` 以连接到当前的 Redis 主节点，设置为 `slave` 以连接到 Redis 副本。

- redis\_connect\_timeout

  integer

  默认值：`1000`

  有效值：

  大于或等于 1

  ***

  建立到 Redis 节点的连接的超时时间（毫秒）。当 `policy` 为 `redis-sentinel` 时可配置。

- redis\_read\_timeout

  integer

  默认值：`1000`

  有效值：

  大于或等于 1

  ***

  从 Redis 节点读取数据的超时时间（毫秒）。当 `policy` 为 `redis-sentinel` 时可配置。

- sentinel\_username

  string

  ***

  用于通过 Redis Sentinel 实例进行身份验证的用户名。当 `policy` 为 `redis-sentinel` 时可配置。

- sentinel\_password

  string

  ***

  用于通过 Redis Sentinel 实例进行身份验证的密码。当 `policy` 为 `redis-sentinel` 时可配置。

- allow\_degradation

  boolean

  默认值：`false`

  ***

  如果为 true，则在插件或其依赖项不可用时，允许网关继续处理请求而不使用该插件。

- rules

  array\[object]

  ***

  速率限制规则数组，按顺序应用。

  在 API7 企业版 3.8.17 版本中可用。

  * count

    integer | string

    必填

    有效值：

    大于 0

    ***

    给定时间间隔内允许的最大请求数。

    此参数还支持字符串数据类型，并允许使用以美元符号（`$`）为前缀的[内置变量](https://docs.apiseven.com/api7-gateway/reference/built-in-variables.md)。

  * time\_window

    integer | string

    必填

    有效值：

    大于 0

    ***

    与速率限制 `count` 对应的时间间隔，以秒为单位。

    此参数还支持字符串数据类型，并允许使用以美元符号（`$`）为前缀的[内置变量](https://docs.apiseven.com/api7-gateway/reference/built-in-variables.md)。

  * key

    string

    必填

    ***

    解析为本规则请求计数 Key 的变量表达式。每个变量都以 `$` 为前缀；支持 `$variable` 和 `${variable}` 两种形式。例如，使用 `${http_custom_a}` 或 `${http_custom_a}_${http_custom_b}`。

    顶层 `key_type` 不适用于规则。至少一个变量引用解析为请求值或其 `??` 默认值时，规则生效。没有默认值的缺失变量贡献空字符串，但不计为已解析，因此只要另一个变量成功解析，部分表达式仍可生效。没有任何已解析变量的表达式（包括不含变量引用的值）会被跳过。

    配置了 `rules`，但没有规则适用于请求时，网关默认返回 HTTP 500。将 `allow_degradation` 设置为 `true` 可使请求继续处理，而不执行限速。

    在 ADC 配置中，名称简单的网关表达式（例如 `${http_user}`）需要转义为 `${http_user}`。ADC 会将未转义且仅包含单词字符的 `${NAME}` 视为加载时的环境变量插值；包含点号的网关变量名称会原样传递。

  * header\_prefix

    string

    ***

    所有限速响应头的前缀。在 API7 企业版 3.8.19 及更高版本中提供。

    配置后，前缀插入响应头名称中的 `X-` 之后。例如，将 `header_prefix` 设置为 `test` 时，响应头变为 `X-Test-RateLimit-Limit`、`X-Test-RateLimit-Remaining` 和 `X-Test-RateLimit-Reset`。

    未配置时，使用规则在规则数组中的索引作为前缀。例如，第一条规则的响应头为 `X-1-RateLimit-Limit`、`X-1-RateLimit-Remaining` 和 `X-1-RateLimit-Reset`。

- show\_limit\_quota\_header

  boolean

  默认值：`true`

  ***

  如果为 true，则包含限速响应头。未设置 `rules` 时，具体如下：

  * `X-RateLimit-Limit` 显示总配额。
  * `X-RateLimit-Remaining` 显示剩余配额。
  * `X-RateLimit-Reset` 显示算法特定的重置或延迟值（秒）。

  <br />设置了 `rules` 时，会在 `X-` 后插入前缀及连字符。详情请参阅 `rules.header_prefix`。

- group

  string

  有效值：

  非空

  ***

  插件的 `group` ID，同一 `group` 的路由可以共享相同的速率限制计数器。

- redis\_host

  string

  ***

  Redis 节点的地址。当 `policy` 为 `redis` 时必填。

- redis\_port

  integer

  默认值：`6379`

  有效值：

  大于或等于 1

  ***

  Redis 节点的端口。当 `policy` 为 `redis` 时使用。

- redis\_username

  string

  ***

  如果使用 Redis ACL，则为 Redis 的用户名。如果你使用传统的认证方法 `requirepass`，则只需配置 `redis_password`。当 `policy` 为 `redis` 时使用。

- redis\_password

  string

  ***

  Redis 节点的密码。当 `policy` 为 `redis` 或 `redis-cluster` 时使用。

- redis\_database

  integer

  默认值：`0`

  有效值：

  大于或等于 0

  ***

  Redis 中的数据库编号。当 `policy` 为 `redis` 或 `redis-sentinel` 时使用。

- redis\_ssl

  boolean

  默认值：`false`

  ***

  如果为 true，则在 `policy` 为 `redis` 时使用 SSL 连接到 Redis。

- redis\_ssl\_verify

  boolean

  默认值：`false`

  ***

  如果为 true，则在 `policy` 为 `redis` 时验证服务器 SSL 证书。

- redis\_server\_name

  string

  ***

  当 `policy` 为 `redis` 且 `redis_ssl` 为 `true` 时，在与 Redis 的 TLS 握手中发送的服务器名称（SNI）。未设置时发送 `redis_host`，但 `redis_host` 为 IP 地址时不发送。在 API7 企业版 3.9.21 和 3.10.8 中引入。

- redis\_timeout

  integer

  默认值：`1000`

  有效值：

  大于或等于 1

  ***

  Redis 超时时间（毫秒）。当 `policy` 为 `redis` 或 `redis-cluster` 时使用。

- redis\_keepalive\_timeout

  integer

  有效值：

  对 `redis` 和 `redis-cluster` 大于或等于 1000；对 `redis-sentinel` 大于或等于 1

  ***

  空闲 Redis 连接在连接池中关闭前保持活动的时间（毫秒）。当 `policy` 为 `redis` 或 `redis-cluster` 时，默认值为 `10000`；当 `policy` 为 `redis-sentinel` 时，默认值为 `60000`。

  对 `redis` 和 `redis-cluster`，此参数在 API7 企业版 3.9.16 和 3.10.3 中引入。

- redis\_keepalive\_pool

  integer

  默认值：`100`

  有效值：

  大于或等于 1

  ***

  保活连接池中空闲 Redis 连接的最大数量。当 `policy` 为 `redis` 或 `redis-cluster` 时使用。

  此参数在 API7 企业版 3.9.16 和 3.10.3 中引入。

- redis\_cluster\_nodes

  array\[string]

  ***

  Redis 集群节点列表，至少包含两个地址。当 `policy` 为 `redis-cluster` 时必填。

- redis\_cluster\_name

  string

  ***

  Redis 集群的名称。当 `policy` 为 `redis-cluster` 时必填。

- redis\_cluster\_ssl

  boolean

  默认值：`false`

  ***

  如果为 true，则在 `policy` 为 `redis-cluster` 时使用 SSL 连接到 Redis 集群。

- redis\_cluster\_ssl\_verify

  boolean

  默认值：`false`

  ***

  如果为 true，则在 `policy` 为 `redis-cluster` 时验证服务器 SSL 证书。

- sync\_interval

  number

  默认值：`-1`

  有效值：

  大于或等于 0.1，或者使用默认值 -1

  ***

  将计数器数据同步到 Redis 的频率。仅在 API7 企业版中可用。

  `sync_interval` 值应小于 `time_window`。值 `1` 导致每秒同步计数器数据。值 `-1` 产生无变化同步行为，即每个请求都会同步计数器数据。
