This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 0e9a07b25 docs: update limit plugin docs (#8154)
0e9a07b25 is described below
commit 0e9a07b25e8c75847f1991a80f0bcf753ffe913e
Author: Fei Han <[email protected]>
AuthorDate: Wed Nov 2 11:38:15 2022 +0800
docs: update limit plugin docs (#8154)
---
docs/en/latest/plugins/limit-conn.md | 122 ++++++++++++++-------------
docs/en/latest/plugins/limit-count.md | 2 +-
docs/zh/latest/plugins/limit-conn.md | 154 +++++++++++++++++-----------------
docs/zh/latest/plugins/limit-count.md | 40 ++++-----
docs/zh/latest/plugins/limit-req.md | 40 +++++----
5 files changed, 184 insertions(+), 174 deletions(-)
diff --git a/docs/en/latest/plugins/limit-conn.md
b/docs/en/latest/plugins/limit-conn.md
index bc000ad75..b2e3feaae 100644
--- a/docs/en/latest/plugins/limit-conn.md
+++ b/docs/en/latest/plugins/limit-conn.md
@@ -120,27 +120,18 @@ curl -i http://127.0.0.1:9080/index.html?sleep=20
</html>
```
-## 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.
+## Disable Plugin
-1. Create a Route, enable the WebSocket proxy and the `limit-conn` plugin.
+To disable 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.
```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
- "uri": "/ws",
- "enable_websocket": true,
+ "methods": ["GET"],
+ "uri": "/index.html",
+ "id": 1,
"plugins": {
- "limit-conn": {
- "conn": 1,
- "burst": 0,
- "default_conn_delay": 0.1,
- "rejected_code": 503,
- "key_type": "var",
- "key": "remote_addr"
- }
},
"upstream": {
"type": "roundrobin",
@@ -151,57 +142,68 @@ curl http://127.0.0.1:9180/apisix/admin/routes/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.
+## Example of application scenarios
-2. Initiate a WebSocket request, and the connection is established
successfully.
+### Limit the number of concurrent WebSocket connections
-```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
-```
+Apache APISIX supports WebSocket proxy, we can use `limit-conn` plugin to
limit the number of concurrent WebSocket connections.
-```shell
-HTTP/1.1 101 Switching Protocols
-```
+1. Create a Route, enable the WebSocket proxy and the `limit-conn` plugin.
-3. Initiate the WebSocket request again in another terminal, the request will
be rejected.
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -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
+ }
+ }
+ }'
+ ```
-```shell
-HTTP/1.1 503 Service Temporarily Unavailable
-···
-<html>
-<head><title>503 Service Temporarily Unavailable</title></head>
-<body>
-<center><h1>503 Service Temporarily Unavailable</h1></center>
-<hr><center>openresty</center>
-</body>
-</html>
-```
+ 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.
-## Disable Plugin
+2. Initiate a WebSocket request, and the connection is established
successfully.
-To disable 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.
+ ```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
+ ```
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "methods": ["GET"],
- "uri": "/index.html",
- "id": 1,
- "plugins": {
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- }
-}'
-```
+3. Initiate the WebSocket request again in another terminal, the request will
be rejected.
+
+ ```shell
+ HTTP/1.1 503 Service Temporarily Unavailable
+ ···
+ <html>
+ <head><title>503 Service Temporarily Unavailable</title></head>
+ <body>
+ <center><h1>503 Service Temporarily Unavailable</h1></center>
+ <hr><center>openresty</center>
+ </body>
+ </html>
+ ```
diff --git a/docs/en/latest/plugins/limit-count.md
b/docs/en/latest/plugins/limit-count.md
index 36e95c893..b098dbd32 100644
--- a/docs/en/latest/plugins/limit-count.md
+++ b/docs/en/latest/plugins/limit-count.md
@@ -28,7 +28,7 @@ description: This document contains information about the
Apache APISIX limit-co
## Description
-The `limit-count` Plugin limits the number of requests to your service by a
given count per time.
+The `limit-count` Plugin limits the number of requests to your service by a
given count per time. The plugin is using Fixed Window algorithm.
## Attributes
diff --git a/docs/zh/latest/plugins/limit-conn.md
b/docs/zh/latest/plugins/limit-conn.md
index 8f5a74dfe..c51ba2eb1 100644
--- a/docs/zh/latest/plugins/limit-conn.md
+++ b/docs/zh/latest/plugins/limit-conn.md
@@ -28,21 +28,21 @@ description: 本文介绍了 Apache APISIX limit-conn 插件的相关操作，
## 描述
-`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` 时，启用插件降级并自动允许请求继续。
|
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
+| ------------------ | ------- | ----- | ------ | --------------------------
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 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` 时，启用插件降级并自动允许请求继续。
|
## 启用插件
@@ -122,28 +122,16 @@ curl -i http://127.0.0.1:9080/index.html?sleep=20
</html>
```
-## 限制 WebSocket 连接的并发数
-
-Apache APISIX 支持 WebSocket 代理，我们可以使用 `limit-conn` 插件限制 WebSocket 连接的并发数。
+## 禁用插件
-1、创建路由并启用 WebSocket 代理和 `limit-conn` 插件。
+当你需要禁用该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -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"
- }
- },
+ "methods": ["GET"],
+ "uri": "/index.html",
"upstream": {
"type": "roundrobin",
"nodes": {
@@ -153,54 +141,70 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
}'
```
-上述路由在 `/ws` 上开启了 WebSocket 代理，并限制了 WebSocket 连接并发数为 1，超过 1 个并发的 WebSocket
连接将返回 `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
-···
-<html>
-<head><title>503 Service Temporarily Unavailable</title></head>
-<body>
-<center><h1>503 Service Temporarily Unavailable</h1></center>
-<hr><center>openresty</center>
-</body>
-</html>
-```
+## 应用场景示例
-## 禁用插件
+### 限制 WebSocket 连接的并发数
-当你需要禁用该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+Apache APISIX 支持 WebSocket 代理，我们可以使用 `limit-conn` 插件限制 WebSocket 连接的并发数。
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "methods": ["GET"],
- "uri": "/index.html",
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
+1. 创建路由并启用 WebSocket 代理和 `limit-conn` 插件。
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -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
+ ···
+ <html>
+ <head><title>503 Service Temporarily Unavailable</title></head>
+ <body>
+ <center><h1>503 Service Temporarily Unavailable</h1></center>
+ <hr><center>openresty</center>
+ </body>
+ </html>
+ ```
diff --git a/docs/zh/latest/plugins/limit-count.md
b/docs/zh/latest/plugins/limit-count.md
index ab4062b35..3055d2267 100644
--- a/docs/zh/latest/plugins/limit-count.md
+++ b/docs/zh/latest/plugins/limit-count.md
@@ -29,29 +29,29 @@ description: 本文介绍了 Apache APISIX limit-count 插件的相关操作，
## 描述
-`limit-count` 插件用于限制客户端在指定的时间范围内对服务的总请求数，并且在 HTTP 响应头中返回剩余可以请求的个数。该插件的原理与
[GitHub API 的速率限制](https://docs.github.com/en/rest/reference/rate-limit)类似。
+`limit-count` 插件使用固定时间窗口算法，主要用于限制**单个客户端**在指定的时间范围内对服务的总请求数，并且会在 HTTP
响应头中返回剩余可以请求的个数。该插件原理与 [GitHub API
的速率限制](https://docs.github.com/en/rest/reference/rate-limit)类似。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 |
有效值
| 描述
[...]
-| ------------------- | ------- | --------------------------------- |
------------- |
-------------------------------------------------------------------------------------------------------
|
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
-| count | integer | 是 |
| count > 0
| 每个客户端在指定时间窗口内的总请求数量阈值。
[...]
-| time_window | integer | 是 |
| time_window > 0
| 时间窗口的大小（以秒为单位），。超过该属性定义的时间，则会重新开始计数。
[...]
-| key_type | string | 否 | "var" | ["var", "var_combination",
"constant"] | key 的类型。 |
-| key | string | 否 | "remote_addr" | | 用来做请求计数的依据。如果
`key_type` 为 `constant`，那么 key 会被当作常量；如果 `key_type` 为 `var`，那么 key 会被当作变量；如果
`key_type` 为 `var_combination`，那么 key 会被当作变量组合，如 `$remote_addr
$consumer_name`，插件会同时受 `$remote_addr` 和 `$consumer_name` 两个变量的约束；如果 key
的值为空，`$remote_addr` 会被作为默认 key。 |
-| rejected_code | integer | 否 | 503
| [200,...,599]
| 当请求超过阈值被拒绝时，返回的 HTTP 状态码。
[...]
-| rejected_msg | string | 否 |
| 非空
| 当请求超过阈值被拒绝时，返回的响应体。
|
-| policy | string | 否 | "local"
| ["local", "redis", "redis-cluster"]
| 用于检索和增加限制计数的策略。当设置为 `local`
时，计数器被以内存方式保存在节点本地；当设置为 `redis` 时，计数器保存在 Redis
服务节点上，从而可以跨节点共享结果，通常用它来完成全局限速；当设置为 `redis-cluster` 时，使用 Redis 集群而不是单个实例。
|
-| allow_degradation | boolean | 否
| false |
| 当插件功能临时不可用时（例如 Redis 超时），当设置为 `true` 时，则表示可以允许插件降级并进行继续请求的操作。 |
-| show_limit_quota_header | boolean | 否
| true |
| 当设置为 `true` 时，在响应头中显示 `X-RateLimit-Limit`（限制的总请求数）和
`X-RateLimit-Remaining`（剩余还可以发送的请求数）字段。 |
-| group | string | 否 |
| 非空
| 配置相同 group 的路由将共享相同的限流计数器。 |
-| redis_host | string | 否 | |
| 当使用 `redis` 限速策略时，Redis 服务节点的地址。**当 `policy` 属性设置为
`redis` 时必选。**
[...]
-| redis_port | integer | 否 | 6379
| [1,...]
| 当使用 `redis` 限速策略时，Redis 服务节点的端口。
[...]
-| redis_password | string | 否 |
|
| 当使用 `redis` 或者 `redis-cluster` 限速策略时，Redis
服务节点的密码。
[...]
-| 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`
时必选。**
[...]
+| 名称 | 类型 | 必选项 | 默认值 | 有效值
| 描述
|
+| ------------------- | ------- | ---------- | ------------- |
--------------------------------------- |
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
+| count | integer | 是 | | count > 0
| 每个客户端在指定时间窗口内的总请求数量阈值。|
+| time_window | integer | 是 | | time_window > 0
| 时间窗口的大小（以秒为单位）。超过该属性定义的时间，则会重新开始计数。|
+| key_type | string | 否 | "var" | ["var",
"var_combination", "constant"] | key 的类型。 |
+| key | string | 否 | "remote_addr" |
| 用来做请求计数的依据。如果 `key_type` 为 `constant`，那么 key 会被当作常量；如果
`key_type` 为 `var`，那么 key 会被当作变量；如果 `key_type` 为 `var_combination`，那么 key
会被当作变量组合，如 `$remote_addr $consumer_name`，插件会同时受 `$remote_addr` 和
`$consumer_name` 两个变量的约束；如果 `key` 的值为空，`$remote_addr` 会被作为默认 `key`。 |
+| rejected_code | integer | 否 | 503 | [200,...,599]
| 当请求超过阈值被拒绝时，返回的 HTTP 状态码。|
+| rejected_msg | string | 否 | | 非空
| 当请求超过阈值被拒绝时，返回的响应体。|
+| policy | string | 否 | "local" | ["local",
"redis", "redis-cluster"] | 用于检索和增加限制计数的策略。当设置为 `local`
时，计数器被以内存方式保存在节点本地；当设置为 `redis` 时，计数器保存在 Redis
服务节点上，从而可以跨节点共享结果，通常用它来完成全局限速；当设置为 `redis-cluster` 时，使用 Redis 集群而不是单个实例。|
+| allow_degradation | boolean | 否 | false |
| 当插件功能临时不可用时（例如 Redis 超时），当设置为 `true`
时，则表示可以允许插件降级并进行继续请求的操作。 |
+| show_limit_quota_header | boolean | 否 | true |
| 当设置为 `true` 时，在响应头中显示 `X-RateLimit-Limit`（限制的总请求数）和
`X-RateLimit-Remaining`（剩余还可以发送的请求数）字段。 |
+| group | string | 否 | | 非空
| 配置相同 group 的路由将共享相同的限流计数器。 |
+| redis_host | string | 否 | |
| 当使用 `redis` 限速策略时，Redis 服务节点的地址。**当 `policy` 属性设置为
`redis` 时必选。**|
+| redis_port | integer | 否 | 6379 | [1,...]
| 当使用 `redis` 限速策略时，Redis 服务节点的端口。|
+| redis_password | string | 否 | |
| 当使用 `redis` 或者 `redis-cluster` 限速策略时，Redis 服务节点的密码。|
+| 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` 时必选。**|
## 启用插件
diff --git a/docs/zh/latest/plugins/limit-req.md
b/docs/zh/latest/plugins/limit-req.md
index e16ad8df6..2de947cbf 100644
--- a/docs/zh/latest/plugins/limit-req.md
+++ b/docs/zh/latest/plugins/limit-req.md
@@ -29,20 +29,20 @@ description: limit-req 插件使用漏桶算法限制对用户服务的请求速
## 描述
-`limit-req` 插件使用漏桶算法限制对用户服务的请求速率。
+`limit-req`
插件使用[漏桶算法](https://baike.baidu.com/item/%E6%BC%8F%E6%A1%B6%E7%AE%97%E6%B3%95/8455361)限制单个客户端对服务的请求速率。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值
| 描述
|
-| ------------- | ------- | ------ | ------ |
------------------------------------------------------------------------ |
-------------------------------------------------------------------------------------------------------------------------------------------------
|
-| rate | integer | 是 | | rate > 0
| 指定的请求速率（以秒为单位），请求速率超过 `rate` 但没有超过（`rate`
+ `burst`）的请求会被加上延时。 |
-| burst | integer | 是 | | burst >= 0
| 请求速率超过（`rate` + `burst`）的请求会被直接拒绝。
|
-| key_type | string | 否 | "var" | ["var", "var_combination"]
| 要使用的用户指定 `key` 的类型。 |
+| 名称 | 类型 | 必选项 | 默认值 | 有效值
| 描述
|
+| ------------- | ------- | ------ | ------ |
-------------------------------------------------------------------------------------
|
-------------------------------------------------------------------------------------------------------------------------------------------------
|
+| rate | integer | 是 | | rate > 0
| 指定的请求速率（以秒为单位），请求速率超过
`rate` 但没有超过（`rate` + `burst`）的请求会被延时处理。|
+| burst | integer | 是 | | burst >= 0
| 请求速率超过（`rate` +
`burst`）的请求会被直接拒绝。|
+| key_type | string | 否 | "var" | ["var", "var_combination"]
| 要使用的用户指定 `key` 的类型。
|
| key | string | 是 | | ["remote_addr", "server_addr",
"http_x_real_ip", "http_x_forwarded_for", "consumer_name"] | 用来做请求计数的依据，当前接受的
`key` 有：`remote_addr`（客户端 IP 地址），`server_addr`（服务端 IP 地址）, 请求头中的
`X-Forwarded-For` 或 `X-Real-IP`，`consumer_name`（Consumer 的 `username`）。 |
-| rejected_code | integer | 否 | 503 | [200,...,599]
| 当超过阈值的请求被拒绝时，返回的 HTTP 状态码。
|
-| rejected_msg | string | 否 |
| 非空 | 当超过阈值的请求被拒绝时，返回的响应体。
|
-| nodelay | boolean | 否 | false |
| 如果设置为 `true`， 请求速率超过 `rate` 但没有超过（`rate`
+ `burst`）的请求不会加上延迟；如果设置为 `false`，则会加上延迟。 |
-| allow_degradation | boolean | 否
| false |
| 当限速插件功能临时不可用时是否允许请求继续。如果设置为 `true`，则自动允许请求继续。|
+| rejected_code | integer | 否 | 503 | [200,...,599]
| 当超过阈值的请求被拒绝时，返回的 HTTP
状态码。|
+| rejected_msg | string | 否 | | 非空
| 当超过阈值的请求被拒绝时，返回的响应体。|
+| nodelay | boolean | 否 | false |
| 当设置为 `true` 时，请求速率超过
`rate` 但没有超过（`rate` + `burst`）的请求不会加上延迟；当设置为 `false`，则会加上延迟。 |
+| allow_degradation | boolean | 否 | false |
| 当设置为 `true`
时，如果限速插件功能临时不可用，将会自动允许请求继续。|
## 启用插件
@@ -51,7 +51,8 @@ description: limit-req 插件使用漏桶算法限制对用户服务的请求速
以下示例展示了如何在指定路由上启用 `limit-req` 插件，并设置 `key_type` 的值为 `var`：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/index.html",
@@ -73,6 +74,8 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
+上述示例表示，APISIX 将客户端的 IP 地址作为限制请求速率的条件，当请求速率小于 3 次每秒（`rate`）时，请求正常；当请求速率大于 3
次每秒（`rate`），小于 5 次每秒（`rate + burst`）时，将会对超出部分的请求进行延迟处理；当请求速率大于 5 次每秒（`rate +
burst`）时，超出规定数量的请求将返回 HTTP 状态码 `503`。
+
你也可以设置 `key_type` 的值为 `var_combination`：
```json
@@ -99,8 +102,6 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
**测试插件**
-上述配置限制了每秒请求速率为 `1`，大于 `1` 且小于 `3` 的请求会被加上延时，速率超过 `3` 就会被拒绝。
-
通过以下命令发送请求：
```shell
@@ -125,7 +126,7 @@ Server: APISIX web server
</html>
```
-同时，如果你设置了 `rejected_msg` 属性的值为 `"Requests are too frequent, please try again
later."`，当请求速率超出限制时，返回如下包含 `503` HTTP 状态码的响应体，插件生效：
+同时，如果你设置了 `rejected_msg` 属性的值为 `"Requests are too frequent, please try again
later."`，当请求速率超出限制时，返回如下包含 `503` HTTP 状态码的响应体：
```shell
HTTP/1.1 503 Service Temporarily Unavailable
@@ -139,12 +140,13 @@ Server: APISIX web server
### 在 Consumer 上启用插件
-Consumer 上启用 `limit-req` 插件需要与授权插件一起配合使用，这里以 [`key-auth`](./key-auth.md)
授权插件为例。
+在 [Consumer](../terminology/consumer.md) 上启用 `limit-req` 插件需要与认证插件一起配合使用，以
[`key-auth`](./key-auth.md) 授权插件为例。
首先，将 `limit-req` 插件绑定到 Consumer 上：
```shell
-curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/consumers \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "consumer_jack",
"plugins": {
@@ -164,7 +166,8 @@ curl http://127.0.0.1:9180/apisix/admin/consumers -H
'X-API-KEY: edd1c9f034335f1
然后，在指定路由上启用并配置 `key-auth` 插件：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/index.html",
@@ -215,7 +218,8 @@ HTTP/1.1 403 Forbidden
当你需要禁用该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/index.html",
