diff --git a/docs/en/latest/plugins/limit-conn.md b/docs/en/latest/plugins/limit-conn.md index 82751d02edb8..8b08ab13a2de 100644 --- a/docs/en/latest/plugins/limit-conn.md +++ b/docs/en/latest/plugins/limit-conn.md @@ -4,7 +4,7 @@ keywords: - Apache APISIX - API Gateway - Limit Connection -description: This document contains information about the Apache APISIX limit-con Plugin, you can use it to limits the number of concurrent requests to your services. +description: The limit-conn plugin restricts the rate of requests by managing concurrent connections. Requests exceeding the threshold may be delayed or rejected, ensuring controlled API usage and preventing overload. --- + + + + ## Description -The `limit-conn` Plugin limits the number of concurrent requests to your services. +The `limit-conn` Plugin limits the rate of requests by the number of concurrent connections. Requests exceeding the threshold will be delayed or rejected based on the configuration, ensuring controlled resource usage and preventing overload. ## Attributes -| Name | Type | Required | Default | Valid values | Description | -|--------------------------|---------| -------- |-------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| conn | integer | True | | conn > 0 | Maximum number of concurrent requests allowed. Requests exceeding this ratio (and below `conn` + `burst`) will be delayed (configured by `default_conn_delay`). | -| burst | integer | True | | burst >= 0 | Number of additional concurrent requests allowed to be delayed per second. If the number exceeds this hard limit, they will get rejected immediately. | -| default_conn_delay | number | True | | default_conn_delay > 0 | Delay in seconds to process the concurrent requests exceeding `conn` (and `conn` + `burst`). | -| only_use_default_delay | boolean | False | false | [true,false] | When set to `true`, the Plugin will always set a delay of `default_conn_delay` and would not use any other calculations. | -| key_type | string | False | "var" | ["var", "var_combination"] | Type of user specified key to use. | -| key | string | True | | | User specified key to base the request limiting on. If the `key_type` attribute is set to `"var"`, the key will be treated as a name of variable, like `remote_addr` or `consumer_name`. If the `key_type` is set to `"var_combination"`, the key will be a combination of variables, like `$remote_addr $consumer_name`. If the value of the key is empty, `remote_addr` will be set as the default key. | -| rejected_code | string | False | 503 | [200,...,599] | HTTP status code returned when the requests exceeding the threshold are rejected. | -| rejected_msg | string | False | | non-empty | Body of the response returned when the requests exceeding the threshold are rejected. | -| allow_degradation | boolean | False | false | | When set to `true` enables Plugin degradation when the Plugin is temporarily unavailable and allows requests to continue. | -| policy | string | False | "local" | ["local", "redis", "redis-cluster"] | Rate-limiting policies to use for retrieving and increment the limit count. When set to `local` the counters will be locally stored in memory on the node. When set to `redis` counters are stored on a Redis server and will be shared across the nodes. It is done usually for global speed limiting, and setting to `redis-cluster` uses a Redis cluster instead of a single instance. | -| redis_host | string | required when `policy` is `redis` | | | Address of the Redis server. Used when the `policy` attribute is set to `redis`. | -| redis_port | integer | False | 6379 | [1,...] | Port of the Redis server. Used when the `policy` attribute is set to `redis`. | -| redis_username | string | False | | | Username for Redis authentication if Redis ACL is used (for Redis version >= 6.0). If you use the legacy authentication method `requirepass` to configure Redis password, configure only the `redis_password`. Used when the `policy` is set to `redis`. | -| redis_password | string | False | | | Password for Redis authentication. Used when the `policy` is set to `redis` or `redis-cluster`. | -| redis_ssl | boolean | False | false | | If set to `true`, then uses SSL to connect to redis instance. Used when the `policy` attribute is set to `redis`. | -| redis_ssl_verify | boolean | False | false | | If set to `true`, then verifies the validity of the server SSL certificate. Used when the `policy` attribute is set to `redis`. See [tcpsock:sslhandshake](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake). | -| redis_database | integer | False | 0 | redis_database >= 0 | Selected database of the Redis server (for single instance operation or when using Redis cloud with a single entrypoint). Used when the `policy` attribute is set to `redis`. | -| redis_timeout | integer | False | 1000 | [1,...] | Timeout in milliseconds for any command submitted to the Redis server. Used when the `policy` attribute is set to `redis` or `redis-cluster`. | -| redis_cluster_nodes | array | required when `policy` is `redis-cluster` | | | Addresses of Redis cluster nodes. Used when the `policy` attribute is set to `redis-cluster`. | -| redis_cluster_name | string | required when `policy` is `redis-cluster` | | | Name of the Redis cluster service nodes. Used when the `policy` attribute is set to `redis-cluster`. | -| redis_cluster_ssl | boolean | False | false | | If set to `true`, then uses SSL to connect to redis-cluster. Used when the `policy` attribute is set to `redis-cluster`. | -| redis_cluster_ssl_verify | boolean | False | false | | If set to `true`, then verifies the validity of the server SSL certificate. Used when the `policy` attribute is set to `redis-cluster`. | - -## Enable Plugin - -You can enable the Plugin on a Route as shown below: +| Name | Type | Required | Default | Valid values | Description | +|------------|---------|----------|-------------|-------------------|-----------------| +| conn | integer | True | | > 0 | The maximum number of concurrent requests allowed. Requests exceeding the configured limit and below `conn + burst` will be delayed. | +| burst | integer | True | | >= 0 | The number of excessive concurrent requests allowed to be delayed per second. Requests exceeding the limit will be rejected immediately. | +| default_conn_delay | number | True | | > 0 | Processing latency allowed in seconds for concurrent requests exceeding `conn + burst`, which can be dynamically adjusted based on `only_use_default_delay` setting. | +| only_use_default_delay | boolean | False | false | | If false, delay requests proportionally based on how much they exceed the `conn` limit. The delay grows larger as congestion increases. For instance, with `conn` being `5`, `burst` being `3`, and `default_conn_delay` being `1`, 6 concurrent requests would result in a 1-second delay, 7 requests a 2-second delay, 8 requests a 3-second delay, and so on, until the total limit of `conn + burst` is reached, beyond which requests are rejected. If true, use `default_conn_delay` to delay all excessive requests within the `burst` range. Requests beyond `conn + burst` are rejected immediately. For instance, with `conn` being `5`, `burst` being `3`, and `default_conn_delay` being `1`, 6, 7, or 8 concurrent requests are all delayed by exactly 1 second each. | +| key_type | string | False | var | ["var","var_combination"] | The type of key. If the `key_type` is `var`, the `key` is interpreted a variable. If the `key_type` is `var_combination`, the `key` is interpreted as a combination of variables. | +| key | string | False | remote_addr | | The key to count requests by. If the `key_type` is `var`, the `key` is interpreted a variable. The variable does not need to be prefixed by a dollar sign (`$`). If the `key_type` is `var_combination`, the `key` is interpreted as a combination of variables. All variables should be prefixed by dollar signs (`$`). For example, to configure the `key` to use a combination of two request headers `custom-a` and `custom-b`, the `key` should be configured as `$http_custom_a $http_custom_b`. | +| rejected_code | integer | False | 503 | [200,...,599] | The HTTP status code returned when a request is rejected for exceeding the threshold. | +| rejected_msg | string | False | | non-empty | The response body returned when a request is rejected for exceeding the threshold. | +| allow_degradation | boolean | False | false | | If true, allow APISIX to continue handling requests without the Plugin when the Plugin or its dependencies become unavailable. | +| policy | string | False | local | ["local","redis","redis-cluster"] | The policy for rate limiting counter. If it is `local`, the counter is stored in memory locally. If it is `redis`, the counter is stored on a Redis instance. If it is `redis-cluster`, the counter is stored in a Redis cluster. | +| redis_host | string | False | | | The address of the Redis node. Required when `policy` is `redis`. | +| redis_port | integer | False | 6379 | [1,...] | The port of the Redis node when `policy` is `redis`. | +| redis_username | string | False | | | The username for Redis if Redis ACL is used. If you use the legacy authentication method `requirepass`, configure only the `redis_password`. Used when `policy` is `redis`. | +| redis_password | string | False | | | The password of the Redis node when `policy` is `redis` or `redis-cluster`. | +| redis_ssl | boolean | False | false | | If true, use SSL to connect to Redis cluster when `policy` is `redis`. | +| redis_ssl_verify | boolean | False | false | | If true, verify the server SSL certificate when `policy` is `redis`. | +| redis_database | integer | False | 0 | >= 0 | The database number in Redis when `policy` is `redis`. | +| redis_timeout | integer | False | 1000 | [1,...] | The Redis timeout value in milliseconds when `policy` is `redis` or `redis-cluster`. | +| redis_cluster_nodes | array[string] | False | | | The list of the Redis cluster nodes with at least two addresses. Required when policy is redis-cluster. | +| redis_cluster_name | string | False | | | The name of the Redis cluster. Required when `policy` is `redis-cluster`. | +| redis_cluster_ssl | boolean | False | false | | If true, use SSL to connect to Redis cluster when `policy` is | +| redis_cluster_ssl_verify | boolean | False | false | | If true, verify the server SSL certificate when `policy` is `redis-cluster`. | + +## Examples + +The examples below demonstrate how you can configure `limit-conn` in different scenarios. :::note + You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: ```bash @@ -70,162 +75,346 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Apply Rate Limiting by Remote Address + +The following example demonstrates how to use `limit-conn` to rate limit requests by `remote_addr`, with example connection and burst thresholds. + +Create a Route with `limit-conn` Plugin to allow 2 concurrent requests and 1 excessive concurrent request. Additionally: + +* Configure the Plugin to allow 0.1 second of processing latency for concurrent requests exceeding `conn + burst`. +* Set the key type to `vars` to interpret `key` as a variable. +* Calculate rate limiting count by request's `remote_address`. +* Set `policy` to `local` to use the local counter in memory. +* Customize the `rejected_code` to `429`. + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uri": "/index.html", +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "limit-conn-route", + "uri": "/get", "plugins": { - "limit-conn": { - "conn": 1, - "burst": 0, - "default_conn_delay": 0.1, - "rejected_code": 503, - "key_type": "var", - "key": "http_a" - } + "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": { - "127.0.0.1:1980": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' ``` -You can also configure the `key_type` to `var_combination` as shown: +Send five concurrent requests to the route: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uri": "/index.html", +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"' +``` + +You should see responses similar to the following, where excessive requests are rejected: + +```text +Response: 200 +Response: 200 +Response: 200 +Response: 429 +Response: 429 +``` + +### Apply Rate Limiting by Remote Address and Consumer Name + +The following example demonstrates how to use `limit-conn` to rate limit requests by a combination of variables, `remote_addr` and `consumer_name`. + +Create a Consumer `john`: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "john" + }' +``` + +Create `key-auth` Credential for the Consumer: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-john-key-auth", "plugins": { - "limit-conn": { - "conn": 1, - "burst": 0, - "default_conn_delay": 0.1, - "rejected_code": 503, - "key_type": "var_combination", - "key": "$consumer_name $remote_addr" - } + "key-auth": { + "key": "john-key" + } + } + }' +``` + +Create a second Consumer `jane`: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "jane" + }' +``` + +Create `key-auth` Credential for the Consumer: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/jane/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-jane-key-auth", + "plugins": { + "key-auth": { + "key": "jane-key" + } + } + }' +``` + +Create a Route with `key-auth` and `limit-conn` Plugins, and specify in the `limit-conn` Plugin to use a combination of variables as the rate limiting key: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_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, + "key_type": "var_combination", + "key": "$remote_addr $consumer_name" + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } + }' +``` + +Send five concurrent requests as the Consumer `john`: + +```shell +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"' +``` + +You should see responses similar to the following, where excessive requests are rejected: + +```text +Response: 200 +Response: 200 +Response: 200 +Response: 429 +Response: 429 +``` + +Immediately send five concurrent requests as the Consumer `jane`: + +```shell +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"' +``` + +You should also see responses similar to the following, where excessive requests are rejected: + +```text +Response: 200 +Response: 200 +Response: 200 +Response: 429 +Response: 429 +``` + +### Rate Limit WebSocket Connections + +The following example demonstrates how you can use the `limit-conn` Plugin to limit the number of concurrent WebSocket connections. + +Start a [sample upstream WebSocket server](https://hub.docker.com/r/jmalloc/echo-server): + +```shell +docker run -d \ + -p 8080:8080 \ + --name websocket-server \ + --network=apisix-quickstart-net \ + jmalloc/echo-server +``` + +Create a Route to the server WebSocket endpoint and enable WebSocket for the route. Adjust the WebSocket server address accordingly. + +```shell +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 + } + }, + "enable_websocket": true, + "upstream": { + "type": "roundrobin", + "nodes": { + "websocket-server:8080": 1 + } + } }' ``` -## Example usage +Install a WebSocket client, such as [websocat](https://github.com/vi/websocat), if you have not already. Establish connection with the WebSocket server through the route: + +```shell +websocat "ws://127.0.0.1:9080/.ws" +``` + +Send a "hello" message in the terminal, you should see the WebSocket server echoes back the same message: + +```text +Request served by 1cd244052136 +hello +hello +``` -The example above configures the Plugin to only allow one connection on this route. When more than one request is received, the Plugin will respond with a `503` HTTP status code and reject the connection: +Open three more terminal sessions and run: ```shell -curl -i http://127.0.0.1:9080/index.html?sleep=20 & +websocat "ws://127.0.0.1:9080/.ws" +``` + +You should see the last terminal session prints `429 Too Many Requests` when you try to establish a WebSocket connection with the server, due to the rate limiting effect. -curl -i http://127.0.0.1:9080/index.html?sleep=20 +### Share Quota Among APISIX Nodes with a Redis Server + +The following example demonstrates the rate limiting of requests across multiple APISIX nodes with a Redis server, such that different APISIX nodes share the same rate limiting quota. + +On each APISIX instance, create a Route with the following configurations. Adjust the address of the Admin API, Redis host, port, password, and database accordingly. + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_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 + } + } + }' ``` +Send five concurrent requests to the route: + ```shell - -503 Service Temporarily Unavailable - -

