跳到主要内容

limit-count

limit-count 插件使用固定窗口算法，根据给定时间间隔内的请求数量来限制请求速率。超过配置配额的请求将被拒绝。

你可能会在响应中看到以下限速响应头：

  • X-RateLimit-Limit：总配额
  • X-RateLimit-Remaining：剩余配额
  • X-RateLimit-Reset：计数器重置前的剩余秒数

如果你使用的是 API7 企业版，可以通过插件元数据自定义这些响应头的名称。

本地限速与基于 Redis 的限速​

limit-count 插件支持以下两种限速模式：

  • 本地限速：每个网关实例独立实施限速。每个实例维护自己的计数器，因此当流量分散到多个实例时，实际限额约为“限额 × 实例数”。未设置 policy 或将其设置为 local 时，这是默认模式。
  • 基于 Redis 的限速：所有网关实例通过 Redis 共享限额，因此配置的限额会应用到所有网关实例。将 policy 设置为 redis 可使用单个 Redis 实例，设置为 redis-cluster 可使用 Redis 集群，设置为 redis-sentinel 可使用 Redis Sentinel 管理的 Redis 节点。
备注

从 API7 企业版 3.9.14 起，高级限速能力已直接内置到 limit-count 中，包括用于高可用的 redis-sentinel 策略、在窗口边界平滑实施限速的 sliding window_type、通过 sync_interval 延迟同步、通过 rules 数组配置多条限速规则，以及从请求变量派生 count。独立的 limit-count-advanced 插件仍保留，以实现向后兼容。

示例​

以下示例展示了如何在不同场景下配置 limit-count。

基于远程地址进行速率限制​

以下示例演示了如何通过单个变量 remote_addr 对请求进行限速。

创建一个使用 limit-count 插件的路由，允许每个远程地址在 30 秒窗口内请求 1 次：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route",
    "uri": "/get",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "key_type": "var",
        "key": "remote_addr",
        "policy": "local"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

发送请求进行验证：

curl -i "http://127.0.0.1:9080/get"

你应该会看到一个 HTTP/1.1 200 OK 响应。

该请求已消耗了时间窗口内允许的所有配额。如果你在同一个 30 秒时间间隔内再次发送请求，应该会收到 HTTP/1.1 429 Too Many Requests 响应，表明请求超过了配额阈值。

使用滑动窗口实施限速​

以下示例演示了如何通过将 window_type 设置为 sliding，使用 API7 企业版 3.9.14 起提供的滑动窗口算法。与默认的固定窗口相比，滑动窗口在计算当前请求数时会对上一窗口加权，从而平滑窗口边界处的流量突发。

创建一条配置了 limit-count 插件的路由，允许每个远程地址在 30 秒滑动窗口内请求 10 次：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route",
    "uri": "/get",
    "plugins": {
      "limit-count": {
        "count": 10,
        "time_window": 30,
        "rejected_code": 429,
        "key_type": "var",
        "key": "remote_addr",
        "policy": "local",
        "window_type": "sliding"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

发送请求进行验证：

curl -i "http://127.0.0.1:9080/get"

你应该会看到 HTTP/1.1 200 OK 响应。持续发送请求时，与固定窗口相比，滑动窗口会在相邻窗口的边界处更均匀地实施配额。

基于远程地址和消费者名称进行速率限制​

以下示例演示了如何通过变量组合 remote_addr 和 consumer_name 对请求进行限速。它允许每个远程地址和每个 Consumer 在 30 秒窗口内请求 1 次。

创建消费者 john：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "john"
  }'

为消费者 john 创建 key-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-john-key-auth",
    "plugins": {
      "key-auth": {
        "key": "john-key"
      }
    }
  }'

创建消费者 jane：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "jane"
  }'

为消费者 jane 创建 key-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/jane/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-jane-key-auth",
    "plugins": {
      "key-auth": {
        "key": "jane-key"
      }
    }
  }'

