跳到主要内容

limit-conn

limit-conn 插件限制 HTTP 并发请求、WebSocket 连接以及 Stream 路由上的 TCP 连接。超过配置阈值的流量可以被延迟或拒绝，从而控制资源使用并防止过载。

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

对于 HTTP 路由，limit-conn 插件支持两种限速模式：

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

Stream 插件 Schema 未定义 policy，因此本文档中的 Stream 配置使用本地计数器。有关 Stream 参数和示例，请参阅限制 Stream 路由上的 TCP 连接。

示例​

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

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

以下示例演示了如何使用 limit-conn 通过 remote_addr 对请求进行速率限制，并配置连接数和突发阈值。

创建一个启用了 limit-conn 插件的路由：

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

❶ conn：允许 2 个并发请求。

❷ burst：允许 1 个额外的并发请求。

❸ default_conn_delay：对于并发数介于 conn 和 conn + burst 之间的请求，允许 0.1 秒的处理延迟。

❹ key_type：设置为 var，将 key 解释为变量。

❺ key：根据请求的 remote_addr 计算限速计数。

❻ policy：使用内存中的本地计数器。

❼ rejected_code：将拒绝状态码设置为 429。

向该路由发送五个并发请求：

seq 1 5 | xargs -n1 -P5 bash -c 'curl -s -o /dev/null -w "Response: %{http_code}\n" "http://127.0.0.1:9080/get"'

你应该会看到类似于以下的响应，其中多余的请求被拒绝：

Response: 200
Response: 200
Response: 200
Response: 429
Response: 429

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

以下示例演示了如何使用 limit-conn 通过变量组合 remote_addr 和 consumer_name 对请求进行速率限制。

创建消费者 john：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "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"
  }'

为该消费者创建 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-conn 插件的路由：

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

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

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

❸ key: 设置为 $remote_addr $consumer_name 以根据远程地址和消费者应用限速配额。

作为消费者 john 发送五个并发请求：

seq 1 5 | xargs -n1 -P5 bash -c 'curl -s -o /dev/null -w "Response: %{http_code}\n" "http://127.0.0.1:9080/get" -H "apikey: john-key"'

你应该会看到类似于以下的响应，其中多余的请求被拒绝：

Response: 200
Response: 200
Response: 200
Response: 429
Response: 429

立即作为消费者 jane 发送五个并发请求：

seq 1 5 | xargs -n1 -P5 bash -c 'curl -s -o /dev/null -w "Response: %{http_code}\n" "http://127.0.0.1:9080/get" -H "apikey: jane-key"'

你应该也会看到类似于以下的响应，其中多余的请求被拒绝：

Response: 200
Response: 200
Response: 200
Response: 429
Response: 429

在这种情况下，插件通过变量组合 remote_addr 和 consumer_name 进行速率限制，这意味着每个消费者的配额是独立的。

限制 WebSocket 连接速率​

以下示例演示了如何使用 limit-conn 插件来限制并发 WebSocket 连接数。

启动一个示例上游 WebSocket 服务器：

docker run -d \
  -p 8080:8080 \
  --name websocket-server \
  --network=apisix-quickstart-net \
  jmalloc/echo-server

该服务器在 /.ws 提供 WebSocket 端点，会原样返回收到的所有消息。

创建一条到 WebSocket 服务器端点的路由，并为该路由启用 WebSocket：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "ws-route",
  "uri": "/.ws",
  "plugins": {
    "limit-conn": {
      "conn": 2,
      "burst": 1,
      "default_conn_delay": 0.1,
      "key_type": "var",
      "key": "remote_addr",
      "rejected_code": 429,
      "policy": "local"
    }
  },
  "enable_websocket": true,
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "websocket-server:8080": 1
    }
  }
}'

❶ 为路由启用 WebSocket。

❷ 替换为你的 WebSocket 服务器地址。

安装一个 WebSocket 客户端，例如 websocat（如果你还没有安装）。通过路由与 WebSocket 服务器建立连接：

