# Limit Conn 配置选项

Limit Conn 插件会延迟或拒绝 APISIX 和 API7 网关中过量的 HTTP、WebSocket 和 TCP 并发连接，防止服务过载。<!-- --> <!-- -->配置涵盖Stream 路由字段和HTTP 路由字段。

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

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

### Stream 路由参数[​](#stream-路由参数 "Stream 路由参数的直接链接")

* conn

  integer

  必填

  有效值：

  大于 0

  ***

  每个解析后的 Key 无需延迟即可使用的并发 Stream 连接数。

* burst

  integer

  必填

  有效值：

  大于或等于 0

  ***

  允许等待的额外并发连接数。超过 `conn + burst` 的连接会通过关闭 Stream 被拒绝。

* default\_conn\_delay

  number

  必填

  有效值：

  大于 0

  ***

  连接数高于 `conn` 且不超过 `conn + burst` 时的基础延迟秒数。延迟时间按 `default_conn_delay × floor((当前连接数 - 1) / conn)` 计算。小于 0.001 秒的延迟不会生效。

* only\_use\_default\_delay

  boolean

  默认值：`false`

  ***

  在 Stream 路由上，连接延迟不会更新该延迟值，因此此设置不会改变 Stream 行为。

* key\_type

  string

  默认值：`var`

  有效值：

  `var` 或 `var_combination`

  ***

  `key` 是指定单个 Stream 变量（`var`），还是组合多个 Stream 变量（`var_combination`）。

* key

  string

  必填

  ***

  用于对连接计数器分组的 Key。

  使用 `key_type: var` 时省略美元符号，例如 `remote_addr`。如果该变量没有值，APISIX 会回退到 `remote_addr`。

  使用 `key_type: var_combination` 时，为每个变量添加美元符号前缀，例如 `$remote_addr $server_addr`。

### HTTP 路由参数[​](#http-路由参数 "HTTP 路由参数的直接链接")

备注

对于 HTTP 路由，在 API7 企业版 3.8.17 及更高版本和 Apache APISIX 3.16.0 及更高版本中，请配置以下两组参数之一，不要同时配置：

* `conn`, `burst`, `default_conn_delay`, `key`
* `rules`, `default_conn_delay`

- conn

  integer | string

  有效值：

  大于 0

  ***

  允许的最大并发请求数。超过此配置限制但低于 `conn + burst` 的请求将被延迟处理。

  字符串值可以通过在变量名前添加美元符号（`$`）来引用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。字符串解析结果必须为不大于 `9007199254740991` 的正整数。解析失败或结果无效时，除非启用降级，否则网关返回 `500 Internal Server Error`。

  字符串值支持自 API7 企业版 3.8.17 和 APISIX 3.16.0 起提供。上述校验要求自 API7 企业版 3.9.14、3.10.1 和 APISIX 3.17.0 起提供。更早的 APISIX 版本仅接受整数值。

  未配置 `rules` 时，必须与 `burst`、`key` 一起配置。配置 `rules` 后，请勿同时配置这些顶层字段。

- burst

  integer | string

  有效值：

  大于或等于 0

  ***

  允许延迟处理的额外并发请求数。超过 `conn + burst` 的请求将被立即拒绝。

  字符串值可以通过在变量名前添加美元符号（`$`）来引用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。字符串解析结果必须为不大于 `9007199254740991` 的非负整数。解析失败或结果无效时，除非启用降级，否则网关返回 `500 Internal Server Error`。

  字符串值支持自 API7 企业版 3.8.17 和 APISIX 3.16.0 起提供。上述校验要求自 API7 企业版 3.9.14、3.10.1 和 APISIX 3.17.0 起提供。更早的 APISIX 版本仅接受整数值。

  未配置 `rules` 时，必须与 `conn`、`key` 一起配置。配置 `rules` 后，请勿同时配置这些顶层字段。

- default\_conn\_delay

  number

  必填

  有效值：

  大于 0

  ***

  并发请求数高于 `conn` 且不超过 `conn + burst` 时的基础延迟（秒）。延迟时间按 `default_conn_delay × floor((当前并发请求数 - 1) / conn)` 计算。小于 0.001 秒的延迟不会生效。

- only\_use\_default\_delay

  boolean

  默认值：`false`

  ***

  如果为 `true`，请求完成后不向限流器反馈请求延迟。如果为 `false`，则将观测到的延迟传给限流器。

  在 APISIX 3.19.0 和 API7 网关 3.9.21、3.10.8 中，该设置的两个取值都不会改变后续请求的延迟。每个请求均使用 `default_conn_delay` 作为延迟单位。

  无论此项如何设置，超过 `conn + burst` 的请求都会立即被拒绝。

