跳到主要内容

GraphQL Limit Count 配置选项

graphql-limit-count 插件在可配置的时间窗口内限制 GraphQL 文档的累计成本,默认使用选择集深度作为度量。 配置涵盖静态设置、插件参数和插件元数据。

静态配置​

网关默认最多读取 1 MiB 的 GraphQL 请求数据。如果 GraphQL 文档或变量可能产生更大的请求体,请提高此上限。以下示例将其提高到 2 MiB(2,097,152 字节):

对于主机或 Docker 部署,配置以下设置:

config.yaml
graphql:
max_size: 2097152

然后重新加载网关,使更改生效。

参数​

有关所有插件都支持的配置选项,请参阅插件通用配置。

  • count

    integer | string

    有效值:

    大于 0

    给定时间间隔内允许累计的最大 GraphQL 查询成本。默认策略下,查询成本即为深度。未配置 rules 时必填。当配置为字符串时,该值可以使用内置变量。

  • time_window

    integer | string

    有效值:

    大于 0

    与限流 count 对应的时间间隔,单位为秒。未配置 rules 时必填。当配置为字符串时,该值可以使用内置变量。

  • 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 的间隔,以秒为单位。适用于 redis、redis-cluster 和 redis-sentinel。-1 表示每次请求都同步。延迟同步可以减少 Redis 往返次数,但会使限速执行略为宽松。

    如果运行时适用的 time_window 小于或等于 sync_interval,网关会直接同步该请求。

    在 API7 企业版 3.9.14、3.10.1 和 APISIX 3.18.0 中引入。

  • rules

    array[object]


    按顺序应用的限流规则数组。rules 与顶层 count 和 time_window 二选一配置,不能同时使用。

    • count

      integer | string

      必填

      有效值:

      大于 0

      规则的 time_window 内允许累计的最大 GraphQL 查询成本。默认策略下,查询成本即为深度。当配置为字符串时,该值可以使用内置变量。

    • time_window

      integer | string

      必填

      有效值:

      大于 0

      与规则 count 对应的时间间隔,单位为秒。当配置为字符串时,该值可以使用内置变量。

    • key

      string

      必填


      用于计数请求的 Key。支持内置变量组合,每个变量必须以美元符号($)为前缀。如果 Key 无法解析,则不会应用该规则。

    • header_prefix

      string


      插入到该规则限流响应头中的前缀。例如,foo 会生成 X-foo-RateLimit-Limit、X-foo-RateLimit-Remaining 和 X-foo-RateLimit-Reset。

  • cost_strategy

    string

    默认值:depth

    有效值:

    depth、complexity 或 node_quantifier

    GraphQL 文档原始成本的计算方式。

    depth 按选择集的嵌套深度计算,并且仍是默认值。

    complexity 对查询解析的节点计分。

    node_quantifier 只对匹配的成本装饰能解析出 mul_arguments 所列参数的节点计分。如果没有节点同时具备匹配装饰和可用量词,原始分数为 0。

    对于 complexity 和 node_quantifier,插件先加 0.01、应用 score_factor,再向上取整后计入配额。使用默认系数时,原始分数 0 的成本为 1;大于 100 的系数会提高该成本。

    该能力在 API7 企业版 3.10.6 和 APISIX 3.19.0 中引入。

  • max_cost

    number

    默认值:0

    有效值:

    大于或等于 0

    在请求到达上游前,以 403 Forbidden 拒绝计入配额的成本超过此值的文档。限速器会先计算并处理该成本,因此被此检查拒绝的请求仍可能消耗配额。0 表示关闭此检查。在 API7 企业版 3.10.6 和 APISIX 3.19.0 中引入。

  • score_factor

    number

    默认值:1

    有效值:

    大于 0

    在成本向上取整、计入配额并与 max_cost 比较之前应用的缩放系数。该能力在 API7 企业版 3.10.6 和 APISIX 3.19.0 中引入。

  • resolve_variables

    boolean

    默认值:true


    如果为 true,则在计算成本时解析已提供的 GraphQL 变量、操作声明的变量默认值,以及上游 schema 中的参数默认值。默认开启可确保以变量提供的量词计入其解析值。该能力在 API7 企业版 3.10.6 和 APISIX 3.19.0 中引入。

  • introspection_endpoint

    string

    有效值:

    以 http:// 或 https:// 开头

    用于对上游 GraphQL Schema 进行内省的端点;complexity 和 node_quantifier 策略需要该 Schema 来匹配成本装饰。未设置时从上游推导。每个 Worker 会在其生命周期内缓存该 Schema。在 API7 企业版 3.10.6 和 APISIX 3.19.0 中引入。

  • introspection_headers

    object


    schema 内省需要凭据时发送的请求头。在数据面启用数据加密后,该字段会加密落盘。该能力在 API7 企业版 3.10.6 和 APISIX 3.19.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

    限速计数器的存储位置。local 使用各个网关实例的本地内存。Redis 策略通过单个 Redis 服务器、Redis Cluster 或 Redis Sentinel 部署共享计数器。

    redis-sentinel 策略在 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 显示算法特定的重置或延迟值(秒)。
    • X-Graphql-Query-Cost 显示计入配额的查询成本,在 API7 企业版 3.10.6 和 APISIX 3.19.0 中提供。
  • group

    string

    有效值:

    非空

    用于让插件配置相同的路由通过同一组 ID 共享一个计数器。不要将 group 与 rules 同时配置。

  • redis_host

    string


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

  • redis_port

    integer

    默认值:6379

    有效值:

    大于或等于 1

    Redis 节点的端口。当 policy 为 redis 时使用。

  • redis_username

    string


    policy 为 redis 或 redis-sentinel 时,用于 Redis ACL 认证的用户名。如果 Redis 仅使用旧版 requirepass 认证方式,请只配置 redis_password,不要配置用户名。

  • 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_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

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

  • redis_keepalive_timeout

    integer

    默认值:`redis` 或 `redis-cluster` 为 `10000`;`redis-sentinel` 为 `60000`

    有效值:

    redis 和 redis-cluster:大于或等于 1000;redis-sentinel:大于或等于 1

    空闲 Redis 连接在连接池中的保留时间,以毫秒为单位。

    对 redis 和 redis-cluster 的支持在 API7 企业版 3.9.16、3.10.3 和 APISIX 3.17.0 中引入。对 Redis Sentinel 的支持在 API7 企业版 3.9.14、3.10.1 和 APISIX 3.18.0 中引入。

  • redis_keepalive_pool

    integer

    默认值:100

    有效值:

    大于或等于 1

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

    此参数在 API7 企业版 3.9.x 系列中自 3.9.16 起可用,在 3.10.x 系列中自 3.10.3 起可用,并且在 APISIX 中自 3.17.0 起可用。

  • redis_cluster_nodes

    array[string]


    非空的 Redis Cluster 节点地址列表。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

      string

      必填

      有效值:

      至少 2 个字符

      Redis Sentinel 节点的主机名或 IP 地址。

    • port

      integer

      必填

      有效值:

      介于 1 和 65535 之间(含边界值)

      Redis Sentinel 节点的端口。

  • redis_master_name

    string


    Sentinel 节点监控的主节点组。policy 为 redis-sentinel 时必填。

  • redis_role

    string

    默认值:master

    有效值:

    master 或 slave

    policy 为 redis-sentinel 时,向 Sentinel 请求的 Redis 角色。

  • redis_connect_timeout

    integer

    默认值:1000

    有效值:

    大于或等于 1

    policy 为 redis-sentinel 时,连接 Redis 的超时时间,以毫秒为单位。

  • redis_read_timeout

    integer

    默认值:1000

    有效值:

    大于或等于 1

    policy 为 redis-sentinel 时,从 Redis 读取数据的超时时间,以毫秒为单位。

  • sentinel_username

    string


    policy 为 redis-sentinel 时,用于 Redis Sentinel 认证的用户名。

  • sentinel_password

    string


    policy 为 redis-sentinel 时,用于 Redis Sentinel 认证的密码。

    API7 企业版会对密码进行静态加密。在 APISIX 中,请启用数据加密,以便在存入 etcd 前加密密码。

    加密功能在 API7 企业版 3.9.16、3.10.2 和 APISIX 3.18.0 中引入。

插件元数据​

  • limit_header

    string

    默认值:X-RateLimit-Limit


    表示速率限制总配额的默认响应头名称。该字段在 API7 企业版 3.10.6 和 APISIX 3.19.0 中引入。

  • remaining_header

    string

    默认值:X-RateLimit-Remaining


    表示速率限制剩余配额的默认响应头名称。该字段在 API7 企业版 3.10.6 和 APISIX 3.19.0 中引入。

  • reset_header

    string

    默认值:X-RateLimit-Reset


    表示速率限制计数器重置前剩余秒数的默认响应头名称。该字段在 API7 企业版 3.10.6 和 APISIX 3.19.0 中引入。