limit-count

描述

limit-count 插件使用固定时间窗口算法,主要用于限制单个客户端在指定的时间范围内对服务的总请求数,并且会在 HTTP 响应头中返回剩余可以请求的个数。该插件原理与 GitHub API 的速率限制类似。

属性

名称类型必选项默认值有效值描述
countintegercount > 0每个客户端在指定时间窗口内的总请求数量阈值。
time_windowintegertime_window > 0时间窗口的大小(以秒为单位)。超过该属性定义的时间,则会重新开始计数。
key_typestring“var”[“var”, “var_combination”, “constant”]key 的类型。
keystring“remote_addr”用来做请求计数的依据。如果 key_typeconstant,那么 key 会被当作常量;如果 key_typevar,那么 key 会被当作变量;如果 key_typevar_combination,那么 key 会被当作变量组合,如 $remote_addr $consumer_name,插件会同时受 $remote_addr$consumer_name 两个变量的约束;如果 key 的值为空,$remote_addr 会被作为默认 key
rejected_codeinteger503[200,…,599]当请求超过阈值被拒绝时,返回的 HTTP 状态码。
rejected_msgstring非空当请求超过阈值被拒绝时,返回的响应体。
policystring“local”[“local”, “redis”, “redis-cluster”]用于检索和增加限制计数的策略。当设置为 local 时,计数器被以内存方式保存在节点本地;当设置为 redis 时,计数器保存在 Redis 服务节点上,从而可以跨节点共享结果,通常用它来完成全局限速;当设置为 redis-cluster 时,使用 Redis 集群而不是单个实例。
allow_degradationbooleanfalse当插件功能临时不可用时(例如 Redis 超时),当设置为 true 时,则表示可以允许插件降级并进行继续请求的操作。
show_limit_quota_headerbooleantrue当设置为 true 时,在响应头中显示 X-RateLimit-Limit(限制的总请求数)和 X-RateLimit-Remaining(剩余还可以发送的请求数)字段。
groupstring非空配置相同 group 的路由将共享相同的限流计数器。
redis_hoststring当使用 redis 限速策略时,Redis 服务节点的地址。policy 属性设置为 redis 时必选。
redis_portinteger6379[1,…]当使用 redis 限速策略时,Redis 服务节点的端口。
redis_passwordstring当使用 redis 或者 redis-cluster 限速策略时,Redis 服务节点的密码。
redis_databaseinteger0redis_database >= 0当使用 redis 限速策略时,Redis 服务节点中使用的 database,并且只针对非 Redis 集群模式(单实例模式或者提供单入口的 Redis 公有云服务)生效。
redis_timeoutinteger1000[1,…]policy 设置为 redisredis-cluster 时,Redis 服务节点的超时时间(以毫秒为单位)。
redis_cluster_nodesarray当使用 redis-cluster 限速策略时,Redis 集群服务节点的地址列表(至少需要两个地址)。policy 属性设置为 redis-cluster 时必选。
redis_cluster_namestring当使用 redis-cluster 限速策略时,Redis 集群服务节点的名称。policy 设置为 redis-cluster 时必选。

启用插件

以下示例展示了如何在指定路由上启用 limit-count 插件,并设置 key_type"var"

  1. curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "uri": "/index.html",
  5. "plugins": {
  6. "limit-count": {
  7. "count": 2,
  8. "time_window": 60,
  9. "rejected_code": 503,
  10. "key_type": "var",
  11. "key": "remote_addr"
  12. }
  13. },
  14. "upstream": {
  15. "type": "roundrobin",
  16. "nodes": {
  17. "127.0.0.1:1980": 1
  18. }
  19. }
  20. }'

你也可以设置 key_type"var_combination"

  1. curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "uri": "/index.html",
  5. "plugins": {
  6. "limit-count": {
  7. "count": 2,
  8. "time_window": 60,
  9. "rejected_code": 503,
  10. "key_type": "var_combination",
  11. "key": "$consumer_name $remote_addr"
  12. }
  13. },
  14. "upstream": {
  15. "type": "roundrobin",
  16. "nodes": {
  17. "127.0.0.1:9001": 1
  18. }
  19. }
  20. }'

支持在多个路由间共享同一个限流计数器。首先通过以下命令创建一个服务:

  1. curl -i http://127.0.0.1:9180/apisix/admin/services/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "plugins": {
  5. "limit-count": {
  6. "count": 1,
  7. "time_window": 60,
  8. "rejected_code": 503,
  9. "key": "remote_addr",
  10. "group": "services_1#1640140620"
  11. }
  12. },
  13. "upstream": {
  14. "type": "roundrobin",
  15. "nodes": {
  16. "127.0.0.1:1980": 1
  17. }
  18. }
  19. }'

