a6-plugin-limit-count

概述

limit-count 插件使用固定窗口计数器算法对请求进行限流。通过 count 定义 time_window 时间间隔内允许的最大请求数。它支持按 IP、消费者、请求头或自定义变量设置键。在分布式 Apache APISIX部署中，请使用 Redis 或 Redis 集群作为共享计数器后端。

适用场景

简单请求计数，例如每小时 100 个请求。
按消费者或 API 密钥实施 API 配额。
通过 Redis 在多个 Apache APISIX节点间共享限流。
在多个路由间共享分组配额。

插件配置参考

核心字段

字段	类型	是否必填	默认值	描述
`count`	integer	是*	—	时间窗口内允许的最大请求数，必须大于 0
`time_window`	integer	是*	—	以秒为单位的时间窗口，必须大于 0
`key_type`	string	否	`"var"`	键类型：`"var"`、`"var_combination"` 或 `"constant"`
`key`	string	否	`"remote_addr"`	用于计数的变量名称或变量组合
`rejected_code`	integer	否	`503`	拒绝请求时的 HTTP 状态码（200 至 599）
`rejected_msg`	string	否	—	自定义拒绝消息正文
`group`	string	否	—	在具有相同组 ID 的路由间共享计数器
`policy`	string	否	`"local"`	存储策略：`"local"`、`"redis"` 或 `"redis-cluster"`
`show_limit_quota_header`	boolean	否	`true`	在响应中包含 X-RateLimit-* 请求头
`allow_degradation`	boolean	否	`false`	插件失败时是否允许请求通过

*除非使用 rules 数组，否则为必填项。

Redis 字段（`policy: "redis"` 时）

字段	类型	是否必填	默认值	描述
`redis_host`	string	是	—	Redis 服务器地址
`redis_port`	integer	否	`6379`	Redis 端口
`redis_username`	string	否	—	Redis ACL 用户名
`redis_password`	string	否	—	Redis 密码
`redis_database`	integer	否	`0`	Redis 数据库索引
`redis_timeout`	integer	否	`1000`	以毫秒为单位的超时时间
`redis_ssl`	boolean	否	`false`	是否为 Redis 启用 TLS

Redis 集群字段（`policy: "redis-cluster"` 时）

字段	类型	是否必填	默认值	描述
`redis_cluster_nodes`	字符串数组	是	—	`"host:port"` 数组，至少两个节点
`redis_cluster_name`	string	是	—	集群名称
`redis_password`	string	否	—	集群密码
`redis_timeout`	integer	否	`1000`	以毫秒为单位的超时时间
`redis_cluster_ssl`	boolean	否	`false`	是否启用 TLS

键类型

`key_type`	`key` 格式	示例	描述
`"var"`	NGINX 变量（不带 `$`）	`"remote_addr"`	单个变量
`"var_combination"`	`$var1 $var2`	`"$remote_addr $consumer_name"`	组合多个变量
`"constant"`	任意字符串	`"global"`	所有请求使用同一计数器

响应头

当 show_limit_quota_header: true（默认值）时：

请求头	描述
`X-RateLimit-Limit`	时间窗口内的总配额
`X-RateLimit-Remaining`	当前窗口内剩余的请求数
`X-RateLimit-Reset`	距离计数器重置的秒数

分步操作：基础限流

1. 按客户端 IP 限流（路由级）

a6 route create -f - <<'EOF'
{
  "id": "rate-limited-api",
  "uri": "/api/*",
  "plugins": {
    "limit-count": {
      "count": 100,
      "time_window": 60,
      "key_type": "var",
      "key": "remote_addr",
      "rejected_code": 429,
      "rejected_msg": "Rate limit exceeded. Try again later."
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "backend:8080": 1
    }
  }
}
EOF

每个客户端 IP 每 60 秒允许 100 个请求。

2. 按消费者限流

a6 consumer create -f - <<'EOF'
{
  "username": "free-tier",
  "plugins": {
    "limit-count": {
      "count": 100,
      "time_window": 3600,
      "rejected_code": 429
    }
  }
}
EOF

a6 consumer create -f - <<'EOF'
{
  "username": "premium",
  "plugins": {
    "limit-count": {
      "count": 10000,
      "time_window": 3600,
      "rejected_code": 429
    }
  }
}
EOF

