You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2022/04/26 12:45:23 UTC
[apisix] branch master updated: docs: update "General" Plugins (#6886)
This is an automated email from the ASF dual-hosted git repository.
spacewander 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 dbe7eeebb docs: update "General" Plugins (#6886)
dbe7eeebb is described below
commit dbe7eeebba06229d4a8df75263f2a78301cc1ca0
Author: homeward <97...@users.noreply.github.com>
AuthorDate: Tue Apr 26 20:45:18 2022 +0800
docs: update "General" Plugins (#6886)
---
docs/en/latest/plugins/ext-plugin-pre-req.md | 2 +-
docs/zh/latest/plugins/batch-requests.md | 122 ++++++++++++++++----------
docs/zh/latest/plugins/echo.md | 53 +++++++----
docs/zh/latest/plugins/ext-plugin-post-req.md | 11 ++-
docs/zh/latest/plugins/ext-plugin-pre-req.md | 41 +++++----
docs/zh/latest/plugins/gzip.md | 48 ++++++----
docs/zh/latest/plugins/real-ip.md | 47 +++++++---
docs/zh/latest/plugins/redirect.md | 76 +++++++++-------
docs/zh/latest/plugins/server-info.md | 73 ++++++++-------
9 files changed, 290 insertions(+), 183 deletions(-)
diff --git a/docs/en/latest/plugins/ext-plugin-pre-req.md b/docs/en/latest/plugins/ext-plugin-pre-req.md
index ad00edaee..efe2dbf8a 100644
--- a/docs/en/latest/plugins/ext-plugin-pre-req.md
+++ b/docs/en/latest/plugins/ext-plugin-pre-req.md
@@ -80,7 +80,7 @@ This will reach the configured Plugin Runner and the `ext-plugin-A` will be exec
## Disable Plugin
-To disable the `echo` 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.
+To disable the `ext-plugin-pre-req` 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:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
diff --git a/docs/zh/latest/plugins/batch-requests.md b/docs/zh/latest/plugins/batch-requests.md
index 362cb3278..63ba18b91 100644
--- a/docs/zh/latest/plugins/batch-requests.md
+++ b/docs/zh/latest/plugins/batch-requests.md
@@ -1,5 +1,10 @@
---
title: batch-requests
+keywords:
+ - APISIX
+ - Plugin
+ - Batch Requests
+description: 本文介绍了关于 Apache APISIX `batch-request` 插件的基本信息及使用方法。
---
<!--
@@ -23,11 +28,17 @@ title: batch-requests
## 描述
-`batch-requests` 插件可以一次接受多个请求并以 [http pipeline](https://en.wikipedia.org/wiki/HTTP_pipelining) 的方式在网关发起多个 http 请求，合并结果后再返回客户端，这在客户端需要访问多个接口时可以显著地提升请求性能。
+`batch-requests` 插件可以一次接受多个请求并以 [HTTP pipeline](https://en.wikipedia.org/wiki/HTTP_pipelining) 的方式在网关发起多个 HTTP 请求，合并结果后再返回客户端。
-> **提示**
->
-> 外层的 Http 请求头会自动设置到每一个独立请求中，如果独立请求中出现相同键值的请求头，那么只有独立请求的请求头会生效。
+在客户端需要访问多个 API 的情况下，这将显著提高性能。
+
+:::note
+
+外部批处理请求的 HTTP 请求头（除了以 `Content-` 开始的请求头，例如：`Content-Type`）适用于**批处理**中的每个请求。
+
+如果在外部请求和单个调用中都指定了相同的 HTTP 请求头，则单个调用的请求头优先。
+
+:::
## 属性
@@ -35,25 +46,31 @@ title: batch-requests
## 接口
-插件会增加 `/apisix/batch-requests` 这个接口，需要通过 [public-api](../../../en/latest/plugins/public-api.md) 插件来暴露它。
+该插件会增加 `/apisix/batch-requests` 接口。
-## 如何启用
+:::note
-你需要在 `config.yaml` 里面启用 batch-requests 插件：
+你需要通过 [public-api](../../../zh/latest/plugins/public-api.md) 插件来暴露它。
-```
-# 加到 config.yaml
+:::
+
+## 启用插件
+
+该插件默认是禁用状态，你可以在配置文件（`./conf/config.yaml`）添加如下配置启用 `batch-requests` 插件：
+
+```yaml title="conf/config.yaml"
plugins:
- - ... # plugin you need
+ - ...
- batch-requests
```
-## 如何配置
+## 配置插件
-默认本插件限制请求体的大小不能大于 1 MiB。这个限制可以通过 `apisix/admin/plugin_metadata/batch-requests` 来修改。
+默认情况下，可以发送到 `/apisix/batch-requests` 的最大请求体不能大于 1 MiB。 你可以通过 `apisix/admin/plugin_metadata/batch-requests` 更改插件的此配置：
```shell
-curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/batch-requests -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/batch-requests \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"max_body_size": 4194304
}'
@@ -61,54 +78,57 @@ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/batch-requests -H 'X-API
## 元数据
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ------------- | ------- | ------ | ------- | ------ | ------------------------------ |
-| max_body_size | integer | 必选 | 1048576 | > 0 | 请求体的最大大小，单位为字节。 |
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+| ------------- | ------- | -------| ------- | ------ | ---------------------------- |
+| max_body_size | integer | 是 | 1048576 |[1, ...]| 请求体的最大大小，单位：bytes。 |
-## 批量接口请求/响应
+## 请求和响应格式
-插件会为 `apisix` 创建一个 `/apisix/batch-requests` 的接口来处理你的批量请求。
+该插件会为 `apisix` 创建一个 `/apisix/batch-requests` 的接口，用来处理批量请求。
-### 接口请求参数：
+### Request
-| 参数名 | 类型 | 可选项 | 默认值 | 有效值 | 描述 |
-| -------- | --------------------------- | ------ | ------ | ------ | -------------------------------- |
-| query | object | 可选 | | | 给所有请求都携带的 `query string` |
-| headers | object | 可选 | | | 给所有请求都携带的 `header` |
-| timeout | number | 可选 | 30000 | | 聚合请求的超时时间，单位为 `ms` |
-| pipeline | [HttpRequest](#httprequest) | 必须 | | | Http 请求的详细信息 |
+| 参数名 | 类型 | 必选项 | 默认值 | 描述 |
+| -------- | --------------------------- | ------ | ------ | -------------------------------- |
+| query | object | 否 | | 给所有请求都携带的 `query string`。 |
+| headers | object | 否 | | 给所有请求都携带的 `header`。 |
+| timeout | number | 否 | 30000 | 聚合请求的超时时间，单位为 `ms`。 |
+| pipeline | [HttpRequest](#httprequest) | 是 | | HTTP 请求的详细信息。 |
#### HttpRequest
-| 参数名 | 类型 | 可选 | 默认值 | 有效值 | 描述 |
-| ---------- | ------- | ---- | ------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| version | string | 可选 | 1.1 | [1.0, 1.1] | 请求用的 `http` 协议版本 |
-| method | string | 可选 | GET | ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE", "PURGE"] | 请求使用的 `http` 方法 |
-| query | object | 可选 | | | 独立请求所携带的 `query string`, 如果 `Key` 和全局的有冲突，以此设置为主。 |
-| headers | object | 可选 | | | 独立请求所携带的 `header`, 如果 `Key` 和全局的有冲突，以此设置为主。 |
-| path | string | 必须 | | | 请求路径 |
-| body | string | 可选 | | | 请求体 |
-| ssl_verify | boolean | 可选 | false | | 验证 SSL 证书与主机名是否匹配 |
+| 参数名 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+| ---------- | ------- | -------- | ------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| version | string | 否 | 1.1 | [1.0, 1.1] | 请求所使用的 HTTP 协议版本。 |
+| method | string | 否 | GET | ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE"] | 请求使用的 HTTP 方法。 |
+| query | object | 否 | | | 独立请求所携带的 `query string`, 如果 `Key` 和全局的有冲突，以此设置为主。 |
+| headers | object | 否 | | | 独立请求所携带的 `header`, 如果 `Key` 和全局的有冲突，以此设置为主。 |
+| path | string | 是 | | | HTTP 请求路径。 |
+| body | string | 否 | | | HTTP 请求体。 |
+| ssl_verify | boolean | 否 | false | | 验证 SSL 证书与主机名是否匹配。 |
-### 接口响应参数：
+### 响应参数：
-返回值为一个 [HttpResponse](#httpresponse) 的 `数组`。
+返回值是一个 [HttpResponse](#httpresponse) 的 `数组`。
#### HttpResponse
-| 参数名 | 类型 | 描述 |
+| 参数名 | 类型 | 描述 |
| ------- | ------- | ------------------- |
-| status | integer | Http 请求的状态码 |
-| reason | string | Http 请求的返回信息 |
-| body | string | Http 请求的响应体 |
-| headers | object | Http 请求的响应头 |
+| status | integer | HTTP 请求的状态码。 |
+| reason | string | HTTP 请求的返回信息。 |
+| body | string | HTTP 请求的响应体。 |
+| headers | object | HTTP 请求的响应头。 |
+
+## 修改自定义 URI
-## 如何修改自定义 uri
+你可以通过 [public-api](../../../en/latest/plugins/public-api.md) 插件设置自定义 URI。
-我们可以使用 [public-api](../../../en/latest/plugins/public-api.md) 插件轻易的设置自定义 uri。只需要在创建路由时设置需要的 uri 并改变 `public-api` 插件的配置即可。
+只需要在创建路由时设置所需的 URI 并更改 `public-api` 插件的配置：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/br -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/br \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/batch-requests",
"plugins": {
@@ -121,10 +141,11 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/br -H 'X-API-KEY: edd1c9f034335
## 测试插件
-首先，你需要为 batch request 的 API 设置一个路由，它将使用 [public-api](../../../en/latest/plugins/public-api.md) 插件。
+首先，你需要为 `batch-requests` 插件的 API 创建一个路由，它将使用 [public-api](../../../en/latest/plugins/public-api.md) 插件。
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/br -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/apisix/batch-requests",
"plugins": {
@@ -159,7 +180,7 @@ curl --location --request POST 'http://127.0.0.1:9080/apisix/batch-requests' \
}'
```
-返回如下：
+正常返回结果如下：
```json
[
@@ -192,4 +213,9 @@ curl --location --request POST 'http://127.0.0.1:9080/apisix/batch-requests' \
## 禁用插件
-正常情况不需要禁用本插件，如有需要，在 `/conf/config.yaml` 中新建一个所需的 `plugins` 列表，以覆盖原列表。
+如果你想禁用插件，可以将 `batch-requests` 从配置文件中的插件列表删除，重新加载 APISIX 后即可生效。
+
+```yaml title="conf/config.yaml"
+plugins: # plugin list
+ - ...
+```
diff --git a/docs/zh/latest/plugins/echo.md b/docs/zh/latest/plugins/echo.md
index 077f4b7af..c818007f5 100644
--- a/docs/zh/latest/plugins/echo.md
+++ b/docs/zh/latest/plugins/echo.md
@@ -1,7 +1,13 @@
---
title: echo
+keywords:
+ - APISIX
+ - Plugin
+ - Echo
+description: 本文介绍了关于 Apache APISIX `echo` 插件的基本信息及使用方法。
---
+
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
@@ -23,29 +29,38 @@ title: echo
## 描述
-echo 可以帮助用户尽可能全面地了解如何开发 APISIX 插件。
+`echo` 插件可以帮助用户尽可能地全面了解如何开发 APISIX 插件。
+
+该插件展示了如何在常见的 `phase` 中实现相应的功能，常见的 `phase` 包括：init, rewrite, access, balancer, header filter, body filter 以及 log。
-该插件展示了如何在常见的 phase 中实现相应的功能，常见的 phase 包括：init, rewrite, access, balancer, header filter, body filter 以及 log。
+:::caution WARNING
-**注意：该插件仅用作示例，并没有处理一些特别的场景。请勿将之用于生产环境上！**
+`echo` 插件只能用作示例，并不能处理一些特别的场景。**请勿将该插件用在生产环境中！**
+
+:::
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ----------- | ------ | ------ | ------ | ------ | ---------------------------------------------------------------------------------------- |
-| before_body | string | 可选 | | | 在 body 属性之前添加的内容，如果 body 属性没有指定将添加在 upstream response body 之前。 |
-| body | string | 可选 | | | 返回给客户端的响应内容，它将覆盖 upstream 返回的响应 body。 |
-| after_body | string | 可选 | | | 在 body 属性之后添加的内容，如果 body 属性没有指定将在 upstream 响应 body 之后添加。 |
-| headers | object | 可选 | | | 返回值的 headers |
+| 名称 | 类型 | 必选项 | 描述 |
+| ----------- | ------ | ------ | ----------------------------------------------------------------------------------------------- |
+| before_body | string | 否 | 在 `body` 属性之前添加的内容，如果 `body` 属性没有指定，就会将其添加在上游 `response body` 之前。 |
+| body | string | 否 | 返回给客户端的响应内容，它将覆盖上游返回的响应 `body`。 |
+| after_body | string | 否 | 在 `body` 属性之后添加的内容，如果 body 属性没有指定将在上游响应 `body` 之后添加。 |
+| headers | object | 否 | 返回值的 headers。 |
+
+:::note
-参数 before_body，body 和 after_body 至少要存在一个
+参数 `before_body`、`body` 和 `after_body` 至少要配置一个。
-## 如何启用
+:::
-为特定路由启用 echo 插件。
+## 启用插件
+
+以下示例展示了如何在指定路由中启用 `echo` 插件。
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"echo": {
@@ -64,10 +79,13 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
## 测试插件
-* 成功：
+通过上述命令启用插件后，你可以使用如下命令测试插件是否启用成功：
```shell
-$ curl -i http://127.0.0.1:9080/hello
+curl -i http://127.0.0.1:9080/hello
+```
+
+```
HTTP/1.1 200 OK
...
before the body modification hello world
@@ -75,10 +93,11 @@ before the body modification hello world
## 禁用插件
-当您要禁用 `echo` 插件时，这很简单，您可以在插件配置中删除相应的 json 配置，无需重新启动服务，它将立即生效：
+当你需要禁用 `echo` 插件时，可通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/hello",
diff --git a/docs/zh/latest/plugins/ext-plugin-post-req.md b/docs/zh/latest/plugins/ext-plugin-post-req.md
index 3b5f9683d..2cc9d27e9 100644
--- a/docs/zh/latest/plugins/ext-plugin-post-req.md
+++ b/docs/zh/latest/plugins/ext-plugin-post-req.md
@@ -1,5 +1,10 @@
---
title: ext-plugin-post-req
+keywords:
+ - APISIX
+ - Plugin
+ - ext-plugin-post-req
+description: 本文介绍了关于 Apache APISIX `ext-plugin-post-req` 插件的基本信息及使用方法。
---
<!--
@@ -23,8 +28,6 @@ title: ext-plugin-post-req
## 描述
-`ext-plugin-post-req` 插件的功能与 `ext-plugin-pre-req` 插件类似。
+`ext-plugin-post-req` 插件的功能与 `ext-plugin-pre-req` 插件的不同之处在于：`ext-plugin-post-req` 插件是在内置 Lua 插件执行之后且在请求到达上游之前工作。
-唯一不同的是：它在内置 Lua 插件执行之后且在请求到达上游之前工作。
-
-参考文档 [ext-plugin-pre-req](./ext-plugin-pre-req.md) 去学习如何配置并使用它。
+你可以参考 [ext-plugin-pre-req](./ext-plugin-pre-req.md) 文档，学习如何配置和使用 `ext-plugin-post-req` 插件。
diff --git a/docs/zh/latest/plugins/ext-plugin-pre-req.md b/docs/zh/latest/plugins/ext-plugin-pre-req.md
index 62a2b5fdd..ce1564e19 100644
--- a/docs/zh/latest/plugins/ext-plugin-pre-req.md
+++ b/docs/zh/latest/plugins/ext-plugin-pre-req.md
@@ -1,5 +1,10 @@
---
title: ext-plugin-pre-req
+keywords:
+ - APISIX
+ - Plugin
+ - ext-plugin-pre-req
+description: 本文介绍了关于 Apache APISIX `ext-plugin-pre-req` 插件的基本信息及使用方法。
---
<!--
@@ -23,25 +28,30 @@ title: ext-plugin-pre-req
## 描述
-`ext-plugin-pre-req` 在执行大多数内置 Lua 插件执行之前，在 Plugin Runner 内运行特定 External Plugin。
+`ext-plugin-pre-req` 插件用于在执行内置 Lua 插件之前和在 Plugin Runner 内运行特定的 External Plugin。
-为了理解什么是 Plugin Runner，请参考 [external plugin](../external-plugin.md) 部分。
+如果你想了解更多关于 External Plugin 的信息，请参考 [External Plugin](../external-plugin.md) 。
-External Plugins 执行的结果会影响当前请求的行为。
+:::note
+
+External Plugin 执行的结果会影响当前请求的行为。
+
+:::
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| --------- | ------------- | ----------- | ---------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| conf | array | 可选 | | [{"name": "ext-plugin-A", "value": "{\"enable\":\"feature\"}"}] | 在 Plugin Runner 内执行的插件列表的配置 |
-| allow_degradation | boolean | 可选 | false | | 当 Plugin Runner 临时不可用时是否允许请求继续。当值设置为 true 时则自动允许请求继续，默认值是 false。|
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+| ----------------- | ------ | ------ | ------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| conf | array | 否 | | [{"name": "ext-plugin-A", "value": "{\"enable\":\"feature\"}"}] | 在 Plugin Runner 内执行的插件列表的配置。 |
+| allow_degradation | boolean| 否 | false | [false, true] | 当 Plugin Runner 临时不可用时是否允许请求继续，当值设置为 true 时则自动允许请求继续。 |
-## 如何启用
+## 启用插件
-以下是一个示例，在指定路由中启用插件：
+以下示例展示了如何在指定路由中启用 `ext-plugin-pre-req` 插件：
```shell
-curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl -i http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -61,20 +71,21 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f03433
## 测试插件
-使用 `curl` 去测试：
+通过上述命令启用插件后，可以使用如下命令测试插件是否启用成功：
```shell
curl -i http://127.0.0.1:9080/index.html
```
-你会看到配置的 Plugin Runner 将会被触发，同时 `ext-plugin-A` 插件将会被执行。
+在返回结果中可以看到刚刚配置的 Plugin Runner 已经被触发，同时 `ext-plugin-A` 插件也已经被执行。
## 禁用插件
-当你想去掉 ext-plugin-pre-req 插件的时候，很简单，在插件的配置中把对应的 json 配置删除即可，无须重启服务，即刻生效：
+当你需要禁用 `ext-plugin-pre-req` 插件时，可通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"upstream": {
@@ -85,5 +96,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}
}'
```
-
-现在就已经移除 `ext-plugin-pre-req` 插件了。其他插件的开启和移除也是同样的方法。
diff --git a/docs/zh/latest/plugins/gzip.md b/docs/zh/latest/plugins/gzip.md
index 45edaa1f6..6048ec93c 100644
--- a/docs/zh/latest/plugins/gzip.md
+++ b/docs/zh/latest/plugins/gzip.md
@@ -1,5 +1,10 @@
---
title: gzip
+keywords:
+ - APISIX
+ - Plugin
+ - gzip
+description: 本文介绍了关于 Apache APISIX `gzip` 插件的基本信息及使用方法。
---
<!--
@@ -23,28 +28,33 @@ title: gzip
## 描述
-`gzip` 插件能动态设置 `Nginx` 的压缩行为。
+`gzip` 插件能动态设置 NGINX 的压缩行为。
-**该插件要求 `APISIX` 运行在 [APISIX-OpenResty](../how-to-build.md#步骤-6-为-apache-apisix-构建-openresty) 上。**
+:::info IMPORTANT
+
+该插件要求 Apache APISIX 运行在 [APISIX-OpenResty](../how-to-build.md#步骤-6-为-apache-apisix-构建-openresty) 上。
+
+:::
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| --------------------------------------| ------------| -------------- | -------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| types | array[string] or "*" | 可选 | ["text/html"] | | 动态设置 [`gzip_types`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_types) 指令，特殊值 `"*"` 匹配任何 MIME 类型 |
-| min_length | integer | 可选 | 20 | >= 1 | 动态设置 [`gzip_min_length`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_min_length) 指令 |
-| comp_level | integer | 可选 | 1 | [1, 9] | 动态设置 [`gzip_comp_level`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_comp_level) 指令 |
-| http_version | number | 可选 | 1.1 | 1.1, 1.0 | 动态设置 [`gzip_http_version`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_http_version) 指令 |
-| buffers.number | integer | 可选 | 32 | >= 1 | 动态设置 [`gzip_buffers`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_buffers) 指令 |
-| buffers.size | integer | 可选 | 4096 | >= 1 | 动态设置 [`gzip_buffers`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_buffers) 指令 |
-| vary | boolean | 可选 | false | | 动态设置 [`gzip_vary`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_vary) 指令 |
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+| ---------------| -------------------- | ------- | -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| types | array[string] or "*" | 否 | ["text/html"] | | 动态设置 [`gzip_types`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_types) 指令，特殊值 `"*"` 匹配任何 MIME 类型。 |
+| min_length | integer | 否 | 20 | >= 1 | 动态设置 [`gzip_min_length`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_min_length) 指令。 |
+| comp_level | integer | 否 | 1 | [1, 9] | 动态设置 [`gzip_comp_level`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_comp_level) 指令。 |
+| http_version | number | 否 | 1.1 | 1.1, 1.0 | 动态设置 [`gzip_http_version`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_http_version) 指令。 |
+| buffers.number | integer | 否 | 32 | >= 1 | 动态设置 [`gzip_buffers`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_buffers) 指令。 |
+| buffers.size | integer | 否 | 4096 | >= 1 | 动态设置 [`gzip_buffers`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_buffers) 指令。 |
+| vary | boolean | 否 | false | | 动态设置 [`gzip_vary`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_vary) 指令。 |
-## 如何启用
+## 启用插件
-下面是一个示例，在指定的 `route` 上开启了 `gzip` 插件：
+以下示例展示了如何在指定路由中启用 `gzip` 插件：
```shell
-curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl -i http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -65,10 +75,13 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f03433
## 测试插件
-使用 `curl` 访问：
+通过上述命令启用插件后，可以使用如下命令测试插件是否启用成功：
```shell
curl http://127.0.0.1:9080/index.html -i -H "Accept-Encoding: gzip"
+```
+
+```
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
@@ -84,10 +97,11 @@ Warning: <FILE>" to save to a file.
## 禁用插件
-想要禁用该插件时很简单，在路由 `plugins` 配置块中删除对应 `JSON` 配置，不需要重启服务，即可立即生效禁用该插件。
+当你需要禁用 `gzip` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"upstream": {
diff --git a/docs/zh/latest/plugins/real-ip.md b/docs/zh/latest/plugins/real-ip.md
index 1ef452b85..6ac810871 100644
--- a/docs/zh/latest/plugins/real-ip.md
+++ b/docs/zh/latest/plugins/real-ip.md
@@ -1,5 +1,11 @@
---
title: real-ip
+keywords:
+ - APISIX
+ - Plugin
+ - Real IP
+ - real ip
+description: 本文介绍了关于 Apache APISIX `real-ip` 插件的基本信息及使用方法。
---
<!--
@@ -23,27 +29,36 @@ title: real-ip
## 描述
-`real-ip` 插件用于动态改变传递到 `APISIX` 的客户端的 `IP` 和端口。
+`real-ip` 插件用于动态改变传递到 Apache APISIX 的客户端的 IP 地址和端口。
-它工作方式和 `Nginx` 里 `ngx_http_realip_module` 模块一样，并且更为灵活。
+它的工作方式和 NGINX 中的 `ngx_http_realip_module` 模块一样，并且更加灵活。
-**该插件要求 `APISIX` 运行在 [APISIX-OpenResty](../how-to-build.md#步骤-6-为-apache-apisix-构建-openresty) 上。**
+:::info IMPORTANT
+
+该插件要求 APISIX 运行在 [APISIX-OpenResty](../how-to-build.md#步骤-6-为-apache-apisix-构建-openresty) 上。
+
+:::
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| --------- | ------------- | ----------- | ---------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| source | string | 必填 | | 任何 Nginx 变量，如 `arg_realip` 或 `http_x_forwarded_for` | 根据变量的值 `APISIX` 动态设置客户端的 `IP` 和端口。如果该值不包含端口，则不会更改客户端的端口。 |
-| trusted_addresses| array[string] | 可选 | | `IP` 或 `CIDR` 范围列表 | 动态设置 `set_real_ip_from` 指令 |
+| 名称 | 类型 | 必选项 | 有效值 | 描述 |
+|-------------------|---------------|-------|-------------------------------------------------------------|----------------------------------------------------------------------|
+| source | string | 是 | 任何 NGINX 变量，如 `arg_realip` 或 `http_x_forwarded_for` 。 | 动态设置客户端的 IP 地址和端口。如果该值不包含端口，则不会更改客户端的端口。|
+| trusted_addresses | array[string] | 否 | IP 或 CIDR 范围列表。 | 动态设置 `set_real_ip_from` 字段。 |
+
+:::note
+
+如果 `source` 属性中设置的地址丢失或者无效，该插件将不会更改客户端地址。
-如果 `source` 设置的远程地址缺失或无效，该插件则直接放行，不会更改客户端地址。
+:::
-## 如何启用
+## 启用插件
-下面是一个示例，在指定的 `route` 上开启了 `real-ip` 插件：
+以下示例展示了如何在指定路由中启用 `real-ip` 插件：
```shell
-curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl -i http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -69,10 +84,13 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f03433
## 测试插件
-使用 `curl` 访问：
+通过上述命令启用插件后，可以使用如下命令测试插件是否启用成功：
```shell
curl 'http://127.0.0.1:9080/index.html?realip=1.2.3.4:9080' -I
+```
+
+```shell
...
remote-addr: 1.2.3.4
remote-port: 9080
@@ -80,10 +98,11 @@ remote-port: 9080
## 禁用插件
-想要禁用该插件时很简单，在路由 `plugins` 配置块中删除对应 `JSON` 配置，不需要重启服务，即可立即生效禁用该插件。
+当你需要禁用 `real-ip` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"upstream": {
diff --git a/docs/zh/latest/plugins/redirect.md b/docs/zh/latest/plugins/redirect.md
index eb467b5cf..4e8e0b8ea 100644
--- a/docs/zh/latest/plugins/redirect.md
+++ b/docs/zh/latest/plugins/redirect.md
@@ -1,5 +1,10 @@
---
title: redirect
+keywords:
+ - APISIX
+ - Plugin
+ - Redirect
+description: 本文介绍了关于 Apache APISIX `redirect` 插件的基本信息及使用方法。
---
<!--
@@ -23,29 +28,32 @@ title: redirect
## 描述
-URI 重定向插件。
+`redirect` 插件可用于配置 URI 重定向。
## 属性
-| Name | Type | Requirement | Default | Valid | Description |
-| ------------- | ------- | ----------- | ------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| http_to_https | boolean | 可选 | false | | 当设置为 `true` 并且请求是 http 时，会自动 301 重定向为 https，uri 保持不变 |
-| uri | string | 可选 | | | 可以包含 Nginx 变量的 URI，例如：`/test/index.html`, `$uri/index.html`。你可以通过类似于 `$ {xxx}` 的方式引用变量，以避免产生歧义，例如：`${uri}foo/index.html`。若你需要保留 `$` 字符，那么使用如下格式：`/\$foo/index.html` |
-| regex_uri | array[string] | 可选 | | | 转发到上游的新 `uri` 地址，使用正则表达式匹配来自客户端的 `uri`，当匹配成功后使用模板替换发送重定向到客户端，未匹配成功时将客户端请求的 `uri` 转发至上游。`uri` 和 `regex_uri` 不可以同时存在。例如：["^/iresty/(.*)/(.*)/(.*)","/$1-$2-$3"] 第一个元素代表匹配来自客户端请求的 `uri` 正则表达式，第二个元素代表匹配成功后发送重定向到客户端的 `uri` 模板。 |
-| ret_code | integer | 可选 | 302 | [200, ...] | 请求响应码 |
-| encode_uri | boolean | 可选 | false | | 当设置为 `true` 时，对返回的 `Location` header 进行编码，编码格式参考 [RFC3986](https://datatracker.ietf.org/doc/html/rfc3986) |
-| append_query_string | boolean | optional | false | | 当设置为 `true` 时，将请求 url 的 query 部分添加到 Location 里。如果在 `uri` 或 `regex_uri` 中配置了 query，那么请求的 query 会被追加在这个 query 后，以 `&` 分隔。 注意：如果已经处理了 query，比如使用了 nginx 变量 `$request_uri`，那么启用此功能会造成 query 重复 |
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+| ------------------- | ------------- | --------- | ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| http_to_https | boolean | 是 | false | [true,false] | 当设置为 `true` 并且请求是 HTTP 时，它将被重定向具有相同 URI 和 301 状态码的 HTTPS。 |
+| uri | string | 是 | | | 要重定向到的 URI，可以包含 NGINX 变量。例如：`/test/index.htm`, `$uri/index.html`，`${uri}/index.html`。如果你引入了一个不存在的变量，它不会报错，而是将其视为一个空变量。 |
+| regex_uri | array[string] | 是 | | | 将来自客户端的 URL 与正则表达式匹配并重定向。当匹配成功后使用模板替换发送重定向到客户端，如果未匹配成功会将客户端请求的 URI 转发至上游。 和 `regex_uri` 不可以同时存在。例如：["^/iresty/(.)/(.)/(.*)","/$1-$2-$3"] 第一个元素代表匹配来自客户端请求的 URI 正则表达式，第二个元素代表匹配成功后发送重定向到客户端的 URI 模板。 |
+| ret_code | integer | 是 | 302 | [200, ...] | HTTP 响应码 |
+| encode_uri | boolean | 是 | false | [true,false] | 当设置为 `true` 时，对返回的 `Location` Header 按照 [RFC3986](https://datatracker.ietf.org/doc/html/rfc3986)的编码格式进行编码。 |
+| append_query_string | boolean | 是 | false | [true,false] | 当设置为 `true` 时，将原始请求中的查询字符串添加到 `Location` Header。如果已配置 `uri` 或 `regex_uri` 已经包含查询字符串，则请求中的查询字符串将附加一个`&`。如果你已经处理过查询字符串（例如，使用 NGINX 变量 `$request_uri`），请不要再使用该参数以避免重复。 |
-`http_to_https`，`uri` 或 `regex_uri` 三个中只能配置一个。
+:::note
-## 示例
+`http_to_https`、`uri` 和 `regex_uri` 只能配置其中一个属性。
-### 启用插件
+:::
-下面是一个基本实例，为特定路由启用 `redirect` 插件：
+## 启用插件
+
+以下示例展示了如何在指定路由中启用 `redirect` 插件：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/test/index.html",
"plugins": {
@@ -63,10 +71,11 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}'
```
-我们可以在新的 URI 中使用 Nginx 内置的任意变量：
+你也可以在新的 URI 中使用 NGINX 内置的任意变量：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/test",
"plugins": {
@@ -84,29 +93,31 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}'
```
-### 测试
+## 测试插件
-测试示例基于上述例子：
+通过上述命令启用插件后，可以使用如下命令测试插件是否启用成功：
```shell
-$ curl http://127.0.0.1:9080/test/index.html -i
+curl http://127.0.0.1:9080/test/index.html -i
+```
+
+```
HTTP/1.1 301 Moved Permanently
Date: Wed, 23 Oct 2019 13:48:23 GMT
Content-Type: text/html
Content-Length: 166
Connection: keep-alive
Location: /test/default.html
-
...
```
-我们可以检查响应码和响应头中的 `Location` 参数，它表示该插件已启用。
+通过上述返回结果，可以看到响应码和响应头中的 `Location` 参数，它表示该插件已启用。
-```
+以下示例展示了如何将 HTTP 重定向到 HTTPS：
-下面是一个实现 http 到 https 跳转的示例：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/hello",
"plugins": {
@@ -117,23 +128,26 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}'
```
-基于上述例子的测试示例：
+基于上述例子进行测试：
```shell
-$ curl http://127.0.0.1:9080/hello -i
+curl http://127.0.0.1:9080/hello -i
+```
+
+```
HTTP/1.1 301 Moved Permanently
...
Location: https://127.0.0.1:9443/hello
-
...
```
-### 禁用插件
+## 禁用插件
-移除插件配置中相应的 JSON 配置可立即禁用该插件，无需重启服务：
+当你需要禁用 `redirect` 插件时，可以通过如下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/test/index.html",
"plugins": {},
@@ -145,5 +159,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}
}'
```
-
-这时该插件已被禁用。
diff --git a/docs/zh/latest/plugins/server-info.md b/docs/zh/latest/plugins/server-info.md
index 4d8d71dd0..2cf132108 100644
--- a/docs/zh/latest/plugins/server-info.md
+++ b/docs/zh/latest/plugins/server-info.md
@@ -1,5 +1,11 @@
---
title: server-info
+keywords:
+ - APISIX
+ - Plugin
+ - Server info
+ - server-info
+description: 本文介绍了关于 Apache APISIX `server-info` 插件的基本信息及使用方法。
---
<!--
@@ -23,21 +29,21 @@ title: server-info
## 描述
-`server-info` 是一款能够定期将服务基本信息上报至 etcd 的插件。
+`server-info` 插件可以定期将服务基本信息上报至 etcd。
服务信息中每一项的含义如下：
-| 名称 | 类型 | 描述 |
+| 名称 | 类型 | 描述 |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
-| boot_time | integer | APISIX 服务实例的启动时间（UNIX 时间戳），如果对 APISIX 进行热更新操作，该值将被重置；普通的 reload 操作不会影响该值。 |
-| id | string | APISIX 服务实例 id 。 |
-| etcd_version | string | etcd 集群的版本信息，如果 APISIX 和 etcd 集群之间存在网络分区，该值将设置为 `"unknown"`。 |
+| boot_time | integer | APISIX 服务实例的启动时间（UNIX 时间戳），如果对 APISIX 进行热更新操作，该值将被重置。普通的 reload 操作不会影响该值。 |
+| id | string | APISIX 服务实例 id。 |
+| etcd_version | string | etcd 集群的版本信息，如果 APISIX 和 etcd 集群之间存在网络分区，该值将设置为 `"unknown"`。 |
| version | string | APISIX 版本信息。 |
-| hostname | string | APISIX 所部署的机器或 pod 的主机名信息。 |
+| hostname | string | 部署 APISIX 的主机或 Pod 的主机名信息。 |
-## 插件属性
+## 属性
-无
+无。
## 插件接口
@@ -45,30 +51,27 @@ title: server-info
## 启用插件
-在配置文件 `apisix/conf/config.yaml` 的插件列表中添加 `server-info`, 即可启用该插件。
+该插件默认是禁用状态，你可以在配置文件（`./conf/config.yaml`）中添加如下配置启用 `server-info` 插件。
-```
+```yaml title="conf/config.yaml"
plugins: # plugin list
- - example-plugin
- - limit-req
- - node-status
+ - ...
- server-info
- - jwt-auth
- - zipkin
- ......
```
-## 如何自定义服务信息上报配置
+## 自定义服务信息上报配置
+
+我们可以在 `./conf/config.yaml` 文件的 `plugin_attr` 部分修改上报配置。
-我们可以在 `conf/config.yaml` 文件的 `plugin_attr` 一节中修改上报配置。
+下表是可以自定义配置的参数：
-| 名称 | 类型 | 默认值 | 描述 |
+| 名称 | 类型 | 默认值 | 描述 |
| --------------- | ------- | ------ | --------------------------------------------------------------- |
-| report_ttl | integer | 36 | etcd 中服务信息保存的 TTL（单位：秒，最大值：86400，最小值：3）|
+| report_ttl | integer | 36 | etcd 中服务信息保存的 TTL（单位：秒，最大值：86400，最小值：3）。|
-下面的例子将 `report_ttl` 修改成了 1 分钟：
+以下是示例是通过修改配置文件（`conf/config.yaml`）中的 `plugin_attr` 部分将 `report_ttl` 设置为 1 分钟：
-```yaml
+```yaml title="conf/config.yaml"
plugin_attr:
server-info:
report_ttl: 60
@@ -76,10 +79,13 @@ plugin_attr:
## 测试插件
-在启用该插件后，你可以通过插件的 Control API 来访问到这些数据：
+在启用 `server-info` 插件后，可以通过插件的 Control API 来访问到这些数据：
```shell
-$ curl http://127.0.0.1:9090/v1/server_info -s | jq .
+curl http://127.0.0.1:9090/v1/server_info -s | jq .
+```
+
+```JSON
{
"etcd_version": "3.5.0",
"id": "b7ce1c5c-b1aa-4df7-888a-cbe403f3e948",
@@ -89,18 +95,17 @@ $ curl http://127.0.0.1:9090/v1/server_info -s | jq .
}
```
-Apache APISIX Dashboard 会收集上报到 etcd 中的服务信息，因此你也可以通过 APISIX Dashboard 来查看这些数据。
+:::tip
+
+你可以通过 [APISIX Dashboard](/docs/dashboard/USER_GUIDE) 查看服务信息报告。
+
+:::
## 禁用插件
-通过移除配置文件 `apisix/conf/config.yaml` 插件列表中的 `server-info`，即可方便地禁用该插件。
+如果你想禁用插件，可以将 `server-info` 从配置文件中的插件列表删除，重新加载 APISIX 后即可生效。
-```
-plugins: # plugin list
- - example-plugin
- - limit-req
- - node-status
- - jwt-auth
- - zipkin
- ......
+```yaml title="conf/config.yaml"
+plugins: # plugin list
+ - ...
```