websocat "ws://127.0.0.1:9080/.ws"

在终端中发送一条 "hello" 消息，你应该会看到 WebSocket 服务器回显相同的消息：

Request served by 1cd244052136
hello
hello

再打开三个终端会话并运行：

websocat "ws://127.0.0.1:9080/.ws"

当你尝试与服务器建立 WebSocket 连接时，你应该会看到最后一个终端会话打印 429 Too Many Requests，这是由于速率限制的影响。

限制 Stream 路由上的 TCP 连接​

此示例限制 APISIX Stream 路由上来自每个客户端地址的 TCP 并发连接。它允许每个客户端有一个活动连接，并在该活动连接结束前关闭其他连接。

创建 Stream 路由前，请配置 APISIX 以监听端口 9100 上的 TCP 流量。

在网关配置文件中添加或更新以下部分：

config.yaml
apisix:
  proxy_mode: http&stream
  stream_proxy:
    tcp:
      - 9100

对于主机安装，更新配置后重新加载 APISIX：

apisix reload

对于 APISIX 快速入门容器，请在创建或重新部署容器时将端口 9100 从容器发布到主机，例如添加 -p 9100:9100。然后在容器中重新加载 APISIX：

docker exec apisix-quickstart apisix reload

有关公开 Stream 监听器的更多信息，请参阅代理传输层（L4）流量。

创建一个 Stream 路由，允许来自每个客户端地址的一个并发连接，并将 TCP 流量代理到一个支持 HTTP 的测试服务：