消费者级限制适用于该消费者访问的所有路由。

常见模式

在路由间共享配额（组）

{
  "plugins": {
    "limit-count": {
      "count": 1000,
      "time_window": 3600,
      "group": "api-v1",
      "rejected_code": 429
    }
  }
}

所有配置 "group": "api-v1" 的路由共享同一个每小时 1000 个请求的计数器。 **重要：**同一组中的所有路由必须使用完全相同的 limit-count 配置。

多变量键（IP 加消费者）

{
  "plugins": {
    "limit-count": {
      "count": 50,
      "time_window": 60,
      "key_type": "var_combination",
      "key": "$remote_addr $consumer_name",
      "rejected_code": 429
    }
  }
}

全局限流（所有请求共享一个计数器）

{
  "plugins": {
    "limit-count": {
      "count": 10000,
      "time_window": 60,
      "key_type": "constant",
      "key": "global",
      "rejected_code": 429
    }
  }
}

使用 Redis 进行分布式限流

{
  "plugins": {
    "limit-count": {
      "count": 1000,
      "time_window": 60,
      "key": "remote_addr",
      "policy": "redis",
      "redis_host": "redis.example.com",
      "redis_port": 6379,
      "redis_password": "secret",
      "redis_database": 0,
      "redis_ssl": true,
      "rejected_code": 429
    }
  }
}

运行多个 Apache APISIX节点时，请使用 Redis 共享计数器。

Redis 集群

{
  "plugins": {
    "limit-count": {
      "count": 1000,
      "time_window": 60,
      "key": "remote_addr",
      "policy": "redis-cluster",
      "redis_cluster_nodes": [
        "192.168.1.10:6379",
        "192.168.1.11:6379",
        "192.168.1.12:6379"
      ],
      "redis_cluster_name": "apisix-cluster",
      "redis_password": "secret",
      "rejected_code": 429
    }
  }
}

故障排查

现象	原因	解决方法
限制未在 Apache APISIX节点间共享	使用了默认的 `policy: "local"`	切换为 `"redis"` 或 `"redis-cluster"`
组配置被拒绝	同一组内的配置不一致	确保组内所有路由使用相同的 limit-count 配置
计数器意外重置	到达固定窗口边界	这是正常行为，计数器会在固定时间间隔重置
键为空，所有客户端共用一个计数器	变量不存在	检查键变量名称；会回退到 `remote_addr`
缺少限流响应头	`show_limit_quota_header: false`	设为默认值 `true`
返回 503 而不是 429	默认 `rejected_code` 为 503	显式设置 `rejected_code: 429`

固定窗口算法说明

limit-count 使用固定窗口算法，计数器会在精确的时间间隔重置。这意味着在两个窗口边界发生突发流量时，可能暂时超过预期速率。例如，100 req/min 的限制中，若在 t=59s 和 t=61s 分别收到 100 个请求，则会允许 200 个请求。如需更平滑的限流，请结合使用漏桶插件 limit-req。

配置同步示例

version: "1"
consumers:
  - username: free-tier
    plugins:
      limit-count:
        count: 100
        time_window: 3600
        rejected_code: 429
routes:
  - id: rate-limited-api
    uri: /api/*
    plugins:
      limit-count:
        count: 1000
        time_window: 60
        key: remote_addr
        rejected_code: 429
    upstream_id: api-upstream
upstreams:
  - id: api-upstream
    type: roundrobin
    nodes:
      "backend:8080": 1

本文根据 api7/a6 仓库中的 a6-plugin-limit-count/SKILL.md 生成。可在 AI Agent Skills 页面浏览全部 Skill。

概述​

适用场景​

插件配置参考​

核心字段​

Redis 字段（policy: "redis" 时）​

Redis 集群字段（policy: "redis-cluster" 时）​

键类型​

响应头​

分步操作：基础限流​

1. 按客户端 IP 限流（路由级）​

2. 按消费者限流​

常见模式​

在路由间共享配额（组）​

多变量键（IP 加消费者）​

全局限流（所有请求共享一个计数器）​

使用 Redis 进行分布式限流​

Redis 集群​

故障排查​

固定窗口算法说明​

配置同步示例​

概述