503 Service Temporarily Unavailable

-
openresty
- - +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"' +``` + +You should see responses similar to the following, where excessive requests are rejected: + +```text +Response: 200 +Response: 200 +Response: 429 +Response: 429 +Response: 429 ``` -## Delete Plugin +This shows the two routes configured in different APISIX instances share the same quota. -To remove the `limit-conn` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. +### Share Quota Among APISIX Nodes with a Redis Cluster + +You can also use a Redis cluster to apply the same quota across multiple APISIX nodes, such that different APISIX nodes share the same rate limiting quota. + +Ensure that your Redis instances are running in [cluster mode](https://redis.io/docs/management/scaling/#create-and-use-a-redis-cluster). A minimum of two nodes are required for the `limit-conn` Plugin configurations. + +On each APISIX instance, create a Route with the following configurations. Adjust the address of the Admin API, Redis cluster nodes, password, cluster name, and SSL varification accordingly. ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uri": "/index.html", - "id": 1, +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_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-1", + "redis_cluster_ssl": true + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' +``` + +Send five concurrent requests to the route: + +```shell +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"' +``` + +You should see responses similar to the following, where excessive requests are rejected: + +```text +Response: 200 +Response: 200 +Response: 429 +Response: 429 +Response: 429 ``` -## Example of application scenarios - -### Limit the number of concurrent WebSocket connections - -Apache APISIX supports WebSocket proxy, we can use `limit-conn` plugin to limit the number of concurrent WebSocket connections. - -1. Create a Route, enable the WebSocket proxy and the `limit-conn` plugin. - - ```shell - curl http://127.0.0.1:9180/apisix/admin/routes/1 \ - -H "X-API-KEY: $admin_key" -X PUT -d ' - { - "uri": "/ws", - "enable_websocket": true, - "plugins": { - "limit-conn": { - "conn": 1, - "burst": 0, - "default_conn_delay": 0.1, - "rejected_code": 503, - "key_type": "var", - "key": "remote_addr" - } - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } - } - }' - ``` - - The above route enables the WebSocket proxy on `/ws`, and limits the number of concurrent WebSocket connections to 1. More than 1 concurrent WebSocket connection will return `503` to reject the request. - -2. Initiate a WebSocket request, and the connection is established successfully. - - ```shell - curl --include \ - --no-buffer \ - --header "Connection: Upgrade" \ - --header "Upgrade: websocket" \ - --header "Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==" \ - --header "Sec-WebSocket-Version: 13" \ - --http1.1 \ - http://127.0.0.1:9080/ws - ``` - - ```shell - HTTP/1.1 101 Switching Protocols - ``` - -3. Initiate the WebSocket request again in another terminal, the request will be rejected. - - ```shell - HTTP/1.1 503 Service Temporarily Unavailable - ··· - - 503 Service Temporarily Unavailable - -