- key\_type

  string

  默认值：`var`

  有效值：

  `var` 或 `var_combination`

  ***

  键的类型。

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

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

- key

  string

  ***

  用于统计请求的键。

  如果 `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`。

  未配置 `rules` 时，必须与 `conn`、`burst` 一起配置。配置 `rules` 后，请勿同时配置这些顶层字段。

- rejected\_code

  integer

  默认值：`503`

  有效值：

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

  ***

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

- rejected\_msg

  string

  有效值：

  任意非空字符串

  ***

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

- allow\_degradation

  boolean

  默认值：`false`

  ***

  如果为 true，当插件或其依赖项不可用时，允许网关在没有该插件的情况下继续处理请求。

- rules

  array\[object]

  ***

  按顺序应用的限流规则数组。

  规则支持自 API7 企业版 3.8.17 和 APISIX 3.16.0 起提供。

  * conn

    integer | string

    必填

    有效值：

    大于 0

    ***

    允许的最大并发请求数。超过此配置限制但低于 `conn + burst` 的请求将被延迟处理。

    字符串值可以通过在变量名前添加美元符号（`$`）来引用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。字符串解析结果必须为不大于 `9007199254740991` 的正整数。

    字符串值校验自 API7 企业版 3.9.14、3.10.1 和 APISIX 3.17.0 起提供。

  * burst

    integer | string

    必填

    有效值：

    大于或等于 0

    ***

    允许延迟处理的额外并发请求数。超过 `conn + burst` 的请求将被立即拒绝。

    字符串值可以通过在变量名前添加美元符号（`$`）来引用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。字符串解析结果必须为不大于 `9007199254740991` 的非负整数。

    字符串值校验自 API7 企业版 3.9.14、3.10.1 和 APISIX 3.17.0 起提供。

  * key

    string

    必填

    ***

    用于解析出本规则计数键的变量表达式。每个变量都需以 `$` 为前缀，支持 `$variable` 和 `${variable}` 两种写法。例如，`${http_custom_a}` 或 `${http_custom_a}_${http_custom_b}`。

    顶层 `key_type` 对规则无效。至少有一个变量引用解析到请求中的值或其 `??` 默认值时，才应用该规则。缺失且无默认值的变量产生空字符串，不计为已解析；表达式中的其他变量解析成功时，规则仍可生效。若没有变量解析成功，包括表达式未引用变量的情况，则跳过该规则。

    已配置 `rules` 且请求不适用任何规则时，网关默认返回 HTTP 500。将 `allow_degradation` 设为 `true` 可让请求继续处理，跳过连接限流。

    在 ADC 配置中，请将简单名称的网关表达式转义，例如把 `${http_user}` 写为 `${http_user}`。对于未转义且名称只含单词字符的 `${NAME}`，ADC 会在加载时进行环境变量插值。带点号的网关变量名会原样传递。

- policy

  string

  默认值：`local`

  有效值：

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

  ***

  限流计数器的策略。如果是 `local`，计数器存储在本地内存中。如果是 `redis`，计数器存储在 Redis 实例上。如果是 `redis-cluster`，计数器存储在 Redis 集群中。

  在 API7 企业版中，此字段自 3.9.0 起为必填项；在 APISIX 中为可选项。

- 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\_password

  string

  ***

  当 `policy` 为 `redis` 或 `redis-cluster` 时 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 中的数据库编号。

- 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

  默认值：`10000`

  有效值：

  大于或等于 1000

  ***

  当 `policy` 为 `redis` 或 `redis-cluster` 时 Redis 的保活超时时间（毫秒）。

  此参数在 API7 企业版 3.9.x 系列中自 3.9.17 起可用，在 3.10.x 系列中自 3.10.4 起可用，并且在 APISIX 中自 3.15.0 起可用。

- redis\_keepalive\_pool

  integer

  默认值：`100`

  有效值：

  大于或等于 1

  ***

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

  此参数在 API7 企业版 3.9.x 系列中自 3.9.17 起可用，在 3.10.x 系列中自 3.10.4 起可用，并且在 APISIX 中自 3.15.0 起可用。

- key\_ttl

  integer

  默认值：`3600`

  ***

  当 `policy` 为 `redis` 或 `redis-cluster` 时，Redis Key 的 TTL，单位为秒。自 API7 企业版 3.9.4 和 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 证书。
