跳到主要内容

Limit Conn 配置选项

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

参数​

有关所有插件均可使用的配置项,请参阅插件通用配置。

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 路由,在 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 的请求将被延迟处理。

    字符串值可以通过在变量名前添加美元符号($)来引用内置变量。字符串解析结果必须为不大于 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 的请求将被立即拒绝。

    字符串值可以通过在变量名前添加美元符号($)来引用内置变量。字符串解析结果必须为不大于 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 被解释为一个变量。变量不需要以美元符号 ($) 为前缀。可用的变量请参见内置变量。

    如果 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 的请求将被延迟处理。

      字符串值可以通过在变量名前添加美元符号($)来引用内置变量。字符串解析结果必须为不大于 9007199254740991 的正整数。

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

    • burst

      integer | string

      必填

      有效值:

      大于或等于 0

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

      字符串值可以通过在变量名前添加美元符号($)来引用内置变量。字符串解析结果必须为不大于 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 中,请启用数据加密,以便在存入 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 证书。