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 2021/09/28 06:41:22 UTC
[apisix] branch master updated: docs: add gzip and real-ip zh docs
(#5116)
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 d413d77 docs: add gzip and real-ip zh docs (#5116)
d413d77 is described below
commit d413d77a9eff5fd5585f83c01fc0843523ef2bf2
Author: huang.xinghui <hu...@gmail.com>
AuthorDate: Tue Sep 28 14:41:15 2021 +0800
docs: add gzip and real-ip zh docs (#5116)
Co-authored-by: 罗泽轩 <sp...@gmail.com>
---
docs/zh/latest/config.json | 2 +
docs/zh/latest/plugins/gzip.md | 108 ++++++++++++++++++++++++++++++++++++++
docs/zh/latest/plugins/real-ip.md | 104 ++++++++++++++++++++++++++++++++++++
3 files changed, 214 insertions(+)
diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json
index 7bbb1de..8e895a4 100644
--- a/docs/zh/latest/config.json
+++ b/docs/zh/latest/config.json
@@ -38,6 +38,8 @@
"plugins/serverless",
"plugins/redirect",
"plugins/echo",
+ "plugins/gzip",
+ "plugins/real-ip",
"plugins/server-info"
]
},
diff --git a/docs/zh/latest/plugins/gzip.md b/docs/zh/latest/plugins/gzip.md
new file mode 100644
index 0000000..6343b06
--- /dev/null
+++ b/docs/zh/latest/plugins/gzip.md
@@ -0,0 +1,108 @@
+---
+title: gzip
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## 目录
+
+- [**简介**](#简介)
+- [**属性**](#属性)
+- [**如何启用**](#如何启用)
+- [**测试插件**](#测试插件)
+- [**禁用插件**](#禁用插件)
+
+## 简介
+
+`gzip` 插件能动态设置 `Nginx` 的压缩行为。
+
+**该插件要求 `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) 指令 |
+
+## 如何启用
+
+下面是一个示例，在指定的 `route` 上开启了 `gzip` 插件：
+
+```shell
+curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "plugins": {
+ "gzip": {
+ "buffers": {
+ "number": 8
+ }
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
+```
+
+## 测试插件
+
+使用 `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
+Connection: keep-alive
+Date: Wed, 21 Jul 2021 03:52:55 GMT
+Server: APISIX/2.7
+Content-Encoding: gzip
+
+Warning: Binary output can mess up your terminal. Use "--output -" to tell
+Warning: curl to output it to your terminal anyway, or consider "--output
+Warning: <FILE>" to save to a file.
+```
+
+## 禁用插件
+
+想要禁用该插件时很简单，在路由 `plugins` 配置块中删除对应 `JSON` 配置，不需要重启服务，即可立即生效禁用该插件。
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
+```
diff --git a/docs/zh/latest/plugins/real-ip.md b/docs/zh/latest/plugins/real-ip.md
new file mode 100644
index 0000000..fd3a743
--- /dev/null
+++ b/docs/zh/latest/plugins/real-ip.md
@@ -0,0 +1,104 @@
+---
+title: real-ip
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## 目录
+
+- [**简介**](#简介)
+- [**属性**](#属性)
+- [**如何启用**](#如何启用)
+- [**测试插件**](#测试插件)
+- [**禁用插件**](#禁用插件)
+
+## 简介
+
+`real-ip` 插件用于动态改变传递到 `APISIX` 的客户端的 `IP` 和端口。
+
+它工作方式和 `Nginx` 里 `ngx_http_realip_module` 模块一样，并且更为灵活。
+
+**该插件要求 `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` 设置的远程地址缺失或无效，该插件则直接放行，不会更改客户端地址。
+
+## 如何启用
+
+下面是一个示例，在指定的 `route` 上开启了 `real-ip` 插件：
+
+```shell
+curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "plugins": {
+ "real-ip": {
+ "source": "arg_realip",
+ "trusted_addresses": ["127.0.0.0/24"]
+ },
+ "response-rewrite": {
+ "headers": {
+ "remote_addr": "$remote_addr",
+ "remote_port": "$remote_port"
+ }
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
+```
+
+## 测试插件
+
+使用 `curl` 访问：
+
+```shell
+curl 'http://127.0.0.1:9080/index.html?realip=1.2.3.4:9080' -I
+...
+remote-addr: 1.2.3.4
+remote-port: 9080
+```
+
+## 禁用插件
+
+想要禁用该插件时很简单，在路由 `plugins` 配置块中删除对应 `JSON` 配置，不需要重启服务，即可立即生效禁用该插件。
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
+```