创建一个启用 key-auth 和 limit-count 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route",
    "uri": "/get",
    "plugins": {
      "key-auth": {},
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "key_type": "var_combination",
        "key": "$remote_addr $consumer_name",
        "policy": "local"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

❶ key-auth：在路由上启用密钥认证。

❷ key_type：设置为 var_combination，将 key 解释为变量组合。

❸ key：设置为 $remote_addr $consumer_name，按远程地址和消费者应用限速配额。

以消费者 jane 的身份发送请求：

curl -i "http://127.0.0.1:9080/get" -H 'apikey: jane-key'

你应看到 HTTP/1.1 200 OK 响应及对应的响应体。

此请求已消耗了该时间窗口的所有配额。如果你在同一个 30 秒时间间隔内再次以消费者 jane 的身份发送相同的请求，应该会收到 HTTP/1.1 429 Too Many Requests 响应，表明请求超过了配额阈值。

在同一个 30 秒时间间隔内以消费者 john 的身份发送相同的请求：

curl -i "http://127.0.0.1:9080/get" -H 'apikey: john-key'

你应该会看到带有相应响应体的 HTTP/1.1 200 OK 响应，表明该请求未被限速。

在同一个 30 秒时间间隔内再次以消费者 john 的身份发送相同的请求，你应该会收到 HTTP/1.1 429 Too Many Requests 响应。

这验证了插件是根据变量组合 remote_addr 和 consumer_name 进行速率限制的。

在路由间共享配额​

以下示例演示了如何通过配置 limit-count 插件的 group 来在多个路由之间共享限速配额。

请注意，同一 group 的 limit-count 插件配置应完全相同。为了避免更新异常和重复配置，你可以创建一个包含 limit-count 插件和上游的 Service，供路由连接。

创建一个配置限速组的服务：

curl "http://127.0.0.1:9180/apisix/admin/services" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-service",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "policy": "local",
        "group": "srv1"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

创建两条使用同一服务的路由以共享配额：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route-1",
    "service_id": "limit-count-service",
    "uri": "/get1",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/get"
      }
    }
  }'
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route-2",
    "service_id": "limit-count-service",
    "uri": "/get2",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/get"
      }
    }
  }'
备注

proxy-rewrite 插件用于将 URI 重写为 /get，使请求转发到正确的端点。

向路由 /get1 发送请求：

curl -i "http://127.0.0.1:9080/get1"

你应看到 HTTP/1.1 200 OK 响应及对应的响应体。

在同一个 30 秒时间间隔内向路由 /get2 发送相同的请求：

curl -i "http://127.0.0.1:9080/get2"

你应该会收到 HTTP/1.1 429 Too Many Requests 响应，这验证了两个路由共享相同的限速配额。

使用 Redis 服务器在 APISIX 节点间共享配额​

以下示例演示了如何使用 Redis 服务器在多个 APISIX 节点之间实施限速，使不同 APISIX 节点共享同一限速配额。

为路由配置 Redis 连接详情，并根据实际环境调整 Redis 主机、凭证和数据库。

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route",
    "uri": "/get",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "key": "remote_addr",
        "policy": "redis",
        "redis_host": "192.168.xxx.xxx",
        "redis_port": 6379,
        "redis_password": "p@ssw0rd",
        "redis_database": 1
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

❶ policy: 设置为 redis 以使用 Redis 实例进行限速。

❷ redis_host: 设置为 Redis 实例的 IP 地址。

❸ redis_port: 设置为 Redis 实例的监听端口。

❹ redis_password: 设置为 Redis 实例的密码（如果有）。

❺ redis_database: 设置为 Redis 实例中的数据库编号。

向 APISIX 实例发送请求：

curl -i "http://127.0.0.1:9080/get"

你应看到 HTTP/1.1 200 OK 响应及对应的响应体。

在相同的 30 秒时间窗口内，向另一个 APISIX 实例发送相同请求，应收到 HTTP/1.1 429 Too Many Requests 响应，这表明不同 APISIX 节点上配置的路由共享同一配额。

使用 Redis 集群在 APISIX 节点间共享配额​

你还可以使用 Redis 集群在多个 APISIX 节点之间应用相同的配额，以便不同的 APISIX 节点共享相同的限速配额。

确保你的 Redis 实例以集群模式运行。limit-count 插件配置至少需要两个节点。

为路由配置 Redis 集群详情，并根据实际环境调整集群节点、凭证和集群名称。

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route",
    "uri": "/get",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "key": "remote_addr",
        "policy": "redis-cluster",
        "redis_cluster_nodes": [
          "192.168.xxx.xxx:6379",
          "192.168.xxx.xxx:16379"
        ],
        "redis_password": "p@ssw0rd",
        "redis_cluster_name": "redis-cluster",
        "redis_cluster_ssl": true
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

❶ policy: 设置为 redis-cluster 以使用 Redis 集群进行限速。

❷ redis_cluster_nodes: 设置为 Redis 集群中的 Redis 节点地址。

❸ redis_password: 设置为 Redis 集群的密码（如果有）。

❹ redis_cluster_name: 设置为 Redis 集群名称。

❺ redis_cluster_ssl: 启用与 Redis 集群的 SSL/TLS 通信。

向 APISIX 实例发送请求：

curl -i "http://127.0.0.1:9080/get"

你应看到 HTTP/1.1 200 OK 响应及对应的响应体。