curl "http://127.0.0.1:9180/apisix/admin/stream_routes/limit-conn-tcp" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "server_port": 9100,
    "plugins": {
      "limit-conn": {
        "conn": 1,
        "burst": 0,
        "default_conn_delay": 0.1,
        "key_type": "var",
        "key": "remote_addr"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

❶ conn：允许每个客户端地址有一个并发 TCP 连接。

❷ burst：将突发容量设为 0，使超出限制的连接立即被拒绝，而不是延迟处理。

❸ default_conn_delay：将必填的基础延迟设为 0.1 秒。由于 burst 为 0，此示例不会延迟超额连接。

❹ key_type：将配置的 Key 解释为变量。

❺ key：使用 remote_addr 分别统计每个客户端地址的连接数。

打开与 Stream 路由的 TCP 连接，并保持该会话打开：

nc 127.0.0.1 9100

在另一个终端中，尝试从同一客户端地址打开第二个连接：

curl -i --max-time 5 \
  -H "Host: httpbin.org" \
  "http://127.0.0.1:9100/get"

第二个连接会被拒绝，终端显示：

curl: (52) Empty reply from server

根据客户端和操作系统的不同，也可能显示 Connection reset by peer。

关闭 nc 会话，然后再次运行请求：

curl -i --max-time 5 \
  -H "Host: httpbin.org" \
  "http://127.0.0.1:9100/get"

由于连接槽位再次可用，连接现在会成功：

HTTP/1.1 200 OK
Content-Type: application/json
...
{
  "url": "http://httpbin.org/get"
}

API7 网关使用 Stream 服务和网关组范围的 Admin API 请求。有关其 limit-conn Stream 路由配置流程，请参阅配置 TCP/UDP 代理。

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

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

在每个 APISIX 实例上，使用以下配置创建路由，并根据实际环境调整配置详情。

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-conn-route",
    "uri": "/get",
    "plugins": {
      "limit-conn": {
        "conn": 1,
        "burst": 1,
        "default_conn_delay": 0.1,
        "rejected_code": 429,
        "key_type": "var",
        "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 实例中的数据库编号。

向该路由发送五个并发请求：

seq 1 5 | xargs -n1 -P5 bash -c 'curl -s -o /dev/null -w "Response: %{http_code}\n" "http://127.0.0.1:9080/get"'

你应该会看到类似于以下的响应，其中多余的请求被拒绝：

Response: 200
Response: 200
Response: 429
Response: 429
Response: 429

这表明配置在不同 APISIX 实例中的两个路由共享相同的配额。

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

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

确保 Redis 实例以集群模式运行。在 limit-conn 插件中配置 redis_cluster_name，并在 redis_cluster_nodes 中配置一个或多个节点地址。

在每个 APISIX 实例上，使用以下配置创建路由，并根据实际环境调整配置详情。

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-conn-route",
    "uri": "/get",
    "plugins": {
      "limit-conn": {
        "conn": 1,
        "burst": 1,
        "default_conn_delay": 0.1,
        "rejected_code": 429,
        "key_type": "var",
        "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 通信。

向该路由发送五个并发请求：

seq 1 5 | xargs -n1 -P5 bash -c 'curl -s -o /dev/null -w "Response: %{http_code}\n" "http://127.0.0.1:9080/get"'

你应该会看到类似于以下的响应，其中多余的请求被拒绝：

Response: 200
Response: 200
Response: 429
Response: 429
Response: 429

这表明配置在不同 APISIX 实例中的两个路由共享相同的配额。

基于规则的速率限制​

以下示例演示了如何配置 limit-conn 以根据请求属性应用不同的速率限制规则（从 API7 企业版 3.8.17 开始可用）。在此示例中，速率限制基于代表调用者访问层级的 HTTP 头值应用。

请注意，所有规则按顺序应用。如果配置的键不存在，则将跳过相应的规则。

提示

除 HTTP 请求头外，还可以根据其他内置变量配置规则，以实现更灵活、更细粒度的限速策略。

创建一个启用了 limit-conn 插件的路由，该插件根据请求头应用不同的速率限制，允许每个订阅（X-Subscription-ID）进行速率限制，并对试用用户（X-Trial-ID）强制执行更严格的限制：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "limit-conn-rules-route",
    "uri": "/get",
    "plugins": {
      "limit-conn": {
        "rejected_code": 429,
        "default_conn_delay": 0.1,
        "policy": "local",
        "rules": [
          {
            "key": "${http_x_subscription_id}",
            "conn": "${http_x_custom_conn ?? 5}",
            "burst": 1
          },
          {
            "key": "${http_x_trial_id}",
            "conn": 1,
            "burst": 1
          }
        ]
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

❶ 使用 X-Subscription-ID 请求头的值作为速率限制键。

❷ 根据 X-Custom-Conn 头动态设置请求连接。如果未提供该头，则应用默认并发连接数 5。

❸ 使用 X-Trial-ID 请求头的值作为速率限制键。

要验证速率限制，使用相同的订阅 ID 发送 7 个并发请求到该路由：

seq 1 7 | xargs -n1 -P7 bash -c 'curl -s -o /dev/null -w "Response: %{http_code}\n" "http://127.0.0.1:9080/get" -H "X-Subscription-ID: sub-123456789"'

你应该会看到以下响应，显示当未提供 X-Custom-Conn 头时，应用了 5 个并发连接限制和 1 个突发请求：

Response: 429
Response: 200
Response: 200
Response: 200
Response: 200
Response: 200
Response: 200

使用相同的订阅 ID 发送 5 个并发请求到该路由，并将 X-Custom-Conn 头设置为 1：

seq 1 5 | xargs -n1 -P5 bash -c 'curl -s -o /dev/null -w "Response: %{http_code}\n" "http://127.0.0.1:9080/get" -H "X-Subscription-ID: sub-123456789" -H "X-Custom-Conn: 1"'

你应该会看到以下响应，显示应用了 1 个并发连接限制和 1 个突发请求：

Response: 429
Response: 429
Response: 429
Response: 200
Response: 200

最后，使用试用 ID 头生成 5 个请求到该路由：

seq 1 5 | xargs -n1 -P5 bash -c 'curl -s -o /dev/null -w "Response: %{http_code}\n" "http://127.0.0.1:9080/get" -H "X-Trial-ID: trial-123456789"'

你应该会看到以下响应，显示应用了 1 个并发连接限制和 1 个突发请求：

Response: 429
Response: 429
Response: 429
Response: 200
Response: 200