# Limit Count 配置选项

limit-count 插件使用固定窗口或滑动窗口实施 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)。

* count

  integer | string

  有效值：

  大于 0

  ***

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

  字符串值可以通过在变量前添加美元符号（`$`）来引用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。自 API7 企业版 3.9.14 和 3.10.1 以及 APISIX 3.16.0 起引入。更早的版本仅接受整数值。

  未配置 `rules` 时，此字段必须与 `time_window` 一起配置。不要同时配置 `count` 或 `time_window` 与 `rules`。

  字符串值必须解析为不大于 `9007199254740991` 的正整数。无效值会返回 `500 Internal Server Error`，除非 `allow_degradation` 为 `true`。自 API7 企业版 3.9.16 和 3.10.2 以及 APISIX 3.18.0 起引入。

* time\_window

  integer | string

  有效值：

  大于 0

  ***

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

  字符串值可以通过在变量前添加美元符号（`$`）来引用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。自 API7 企业版 3.9.14 和 3.10.1 以及 APISIX 3.16.0 起引入。更早的版本仅接受整数值。

  未配置 `rules` 时，此字段必须与 `count` 一起配置。不要同时配置 `count` 或 `time_window` 与 `rules`。

  字符串值必须解析为不大于 `9007199254740991` 的正整数。无效值会返回 `500 Internal Server Error`，除非 `allow_degradation` 为 `true`。自 API7 企业版 3.9.16 和 3.10.2 以及 APISIX 3.18.0 起引入。

