跳到主要内容
版本：3.10.x

API7 网关 AI Agent Skill：limit-count 插件

概述​

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

适用场景​

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

插件配置参考​

核心字段​

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

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

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

字段类型是否必填默认值描述
redis_hoststring是—Redis 服务器地址
redis_portinteger否6379Redis 端口
redis_usernamestring否—Redis ACL 用户名
redis_passwordstring否—Redis 密码
redis_databaseinteger否0Redis 数据库索引
redis_timeoutinteger否1000以毫秒为单位的超时时间
redis_sslboolean否false是否为 Redis 启用 TLS

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

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

键类型​

key_typekey 格式示例描述
"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 限流（路由级）​

a7 route create -g default -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": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

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

2. 按消费者限流​

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

a7 consumer create -g default -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
    }
  }
}

运行多个 API7 企业版节点时，请使用 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
    }
  }
}

故障排查​

现象原因解决方法
限制未在 API7 企业版节点间共享使用了默认的 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"
gateway_groups:
  - name: default
    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:
          type: roundrobin
          nodes:
            - host: backend
              port: 8080
              weight: 1

本页由 api7/a7 仓库中的 a7-plugin-limit-count/SKILL.md 生成。请在 AI Agent Skills 页面浏览所有 Skill。