503 Service Temporarily Unavailable

-
openresty
- - - ``` +This shows the two routes configured in different APISIX instances share the same quota. diff --git a/docs/zh/latest/plugins/limit-conn.md b/docs/zh/latest/plugins/limit-conn.md index 51142e1ce2c7..e90fabd644bd 100644 --- a/docs/zh/latest/plugins/limit-conn.md +++ b/docs/zh/latest/plugins/limit-conn.md @@ -4,7 +4,7 @@ keywords: - APISIX - API 网关 - Limit Connection -description: 本文介绍了 Apache APISIX limit-conn 插件的相关操作，你可以使用此插件限制客户端对服务的并发请求数。 +description: limit-conn 插件通过管理并发连接来限制请求速率。超过阈值的请求可能会被延迟或拒绝，以确保 API 使用受控并防止过载。 --- + + + + ## 描述 -`limit-conn` 插件用于限制客户端对单个服务的并发请求数。当客户端对路由的并发请求数达到限制时，可以返回自定义的状态码和响应信息。 +`limit-conn` 插件通过并发连接数来限制请求速率。超过阈值的请求将根据配置被延迟或拒绝，从而确保可控的资源使用并防止过载。 ## 属性 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| ------------------ | ------- |----------------------------------| ------ | -------------------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| conn | integer | 是 | | conn > 0 | 允许的最大并发请求数。超过 `conn` 的限制、但是低于 `conn` + `burst` 的请求，将被延迟处理。 | -| burst | integer | 是 | | burst >= 0 | 每秒允许被延迟处理的额外并发请求数。 | -| default_conn_delay | number | 是 | | default_conn_delay > 0 | 默认的典型连接（或请求）的处理延迟时间。 | -| only_use_default_delay | boolean | 否 | false | [true,false] | 延迟时间的严格模式。当设置为 `true` 时，将会严格按照设置的 `default_conn_delay` 时间来进行延迟处理。 | -| key_type | string | 否 | "var" | ["var", "var_combination"] | `key` 的类型。 | -| key | string | 是 | | | 用来做请求计数的依据。如果 `key_type` 为 `"var"`，那么 `key` 会被当作变量名称，如 `remote_addr` 和 `consumer_name`；如果 `key_type` 为 `"var_combination"`，那么 `key` 会当作变量组合，如 `$remote_addr $consumer_name`；如果 `key` 的值为空，`$remote_addr` 会被作为默认 `key`。 | -| rejected_code | string | 否 | 503 | [200,...,599] | 当请求数超过 `conn` + `burst` 阈值时，返回的 HTTP 状态码。 | -| rejected_msg | string | 否 | | 非空 | 当请求数超过 `conn` + `burst` 阈值时，返回的信息。 | -| allow_degradation | boolean | 否 | false | | 当设置为 `true` 时，启用插件降级并自动允许请求继续。 | -| policy | string | 否 | "local" | ["local", "redis", "redis-cluster"] | 用于检索和增加限制计数的策略。当设置为 `local` 时，计数器被以内存方式保存在节点本地；当设置为 `redis` 时，计数器保存在 Redis 服务节点上，从而可以跨节点共享结果，通常用它来完成全局限速；当设置为 `redis-cluster` 时，使用 Redis 集群而不是单个实例。| -| redis_host | string | 否 | | | 当使用 `redis` 限速策略时，Redis 服务节点的地址。**当 `policy` 属性设置为 `redis` 时必选。** | -| redis_port | integer | 否 | 6379 | [1,...] | 当使用 `redis` 限速策略时，Redis 服务节点的端口。 | -| redis_username | string | 否 | | | 若使用 Redis ACL 进行身份验证（适用于 Redis 版本 >=6.0），则需要提供 Redis 用户名。若使用 Redis legacy 方式 `requirepass` 进行身份验证，则只需将密码配置在 `redis_password`。当 `policy` 设置为 `redis` 时使用。 | -| redis_password | string | 否 | | | 当使用 `redis` 或者 `redis-cluster` 限速策略时，Redis 服务节点的密码。 | -| redis_ssl | boolean | 否 | false | | 当使用 `redis` 限速策略时，如果设置为 true，则使用 SSL 连接到 `redis` | -| redis_ssl_verify | boolean | 否 | false | | 当使用 `redis` 限速策略时，如果设置为 true，则验证服务器 SSL 证书的有效性，具体请参考 [tcpsock:sslhandshake](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake). | -| redis_database | integer | 否 | 0 | redis_database >= 0 | 当使用 `redis` 限速策略时，Redis 服务节点中使用的 `database`，并且只针对非 Redis 集群模式（单实例模式或者提供单入口的 Redis 公有云服务）生效。 | -| redis_timeout | integer | 否 | 1000 | [1,...] | 当 `policy` 设置为 `redis` 或 `redis-cluster` 时，Redis 服务节点的超时时间（以毫秒为单位）。 | -| redis_cluster_nodes | array | 否 | | | 当使用 `redis-cluster` 限速策略时，Redis 集群服务节点的地址列表（至少需要两个地址）。**当 `policy` 属性设置为 `redis-cluster` 时必选。** | -| redis_cluster_name | string | 否 | | | 当使用 `redis-cluster` 限速策略时，Redis 集群服务节点的名称。**当 `policy` 设置为 `redis-cluster` 时必选。** | -| redis_cluster_ssl | boolean | 否 | false | | 当使用 `redis-cluster` 限速策略时，如果设置为 true，则使用 SSL 连接到 `redis-cluster` | -| redis_cluster_ssl_verify | boolean | 否 | false | | 当使用 `redis-cluster` 限速策略时，如果设置为 true，则验证服务器 SSL 证书的有效性 | - -## 启用插件 - -以下示例展示了如何在指定路由上启用 `limit-conn` 插件，并设置 `key_type` 为 `"var"`： +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|------------|---------|----------|-------|----------------------------|------------------| +| conn | integer | 是 | | > 0 | 允许的最大并发请求数。超过配置的限制且低于`conn + burst`的请求将被延迟。| +| burst | integer | 是 | | >= 0 | 每秒允许延迟的过多并发请求数。超过限制的请求将被立即拒绝。| +| default_conn_delay | number | 是 | | > 0 | 允许超过`conn + burst`的并发请求的处理延迟（秒），可根据`only_use_default_delay`设置动态调整。| +| only_use_default_delay | boolean | 否 | false | | 如果为 false，则根据请求超出`conn`限制的程度按比例延迟请求。拥塞越严重，延迟就越大。例如，当 `conn` 为 `5`、`burst` 为 `3` 且 `default_conn_delay` 为 `1` 时，6 个并发请求将导致 1 秒的延迟，7 个请求将导致 2 秒的延迟，8 个请求将导致 3 秒的延迟，依此类推，直到达到 `conn + burst` 的总限制，超过此限制的请求将被拒绝。如果为 true，则使用 `default_conn_delay` 延迟 `burst` 范围内的所有超额请求。超出 `conn + burst` 的请求将被立即拒绝。例如，当 `conn` 为 `5`、`burst` 为 `3` 且 `default_conn_delay` 为 `1` 时，6、7 或 8 个并发请求都将延迟 1 秒。| +| key_type | string | 否 | var | ["var","var_combination"] | key 的类型。如果`key_type` 为 `var`，则 `key` 将被解释为变量。如果 `key_type` 为 `var_combination`，则 `key` 将被解释为变量的组合。 | +| key | string | 否 | remote_addr | | 用于计数请求的 key。如果 `key_type` 为 `var`，则 `key` 将被解释为变量。变量不需要以美元符号（`$`）为前缀。如果 `key_type` 为 `var_combination`，则 `key` 会被解释为变量的组合。所有变量都应该以美元符号 (`$`) 为前缀。例如，要配置 `key` 使用两个请求头 `custom-a` 和 `custom-b` 的组合，则 `key` 应该配置为 `$http_custom_a $http_custom_b`。| +| rejection_code | integer | 否 | 503 | [200,...,599] | 请求因超出阈值而被拒绝时返回的 HTTP 状态代码。| +| rejection_msg | string | 否 | | 非空 | 请求因超出阈值而被拒绝时返回的响应主体。| +| allow_degradation | boolean | 否 | false | | 如果为 true，则允许 APISIX 在插件或其依赖项不可用时继续处理没有插件的请求。| +| policy | string | 否 | local | ["local","re​​dis","re​​dis-cluster"] | 速率限制计数器的策略。如果是 `local`，则计数器存储在本地内存中。如果是 `redis`，则计数器存储在 Redis 实例上。如果是 `redis-cluster`，则计数器存储在 Redis 集群中。| +| redis_host | string | 否 | | | Redis 节点的地址。当 `policy` 为 `redis` 时必填。 | +| redis_port | integer | 否 | 6379 | [1,...] | 当 `policy` 为 `redis` 时，Redis 节点的端口。 | +| redis_username | string | 否 | | | 如果使用 Redis ACL，则为 Redis 的用户名。如果使用旧式身份验证方法 `requirepass`，则仅配置 `redis_password`。当 `policy` 为 `redis` 时使用。 | +| redis_password | string | 否 | | | 当 `policy` 为 `redis` 或 `redis-cluster` 时，Redis 节点的密码。 | +| redis_ssl | boolean | 否 | false |如果为 true，则在 `policy` 为 `redis` 时使用 SSL 连接到 Redis 集群。| +| redis_ssl_verify | boolean | 否 | false | | 如果为 true，则在 `policy` 为 `redis` 时验证服务器 SSL 证书。| +| redis_database | integer | 否 | 0 | >= 0 | 当 `policy` 为 `redis` 时，Redis 中的数据库编号。| +| redis_timeout | integer | 否 | 1000 | [1,...] | 当 `policy` 为 `redis` 或 `redis-cluster` 时，Redis 超时值（以毫秒为单位）。 | +| redis_cluster_nodes | array[string] | 否 | | | 具有至少两个地址的 Redis 群集节点列表。当 policy 为 redis-cluster 时必填。 | +redis_cluster_name | string | 否 | | | | Redis 集群的名称。当 `policy` 为 `redis-cluster` 时必须使用。| +| redis_cluster_ssl | boolean | 否 | false | | 如果为 `true`，当 `policy` 为 `redis-cluster`时，使用 SSL 连接 Redis 集群。| +| redis_cluster_ssl_verify | boolean | 否 | false | | 如果为 `true`，当 `policy` 为 `redis-cluster` 时，验证服务器 SSL 证书。 | + +## 示例 + +以下示例演示了如何在不同场景中配置 `limit-conn`。 :::note @@ -71,163 +75,346 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### 通过远程地址应用速率限制 + +以下示例演示如何使用 `limit-conn` 通过 `remote_addr` 限制请求速率，并附带示例连接和突发阈值。 + +使用 `limit-conn` 插件创建路由，以允许 2 个并发请求和 1 个过多的并发请求。此外： + +* 配置插件，允许超过 `conn + burst` 的并发请求有 0.1 秒的处理延迟。 +* 将密钥类型设置为 `vars`，以将 `key` 解释为变量。 +* 根据请求的 `remote_address` 计算速率限制计数。 +* 将 `policy` 设置为 `local`，以使用内存中的本地计数器。 +* 将 `rejected_code` 自定义为 `429`。 + ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uri": "/index.html", - "id": 1, +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "limit-conn-route", + "uri": "/get", "plugins": { - "limit-conn": { - "conn": 1, - "burst": 0, - "default_conn_delay": 0.1, - "rejected_code": 503, - "key_type": "var", - "key": "remote_addr" - } + "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": { - "127.0.0.1:1980": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' ``` -你也可以设置 `key_type` 为 `"var_combination"`： +向路由发送五个并发请求： ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uri": "/index.html", - "id": 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"' +``` + +您应该会看到类似以下内容的响应，其中超过阈值的请求被拒绝： + +```text +Response: 200 +Response: 200 +Response: 200 +Response: 429 +Response: 429 +``` + +### 通过远程地址和消费者名称应用速率限制 + +以下示例演示如何使用 `limit-conn` 通过变量组合 `remote_addr` 和 `consumer_name` 对请求进行速率限制。 + +创建消费者 `john`： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "john" + }' +``` + +为消费者创建 `key-auth` 凭证： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-john-key-auth", "plugins": { - "limit-conn": { - "conn": 1, - "burst": 0, - "default_conn_delay": 0.1, - "rejected_code": 503, - "key_type": "var_combination", - "key": "$consumer_name $remote_addr" - } + "key-auth": { + "key": "john-key" + } + } + }' +``` + +创建第二个消费者 `jane`： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "jane" + }' +``` + +为消费者创建 `key-auth` 凭证： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/jane/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-jane-key-auth", + "plugins": { + "key-auth": { + "key": "jane-key" + } + } + }' +``` + +创建一个带有 `key-auth` 和 `limit-conn` 插件的路由，并在 `limit-conn` 插件中指定使用变量组合作为速率限制 key： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_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, + "key_type": "var_combination", + "key": "$remote_addr $consumer_name" + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +作为消费者 `john` 发送五个并发请求： + +```shell +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"' +``` + +您应该会看到类似以下内容的响应，其中超过阈值的请求被拒绝： + +```text +Response: 200 +Response: 200 +Response: 200 +Response: 429 +Response: 429 +``` + +接下来立刻以消费者 `jane` 的身份发送五个并发请求： + +```shell +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"' +``` + +您还应该看到类似以下内容的响应，其中过多的请求被拒绝： + +```text +Response: 200 +Response: 200 +Response: 200 +Response: 429 +Response: 429 +``` + +### 限制 WebSocket 连接速率 + +以下示例演示了如何使用 `limit-conn` 插件来限制并发 WebSocket 连接的数量。 + +启动 [上游 WebSocket 服务器](https://hub.docker.com/r/jmalloc/echo-server)： + +```shell +docker run -d \ + -p 8080:8080 \ + --name websocket-server \ + --network=apisix-quickstart-net \ + jmalloc/echo-server +``` + +创建到服务器 WebSocket 端点的路由，并为路由启用 WebSocket。相应地调整 WebSocket 服务器地址。 + +```shell +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 + } + }, + "enable_websocket": true, + "upstream": { + "type": "roundrobin", + "nodes": { + "websocket-server:8080": 1 } + } }' ``` -## 测试插件 +安装 WebSocket 客户端，例如 [websocat](https://github.com/vi/websocat)，通过以下路由与 WebSocket 服务器建立连接： + +```shell +websocat "ws://127.0.0.1:9080/.ws" +``` + +在终端中发送 `hello` 消息，您应该会看到 WebSocket 服务器回显相同的消息： -按上述配置启用插件后，在这条路由资源上，APISIX 将只允许一个连接；当有更多连接进入时，APISIX 会直接返回 `503` HTTP 状态码，拒绝连接。 +```text +Request served by 1cd244052136 +hello +hello +``` + +再打开三个终端会话并运行： ```shell -curl -i http://127.0.0.1:9080/index.html?sleep=20 & +websocat "ws://127.0.0.1:9080/.ws" +``` + +由于速率限制的影响，当您尝试与服务器建立 WebSocket 连接时，您应该会看到最后一个终端会话打印 `429 Too Many Requests`。 + +### 使用 Redis 服务器在 APISIX 节点之间共享配额 + +以下示例演示了使用 Redis 服务器对多个 APISIX 节点之间的请求进行速率限制，以便不同的 APISIX 节点共享相同的速率限制配额。 -curl -i http://127.0.0.1:9080/index.html?sleep=20 +在每个 APISIX 实例上，使用以下配置创建路由。相应地调整管理 API、Redis 主机、端口、密码和数据库的地址。 + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_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 + } + } + }' ``` +向路由发送五个并发请求： + ```shell - -503 Service Temporarily Unavailable - -