然后为路由配置 service_id1 ,不同路由将共享同一个计数器:

  1. curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "service_id": "1",
  5. "uri": "/hello"
  6. }'
  1. curl -i http://127.0.0.1:9180/apisix/admin/routes/2 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "service_id": "1",
  5. "uri": "/hello2"
  6. }'

通过将 key_type 设置为 "constant",你也可以在所有请求间共享同一个限流计数器:

  1. curl -i http://127.0.0.1:9180/apisix/admin/services/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "plugins": {
  5. "limit-count": {
  6. "count": 1,
  7. "time_window": 60,
  8. "rejected_code": 503,
  9. "key": "remote_addr",
  10. "key_type": "constant",
  11. "group": "services_1#1640140621"
  12. }
  13. },
  14. "upstream": {
  15. "type": "roundrobin",
  16. "nodes": {
  17. "127.0.0.1:1980": 1
  18. }
  19. }
  20. }'

以上配置表示:当多个路由中 limit-count 插件的 group 属性均配置为 services_1#1640140620 时,访问这些路由的请求将会共享同一个计数器,即使这些请求来自于不同的 IP 地址。

limit-count - 图1注意

同一个 group 里面的 limit-count 的配置必须保持一致。如果修改配置,需要同时更新对应的 group 的值。

如果你需要一个集群级别的流量控制,我们可以借助 Redis 服务器来完成。不同的 APISIX 节点之间将共享流量限速结果,实现集群流量限速。

以下示例展示了如何在指定路由上启用 redis 策略:

  1. curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "uri": "/index.html",
  5. "plugins": {
  6. "limit-count": {
  7. "count": 2,
  8. "time_window": 60,
  9. "rejected_code": 503,
  10. "key": "remote_addr",
  11. "policy": "redis",
  12. "redis_host": "127.0.0.1",
  13. "redis_port": 6379,
  14. "redis_password": "password",
  15. "redis_database": 1,
  16. "redis_timeout": 1001
  17. }
  18. },
  19. "upstream": {
  20. "type": "roundrobin",
  21. "nodes": {
  22. "127.0.0.1:1980": 1
  23. }
  24. }
  25. }'

你也可以使用 redis-cluster 策略:

  1. curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "uri": "/index.html",
  5. "plugins": {
  6. "limit-count": {
  7. "count": 2,
  8. "time_window": 60,
  9. "rejected_code": 503,
  10. "key": "remote_addr",
  11. "policy": "redis-cluster",
  12. "redis_cluster_nodes": [
  13. "127.0.0.1:5000",
  14. "127.0.0.1:5001"
  15. ],
  16. "redis_password": "password",
  17. "redis_cluster_name": "redis-cluster-1"
  18. }
  19. },
  20. "upstream": {
  21. "type": "roundrobin",
  22. "nodes": {
  23. "127.0.0.1:1980": 1
  24. }
  25. }
  26. }'

测试插件

在上文提到的配置中,其限制了 60 秒内请求只能访问 2 次,可通过如下 curl 命令测试请求访问:

  1. curl -i http://127.0.0.1:9080/index.html

在执行测试命令的前两次都会正常访问。其中响应头中包含了 X-RateLimit-LimitX-RateLimit-Remaining 字段,分别代表限制的总请求数和剩余还可以发送的请求数:

  1. HTTP/1.1 200 OK
  2. Content-Type: text/html
  3. Content-Length: 13175
  4. Connection: keep-alive
  5. X-RateLimit-Limit: 2
  6. X-RateLimit-Remaining: 0
  7. Server: APISIX web server

当第三次进行测试访问时,会收到包含 503 HTTP 状态码的响应头,表示插件生效:

  1. HTTP/1.1 503 Service Temporarily Unavailable
  2. Content-Type: text/html
  3. Content-Length: 194
  4. Connection: keep-alive
  5. Server: APISIX web server

如果你设置了属性 rejected_msg 的值为 "Requests are too frequent, please try again later.",当第三次访问时,就会收到如下带有 error_msg 返回信息的响应体:

  1. HTTP/1.1 503 Service Temporarily Unavailable
  2. Content-Type: text/html
  3. Content-Length: 194
  4. Connection: keep-alive
  5. Server: APISIX web server
  6. {"error_msg":"Requests are too frequent, please try again later."}

禁用插件

当你需要禁用该插件时,可以通过以下命令删除相应的 JSON 配置,APISIX 将会自动重新加载相关配置,无需重启服务:

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "methods": ["GET"],
  5. "uri": "/index.html",
  6. "upstream": {
  7. "type": "roundrobin",
  8. "nodes": {
  9. "127.0.0.1:1980": 1
  10. }
  11. }
  12. }'