在相同的 30 秒时间窗口内，向另一个 APISIX 实例发送相同请求，应收到 HTTP/1.1 429 Too Many Requests 响应，这表明不同 APISIX 节点上配置的路由共享同一配额。

使用 Redis Sentinel 在 APISIX 节点之间共享配额​

从 API7 企业版 3.9.14 起，还可以使用由 Redis Sentinel 管理的 Redis 节点，在多个 APISIX 节点之间应用同一配额，并通过主节点自动故障转移实现高可用。

为路由配置 Redis Sentinel 详情，并根据实际环境调整 Sentinel 节点、凭证和受监控的主节点名称。

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route",
    "uri": "/get",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "key": "remote_addr",
        "policy": "redis-sentinel",
        "redis_sentinels": [
          { "host": "192.168.xxx.xxx", "port": 26379 },
          { "host": "192.168.xxx.xxx", "port": 26380 }
        ],
        "redis_master_name": "mymaster",
        "sentinel_username": "sentinel-user",
        "sentinel_password": "p@ssw0rd",
        "redis_database": 1
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

其中：

  • 将 policy 设置为 redis-sentinel，以使用 Redis Sentinel 管理的 Redis 节点。
  • redis_sentinels 列出 Sentinel 节点，每个节点包含 host 和 port。
  • redis_master_name 是 Sentinel 监控的主节点名称。
  • 如果需要，使用 sentinel_username 和 sentinel_password 向 Sentinel 节点进行身份认证。

向 APISIX 实例发送请求：

curl -i "http://127.0.0.1:9080/get"

你应看到 HTTP/1.1 200 OK 响应及对应的响应体。

在相同的 30 秒时间窗口内，向另一个 APISIX 实例发送相同请求，应收到 HTTP/1.1 429 Too Many Requests 响应，这表明不同 APISIX 节点上配置的路由共享同一配额。

对匿名消费者进行限速​

以下示例演示了如何为普通消费者和匿名消费者配置不同的限速策略。匿名消费者无需进行身份认证，且拥有较少的配额。尽管本示例使用 key-auth 进行身份认证，也可以为匿名消费者配置 basic-auth、jwt-auth 或 hmac-auth。

创建配额为 3 的消费者 john：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "john",
    "plugins": {
      "limit-count": {
        "count": 3,
        "time_window": 30,
        "rejected_code": 429,
        "policy": "local"
      }
    }
  }'

为消费者 john 创建 key-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-john-key-auth",
    "plugins": {
      "key-auth": {
        "key": "john-key"
      }
    }
  }'

创建配额为 1 的匿名用户 anonymous：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "anonymous",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "policy": "local"
      }
    }
  }'

创建一条配置 key-auth 插件且接受匿名消费者的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "key-auth-route",
    "uri": "/anything",
    "plugins": {
      "key-auth": {
        "anonymous_consumer": "anonymous"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

要进行验证，请使用 john 的密钥发送五个连续请求：

resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/anything" -H 'apikey: john-key' -o /dev/null -s -w "%{http_code}\n") && \
  count_200=$(echo "$resp" | grep "200" | wc -l) && \
  count_429=$(echo "$resp" | grep "429" | wc -l) && \
  echo "200": $count_200, "429": $count_429

你应该会看到以下响应，显示在 5 个请求中，3 个请求成功（状态码 200），而其他请求被拒绝（状态码 429）。

200:    3, 429:    2

发送五个匿名请求：

resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/anything" -o /dev/null -s -w "%{http_code}\n") && \
  count_200=$(echo "$resp" | grep "200" | wc -l) && \
  count_429=$(echo "$resp" | grep "429" | wc -l) && \
  echo "200": $count_200, "429": $count_429

你应该会看到以下响应，显示只有一个请求成功：

200:    1, 429:    4

自定义速率限制头​

以下示例演示了如何使用插件元数据自定义速率限制响应头名称，默认情况下为 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset。

配置插件元数据以自定义限速响应头：

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/limit-count" -X PUT -d '
{
  "limit_header": "X-Custom-RateLimit-Limit",
  "remaining_header": "X-Custom-RateLimit-Remaining",
  "reset_header": "X-Custom-RateLimit-Reset"
}'

创建一条配置了 limit-count 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-count-route",
    "uri": "/get",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "key_type": "var",
        "key": "remote_addr",
        "policy": "local"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

发送请求进行验证：

curl -i "http://127.0.0.1:9080/get"

你应该收到一个 HTTP/1.1 200 OK 响应并看到以下头部：

X-Custom-RateLimit-Limit: 1
X-Custom-RateLimit-Remaining: 0
X-Custom-RateLimit-Reset: 28