* 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/apisix/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`

  ***

  速率限制计数器的策略。API7 企业版中为必填项，APISIX 中为可选项。

  限速计数器的策略。如果为 `local`，则计数器存储在本地内存中。如果为 `redis`，则计数器存储在 Redis 实例上。如果为 `redis-cluster`，则计数器存储在 Redis 集群中。如果为 `redis-sentinel`，则计数器存储在由 Redis Sentinel 管理的 Redis 节点上，以实现高可用。

  `redis-sentinel` 通过由 Sentinel 管理的故障转移提供高可用性。自 API7 企业版 3.9.14 和 3.10.1 以及 APISIX 3.18.0 起引入。

* window\_type

  string

  默认值：`fixed`

  有效值：

  `fixed` 或 `sliding`

  ***

  限速窗口算法。如果为 `fixed`，则使用固定窗口算法，每个时间窗口独立地实施配额。如果为 `sliding`，则使用滑动窗口算法，在计算当前计数时对上一个窗口进行加权，从而平滑窗口边界处的突发流量。

  自 API7 企业版 3.9.14 和 3.10.1 以及 APISIX 3.18.0 起引入。

* sync\_interval

  number

  默认值：`-1`

  有效值：

  `-1`，或大于或等于 `0.1`；必须小于数值类型的顶层 `time_window`

  ***

  将本地计数器同步到共享存储（Redis）的时间间隔（以秒为单位）。仅当 `policy` 为 `redis`、`redis-cluster` 或 `redis-sentinel` 时生效。取值为 `-1` 时禁用延迟同步，每个请求都直接同步。启用时，取值不应小于 `0.1` 且应小于 `time_window`。启用延迟同步可减少访问共享存储的往返次数，但代价是限速实施略微宽松。

  运行时，如果适用的 `time_window` 小于或等于 `sync_interval`，网关会对该请求回退为直接同步。这可能发生在请求时求值的变量解析值或 `rules` 内的值上。

  自 API7 企业版 3.9.14 和 3.10.1 以及 APISIX 3.18.0 起引入。

* allow\_degradation

  boolean

  默认值：`false`

  ***

  如果为 true，则在计数器后端失败，或变量解析的 `count` 或 `time_window` 无效时，继续处理请求但不进行速率限制。如果为 false，这些失败会返回 `500 Internal Server Error`。

* show\_limit\_quota\_header

  boolean

  默认值：`true`

  ***

  如果为 true，则在响应中包含配额响应头。

  使用默认名称时，`X-RateLimit-Limit` 表示总配额，`X-RateLimit-Remaining` 表示窗口内剩余的请求数，`X-RateLimit-Reset` 表示算法特定的重置或延迟值（秒）。

  可以通过插件元数据重命名这些响应头。配置 `rules` 时，每条规则会在 `RateLimit-` 前插入其 `header_prefix`（省略时使用规则索引），使各规则的 Limit、Remaining 和 Reset 保持可区分。请参阅 `rules.header_prefix`。

* group

  string

  有效值：

  非空

  ***

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

* redis\_host

  string

  ***

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

* redis\_port

  integer

  默认值：`6379`

  有效值：

  大于或等于 1

  ***

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

* redis\_username

  string

  ***

  如果使用 Redis ACL，则为 Redis 用户名。如果你使用传统的身份验证方法 `requirepass`，请仅配置 `redis_password`。当 `policy` 为 `redis` 或 `redis-sentinel` 时使用。

* redis\_password

  string

  ***

  当 `policy` 为 `redis`、`redis-cluster` 或 `redis-sentinel` 时 Redis 节点的密码。该密码在 API7 企业版中静态加密。在 APISIX 中，请[启用数据加密](https://docs.apiseven.com/apisix/production/security/data-encryption-with-keyring.md)，使其在存储到 etcd 前加密。加密功能自 API7 企业版 3.9.16 和 3.10.2 以及 APISIX 3.18.0 起引入。

* redis\_database

  integer

  默认值：`0`

  有效值：

  大于或等于 0

  ***

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

* redis\_ssl

  boolean

  默认值：`false`

  ***

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

* redis\_ssl\_verify

  boolean

  默认值：`false`

  ***

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

* redis\_server\_name

  string

  ***

  用于 SNI 的 TLS 服务器名称；启用证书验证时，也用于主机名验证。适用于 `policy` 为 `redis` 且 `redis_ssl` 为 `true` 的情况。默认为 `redis_host`。所选值为 IP 地址时，不发送服务器名称。若通过 IP 地址连接但需要验证 DNS 名称证书，请将该字段设为证书中的 DNS 名称，并启用 `redis_ssl_verify`。

  该字段在 API7 企业版 3.9.21、3.10.8 和 APISIX 3.19.0 中引入。该字段适用于单节点 Redis 连接器，不适用于 Redis Cluster 或 Sentinel。

* redis\_timeout

  integer

  默认值：`1000`

  有效值：

  大于或等于 1

  ***

  当 `policy` 为 `redis` 或 `redis-cluster` 时的 Redis 超时值（以毫秒为单位）。

* redis\_keepalive\_timeout

  integer

  有效值：

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

  ***

  Redis 连接的保活超时时间（毫秒）。当 `policy` 为 `redis` 或 `redis-cluster` 时，默认值为 `10000`，最小值为 `1000`；当 `policy` 为 `redis-sentinel` 时，默认值为 `60000`，最小值为 `1`。

  自 API7 企业版 3.9.16 和 3.10.3 以及 APISIX 3.15.0 起引入。Sentinel 默认值自 API7 企业版 3.9.14 和 3.10.1 以及 APISIX 3.18.0 起引入。

* redis\_keepalive\_pool

  integer

  默认值：`100`

  有效值：

  大于或等于 1

  ***

  当 `policy` 为 `redis` 或 `redis-cluster` 时的 Redis keepalive 连接池大小。

  此参数自 API7 企业版 3.9.16 和 3.10.3 以及 APISIX 3.15.0 起可用。

* 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 证书。

* redis\_sentinels

  array\[object]

  ***

  Redis Sentinel 节点列表，至少包含一个节点。当 `policy` 为 `redis-sentinel` 时必填。每个节点为一个对象，包含 `host`（字符串）和 `port`（介于 1 到 65535 之间的整数）。

  自 API7 企业版 3.9.14 和 3.10.1 以及 APISIX 3.18.0 起可用。

* redis\_master\_name

  string

  ***

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

  自 API7 企业版 3.9.14 和 3.10.1 以及 APISIX 3.18.0 起可用。

* redis\_role

  string

  默认值：`master`

  有效值：

  `master` 或 `slave`

  ***

  当 `policy` 为 `redis-sentinel` 时要连接的 Redis 节点角色。使用 `master` 进行读写操作，或使用 `slave` 连接只读副本。

  自 API7 企业版 3.9.14 和 3.10.1 以及 APISIX 3.18.0 起可用。

* redis\_connect\_timeout

  integer

  默认值：`1000`

  有效值：

  大于或等于 1

  ***

  当 `policy` 为 `redis-sentinel` 时的连接超时时间（以毫秒为单位）。

  自 API7 企业版 3.9.14 和 3.10.1，以及 APISIX 3.18.0 起可用。

* redis\_read\_timeout

  integer

  默认值：`1000`

  有效值：

  大于或等于 1

  ***

  当 `policy` 为 `redis-sentinel` 时的读取超时时间（以毫秒为单位）。

  自 API7 企业版 3.9.14 和 3.10.1，以及 APISIX 3.18.0 起可用。

* sentinel\_username

  string

  ***

  当 `policy` 为 `redis-sentinel` 时用于向 Redis Sentinel 节点进行身份验证的用户名。

  自 API7 企业版 3.9.14 和 3.10.1，以及 APISIX 3.18.0 起可用。

* sentinel\_password

  string

  ***

  当 `policy` 为 `redis-sentinel` 时用于向 Redis Sentinel 节点进行身份验证的密码。

  自 API7 企业版 3.9.14 和 3.10.1 以及 APISIX 3.18.0 起引入。

  该密码在 API7 企业版中静态加密。在 APISIX 中，请[启用数据加密](https://docs.apiseven.com/apisix/production/security/data-encryption-with-keyring.md)，使其在存储到 etcd 前加密。加密功能自 API7 企业版 3.9.16 和 3.10.2 以及 APISIX 3.18.0 起引入。

* rules

  array\[object]

  ***

  按顺序应用的速率限制规则数组。不要同时配置 `rules` 与顶层 `count`、`time_window` 或 `group` 字段。规则模式不使用顶层 `key` 和 `key_type`。规则的键必须唯一。如果请求中不存在规则的 `key` 变量，则跳过该规则。

  自 API7 企业版 3.9.14 和 3.10.1 以及 APISIX 3.16.0 起引入。

  * count

    integer | string

    必填

    有效值：

    大于 0

    ***

    给定 `time_window` 内允许的最大请求数。

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

    字符串值必须解析为不大于 `9007199254740991` 的正整数。如果规则适用但值无效，请求会返回 `500 Internal Server Error`，除非 `allow_degradation` 为 `true`。自 API7 企业版 3.9.16 和 3.10.2 以及 APISIX 3.18.0 起引入。

  * time\_window

    integer | string

    必填

    有效值：

    大于 0

    ***

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

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

    字符串值必须解析为不大于 `9007199254740991` 的正整数。如果规则适用但值无效，请求会返回 `500 Internal Server Error`，除非 `allow_degradation` 为 `true`。自 API7 企业版 3.9.16 和 3.10.2 以及 APISIX 3.18.0 起引入。

  * key

    string

    必填

    ***

    解析为此规则请求计数键的变量表达式。每个 APISIX [内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)或 NGINX 变量都必须以美元符号（`$`）开头，例如 `$remote_addr` 或 `$remote_addr $http_x_tenant`。

    顶层 `key_type` 不适用于规则。无法解析变量的规则会针对该请求被跳过。

  * header\_prefix

    string

    ***

    插入到此规则配额响应头中 `RateLimit-` 之前的前缀，使每条规则保持可区分。使用默认名称时，`foo` 会生成 `X-foo-RateLimit-Limit`、`X-foo-RateLimit-Remaining` 和 `X-foo-RateLimit-Reset`。这些响应头仍分别表示总配额、剩余配额以及由限流算法决定的重置或延迟时间（秒）。省略时使用规则的数组索引，因此第一条规则会生成 `X-1-RateLimit-Limit`。仅在 `show_limit_quota_header` 为 `true` 时发送。

## 插件元数据[​](#插件元数据 "插件元数据的直接链接")

* limit\_header

  string

  默认值：`X-RateLimit-Limit`

  ***

  表示速率限制总配额的默认响应头名称。

* remaining\_header

  string

  默认值：`X-RateLimit-Remaining`

  ***

  表示速率限制剩余配额的默认响应头名称。

* reset\_header

  string

  默认值：`X-RateLimit-Reset`

  ***

  用于报告由限流算法决定的重置或延迟时间（秒）的默认响应头名称。

## 相关变量[​](#相关变量 "相关变量的直接链接")

该插件会在 `$rate_limiting_info` 中记录每个请求的评估结果，你可以将其添加到访问日志中。有关 Limit Count 的字段，请参阅[限流信息](https://docs.apiseven.com/hub/limit-count-rate-limiting-info.md)；有关其他限流插件，请参阅 [API7 Gateway 内置变量参考](https://docs.apiseven.com/api7-gateway/reference/built-in-variables.md#rate-limiting-information)。
