# GraphQL Limit Count 配置选项

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

## 静态配置[​](#static-configurations "静态配置的直接链接")

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

* 主机或 Docker
* Kubernetes (Helm)

对于主机或 Docker 部署，配置以下设置：

config.yaml

```
graphql:

  max_size: 2097152
```

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

对于 `2.16.0` 或更高版本的 APISIX Helm Chart，配置以下值：

values.yaml

```
apisix:

  graphql:

    maxSize: 2097152
```

对于 `3.10.3` 或更高版本的 API7 Gateway Helm Chart，配置以下值：

values.yaml

```
graphql:

  maxSize: 2097152
```

早期版本的 Chart 未提供此设置对应的值。请升级 Chart，或维护 Chart overlay 或 Helm post-renderer，将 **主机或 Docker** 标签页中的 `graphql.max_size` 块添加到生成的 `config.yaml`。向旧版 Chart 添加上述任一值都不会生效。

将此设置加入部署所用的、纳入版本控制的完整 values 文件。设置 Release 信息，包括已安装的 Chart 及其版本：

```
export GATEWAY_RELEASE=replace-with-gateway-release-name

export GATEWAY_NAMESPACE=replace-with-gateway-namespace

export GATEWAY_CHART=replace-with-installed-chart-name

export GATEWAY_CHART_VERSION=replace-with-installed-chart-version
```

应用完整的 values 文件，并保持 Chart 版本不变：

```
helm upgrade "$GATEWAY_RELEASE" "$GATEWAY_CHART" \

  --namespace "$GATEWAY_NAMESPACE" \

  --version "$GATEWAY_CHART_VERSION" \

  -f values.yaml
```

## 参数[​](#parameters "参数的直接链接")

有关所有插件都支持的配置选项，请参阅插件[通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md)。

* count

  integer | string

  有效值：

  大于 0

  ***

  给定时间间隔内允许累计的最大 GraphQL 查询成本。默认策略下，查询成本即为深度。未配置 `rules` 时必填。当配置为字符串时，该值可以使用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。

* time\_window

  integer | string

  有效值：

  大于 0

  ***

  与限流 `count` 对应的时间间隔，单位为秒。未配置 `rules` 时必填。当配置为字符串时，该值可以使用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。

* 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 查询成本。默认策略下，查询成本即为深度。当配置为字符串时，该值可以使用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。

  * time\_window

    integer | string

    必填

    有效值：

    大于 0

    ***

    与规则 `count` 对应的时间间隔，单位为秒。当配置为字符串时，该值可以使用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。

  * key

    string

    必填

    ***

    用于计数请求的 Key。支持[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)组合，每个变量必须以美元符号（`$`）为前缀。如果 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` 被解释为变量。变量不需要以美元符号（`$`）作为前缀。查看[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)以获取可用变量。

  如果 `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 中，请[启用数据加密](https://docs.apiseven.com/apisix/production/security/data-encryption-with-keyring.md)，以便在存入 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 中，请[启用数据加密](https://docs.apiseven.com/apisix/production/security/data-encryption-with-keyring.md)，以便在存入 etcd 前加密密码。

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

## 插件元数据[​](#plugin-metadata "插件元数据的直接链接")

* 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 中引入。