503 Service Temporarily Unavailable

-
openresty
- - +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"' +``` + +您应该会看到类似以下内容的响应，其中超过阈值的请求被拒绝： + +```text +Response: 200 +Response: 200 +Response: 429 +Response: 429 +Response: 429 ``` -## 删除插件 +这表明在不同 APISIX 实例中配置的两个路由共享相同的配额。 + +### 使用 Redis 集群在 APISIX 节点之间共享配额 + +您还可以使用 Redis 集群在多个 APISIX 节点之间应用相同的配额，以便不同的 APISIX 节点共享相同的速率限制配额。 -当你需要删除该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务： +确保您的 Redis 实例在 [集群模式](https://redis.io/docs/management/scaling/#create-and-use-a-redis-cluster) 下运行。`limit-conn` 插件配置至少需要两个节点。 + +在每个 APISIX 实例上，使用以下配置创建一个路由。相应地调整管理 API 的地址、Redis 集群节点、密码、集群名称和 SSL 验证。 ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uri": "/index.html", +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_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-1", + "redis_cluster_ssl": true + } + }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' +``` + +向路由发送五个并发请求： + +```shell +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"' +``` + +您应该会看到类似以下内容的响应，其中超过阈值的请求被拒绝： + +```text +Response: 200 +Response: 200 +Response: 429 +Response: 429 +Response: 429 ``` -## 应用场景示例 - -### 限制 WebSocket 连接的并发数 - -Apache APISIX 支持 WebSocket 代理，我们可以使用 `limit-conn` 插件限制 WebSocket 连接的并发数。 - -1. 创建路由并启用 WebSocket 代理和 `limit-conn` 插件。 - - ```shell - curl http://127.0.0.1:9180/apisix/admin/routes/1 \ - -H "X-API-KEY: $admin_key" -X PUT -d ' - { - "uri": "/ws", - "enable_websocket": true, - "plugins": { - "limit-conn": { - "conn": 1, - "burst": 0, - "default_conn_delay": 0.1, - "rejected_code": 503, - "key_type": "var", - "key": "remote_addr" - } - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } - } - }' - ``` - - 上述路由在 `/ws` 上开启了 WebSocket 代理，并限制了 WebSocket 连接并发数为 `1`。 - - 当 WebSocket 连接并发数超过 `1` 时，APISIX 将会拒绝请求，并返回 HTTP 状态码 `503`。 - -2. 发起 WebSocket 请求，返回 `101` HTTP 状态码表示连接建立成功。 - - ```shell - curl --include \ - --no-buffer \ - --header "Connection: Upgrade" \ - --header "Upgrade: websocket" \ - --header "Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==" \ - --header "Sec-WebSocket-Version: 13" \ - --http1.1 \ - http://127.0.0.1:9080/ws - ``` - - ```shell - HTTP/1.1 101 Switching Protocols - ``` - -3. 在另一个终端中再次发起 WebSocket 请求，返回 `503` HTTP 状态码表示请求将被拒绝。 - - ```shell - HTTP/1.1 503 Service Temporarily Unavailable - ··· - - 503 Service Temporarily Unavailable - -

503 Service Temporarily Unavailable

-
openresty
- - - ``` +这表明在不同的 APISIX 实例中配置的两条路由共享相同的配额。