跳到主要内容

参数​

请参阅 插件通用配置 了解所有插件可用的配置选项。

该插件支持使用 env:// 前缀引用环境变量中的敏感参数值，或使用 secret:// 前缀引用 Secret 管理器（如 HashiCorp Vault 的 KV 密钥引擎 中的值。更多信息，请参阅环境变量中的插件和Secrets。

备注

在 API7 企业版（从 3.8.17 开始）中，你应该配置以下参数集之一，但不能同时配置两者：

  • count, time_window
  • rules

  • count

    integer | string

    required

    vaild vaule:

    大于 0

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

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

  • time_window

    integer | string

    required

    vaild vaule:

    大于 0

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

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

  • window_type

    string

    default: fixed

    vaild vaule:

    fixed or sliding

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

  • key_type

    string

    default: var

    vaild vaule:

    var, var_combination, or constant

    键的类型。

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

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

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

  • key

    string

    default: 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

    default: 503

    vaild vaule:

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

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

  • rejected_msg

    string

    vaild vaule:

    任意非空字符串

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

  • policy

    string

    default: local

    vaild vaule:

    local, redis, redis-cluster, or 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

    default: master

    vaild vaule:

    master or slave

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

  • redis_connect_timeout

    integer

    default: 1000

    vaild vaule:

    大于或等于 1

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

  • redis_read_timeout

    integer

    default: 1000

    vaild vaule:

    大于或等于 1

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

  • redis_keepalive_timeout

    integer

    default: 60000

    vaild vaule:

    大于或等于 1

    空闲 Redis 连接在连接池中关闭前保持活动的时间（毫秒）。当 policy 为 redis-sentinel 时可配置。

  • sentinel_username

    string

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

  • sentinel_password

    string

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

  • allow_degradation

    boolean

    default: false

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

  • rules

    array[object]

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

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

    • count

      integer | string

      required

      vaild vaule:

      大于 0

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

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

    • time_window

      integer | string

      required

      vaild vaule:

      大于 0

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

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

    • key

      string

      required

      用于计数请求的键。如果配置的键不存在，则不会执行该规则。

      key 被解释为变量组合，例如 $http_custom_a $http_custom_b。

    • 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

    default: true

    如果为 true，则包含速率限制响应头。具体来说，如果未设置 rules，则头部为：

    • X-RateLimit-Limit 显示总配额。
    • X-RateLimit-Remaining 显示剩余配额。
    • X-RateLimit-Reset 显示计数器重置前的剩余秒数。


    当设置了 rules 时，前缀（后跟连字符）将插入到 X- 之后。有关详细信息，请参阅 rules.header_prefix。

  • group

    string

    vaild vaule:

    non-empty

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

  • redis_host

    string

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

  • redis_port

    integer

    default: 6379

    vaild vaule:

    大于或等于 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

    default: 0

    vaild vaule:

    大于或等于 0

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

  • redis_ssl

    boolean

    default: false

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

  • redis_ssl_verify

    boolean

    default: false

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

  • redis_timeout

    integer

    default: 1000

    vaild vaule:

    大于或等于 1

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

  • redis_cluster_nodes

    array[string]

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

  • redis_cluster_name

    string

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

  • redis_cluster_ssl

    boolean

    default: false

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

  • redis_cluster_ssl_verify

    boolean

    default: false

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

  • sync_interval

    number

    default: -1

    vaild vaule:

    大于或等于 0.1，或默认值 -1

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

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