跳到主要内容

Limit Count Advanced 配置选项

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

参数​

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

该插件支持在字符串类型的配置字段中使用网关引用。使用 $env:// 前缀引用环境变量中的值,或使用 $secret:// 前缀引用密钥管理器中的值,例如 HashiCorp Vault 的 KV 密钥引擎。网关在运行时解析这些引用。ADC 的 ${NAME} 插值有所不同:ADC 在同步前加载配置文件时解析插值。有关更多信息,请参阅插件中的环境变量和密钥。

备注

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

  • count, time_window
  • rules
  • count

    integer | string

    有效值:

    大于 0

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

    在 API7 企业版(从 3.8.17 开始)中,此参数还支持字符串数据类型,并允许使用以美元符号($)为前缀的内置变量。

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

  • time_window

    integer | string

    有效值:

    大于 0

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

    在 API7 企业版(从 3.8.17 开始)中,此参数还支持字符串数据类型,并允许使用以美元符号($)为前缀的内置变量。

    未配置 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 被解释为变量。变量不需要以美元符号($)作为前缀。查看内置变量以获取可用变量。

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

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

      此参数还支持字符串数据类型,并允许使用以美元符号($)为前缀的内置变量。

    • time_window

      integer | string

      必填

      有效值:

      大于 0

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

      此参数还支持字符串数据类型,并允许使用以美元符号($)为前缀的内置变量。

    • 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 显示算法特定的重置或延迟值(秒)。


    设置了 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 产生无变化同步行为,即每个请求都会同步计数器数据。