跳到主要内容

参数​

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

该插件支持使用 env:// 前缀从环境变量引用参数值，也支持使用 secret:// 前缀从密钥管理器（例如 HashiCorp Vault 的 KV 密钥引擎）引用参数值。有关更多信息，请参阅插件中的环境变量和密钥。

  • count

    integer | string

    有效值：

    大于 0

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

    字符串值可以通过在变量前添加美元符号（$）来引用内置变量。自 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 对应的时间间隔，单位为秒。

    字符串值可以通过在变量前添加美元符号（$）来引用内置变量。自 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 将被解释为变量。变量不需要以美元符号（$）作为前缀。请参阅内置变量以获取可用变量。

    如果 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 中，请启用数据加密，使其在存储到 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_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 中，请启用数据加密，使其在存储到 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 内允许的最大请求数。

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

      字符串值必须解析为不大于 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 对应的时间间隔，单位为秒。

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

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

    • key

      string

      必填

      解析为此规则请求计数键的变量表达式。每个 APISIX 内置变量或 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

    表示速率限制计数器重置前剩余秒数的默认响应头名称。