test/apisix
1
0
Fork 0
mirror of https://gitee.com/iresty/apisix.git synced 2024-11-29 18:48:31 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs(lint): import Chinese copywriting autocorrect linter (#6568)

Browse Source 
Co-authored-by: leslie <59061168+leslie-tsang@users.noreply.github.com>
Co-authored-by: 琚致远 <juzhiyuan@apache.org>
This commit is contained in:
kwanhur 2022-03-24 15:19:39 +08:00 committed by GitHub
parent 2149ab12bc
commit 96838b9b47
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
83 changed files with 612 additions and 587 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
.github/workflows/doc-lint.yml vendored
View File

@ -34,3 +34,17 @@ jobs:
echo "You need to run ./utils/fix-zh-doc-segment.py to fix them."
exit 1
fi
Chinse-Copywriting-lint:
name: Chinese Copywriting
runs-on: ubuntu-latest
timeout-minutes: 1
steps:
- uses: actions/checkout@v3
- name: check Chinese copywriting
run: |
version=v1.5.6
wget -O- "https://github.com/huacnlee/autocorrect/releases/download/$version/autocorrect-linux-amd64.tar.gz" | tar -xzv
mv -v autocorrect /usr/local/bin/
autocorrect --version
git ls-files | grep "^docs/zh/latest/.*.md$" | xargs -t autocorrect --lint

12
CONTRIBUTING.md
View File

@ -58,6 +58,18 @@ Once we've discussed your changes and you've got your code ready, make sure that
- npm based [markdownlint-cli](https://www.npmjs.com/package/markdownlint-cli)
For linting all files' license header we use:
- [license-eye](https://github.com/apache/skywalking-eyes)
For linting our shell files we use:
- [shellcheck](https://github.com/koalaman/shellcheck)
For linting our zh document files we use:
- [autocorrect](https://github.com/huacnlee/autocorrect)
* Active Voice
In general, use active voice when formulating the sentence instead of passive voice. A sentence written in the active voice will emphasize

108
docs/zh/latest/CHANGELOG.md
View File

@ -323,8 +323,8 @@ title: CHANGELOG
### Plugin
- :sunrise: redirect 插件，支持编码 uri [#4244](https://github.com/apache/apisix/pull/4244)
- :sunrise: key-auth 插件: 支持自定义鉴权头 [#4013](https://github.com/apache/apisix/pull/4013)
- :sunrise: response-rewrite 插件: 允许在 header 里面使用变量 [#4194](https://github.com/apache/apisix/pull/4194)
- :sunrise: key-auth 插件：支持自定义鉴权头 [#4013](https://github.com/apache/apisix/pull/4013)
- :sunrise: response-rewrite 插件：允许在 header 里面使用变量 [#4194](https://github.com/apache/apisix/pull/4194)
- :sunrise: 实现 ext-plugin 第一版，APISIX 现在支持使用其他语言编写自定义插件 [#4183](https://github.com/apache/apisix/pull/4183)
### Bugfix
@ -347,7 +347,7 @@ title: CHANGELOG
- :sunrise: 支持 etcd 客户端证书校验 [#3905](https://github.com/apache/apisix/pull/3905)
- :sunrise: 支持表达式使用“或”和“非”的逻辑 [#3809](https://github.com/apache/apisix/pull/3809)
- :sunrise: 默认启动时会同步etcd配置 [#3799](https://github.com/apache/apisix/pull/3799)
- :sunrise: 默认启动时会同步 etcd 配置 [#3799](https://github.com/apache/apisix/pull/3799)
- :sunrise: 负载均衡支持节点优先级 [#3755](https://github.com/apache/apisix/pull/3755)
- :sunrise: 服务发现提供了一系列 control API [#3742](https://github.com/apache/apisix/pull/3742)
@ -478,11 +478,11 @@ title: CHANGELOG
### Core
- :sunrise: **支持使用环境变量来配置参数.** [#2743](https://github.com/apache/apisix/pull/2743)
- :sunrise: **支持使用环境变量来配置参数。** [#2743](https://github.com/apache/apisix/pull/2743)
- :sunrise: **支持使用 TLS 来连接 etcd.** [#2548](https://github.com/apache/apisix/pull/2548)
- 自动生成对象的创建和更新时间. [#2740](https://github.com/apache/apisix/pull/2740)
- 在上游中开启 websocket 时，增加日志来提示此功能即将废弃.[#2691](https://github.com/apache/apisix/pull/2691)
- 增加日志来提示 consumer id 即将废弃.[#2829](https://github.com/apache/apisix/pull/2829)
- 自动生成对象的创建和更新时间。[#2740](https://github.com/apache/apisix/pull/2740)
- 在上游中开启 websocket 时，增加日志来提示此功能即将废弃。[#2691](https://github.com/apache/apisix/pull/2691)
- 增加日志来提示 consumer id 即将废弃。[#2829](https://github.com/apache/apisix/pull/2829)
- 增加 `X-APISIX-Upstream-Status` 头来区分 5xx 错误来自上游还是 APISIX 自身。[#2817](https://github.com/apache/apisix/pull/2817)
- 支持 Nginx 配置片段。[#2803](https://github.com/apache/apisix/pull/2803)
@ -490,7 +490,7 @@ title: CHANGELOG
- :sunrise: **升级协议来 Apache Skywalking 8.0**[#2389](https://github.com/apache/apisix/pull/2389). 这个版本只支持 skywalking 8.0 协议。此插件默认关闭，需要修改 config.yaml 来开启。这是不向下兼容的修改。
- :sunrise: 新增阿里云 sls 日志服务插件。[#2169](https://github.com/apache/apisix/issues/2169)
- proxy-cache: cache_zone 字段改为可选.[#2776](https://github.com/apache/apisix/pull/2776)
- proxy-cache: cache_zone 字段改为可选。[#2776](https://github.com/apache/apisix/pull/2776)
- 在数据平面校验插件的配置。[#2856](https://github.com/apache/apisix/pull/2856)
### Bugfix
@ -501,7 +501,7 @@ title: CHANGELOG
### 不向下兼容特性预告
- 在 2.3 发布版本中，consumer 将只支持用户名，废弃 id，consumer需要在 etcd 中手工清理掉 id 字段，不然使用时 schema 校验会报错
- 在 2.3 发布版本中，consumer 将只支持用户名，废弃 id，consumer 需要在 etcd 中手工清理掉 id 字段，不然使用时 schema 校验会报错
- 在 2.3 发布版本中，将不再支持在 upstream 上开启 websocket
- 在 3.0 版本中，数据平面和控制平面将分开为两个独立的端口，即现在的 9080 端口将只处理数据平面的请求，不再处理 admin API 的请求
@ -530,9 +530,9 @@ title: CHANGELOG
### Bugfix
- :bug: **`高优先级`** 当数据平面接收到删除某一个资源(路由、上游等)的指令时，没有正确的清理缓存，导致存在的资源也会找不到。这个问题在长时间、频繁删除操作的情况下才会出现。[#2168](https://github.com/apache/apisix/pull/2168)
- :bug: **`高优先级`** 当数据平面接收到删除某一个资源 (路由、上游等) 的指令时，没有正确的清理缓存，导致存在的资源也会找不到。这个问题在长时间、频繁删除操作的情况下才会出现。[#2168](https://github.com/apache/apisix/pull/2168)
- 修复路由优先级不生效的问题。[#2447](https://github.com/apache/apisix/pull/2447)
- 在 `init_worker` 阶段设置随机数, 而不是 `init` 阶段。[#2357](https://github.com/apache/apisix/pull/2357)
- 在 `init_worker` 阶段设置随机数，而不是 `init` 阶段。[#2357](https://github.com/apache/apisix/pull/2357)
- 删除 jwt 插件中不支持的算法。[#2356](https://github.com/apache/apisix/pull/2356)
- 当重定向插件的 `http_to_https` 开启时，返回正确的响应码。[#2311](https://github.com/apache/apisix/pull/2311)
@ -546,8 +546,8 @@ title: CHANGELOG
### Core
- Admin API：支持使用SSL证书进行身份验证。[1747](https://github.com/apache/apisix/pull/1747)
- Admin API：同时支持标准的PATCH和子路径PATCH。[1930](https://github.com/apache/apisix/pull/1930)
- Admin API：支持使用 SSL 证书进行身份验证。[1747](https://github.com/apache/apisix/pull/1747)
- Admin API：同时支持标准的 PATCH 和子路径 PATCH。[1930](https://github.com/apache/apisix/pull/1930)
- HealthCheck：支持自定义检查端口。[1914](https://github.com/apache/apisix/pull/1914)
- Upstream：支持禁用 `Nginx` 默认重试机制。[1919](https://github.com/apache/apisix/pull/1919)
- URI：支持以配置方式删除 `URI` 末尾的 `/` 符号。[1766](https://github.com/apache/apisix/pull/1766)
@ -591,7 +591,7 @@ title: CHANGELOG
- 文档：修正 `README` 中 `gRPC transcoding` 文档路径。[1945](https://github.com/apache/apisix/pull/1945)
- 文档：修正 `README` 中 `uri-blocker` 文档路径。[1950](https://github.com/apache/apisix/pull/1950)
- 文档：修正 `README` 中 `grpc-transcode` 文档路径。[1946](https://github.com/apache/apisix/pull/1946)
- 文档: 删除 `k8s` 文档中不必要的配置。[1891](https://github.com/apache/apisix/pull/1891)
- 文档：删除 `k8s` 文档中不必要的配置。[1891](https://github.com/apache/apisix/pull/1891)
## 1.4.1
@ -631,7 +631,7 @@ title: CHANGELOG
### Plugin
- :sunrise: **新增 batch request 插件**. [#1388](https://github.com/apache/incubator-apisix/pull/1388)
- 实现完成 `sys logger` 插件. [#1414](https://github.com/apache/incubator-apisix/pull/1414)
- 实现完成 `sys logger` 插件。[#1414](https://github.com/apache/incubator-apisix/pull/1414)
## 1.2.0
@ -640,11 +640,11 @@ title: CHANGELOG
### Core
- :sunrise: **支持 etcd 集群**. [#1283](https://github.com/apache/incubator-apisix/pull/1283)
- 默认使用本地 DNS resolver, 这对于 k8s 环境更加友好. [#1387](https://github.com/apache/incubator-apisix/pull/1387)
- 支持在 `header_filter`、`body_filter` 和 `log` 阶段运行全局插件. [#1364](https://github.com/apache/incubator-apisix/pull/1364)
- 默认使用本地 DNS resolver，这对于 k8s 环境更加友好。[#1387](https://github.com/apache/incubator-apisix/pull/1387)
- 支持在 `header_filter`、`body_filter` 和 `log` 阶段运行全局插件。[#1364](https://github.com/apache/incubator-apisix/pull/1364)
- 将目录 `lua/apisix` 修改为 `apisix`(**不向下兼容**). [#1351](https://github.com/apache/incubator-apisix/pull/1351)
- 增加 dashboard 子模块. [#1360](https://github.com/apache/incubator-apisix/pull/1360)
- 允许自定义共享字典. [#1367](https://github.com/apache/incubator-apisix/pull/1367)
- 增加 dashboard 子模块。[#1360](https://github.com/apache/incubator-apisix/pull/1360)
- 允许自定义共享字典。[#1367](https://github.com/apache/incubator-apisix/pull/1367)
### Plugin
@ -654,27 +654,27 @@ title: CHANGELOG
- :sunrise: **新增 UDP logger 插件**. [1070](https://github.com/apache/incubator-apisix/pull/1070)
- :sunrise: **新增 proxy mirror 插件**. [#1288](https://github.com/apache/incubator-apisix/pull/1288)
- :sunrise: **新增 proxy cache 插件**. [#1153](https://github.com/apache/incubator-apisix/pull/1153)
- 在 proxy-rewrite 插件中废弃 websocket 开关(**不向下兼容**). [1332](https://github.com/apache/incubator-apisix/pull/1332)
- OAuth 插件中增加基于公钥的自省支持. [#1266](https://github.com/apache/incubator-apisix/pull/1266)
- response-rewrite 插件通过 base64 来支持传输二进制数据. [#1381](https://github.com/apache/incubator-apisix/pull/1381)
- 在 proxy-rewrite 插件中废弃 websocket 开关 (**不向下兼容**). [1332](https://github.com/apache/incubator-apisix/pull/1332)
- OAuth 插件中增加基于公钥的自省支持。[#1266](https://github.com/apache/incubator-apisix/pull/1266)
- response-rewrite 插件通过 base64 来支持传输二进制数据。[#1381](https://github.com/apache/incubator-apisix/pull/1381)
- gRPC 转码插件支持 `deadline`. [#1149](https://github.com/apache/incubator-apisix/pull/1149)
- limit count 插件支持 redis 权限认证. [#1150](https://github.com/apache/incubator-apisix/pull/1150)
- Zipkin 插件支持名字和本地服务器 ip 的记录. [#1386](https://github.com/apache/incubator-apisix/pull/1386)
- Wolf-Rbac 插件增加 `change_pwd` 和 `user_info` 参数. [#1204](https://github.com/apache/incubator-apisix/pull/1204)
- limit count 插件支持 redis 权限认证。[#1150](https://github.com/apache/incubator-apisix/pull/1150)
- Zipkin 插件支持名字和本地服务器 ip 的记录。[#1386](https://github.com/apache/incubator-apisix/pull/1386)
- Wolf-Rbac 插件增加 `change_pwd` 和 `user_info` 参数。[#1204](https://github.com/apache/incubator-apisix/pull/1204)
### Admin API
- :sunrise: 对调用 Admin API 增加 key-auth 权限认证(**not backward compatible**). [#1169](https://github.com/apache/incubator-apisix/pull/1169)
- 隐藏 SSL 私钥的返回值. [#1240](https://github.com/apache/incubator-apisix/pull/1240)
- :sunrise: 对调用 Admin API 增加 key-auth 权限认证 (**not backward compatible**). [#1169](https://github.com/apache/incubator-apisix/pull/1169)
- 隐藏 SSL 私钥的返回值。[#1240](https://github.com/apache/incubator-apisix/pull/1240)
### Bugfix
- 在复用 table 之前遗漏了对数据的清理 (**会引发内存泄漏**). [#1134](https://github.com/apache/incubator-apisix/pull/1134)
- 如果 yaml 中路由非法就打印警告信息. [#1141](https://github.com/apache/incubator-apisix/pull/1141)
- 如果 yaml 中路由非法就打印警告信息。[#1141](https://github.com/apache/incubator-apisix/pull/1141)
- 使用空字符串替代空的 balancer IP. [#1166](https://github.com/apache/incubator-apisix/pull/1166)
- 修改 node-status 和 heartbeat 插件没有 schema 的问题. [#1249](https://github.com/apache/incubator-apisix/pull/1249)
- basic-auth 增加 required 字段. [#1251](https://github.com/apache/incubator-apisix/pull/1251)
- 检查上游合法节点的个数. [#1292](https://github.com/apache/incubator-apisix/pull/1292)
- 修改 node-status 和 heartbeat 插件没有 schema 的问题。[#1249](https://github.com/apache/incubator-apisix/pull/1249)
- basic-auth 增加 required 字段。[#1251](https://github.com/apache/incubator-apisix/pull/1251)
- 检查上游合法节点的个数。[#1292](https://github.com/apache/incubator-apisix/pull/1292)
## 1.1.0
@ -691,7 +691,7 @@ title: CHANGELOG
### Doc
- 增加 Grafana 元数据下载链接. [#1119](https://github.com/apache/incubator-apisix/pull/1119)
- 增加 Grafana 元数据下载链接。[#1119](https://github.com/apache/incubator-apisix/pull/1119)
- 更新 README.md。 [#1118](https://github.com/apache/incubator-apisix/pull/1118)
- 增加 wolf-rbac 插件说明文档 [#1116](https://github.com/apache/incubator-apisix/pull/1116)
- 更新 rpm 下载链接。 [#1108](https://github.com/apache/incubator-apisix/pull/1108)
@ -710,7 +710,7 @@ title: CHANGELOG
### Plugins
- 「节点状态」插件使用 nginx 内部请求替换原来的外部请求。 [#1109](https://github.com/apache/incubator-apisix/pull/1109)
- 在「节点状态」插件使用 nginx 内部请求替换原来的外部请求。 [#1109](https://github.com/apache/incubator-apisix/pull/1109)
- 增加 wolf-rbac 插件。 [#1095](https://github.com/apache/incubator-apisix/pull/1095)
- 增加 udp-logger 插件。 [#1070](https://github.com/apache/incubator-apisix/pull/1070)
@ -745,7 +745,7 @@ title: CHANGELOG
## 0.9.0
这个版本带来很多新特性，比如支持使用 Tengine 运行 APISIX，增加了对开发人员更友好的高级调试模式，还有新的URI重定向插件等。
这个版本带来很多新特性，比如支持使用 Tengine 运行 APISIX，增加了对开发人员更友好的高级调试模式，还有新的 URI 重定向插件等。
### Core
@ -766,17 +766,17 @@ title: CHANGELOG
- lua-resty-radixtree
- 支持将`host + uri`作为索引。
- lua-resty-jsonschema
- 该扩展作用是JSON数据验证器，用于替换现有的 `lua-rapidjson` 扩展。
- 该扩展作用是 JSON 数据验证器，用于替换现有的 `lua-rapidjson` 扩展。
### Bugfix
- 在多个使用者的情况下，`key-auth` 插件无法正确运行。 [#826](https://github.com/apache/incubator-apisix/pull/826)
- 无法在 `API Server` 中获取 `serverless`插件配置。 [#787](https://github.com/apache/incubator-apisix/pull/787)
- 解决使用 `proxy-write` 重写URI时GET参数丢失问题。 [#642](https://github.com/apache/incubator-apisix/pull/642)
- `Zipkin` 插件未将跟踪数据设置为请求头. [#715](https://github.com/apache/incubator-apisix/pull/715)
- 解决使用 `proxy-write` 重写 URI 时 GET 参数丢失问题。 [#642](https://github.com/apache/incubator-apisix/pull/642)
- `Zipkin` 插件未将跟踪数据设置为请求头。[#715](https://github.com/apache/incubator-apisix/pull/715)
- 使用本地文件作为配置中心时，跳过 etcd 初始化。 [#737](https://github.com/apache/incubator-apisix/pull/737)
- 在APISIX CLI中跳过 luajit 环境的`check cjson`。[#652](https://github.com/apache/incubator-apisix/pull/652)
- 配置 `Upstream` 时，选择 `balancer` 类型为 `chash` 时，支持更多Nginx内置变量作为计算key。 [#775](https://github.com/apache/incubator-apisix/pull/775)
- 在 APISIX CLI 中跳过 luajit 环境的`check cjson`。[#652](https://github.com/apache/incubator-apisix/pull/652)
- 配置 `Upstream` 时，选择 `balancer` 类型为 `chash` 时，支持更多 Nginx 内置变量作为计算 key。 [#775](https://github.com/apache/incubator-apisix/pull/775)
### Dependencies
@ -786,7 +786,7 @@ title: CHANGELOG
> Released on 2019/09/30
这个版本带来很多新的特性，比如四层协议的代理, 支持 MQTT 协议代理，以及对 ARM 平台的支持, 和代理改写插件等。
这个版本带来很多新的特性，比如四层协议的代理，支持 MQTT 协议代理，以及对 ARM 平台的支持，和代理改写插件等。
### Core
@ -817,7 +817,7 @@ title: CHANGELOG
### Bugfix
- 健康检查: 修复在多 worker 下运行时健康检查 checker 的名字错误。 [#568](https://github.com/apache/incubator-apisix/issues/568)
- 健康检查：修复在多 worker 下运行时健康检查 checker 的名字错误。 [#568](https://github.com/apache/incubator-apisix/issues/568)
### Dependencies
@ -827,14 +827,14 @@ title: CHANGELOG
> Released on 2019/09/06
这个版本带来很多新的特性，比如 IP 黑白名单、gPRC 协议转换、支持 IPv6、对接 IdP（身份认证提供商）服务、serverless、默认路由修改为radix tree（**不向下兼容**）等。
这个版本带来很多新的特性，比如 IP 黑白名单、gPRC 协议转换、支持 IPv6、对接 IdP（身份认证提供商）服务、serverless、默认路由修改为 radix tree（**不向下兼容**）等。
### Core
- :sunrise: **[gRPC 协议转换](https://github.com/apache/incubator-apisix/blob/master/docs/zh/latest//plugins/grpc-transcoding-cn.md)**: 支持 gRPC 协议的转换，这样客户端可以通过 HTTP/JSON 来访问你的 gRPC API. [#395](https://github.com/apache/incubator-apisix/issues/395)
- :sunrise: **[radix tree 路由](https://github.com/apache/incubator-apisix/blob/master/docs/zh/latest//router-radixtree.md)**: 默认的路由器更改为 radix tree，支持把 uri、host、cookie、请求头、请求参数、Nginx 内置变量等作为路由的条件，并支持等于、大于、小于等常见操作符，更加强大和灵活. **需要注意的是，这个改动不向下兼容，所有使用历史版本的用户，需要手动修改路由才能正常使用**。[#414](https://github.com/apache/incubator-apisix/issues/414)
- :sunrise: **[radix tree 路由](https://github.com/apache/incubator-apisix/blob/master/docs/zh/latest//router-radixtree.md)**: 默认的路由器更改为 radix tree，支持把 uri、host、cookie、请求头、请求参数、Nginx 内置变量等作为路由的条件，并支持等于、大于、小于等常见操作符，更加强大和灵活。**需要注意的是，这个改动不向下兼容，所有使用历史版本的用户，需要手动修改路由才能正常使用**。[#414](https://github.com/apache/incubator-apisix/issues/414)
- 动态上游支持更多的参数，可以指定上游的 uri 和 host，以及是否开启 websocket. [#451](https://github.com/apache/incubator-apisix/pull/451)
- 支持从 `ctx.var` 中直接获取 cookie 中的值. [#449](https://github.com/apache/incubator-apisix/pull/449)
- 支持从 `ctx.var` 中直接获取 cookie 中的值。[#449](https://github.com/apache/incubator-apisix/pull/449)
- 路由支持 IPv6. [#331](https://github.com/apache/incubator-apisix/issues/331)
### Plugins
@ -846,7 +846,7 @@ title: CHANGELOG
### CLI
- 增加 `version` 指令，获取 APISIX 的版本号. [#420](https://github.com/apache/incubator-apisix/issues/420)
- 增加 `version` 指令，获取 APISIX 的版本号。[#420](https://github.com/apache/incubator-apisix/issues/420)
### Admin
@ -867,13 +867,13 @@ title: CHANGELOG
### Core
- :sunrise: **[健康检查和服务熔断](https://github.com/apache/incubator-apisix/blob/master/docs/zh/latest//health-check.md)**: 对上游节点开启健康检查，智能判断服务状态进行熔断和连接. [#249](https://github.com/apache/incubator-apisix/pull/249)
- 阻止ReDoS(Regular expression Denial of Service). [#252](https://github.com/apache/incubator-apisix/pull/250)
- 支持 debug 模式. [#319](https://github.com/apache/incubator-apisix/pull/319)
- 允许自定义路由. [#364](https://github.com/apache/incubator-apisix/pull/364)
- 路由支持 host 和 uri 的组合. [#325](https://github.com/apache/incubator-apisix/pull/325)
- 允许在 balance 阶段注入插件. [#299](https://github.com/apache/incubator-apisix/pull/299)
- 为 upstream 和 service 在 schema 中增加描述信息. [#289](https://github.com/apache/incubator-apisix/pull/289)
- :sunrise: **[健康检查和服务熔断](https://github.com/apache/incubator-apisix/blob/master/docs/zh/latest//health-check.md)**: 对上游节点开启健康检查，智能判断服务状态进行熔断和连接。[#249](https://github.com/apache/incubator-apisix/pull/249)
- 阻止 ReDoS(Regular expression Denial of Service). [#252](https://github.com/apache/incubator-apisix/pull/250)
- 支持 debug 模式。[#319](https://github.com/apache/incubator-apisix/pull/319)
- 允许自定义路由。[#364](https://github.com/apache/incubator-apisix/pull/364)
- 路由支持 host 和 uri 的组合。[#325](https://github.com/apache/incubator-apisix/pull/325)
- 允许在 balance 阶段注入插件。[#299](https://github.com/apache/incubator-apisix/pull/299)
- 为 upstream 和 service 在 schema 中增加描述信息。[#289](https://github.com/apache/incubator-apisix/pull/289)
### Plugins
@ -882,7 +882,7 @@ title: CHANGELOG
### CLI
- `allow` 指令中支持多个 ip 地址. [#340](https://github.com/apache/incubator-apisix/pull/340)
- `allow` 指令中支持多个 ip 地址。[#340](https://github.com/apache/incubator-apisix/pull/340)
- 支持在 nginx.conf 中配置 real_ip 指令，以及增加函数来获取 ip. [#236](https://github.com/apache/incubator-apisix/pull/236)
### Dashboard
@ -892,6 +892,6 @@ title: CHANGELOG
### Test
- 在 Travis CI 中支持 OSX. [#217](https://github.com/apache/incubator-apisix/pull/217)
- 把所有依赖安装到 `deps` 目录. [#248](https://github.com/apache/incubator-apisix/pull/248)
- 把所有依赖安装到 `deps` 目录。[#248](https://github.com/apache/incubator-apisix/pull/248)
[Back to TOC](#table-of-contents)

6
docs/zh/latest/CODE_STYLE.md
View File

@ -190,7 +190,7 @@ local i = 1
local s = "apisix"
```
变量命名使用 `snake_case`（蛇形命名法） 风格:
变量命名使用 `snake_case`（蛇形命名法）风格：
```lua
--No
@ -246,7 +246,7 @@ end
local t = {1, 2, nil, 3}
```
如果一定要使用空值，请用 `ngx.null` 来表示:
如果一定要使用空值，请用 `ngx.null` 来表示：
```lua
--Yes
@ -344,7 +344,7 @@ local function foo()
end
```
为了风格的统一，`require` 和 `ngx` 也需要 `local` 化:
为了风格的统一，`require` 和 `ngx` 也需要 `local` 化：
```lua
--No

6
docs/zh/latest/FAQ.md
View File

@ -403,9 +403,9 @@ HTTP/1.1 404 Not Found
在 route 中，我们可以通过 `uri` 结合 `vars` 字段来实现更多的条件匹配，`vars` 的更多使用细节请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。
## upstream 节点是否支持配置 [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) 地址?
## upstream 节点是否支持配置 [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) 地址？
这是支持的，下面是一个 `FQDN` 为 `httpbin.default.svc.cluster.local`（一个 Kubernetes Service） 的示例：
这是支持的，下面是一个 `FQDN` 为 `httpbin.default.svc.cluster.local`（一个 Kubernetes Service）的示例：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -546,7 +546,7 @@ apisix:
# ... 忽略其余无关项
```
**注意:**
**注意：**
尝试使用 cosocket 连接任何 TLS 服务时，如果 APISIX 不信任对端 TLS 服务证书，都需要配置 `apisix.ssl.ssl_trusted_certificate`。

58
docs/zh/latest/README.md
View File

@ -61,18 +61,18 @@ Apache APISIX 的技术架构如下图所示：
## 特性
你可以把 Apache APISIX 当做流量入口，来处理所有的业务数据，包括动态路由、动态上游、动态证书、
A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵御恶意攻击、监控报警、服务可观测性、服务治理等。
A/B 测试、金丝雀发布（灰度发布）、蓝绿部署、限流限速、抵御恶意攻击、监控报警、服务可观测性、服务治理等。
- **全平台**
- 云原生: 平台无关，没有供应商锁定，无论裸机还是 Kubernetes，APISIX 都可以运行。
- 支持 ARM64: 不用担心底层技术的锁定。
- 云原生：平台无关，没有供应商锁定，无论裸机还是 Kubernetes，APISIX 都可以运行。
- 支持 ARM64：不用担心底层技术的锁定。
- **多协议**
- [TCP/UDP 代理](stream-proxy.md): 动态 TCP/UDP 代理。
- [Dubbo 代理](plugins/dubbo-proxy.md): 动态代理 HTTP 请求到 Dubbo 后端。
- [动态 MQTT 代理](plugins/mqtt-proxy.md): 支持用 `client_id` 对 MQTT 进行负载均衡，同时支持 MQTT [3.1.\*](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) 和 [5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html) 两个协议标准。
- [TCP/UDP 代理](stream-proxy.md)：动态 TCP/UDP 代理。
- [Dubbo 代理](plugins/dubbo-proxy.md)：动态代理 HTTP 请求到 Dubbo 后端。
- [动态 MQTT 代理](plugins/mqtt-proxy.md)：支持用 `client_id` 对 MQTT 进行负载均衡，同时支持 MQTT [3.1.\*](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) 和 [5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html) 两个协议标准。
- [gRPC 代理](grpc-proxy.md)：通过 APISIX 代理 gRPC 连接，并使用 APISIX 的大部分特性管理你的 gRPC 服务。
- [gRPC Web 代理](plugins/grpc-web.md)：通过 APISIX 代理 gRPC Web 请求到上游 gRPC 服务。
- [gRPC 协议转换](plugins/grpc-transcode.md)：支持协议的转换，这样客户端可以通过 HTTP/JSON 来访问你的 gRPC API。
@ -83,16 +83,16 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵
- **全动态能力**
- [热更新和热插件](architecture-design/plugin.md): 无需重启服务，就可以持续更新配置和插件。
- [代理请求重写](plugins/proxy-rewrite.md): 支持重写请求上游的`host`、`uri`、`schema`、`enable_websocket`、`headers`信息。
- [输出内容重写](plugins/response-rewrite.md): 支持自定义修改返回内容的 `status code`、`body`、`headers`。
- [Serverless](plugins/serverless.md): 在 APISIX 的每一个阶段，你都可以添加并调用自己编写的函数。
- [热更新和热插件](architecture-design/plugin.md)：无需重启服务，就可以持续更新配置和插件。
- [代理请求重写](plugins/proxy-rewrite.md)：支持重写请求上游的`host`、`uri`、`schema`、`enable_websocket`、`headers`信息。
- [输出内容重写](plugins/response-rewrite.md)：支持自定义修改返回内容的 `status code`、`body`、`headers`。
- [Serverless](plugins/serverless.md)：在 APISIX 的每一个阶段，你都可以添加并调用自己编写的函数。
- 动态负载均衡：动态支持有权重的 round-robin 负载平衡。
- 支持一致性 hash 的负载均衡：动态支持一致性 hash 的负载均衡。
- [健康检查](health-check.md)：启用上游节点的健康检查，将在负载均衡期间自动过滤不健康的节点，以确保系统稳定性。
- 熔断器: 智能跟踪不健康上游服务。
- [代理镜像](plugins/proxy-mirror.md): 提供镜像客户端请求的能力。
- [流量拆分](plugins/traffic-split.md): 允许用户逐步控制各个上游之间的流量百分比。
- 熔断器：智能跟踪不健康上游服务。
- [代理镜像](plugins/proxy-mirror.md)：提供镜像客户端请求的能力。
- [流量拆分](plugins/traffic-split.md)：允许用户逐步控制各个上游之间的流量百分比。
- **精细化路由**
@ -101,17 +101,17 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵
- 支持[各类操作符做为路由的判断条件](https://github.com/api7/lua-resty-radixtree#operator-list)，比如 `{"arg_age", ">", 24}`
- 支持[自定义路由匹配函数](https://github.com/api7/lua-resty-radixtree/blob/master/t/filter-fun.t#L10)
- IPv6：支持使用 IPv6 格式匹配路由
- 支持路由的[自动过期(TTL)](admin-api.md#route)
- 支持路由的[自动过期 (TTL)](admin-api.md#route)
- [支持路由的优先级](../../en/latest/router-radixtree.md#3-match-priority)
- [支持批量 Http 请求](plugins/batch-requests.md)
- [支持通过GraphQL属性过滤路由](../../en/latest/router-radixtree.md#how-to-filter-route-by-graphql-attributes)
- [支持通过 GraphQL 属性过滤路由](../../en/latest/router-radixtree.md#how-to-filter-route-by-graphql-attributes)
- **安全防护**
- 多种身份认证方式: [key-auth](plugins/key-auth.md), [JWT](plugins/jwt-auth.md), [basic-auth](plugins/basic-auth.md), [wolf-rbac](plugins/wolf-rbac.md), casbin, [keycloak](plugins/authz-keycloak.md)。
- 多种身份认证方式：[key-auth](plugins/key-auth.md)、[JWT](plugins/jwt-auth.md)、[basic-auth](plugins/basic-auth.md)、[wolf-rbac](plugins/wolf-rbac.md)、[casbin](plugins/authz-casbin.md)、[keycloak](plugins/authz-keycloak.md)。
- [IP 黑白名单](plugins/ip-restriction.md)
- [Referer 黑白名单](plugins/referer-restriction.md)
- [IdP 支持](plugins/openid-connect.md): 支持外部的身份认证服务，比如 Auth0，Okta，Authing 等，用户可以借此来对接 Oauth2.0 等认证方式。
- [IdP 支持](plugins/openid-connect.md)：支持外部的身份认证服务，比如 Auth0，Okta，Authing 等，用户可以借此来对接 Oauth2.0 等认证方式。
- [限制速率](plugins/limit-req.md)
- [限制请求数](plugins/limit-count.md)
- [限制并发](plugins/limit-conn.md)
@ -123,38 +123,38 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵
- **运维友好**
- OpenTracing 可观测性: 支持 [Apache Skywalking](plugins/skywalking.md) 和 [Zipkin](plugins/zipkin.md)。
- OpenTracing 可观测性：支持 [Apache Skywalking](plugins/skywalking.md) 和 [Zipkin](plugins/zipkin.md)。
- 对接外部服务发现：除了内置的 etcd 外，还支持 [Consul](../../en/latest/discovery/consul_kv.md) 和 [Nacos](../../en/latest/discovery/nacos.md)，以及 [Eureka](discovery.md)。
- 监控和指标: [Prometheus](plugins/prometheus.md)
- 监控和指标：[Prometheus](plugins/prometheus.md)
- 集群：APISIX 节点是无状态的，创建配置中心集群请参考 [etcd Clustering Guide](https://etcd.io/docs/v3.5/op-guide/clustering/)。
- 高可用：支持配置同一个集群内的多个 etcd 地址。
- [控制台](https://github.com/apache/apisix-dashboard): 操作 APISIX 集群。
- 版本控制：支持操作的多次回滚。
- CLI: 使用命令行来启动、关闭和重启 APISIX。
- [单机模式](stand-alone.md): 支持从本地配置文件中加载路由规则，在 kubernetes(k8s) 等环境下更友好。
- CLI：使用命令行来启动、关闭和重启 APISIX。
- [单机模式](stand-alone.md)：支持从本地配置文件中加载路由规则，在 kubernetes(k8s) 等环境下更友好。
- [全局规则](architecture-design/global-rule.md)：允许对所有请求执行插件，比如黑白名单、限流限速等。
- 高性能：在单核上 QPS 可以达到 18k，同时延迟只有 0.2 毫秒。
- [故障注入](plugins/fault-injection.md)
- [REST Admin API](admin-api.md): 使用 REST Admin API 来控制 Apache APISIX，默认只允许 127.0.0.1 访问，你可以修改 `conf/config.yaml` 中的 `allow_admin` 字段，指定允许调用 Admin API 的 IP 列表。同时需要注意的是，Admin API 使用 key auth 来校验调用者身份，**在部署前需要修改 `conf/config.yaml` 中的 `admin_key` 字段，来保证安全。**
- [REST Admin API](admin-api.md)：使用 REST Admin API 来控制 Apache APISIX，默认只允许 127.0.0.1 访问，你可以修改 `conf/config.yaml` 中的 `allow_admin` 字段，指定允许调用 Admin API 的 IP 列表。同时需要注意的是，Admin API 使用 key auth 来校验调用者身份，**在部署前需要修改 `conf/config.yaml` 中的 `admin_key` 字段，来保证安全。**
- 外部日志记录器：将访问日志导出到外部日志管理工具。（[HTTP Logger](plugins/http-logger.md)、[TCP Logger](plugins/tcp-logger.md)、[Kafka Logger](plugins/kafka-logger.md)、[UDP Logger](plugins/udp-logger.md)、[RocketMQ Logger](plugins/rocketmq-logger.md)、[SkyWalking Logger](plugins/skywalking-logger.md)、[Alibaba Cloud Logging(SLS)](plugins/sls-logger.md)、[Google Cloud Logging](plugins/google-cloud-logging.md)、[Splunk HEC Logging](plugins/splunk-hec-logging.md)、[File Logger](plugins/file-logger.md)）
- [Helm charts](https://github.com/apache/apisix-helm-chart)
- **高度可扩展**
- [自定义插件](plugin-develop.md): 允许挂载常见阶段，例如`init`, `rewrite`，`access`，`balancer`,`header filter`，`body filter` 和 `log` 阶段。
- [自定义插件](plugin-develop.md)：允许挂载常见阶段，例如`init`，`rewrite`，`access`，`balancer`，`header filter`，`body filter` 和 `log` 阶段。
- [插件可以用 Java/Go/Python 编写](../../zh/latest/external-plugin.md)
- 自定义负载均衡算法：可以在 `balancer` 阶段使用自定义负载均衡算法。
- 自定义路由: 支持用户自己实现路由算法。
- 自定义路由：支持用户自己实现路由算法。
- **多语言支持**
- Apache APISIX 是一个通过 `RPC` 和 `Wasm` 支持不同语言来进行插件开发的网关.
- Apache APISIX 是一个通过 `RPC` 和 `Wasm` 支持不同语言来进行插件开发的网关。
![Multi Language Support into Apache APISIX](../../../docs/assets/images/apisix-multi-lang-support.png)
- RPC 是当前采用的开发方式。开发者可以使用他们需要的语言来进行 RPC 服务的开发，该 RPC 通过本地通讯来跟 APISIX 进行数据交换。到目前为止，APISIX 已支持[Java](https://github.com/apache/apisix-java-plugin-runner), [Golang](https://github.com/apache/apisix-go-plugin-runner), [Python](https://github.com/apache/apisix-python-plugin-runner) 和 Node.js。
- Wasm 或 WebAssembly 是实验性的开发方式。 APISIX 能加载运行使用[Proxy Wasm SDK](https://github.com/proxy-wasm/spec#sdks)编译的 Wasm 字节码。开发者仅需要使用该 SDK 编写代码，然后编译成 Wasm 字节码，即可运行在 APISIX 中的 Wasm 虚拟机中。
- **Serverless**
- [Lua functions](plugins/serverless.md): 能在 APISIX 每个阶段调用 lua 函数.
- [Azure functions](docs/en/latest/plugins/azure-functions.md): 能无缝整合进 Azure Serverless Function 中。作为动态上游，能将特定的 URI 请求全部代理到微软 Azure 云中。
- [Apache OpenWhisk](docs/en/latest/plugins/openwhisk.md): 与Apache OpenWhisk集成。作为动态上游，能将特定的 URI 请求代理到你自己的 OpenWhisk 集群。
- [Lua functions](plugins/serverless.md)：能在 APISIX 每个阶段调用 lua 函数。
- [Azure functions](docs/en/latest/plugins/azure-functions.md)：能无缝整合进 Azure Serverless Function 中。作为动态上游，能将特定的 URI 请求全部代理到微软 Azure 云中。
- [Apache OpenWhisk](docs/en/latest/plugins/openwhisk.md)：与 Apache OpenWhisk 集成。作为动态上游，能将特定的 URI 请求代理到你自己的 OpenWhisk 集群。
## 立刻开始
@ -210,7 +210,7 @@ A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵
## 用户实际使用案例
- [新浪微博: 基于 Apache APISIX，新浪微博 API 网关的定制化开发之路](https://apisix.apache.org/blog/2021/07/14/the-road-to-customization-of-Sina-Weibo-API-gateway-based-on-Apache-APISIX)
- [新浪微博：基于 Apache APISIX，新浪微博 API 网关的定制化开发之路](https://apisix.apache.org/blog/2021/07/14/the-road-to-customization-of-Sina-Weibo-API-gateway-based-on-Apache-APISIX)
- [欧盟数字工厂平台: API Security Gateway – Using APISIX in the eFactory Platform](https://www.efactory-project.eu/post/api-security-gateway-using-apisix-in-the-efactory-platform)
- [贝壳找房：如何基于 Apache APISIX 搭建网关](https://mp.weixin.qq.com/s/yZl9MWPyF1-gOyCp8plflA)
- [360：Apache APISIX 在基础运维平台项目中的实践](https://mp.weixin.qq.com/s/mF8w8hW4alIMww0MSu9Sjg)

64
docs/zh/latest/admin-api.md
View File

@ -58,7 +58,7 @@ Admin API 是为 Apache APISIX 服务的一组 API，我们可以将参数传递
### body 请求参数
| 名字 | 可选项 | 类型 | 说明 | 示例 |
| ---------------- | ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| ---------------- | ---------------------------------- | -------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------------------------------------------- |
| uri | 必选，不能与 `uris` 一起使用 | 匹配规则 | 除了如 `/foo/bar`、`/foo/gloo` 这种全量匹配外，使用不同 [Router](architecture-design/router.md) 还允许更高级匹配，更多见 [Router](architecture-design/router.md)。 | "/hello" |
| uris | 必选，不能与 `uri` 一起使用 | 匹配规则 | 非空数组形式，可以匹配多个 `uri` | ["/hello", "/world"] |
| plugins | 可选 | Plugin | 详见 [Plugin](architecture-design/plugin.md) | |
@ -71,16 +71,16 @@ Admin API 是为 Apache APISIX 服务的一组 API，我们可以将参数传递
| desc | 可选 | 辅助 | 标识描述、使用场景等。 | 路由 xxxx |
| host | 可选，不能与 `hosts` 一起使用 | 匹配规则 | 当前请求域名，比如 `foo.com`；也支持泛域名，比如 `*.foo.com`。 | "foo.com" |
| hosts | 可选，不能与 `host` 一起使用 | 匹配规则 | 非空列表形态的 `host`，表示允许有多个不同 `host`，匹配其中任意一个即可。 | ["foo.com", "\*.bar.com"] |
| remote_addr | 可选，不能与 `remote_addrs` 一起使用 | 匹配规则 | 客户端请求 IP 地址: `192.168.1.101`、`192.168.1.102` 以及 CIDR 格式的支持 `192.168.1.0/24`。特别的，APISIX 也完整支持 IPv6 地址匹配：`::1`，`fe80::1`, `fe80::1/64` 等。 | "192.168.1.0/24" |
| remote_addr | 可选，不能与 `remote_addrs` 一起使用 | 匹配规则 | 客户端请求 IP 地址：`192.168.1.101`、`192.168.1.102` 以及 CIDR 格式的支持 `192.168.1.0/24`。特别的，APISIX 也完整支持 IPv6 地址匹配：`::1`，`fe80::1`，`fe80::1/64` 等。 | "192.168.1.0/24" |
| remote_addrs | 可选，不能与 `remote_addr` 一起使用 | 匹配规则 | 非空列表形态的 `remote_addr`，表示允许有多个不同 IP 地址，符合其中任意一个即可。 | ["127.0.0.1", "192.0.0.0/8", "::1"] |
| methods | 可选 | 匹配规则 | 如果为空或没有该选项，代表没有任何 `method` 限制，也可以是一个或多个的组合：`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`，`CONNECT`，`TRACE`。 | ["GET", "POST"] |
| methods | 可选 | 匹配规则 | 如果为空或没有该选项，代表没有任何 `method` 限制，也可以是一个或多个的组合：`GET`，`POST`，`PUT`，`DELETE`，`PATCH`，`HEAD`，`OPTIONS`，`CONNECT`，`TRACE`。 | ["GET", "POST"] |
| priority | 可选 | 匹配规则 | 如果不同路由包含相同 `uri`，根据属性 `priority` 确定哪个 `route` 被优先匹配，值越大优先级越高，默认值为 0。 | priority = 10 |
| vars | 可选 | 匹配规则 | 由一个或多个`[var, operator, val]`元素组成的列表，类似这样：`[[var, operator, val], [var, operator, val], ...]]`。例如：`["arg_name", "==", "json"]`，表示当前请求参数 `name` 是 `json`。这里的 `var` 与 Nginx 内部自身变量命名是保持一致，所以也可以使用 `request_uri`、`host` 等。更多细节请参考[lua-resty-expr](https://github.com/api7/lua-resty-expr) | [["arg_name", "==", "json"], ["arg_age", ">", 18]] |
| filter_func | 可选 | 匹配规则 | 用户自定义的过滤函数。可以使用它来实现特殊场景的匹配要求实现。该函数默认接受一个名为 vars 的输入参数，可以用它来获取 Nginx 变量。 | function(vars) return vars["arg_name"] == "json" end |
| labels | 可选 | 匹配规则 | 标识附加属性的键值对 | {"version":"v2","build":"16","env":"production"} |
| timeout | 可选 | 辅助 | 为 route 设置 upstream 的连接、发送消息、接收消息的超时时间。这个配置将会覆盖在 upstream 中 配置的 [timeout](#upstream) 选项 | {"connect": 3, "send": 3, "read": 3} |
| enable_websocket | 可选 | 辅助 | 是否启用 `websocket`(boolean), 缺省 `false`. | |
| status | 可选 | 辅助 | 是否启用此路由, 缺省 `1`。 | `1` 表示启用，`0` 表示禁用 |
| enable_websocket | 可选 | 辅助 | 是否启用 `websocket`(boolean), 缺省 `false`。 | |
| status | 可选 | 辅助 | 是否启用此路由，缺省 `1`。 | `1` 表示启用，`0` 表示禁用 |
| create_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
@ -99,7 +99,7 @@ route 对象 json 配置内容：
"hosts": ["a.com","b.com"], # 一组 host 域名
"plugins": {}, # 指定 route 绑定的插件
"priority": 0, # apisix 支持多种匹配方式，可能会在一次匹配中同时匹配到多条路由，此时优先级高的优先匹配中
"name": "路由xxx",
"name": "路由 xxx",
"desc": "hello world",
"remote_addrs": ["127.0.0.1"], # 一组客户端请求 IP 地址
"vars": [["http_user", "==", "ios"]], # 由一个或多个 [var, operator, val] 元素组成的列表
@ -332,7 +332,7 @@ service 对象 json 配置内容：
具体示例：
```shell
# 创建一个Service
# 创建一个 Service
$ curl http://127.0.0.1:9080/apisix/admin/services/201 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
"plugins": {
@ -532,9 +532,9 @@ APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上
| 名字 | 可选项 | 类型 | 说明 | 示例 |
| -------------- | ---------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| type | 必需 | 枚举 | 负载均衡算法 | | |
| nodes | 必需，不能和 `service_name` 一起用 | Node | 哈希表或数组。当它是哈希表时，内部元素的 key 是上游机器地址列表，格式为`地址 + （可选的）端口`，其中地址部分可以是 IP 也可以是域名，比如 `192.168.1.100:80`、`foo.com:80`等。value 则是节点的权重。当它是数组时，数组中每个元素都是一个哈希表，其中包含 `host`、`weight` 以及可选的 `port`、`priority`。`nodes` 可以为空，这通常用作占位符。客户端命中这样的上游会返回 502。 | `192.168.1.100:80` |
| nodes | 必需，不能和 `service_name` 一起用 | Node | 哈希表或数组。当它是哈希表时，内部元素的 key 是上游机器地址列表，格式为`地址 +（可选的）端口`，其中地址部分可以是 IP 也可以是域名，比如 `192.168.1.100:80`、`foo.com:80`等。value 则是节点的权重。当它是数组时，数组中每个元素都是一个哈希表，其中包含 `host`、`weight` 以及可选的 `port`、`priority`。`nodes` 可以为空，这通常用作占位符。客户端命中这样的上游会返回 502。 | `192.168.1.100:80` |
| service_name | 必需，不能和 `nodes` 一起用 | string | 服务发现时使用的服务名，见[集成服务发现注册中心](./discovery.md) | `a-bootiful-client` |
| discovery_type | 必需，如果设置了 `service_name` | string | 服务发现类型，见[集成服务发现注册中心](./discovery.md) | `eureka` |
| discovery_type | 必需，如果设置了 `service_name` | string | 服务发现类型，见 [集成服务发现注册中心](./discovery.md) | `eureka` |
| key | 条件必需 | 匹配类型 | 该选项只有类型是 `chash` 才有效。根据 `key` 来查找对应的 node `id`，相同的 `key` 在同一个对象中，永远返回相同 id，目前支持的 Nginx 内置变量有 `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`，其中 `arg_***` 是来自 URL 的请求参数，[Nginx 变量列表](http://nginx.org/en/docs/varindex.html) | |
| checks | 可选 | health_checker | 配置健康检查的参数，详细可参考[health-check](health-check.md) | |
| retries | 可选 | 整型 | 使用底层的 Nginx 重试机制将请求传递给下一个上游，默认启用重试且次数为后端可用的 node 数量。如果指定了具体重试次数，它将覆盖默认值。`0` 代表不启用重试机制。 | |
@ -551,9 +551,9 @@ APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上
| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
| tls.client_cert | 可选 | https 证书 | 设置跟上游通信时的客户端证书，细节见下文 | |
| tls.client_key | 可选 | https 证书私钥 | 设置跟上游通信时的客户端私钥，细节见下文 | |
|keepalive_pool.size |可选| 辅助 | 动态设置 `keepalive` 指令，细节见下文|
|keepalive_pool.idle_timeout |可选| 辅助 | 动态设置 `keepalive_timeout` 指令，细节见下文|
|keepalive_pool.requests |可选| 辅助 | 动态设置 `keepalive_requests` 指令，细节见下文|
|keepalive_pool.size | 可选 | 辅助 | 动态设置 `keepalive` 指令，细节见下文 |
|keepalive_pool.idle_timeout | 可选 | 辅助 | 动态设置 `keepalive_timeout` 指令，细节见下文 |
|keepalive_pool.requests | 可选 | 辅助 | 动态设置 `keepalive_requests` 指令，细节见下文 |
`type` 可以是以下的一种：
@ -566,12 +566,12 @@ APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上
`hash_on` 比较复杂，这里专门说明下：
1. 设为 `vars` 时，`key` 为必传参数，目前支持的 Nginx 内置变量有 `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`，其中 `arg_***` 是来自 URL 的请求参数，[Nginx 变量列表](http://nginx.org/en/docs/varindex.html)
2. 设为 `header` 时, `key` 为必传参数，其值为自定义的 header name, 即 "http\_`key`"
3. 设为 `cookie` 时, `key` 为必传参数，其值为自定义的 cookie name，即 "cookie\_`key`"。请注意 cookie name 是**区分大小写字母**的。例如："cookie_x_foo" 与 "cookie_X_Foo" 表示不同的 `cookie`。
2. 设为 `header` 时，`key` 为必传参数，其值为自定义的 header name，即 "http\_`key`"
3. 设为 `cookie` 时，`key` 为必传参数，其值为自定义的 cookie name，即 "cookie\_`key`"。请注意 cookie name 是**区分大小写字母**的。例如："cookie_x_foo" 与 "cookie_X_Foo" 表示不同的 `cookie`。
4. 设为 `consumer` 时，`key` 不需要设置。此时哈希算法采用的 `key` 为认证通过的 `consumer_name`。
5. 如果指定的 `hash_on` 和 `key` 获取不到值时，就是用默认值：`remote_addr`。
以下特性需要 APISIX 运行于 [APISIX-OpenResty](./how-to-build.md#步骤6：为-apache-apisix-构建-openresty)：
以下特性需要 APISIX 运行于 [APISIX-OpenResty](./how-to-build.md#步骤-6-为-apache-apisix-构建-openresty)：
`scheme` 可以设置成 `tls`，表示 "TLS over TCP"。
@ -580,7 +580,7 @@ APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上
`keepalive_pool` 允许 upstream 对象有自己单独的连接池。
它下属的字段，比如 `requests`，可以用了配置上游连接保持的参数。
这个特性需要 APISIX 运行于 [APISIX-OpenResty](./how-to-build.md#步骤6：为-apache-apisix-构建-openresty)。
这个特性需要 APISIX 运行于 [APISIX-OpenResty](./how-to-build.md#步骤-6-为-apache-apisix-构建-openresty)。
**upstream 对象 json 配置内容：**
@ -732,7 +732,7 @@ $ curl http://127.0.0.1:9080/get
节点可以配置自己的优先级。只有在高优先级的节点不可用或者尝试过，才会访问一个低优先级的节点。
由于默认的优先级是 0，我们可以给一些节点配置负数的优先级来作为备份。
举个例子:
举个例子：
```json
{
@ -793,13 +793,13 @@ $ curl http://127.0.0.1:9080/get
| key | 必需 | 私钥 | https 证书私钥 | |
| certs | 可选 | 证书字符串数组 | 当你想给同一个域名配置多个证书时，除了第一个证书需要通过 cert 传递外，剩下的证书可以通过该参数传递上来 | |
| keys | 可选 | 私钥字符串数组 | certs 对应的证书私钥，注意要跟 certs 一一对应 | |
| client.ca | 可选 | 证书| 设置将用于客户端证书校验的 CA 证书。该特性需要 OpenResty 1.19+ | |
| client.depth | 可选 | 辅助| 设置客户端证书校验的深度，默认为 1。该特性需要 OpenResty 1.19+ | |
| client.ca | 可选 | 证书 | 设置将用于客户端证书校验的 CA 证书。该特性需要 OpenResty 1.19+ | |
| client.depth | 可选 | 辅助 | 设置客户端证书校验的深度，默认为 1。该特性需要 OpenResty 1.19+ | |
| snis | 必需 | 匹配规则 | 非空数组形式，可以匹配多个 SNI | |
| labels | 可选 | 匹配规则 | 标识附加属性的键值对 | {"version":"v2","build":"16","env":"production"} |
| create_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
| status | 可选 | 辅助 | 是否启用此 SSL, 缺省 `1`。 | `1` 表示启用，`0` 表示禁用 |
| status | 可选 | 辅助 | 是否启用此 SSL，缺省 `1`。 | `1` 表示启用，`0` 表示禁用 |
ssl 对象 json 配置内容：
@ -862,13 +862,13 @@ ssl 对象 json 配置内容：
### body 请求参数
|名字 |可选项 |类型 |说明 |示例|
| 名字 | 可选项 | 类型 | 说明 | 示例 |
|---------|---------|----|-----------|----|
|plugins |必需|Plugin|详见 [Plugin](architecture-design/plugin.md) ||
|desc |可选|辅助|标识描述、使用场景等|customer xxxx|
|labels |可选|辅助|标识附加属性的键值对|{"version":"v2","build":"16","env":"production"}|
|create_time|可选|辅助|单位为秒的 epoch 时间戳，如果不指定则自动创建|1602883670|
|update_time|可选|辅助|单位为秒的 epoch 时间戳，如果不指定则自动创建|1602883670|
|plugins | 必需 |Plugin| 详见 [Plugin](architecture-design/plugin.md) ||
|desc | 可选 | 辅助 | 标识描述、使用场景等 |customer xxxx|
|labels | 可选 | 辅助 | 标识附加属性的键值对 |{"version":"v2","build":"16","env":"production"}|
|create_time| 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 |1602883670|
|update_time| 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 |1602883670|
[Back to TOC](#目录)
@ -890,7 +890,7 @@ ssl 对象 json 配置内容：
一个根据插件 ({plugin_name}) 的 `metadata_schema` 定义的数据结构的 json object 。
例子:
例子：
```shell
$ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/example-plugin -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
@ -917,13 +917,13 @@ Content-Type: text/plain
| ----------- | ----------------------------------- | ---------- | ------------- |
| GET       | /apisix/admin/plugins/list | 无 | 获取资源列表 |
| GET       | /apisix/admin/plugins/{plugin_name} | 无 | 获取资源 |
| GET | /apisix/admin/plugins?all=true | 无 | 获取所有插件的所有属性|
| GET | /apisix/admin/plugins?all=true | 无 | 获取所有插件的所有属性 |
### body 请求参数
获取插件  ({plugin_name})  数据结构的  json object 。
例子:
例子：
```shell
$ curl "http://127.0.0.1:9080/apisix/admin/plugins/list" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
@ -957,7 +957,7 @@ $ curl "http://127.0.0.1:9080/apisix/admin/plugins/key-auth" -H 'X-API-KEY:
*API*：/apisix/admin/stream_routes/{id}
*Description*：Stream Route 是用于 TCP/UDP 动态代理的路由。参见 [TCP/UDP 动态代理](./stream-proxy.md) 一节.
*Description*：Stream Route 是用于 TCP/UDP 动态代理的路由。参见 [TCP/UDP 动态代理](./stream-proxy.md) 一节。
### 请求方法
@ -971,14 +971,14 @@ $ curl "http://127.0.0.1:9080/apisix/admin/plugins/key-auth" -H 'X-API-KEY:
### body 请求参数
| 名字 | 可选项| 类型 | 说明 | 示例 |
| 名字 | 可选项 | 类型 | 说明 | 示例 |
| ---------------- | ------| -------- | ------| -----|
| upstream | 可选 | Upstream | 启用的 Upstream 配置，详见 [Upstream](architecture-design/upstream.md) | |
| upstream_id | 可选 | Upstream | 启用的 upstream id，详见 [Upstream](architecture-design/upstream.md) | |
| remote_addr | 可选 | IP/CIDR | 过滤选项：如果客户端 IP 匹配，则转发到上游 | "127.0.0.1/32" 或 "127.0.0.1" |
| server_addr | 可选 | IP/CIDR | 过滤选项：如果 APISIX 服务器 IP 与 server_addr 匹配，则转发到上游 | "127.0.0.1/32" 或 "127.0.0.1" |
| server_port | 可选 | 整数 | 过滤选项：如果 APISIX 服务器 port 与 server_port 匹配，则转发到上游 | 9090 |
| sni | 可选 | Host | 服务器名称指示| "test.com" |
| sni | 可选 | Host | 服务器名称指示 | "test.com" |
点击 [此处](./stream-proxy.md#more-route-match-options)，了解更多有关过滤器如何工作的信息。

4
docs/zh/latest/architecture-design/consumer.md
View File

@ -98,7 +98,7 @@ HTTP/1.1 503 Service Temporarily Unavailable
结合 [consumer-restriction](../plugins/consumer-restriction.md) 插件，限制 jack 对该 route 的访问
```shell
# 设置黑名单，禁止jack访问该API
# 设置黑名单，禁止 jack 访问该 API
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
@ -119,7 +119,7 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f
"uri": "/hello"
}'
# 反复测试，均返回 403，jack被禁止访问
# 反复测试，均返回 403，jack 被禁止访问
$ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
HTTP/1.1 403
...

2
docs/zh/latest/architecture-design/debug-mode.md
View File

@ -23,7 +23,7 @@ title: Debug Mode
### 基本调试模式
设置 `conf/debug.yaml` 即可开启基本调试模式:
设置 `conf/debug.yaml` 即可开启基本调试模式：
```
basic:

4
docs/zh/latest/architecture-design/plugin-config.md
View File

@ -29,7 +29,7 @@ title: Plugin Config
# 创建 Plugin config
$ curl http://127.0.0.1:9080/apisix/admin/plugin_configs/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
"desc": "吾乃插件配置1",
"desc": "吾乃插件配置 1",
"plugins": {
"limit-count": {
"count": 2,
@ -62,7 +62,7 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f
```
{
"desc": "吾乃插件配置1",
"desc": "吾乃插件配置 1",
"plugins": {
"ip-restriction": {
"whitelist": [

8
docs/zh/latest/architecture-design/router.md
View File

@ -27,13 +27,13 @@ APISIX 区别于其他 API 网关的一大特点是允许用户选择不同 Rout
- `apisix.router.http`: HTTP 请求路由。
- `radixtree_uri`: （默认）只使用 `uri` 作为主索引。基于 `radixtree` 引擎，支持全量和深前缀匹配，更多见 [如何使用 router-radixtree](../../../en/latest/router-radixtree.md)。
- `radixtree_uri`：（默认）只使用 `uri` 作为主索引。基于 `radixtree` 引擎，支持全量和深前缀匹配，更多见 [如何使用 router-radixtree](../../../en/latest/router-radixtree.md)。
- `绝对匹配`：完整匹配给定的 `uri` ，比如 `/foo/bar`，`/foo/glo`。
- `前缀匹配`：末尾使用 `*` 代表给定的 `uri` 是前缀匹配。比如 `/foo*`，则允许匹配 `/foo/`、`/foo/a`和`/foo/b`等。
- `匹配优先级`：优先尝试绝对匹配，若无法命中绝对匹配，再尝试前缀匹配。
- `任意过滤属性`：允许指定任何 Nginx 内置变量作为过滤条件，比如 URL 请求参数、请求头、cookie 等。
- `radixtree_uri_with_parameter`: 同 `radixtree_uri` 但额外有参数匹配的功能。
- `radixtree_host_uri`: 使用 `host + uri` 作为主索引（基于 `radixtree` 引擎），对当前请求会同时匹配 host 和 uri，支持的匹配条件与 `radixtree_uri` 基本一致。
- `radixtree_host_uri`：使用 `host + uri` 作为主索引（基于 `radixtree` 引擎），对当前请求会同时匹配 host 和 uri，支持的匹配条件与 `radixtree_uri` 基本一致。
- `apisix.router.ssl`: SSL 加载匹配路由。
- `radixtree_sni`: （默认）使用 `SNI` (Server Name Indication) 作为主索引（基于 radixtree 引擎）。
- `apisix.router.ssl`：SSL 加载匹配路由。
- `radixtree_sni`：（默认）使用 `SNI` (Server Name Indication) 作为主索引（基于 radixtree 引擎）。

2
docs/zh/latest/architecture-design/upstream.md
View File

@ -124,7 +124,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
#### Consumer
创建一个 consumer 对象:
创建一个 consumer 对象：
```shell
curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

10
docs/zh/latest/benchmark.md
View File

@ -25,7 +25,7 @@ title: 压力测试
使用谷歌云的服务器进行测试，型号为 n1-highcpu-8 (8 vCPUs, 7.2 GB memory)
我们最多只使用 4 核去运行 APISIX, 剩下的 4 核用于系统和压力测试工具 [wrk](https://github.com/wg/wrk)。
我们最多只使用 4 核去运行 APISIX，剩下的 4 核用于系统和压力测试工具 [wrk](https://github.com/wg/wrk)。
### 测试反向代理
@ -39,13 +39,13 @@ title: 压力测试
#### 延时
请注意 y 轴延时的单位是**微秒(μs)**，而不是毫秒：
请注意 y 轴延时的单位是**微秒（μs）**，而不是毫秒：
![latency-1](../../assets/images/latency-1.jpg)
#### 火焰图
火焰图的采样结果:
火焰图的采样结果：
![flamegraph-1](../../assets/images/flamegraph-1.jpg)
@ -61,11 +61,11 @@ title: 压力测试
#### Latency
请注意 y 轴延时的单位是**微秒(μs)**，而不是毫秒：
请注意 y 轴延时的单位是**微秒（μs）**，而不是毫秒：
![latency-2](../../assets/images/latency-2.jpg)
#### 火焰图
火焰图的采样结果:
火焰图的采样结果：
![火焰图采样结果](../../assets/images/flamegraph-2.jpg)

12
docs/zh/latest/certificate.md
View File

@ -23,17 +23,17 @@ title: 证书
`APISIX` 支持通过 TLS 扩展 SNI 实现加载特定的 SSL 证书以实现对 https 的支持。
SNI(Server Name Indication)是用来改善 SSL 和 TLS 的一项特性，它允许客户端在服务器端向其发送证书之前向服务器端发送请求的域名，服务器端根据客户端请求的域名选择合适的 SSL 证书发送给客户端。
SNI（Server Name Indication）是用来改善 SSL 和 TLS 的一项特性，它允许客户端在服务器端向其发送证书之前向服务器端发送请求的域名，服务器端根据客户端请求的域名选择合适的 SSL 证书发送给客户端。
### 单一域名指定
通常情况下一个 SSL 证书只包含一个静态域名，配置一个 `ssl` 参数对象，它包括 `cert`、`key`和`sni`三个属性，详细如下：
* `cert`: SSL 密钥对的公钥，pem 格式
* `key`: SSL 密钥对的私钥，pem 格式
* `snis`: SSL 证书所指定的一个或多个域名，注意在设置这个参数之前，你需要确保这个证书对应的私钥是有效的。
* `cert`：SSL 密钥对的公钥，pem 格式
* `key`：SSL 密钥对的私钥，pem 格式
* `snis`：SSL 证书所指定的一个或多个域名，注意在设置这个参数之前，你需要确保这个证书对应的私钥是有效的。
为了简化示例，我们会使用下面的 Python 脚本:
为了简化示例，我们会使用下面的 Python 脚本：
```python
#!/usr/bin/env python
@ -108,7 +108,7 @@ curl --resolve 'test.com:9443:127.0.0.1' https://test.com:9443/hello -vvv
一个 SSL 证书的域名也可能包含泛域名，如 `*.test.com`，它代表所有以 `test.com` 结尾的域名都可以使用该证书。
比如 `*.test.com`，可以匹配 `www.test.com`、`mail.test.com`。
看下面这个例子，请注意我们把 `*.test.com` 作为 sni 传递进来:
看下面这个例子，请注意我们把 `*.test.com` 作为 sni 传递进来：
```shell
./ssl.py t.crt t.key '*.test.com'

2
docs/zh/latest/control-api.md
View File

@ -86,7 +86,7 @@ APISIX 中一些插件添加了自己的 control API。如果你对他们感兴
}
```
只有启用了的插件才会被包含在返回结果中 `plugins` 部分。(返回结果中的)一些插件可能会缺失如 `consumer_schema` 或者 `type` 字段，这取决于插件的定义。
只有启用了的插件才会被包含在返回结果中 `plugins` 部分。（返回结果中的）一些插件可能会缺失如 `consumer_schema` 或者 `type` 字段，这取决于插件的定义。
### GET /v1/healthcheck

6
docs/zh/latest/debug-function.md
View File

@ -31,7 +31,7 @@ title: 调试功能
## 示例
示例1：`502` 响应状态码来源于 `Upstream` (IP 地址不可用)
示例 1：`502` 响应状态码来源于 `Upstream` (IP 地址不可用)
```shell
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -72,7 +72,7 @@ $ curl http://127.0.0.1:9080/hello -v
具有 `X-APISIX-Upstream-Status: 502` 的响应头。
示例2: `502` 响应状态码来源于 `APISIX`
示例 2：`502` 响应状态码来源于 `APISIX`
```shell
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -106,7 +106,7 @@ Fault Injection!
没有 `X-APISIX-Upstream-Status` 的响应头。
示例3：`Upstream` 具有多节点，并且所有节点不可用
示例 3：`Upstream` 具有多节点，并且所有节点不可用
```shell
$ curl http://127.0.0.1:9080/apisix/admin/upstreams/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

10
docs/zh/latest/discovery.md
View File

@ -133,7 +133,7 @@ APISIX 是通过 `upstream.nodes` 来配置上游服务的，所以使用注册
1. 首先要选择状态为 “UP” 的实例： overriddenStatus 值不为 "UNKNOWN" 以 overriddenStatus 为准，否则以 status 的值为准；
2. IP 地址：以 ipAddr 的值为 IP; 并且必须是 IPv4 或 IPv6 格式的；
3. 端口：端口取值规则是，如果 port["@enabled"] 等于 "true" 那么使用 port["\$"] 的值；如果 securePort["@enabled"] 等于 "true" 那么使用 securePort["$"] 的值；
4. 权重：权重取值顺序是，先判断 `metadata.weight` 是否有值，如果没有，则取配置中的 `eureka.weight` 的值, 如果还没有，则取默认值`100`；
4. 权重：权重取值顺序是，先判断 `metadata.weight` 是否有值，如果没有，则取配置中的 `eureka.weight` 的值，如果还没有，则取默认值`100`；
这个例子转成 APISIX nodes 的结果如下：
@ -176,12 +176,12 @@ discovery:
- "http://${username}:${password}@${eureka_host1}:${eureka_port1}"
- "http://${username}:${password}@${eureka_host2}:${eureka_port2}"
prefix: "/eureka/"
fetch_interval: 30 # 从 eureka 中拉取数据的时间间隔，默认30秒
fetch_interval: 30 # 从 eureka 中拉取数据的时间间隔，默认 30 秒
weight: 100 # default weight for node
timeout:
connect: 2000 # 连接 eureka 的超时时间，默认2000ms
send: 2000 # 向 eureka 发送数据的超时时间，默认2000ms
read: 5000 # 从 eureka 读数据的超时时间，默认5000ms
connect: 2000 # 连接 eureka 的超时时间，默认 2000ms
send: 2000 # 向 eureka 发送数据的超时时间，默认 2000ms
read: 5000 # 从 eureka 读数据的超时时间，默认 5000ms
```
通过 `discovery.eureka.host` 配置 eureka 的服务器地址。

42
docs/zh/latest/discovery/kubernetes.md
View File

@ -23,13 +23,13 @@ title: Kubernetes
## 基于 Kubernetes 的服务发现
Kubernetes 服务发现模块以 [_List-Watch_](https://kubernetes.io/docs/reference/using-api/api-concepts) 方式监听 [_Kubernetes_](https://kubernetes.io) 集群 [_Endpoints_](https://kubernetes.io/docs/concepts/services-networking/service) 资源的实时变化,
Kubernetes 服务发现模块以 [_List-Watch_](https://kubernetes.io/docs/reference/using-api/api-concepts) 方式监听 [_Kubernetes_](https://kubernetes.io) 集群 [_Endpoints_](https://kubernetes.io/docs/concepts/services-networking/service) 资源的实时变化，
并将其值存储到 ngx.shared.kubernetes 中 \
模块同时遵循 [_APISIX Discovery 规范_](https://github.com/apache/apisix/blob/master/docs/zh/latest/discovery.md) 提供了节点查询接口
## Kubernetes 服务发现模块的配置
Kubernetes 服务发现模块的完整配置如下:
Kubernetes 服务发现模块的完整配置如下：
```yaml
discovery:
@ -77,14 +77,14 @@ discovery:
first="a",second="b"
```
如果 Kubernetes 服务发现模块运行在 Pod 内, 你可以使用最简配置:
如果 Kubernetes 服务发现模块运行在 Pod 内，你可以使用最简配置：
```yaml
discovery:
kubernetes: { }
```
如果 Kubernetes 服务发现模块运行在 Pod 外, 你需要新建或选取指定的 [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/), 获取其 Token 值, 然后使用如下配置:
如果 Kubernetes 服务发现模块运行在 Pod 外，你需要新建或选取指定的 [_ServiceAccount_](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/), 获取其 Token 值，然后使用如下配置：
```yaml
discovery:
@ -102,20 +102,20 @@ discovery:
Kubernetes 服务发现模块遵循 [_APISIX Discovery 规范_](https://github.com/apache/apisix/blob/master/docs/zh/latest/discovery.md) 提供查询接口
**函数:**
nodes(service_name)
**函数：**
nodes(service_name)
**说明:**
service_name 必须满足格式: [namespace]/[name]:[portName]
**说明：**
service_name 必须满足格式: [namespace]/[name]:[portName]
+ namespace: Endpoints 所在的命名空间
+ namespace: Endpoints 所在的命名空间
+ name: Endpoints 的资源名
+ name: Endpoints 的资源名
+ portName: Endpoints 定义包含的 portName, 如果 Endpoints 没有定义 portName, 请使用 targetPort,Port 代替
+ portName: Endpoints 定义包含的 portName，如果 Endpoints 没有定义 portName，请使用 targetPort,Port 代替
**返回值:**
以如下 Endpoints 为例:
**返回值：**
以如下 Endpoints 为例：
```yaml
apiVersion: v1
@ -131,7 +131,7 @@ Kubernetes 服务发现模块遵循 [_APISIX Discovery 规范_](https://github.c
- port: 3306
```
nodes("default/plat-dev:3306") 调用会得到如下的返回值:
nodes("default/plat-dev:3306") 调用会得到如下的返回值：
```
{
@ -151,20 +151,20 @@ Kubernetes 服务发现模块遵循 [_APISIX Discovery 规范_](https://github.c
## Q&A
> Q: 为什么只支持配置 token 来访问 Kubernetes APIServer \
> A: 一般情况下,我们有三种方式可以完成与 Kubernetes APIServer 的认证:
> A: 一般情况下，我们有三种方式可以完成与 Kubernetes APIServer 的认证：
>
>+ mTLS
>+ token
>+ basic authentication
>
> 因为 lua-resty-http 目前不支持 mTLS, basic authentication 不被推荐使用,\
> 因为 lua-resty-http 目前不支持 mTLS, basic authentication 不被推荐使用，\
> 所以当前只实现了 token 认证方式
---
> Q: APISIX 继承了 Nginx 的多进程模型, 是否意味着每个 APISIX 工作进程都会监听 Kubernetes Endpoints \
> A: Kubernetes 服务发现模块只使用特权进程监听 Kubernetes Endpoints, 然后将其值存储\
> 到 ngx.shared.kubernetes, 工作进程通过查询 ngx.shared.kubernetes 来获取结果
> Q: APISIX 继承了 Nginx 的多进程模型，是否意味着每个 APISIX 工作进程都会监听 Kubernetes Endpoints \
> A: Kubernetes 服务发现模块只使用特权进程监听 Kubernetes Endpoints，然后将其值存储\
> 到 ngx.shared.kubernetes，工作进程通过查询 ngx.shared.kubernetes 来获取结果
---
@ -172,14 +172,14 @@ Kubernetes 服务发现模块遵循 [_APISIX Discovery 规范_](https://github.c
> A: 假定你指定的 ServiceAccount 资源名为 “kubernetes-discovery“, 命名空间为 “apisix”, 请按如下步骤获取其 Token 值
>
> 1. 获取 _Secret_ 资源名: \
> 执行以下命令, 输出的第一列内容就是目标 _Secret_ 资源名
> 执行以下命令，输出的第一列内容就是目标 _Secret_ 资源名
>
> ```shell
> kubectl -n apisix get secrets | grep kubernetes-discovery
> ```
>
> 2. 获取 Token 值: \
> 假定你获取到的 _Secret_ 资源名为 "kubernetes-discovery-token-c64cv", 执行以下命令, 输出内容就是目标 Token 值
> 假定你获取到的 _Secret_ 资源名为 "kubernetes-discovery-token-c64cv", 执行以下命令，输出内容就是目标 Token 值
>
> ```shell
> kubectl -n apisix get secret kubernetes-discovery-token-c64cv -o jsonpath={.data.token} | base64 -d

8
docs/zh/latest/grpc-proxy.md
View File

@ -32,11 +32,11 @@ title: gRPC 代理
### 创建代理 gRPC 的 Route
在指定 Route 中，代理 gRPC 服务接口:
在指定 Route 中，代理 gRPC 服务接口：
* 注意：这个 Route 对应的 Upstream 的 `scheme` 必须设置为 `grpc` 或者 `grpcs`。
* 注意： APISIX 使用 TLS 加密的 HTTP/2 暴露 gRPC 服务, 所以需要先 [配置 SSL 证书](certificate.md)；
* 注意： APISIX 也支持通过纯文本的 HTTP/2 暴露 gRPC 服务，这不需要依赖 SSL，通常用于内网环境代理gRPC服务
* 注意： APISIX 使用 TLS 加密的 HTTP/2 暴露 gRPC 服务，所以需要先 [配置 SSL 证书](certificate.md)；
* 注意： APISIX 也支持通过纯文本的 HTTP/2 暴露 gRPC 服务，这不需要依赖 SSL，通常用于内网环境代理 gRPC 服务
* 下面例子所代理的 gRPC 服务可供参考：[grpc_server_example](https://github.com/api7/grpc_server_example)。
```shell
@ -72,7 +72,7 @@ grpcurl -insecure -import-path /pathtoprotos -proto helloworld.proto \
### 测试纯文本的 HTTP/2
默认情况下，APISIX只在 `9443` 端口支持 TLS 加密的 HTTP/2。你也可以支持纯本文的 HTTP/2，只需要修改 `conf/config.yaml` 文件中的 `node_listen` 配置即可。
默认情况下，APISIX 只在 `9443` 端口支持 TLS 加密的 HTTP/2。你也可以支持纯本文的 HTTP/2，只需要修改 `conf/config.yaml` 文件中的 `node_listen` 配置即可。
```yaml
apisix:

34
docs/zh/latest/health-check.md
View File

@ -25,7 +25,7 @@ title: 健康检查
Apache APISIX 的健康检查使用 [lua-resty-healthcheck](https://github.com/Kong/lua-resty-healthcheck) 实现。
注意:
注意：
* 只有在 `upstream` 被请求时才会开始健康检查，如果 `upstream` 被配置但没有被请求，不会触发启动健康检查。
* 如果没有健康的节点，那么请求会继续发送给上游。
@ -42,22 +42,22 @@ Apache APISIX 的健康检查使用 [lua-resty-healthcheck](https://github.com/K
| upstream.checks.active.http_path | 主动检查 | string | | / | 主动检查的 HTTP 请求路径。 |
| upstream.checks.active.host | 主动检查 | string | | ${upstream.node.host} | 主动检查的 HTTP 请求主机名。 |
| upstream.checks.active.port | 主动检查 | integer | `1` 至 `65535` | ${upstream.node.port} | 主动检查的 HTTP 请求主机端口。 |
| upstream.checks.active.https_verify_certificate | 主动检查 | boolean | | true | 主动检查使用 HTTPS 类型检查时，是否检查远程主机的SSL证书。 |
| upstream.checks.active.req_headers | 主动检查 | array | | [] | 主动检查使用 HTTP 或 HTTPS类型检查时，设置额外的请求头信息。 |
| upstream.checks.active.healthy.interval | 主动检查（健康节点） | integer | `>= 1` | 1 | 主动检查（健康节点）检查的间隔时间（单位：秒） |
| upstream.checks.active.healthy.http_statuses | 主动检查（健康节点） | array | `200` 至 `599` | [200, 302] | 主动检查（健康节点） HTTP 或 HTTPS 类型检查时，健康节点的HTTP状态码。 |
| upstream.checks.active.healthy.successes | 主动检查（健康节点） | integer | `1` 至 `254` | 2 | 主动检查（健康节点）确定节点健康的次数。 |
| upstream.checks.active.unhealthy.interval | 主动检查（非健康节点） | integer | `>= 1` | 1 | 主动检查（非健康节点）检查的间隔时间（单位：秒） |
| upstream.checks.active.unhealthy.http_statuses | 主动检查（非健康节点） | array | `200` 至 `599` | [429, 404, 500, 501, 502, 503, 504, 505] | 主动检查（非健康节点） HTTP 或 HTTPS 类型检查时，非健康节点的HTTP状态码。 |
| upstream.checks.active.unhealthy.http_failures | 主动检查（非健康节点） | integer | `1` 至 `254` | 5 | 主动检查（非健康节点）HTTP 或 HTTPS 类型检查时，确定节点非健康的次数。 |
| upstream.checks.active.unhealthy.tcp_failures | 主动检查（非健康节点） | integer | `1` 至 `254` | 2 | 主动检查（非健康节点）TCP 类型检查时，确定节点非健康的次数。 |
| upstream.checks.active.unhealthy.timeouts | 主动检查（非健康节点） | integer | `1` 至 `254` | 3 | 主动检查（非健康节点）确定节点非健康的超时次数。 |
| upstream.checks.passive.healthy.http_statuses | 被动检查（健康节点） | array | `200` 至 `599` | [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308] | 被动检查（健康节点） HTTP 或 HTTPS 类型检查时，健康节点的HTTP状态码。 |
| upstream.checks.passive.healthy.successes | 被动检查（健康节点） | integer | `0` 至 `254` | 5 | 被动检查（健康节点）确定节点健康的次数。 |
| upstream.checks.passive.unhealthy.http_statuses | 被动检查（非健康节点） | array | `200` 至 `599` | [429, 500, 503] | 被动检查（非健康节点） HTTP 或 HTTPS 类型检查时，非健康节点的HTTP状态码。 |
| upstream.checks.passive.unhealthy.tcp_failures | 被动检查（非健康节点） | integer | `0` 至 `254` | 2 | 被动检查（非健康节点）TCP 类型检查时，确定节点非健康的次数。 |
| upstream.checks.passive.unhealthy.timeouts | 被动检查（非健康节点） | integer | `0` 至 `254` | 7 | 被动检查（非健康节点）确定节点非健康的超时次数。 |
| upstream.checks.passive.unhealthy.http_failures | 被动检查（非健康节点） | integer | `0` 至 `254` | 5 | 被动检查（非健康节点）HTTP 或 HTTPS 类型检查时，确定节点非健康的次数。 |
| upstream.checks.active.https_verify_certificate | 主动检查 | boolean | | true | 主动检查使用 HTTPS 类型检查时，是否检查远程主机的 SSL 证书。 |
| upstream.checks.active.req_headers | 主动检查 | array | | [] | 主动检查使用 HTTP 或 HTTPS 类型检查时，设置额外的请求头信息。 |
| upstream.checks.active.healthy.interval | 主动检查（健康节点）| integer | `>= 1` | 1 | 主动检查（健康节点）检查的间隔时间（单位：秒）|
| upstream.checks.active.healthy.http_statuses | 主动检查（健康节点）| array | `200` 至 `599` | [200, 302] | 主动检查（健康节点）HTTP 或 HTTPS 类型检查时，健康节点的 HTTP 状态码。 |
| upstream.checks.active.healthy.successes | 主动检查（健康节点）| integer | `1` 至 `254` | 2 | 主动检查（健康节点）确定节点健康的次数。 |
| upstream.checks.active.unhealthy.interval | 主动检查（非健康节点）| integer | `>= 1` | 1 | 主动检查（非健康节点）检查的间隔时间（单位：秒）|
| upstream.checks.active.unhealthy.http_statuses | 主动检查（非健康节点）| array | `200` 至 `599` | [429, 404, 500, 501, 502, 503, 504, 505] | 主动检查（非健康节点）HTTP 或 HTTPS 类型检查时，非健康节点的 HTTP 状态码。 |
| upstream.checks.active.unhealthy.http_failures | 主动检查（非健康节点）| integer | `1` 至 `254` | 5 | 主动检查（非健康节点）HTTP 或 HTTPS 类型检查时，确定节点非健康的次数。 |
| upstream.checks.active.unhealthy.tcp_failures | 主动检查（非健康节点）| integer | `1` 至 `254` | 2 | 主动检查（非健康节点）TCP 类型检查时，确定节点非健康的次数。 |
| upstream.checks.active.unhealthy.timeouts | 主动检查（非健康节点）| integer | `1` 至 `254` | 3 | 主动检查（非健康节点）确定节点非健康的超时次数。 |
| upstream.checks.passive.healthy.http_statuses | 被动检查（健康节点）| array | `200` 至 `599` | [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308] | 被动检查（健康节点）HTTP 或 HTTPS 类型检查时，健康节点的 HTTP 状态码。 |
| upstream.checks.passive.healthy.successes | 被动检查（健康节点）| integer | `0` 至 `254` | 5 | 被动检查（健康节点）确定节点健康的次数。 |
| upstream.checks.passive.unhealthy.http_statuses | 被动检查（非健康节点）| array | `200` 至 `599` | [429, 500, 503] | 被动检查（非健康节点）HTTP 或 HTTPS 类型检查时，非健康节点的 HTTP 状态码。 |
| upstream.checks.passive.unhealthy.tcp_failures | 被动检查（非健康节点）| integer | `0` 至 `254` | 2 | 被动检查（非健康节点）TCP 类型检查时，确定节点非健康的次数。 |
| upstream.checks.passive.unhealthy.timeouts | 被动检查（非健康节点）| integer | `0` 至 `254` | 7 | 被动检查（非健康节点）确定节点非健康的超时次数。 |
| upstream.checks.passive.unhealthy.http_failures | 被动检查（非健康节点）| integer | `0` 至 `254` | 5 | 被动检查（非健康节点）HTTP 或 HTTPS 类型检查时，确定节点非健康的次数。 |
### 配置示例：

40
docs/zh/latest/how-to-build.md
View File

@ -21,7 +21,7 @@ title: 如何构建 Apache APISIX
#
-->
## 步骤1：安装 Apache APISIX
## 步骤 1 安装 Apache APISIX
你可以通过 RPM 仓库、Docker、Helm Chart、源码包、源码包（LTS 版本）等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
@ -53,7 +53,7 @@ sudo yum --showduplicates list apisix
# 安装最新的 apisix 软件包
sudo yum install apisix
# 安装指定版本（本例中为2.10.3版本）的 apisix 软件包
# 安装指定版本（本例中为 2.10.3 版本）的 apisix 软件包
sudo yum install apisix-2.10.3-0.el7
```
@ -106,7 +106,7 @@ sudo yum install ./apisix/*.rpm
wget https://downloads.apache.org/apisix/${APISIX_VERSION}/apache-apisix-${APISIX_VERSION}-src.tgz
```
您也可以通过 Apache APISIX 官网下载 Apache APISIX Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考 [Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
您也可以通过 Apache APISIX 官网下载 Apache APISIX Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考 [Apache APISIX 官网 - 下载页](https://apisix.apache.org/zh/downloads)。
4. 解压 Apache APISIX Release 源码包：
@ -123,16 +123,16 @@ sudo yum install ./apisix/*.rpm
LUAROCKS_SERVER=https://luarocks.cn make deps
```
**注意**：使用 `make deps` 安装 `lualdap`、`PCRE`、`openssl` 等依赖包失败，错误信息如： `Could not find header file for LDAP/PCRE/openssl`，可使用本方法解决。
**注意**：使用 `make deps` 安装 `lualdap`、`PCRE`、`openssl` 等依赖包失败，错误信息如： `Could not find header file for LDAP/PCRE/openssl`，可使用本方法解决。
解决思路：`luarocks` 支持自定义编译时依赖目录（来自此[链接](https://github.com/luarocks/luarocks/wiki/Config-file-format))，使用第三方工具安装缺失的依赖，并将其文件路径添加到 `luarocks` 的变量表中。这是一种通用的解决方法，适用于在各种常见操作系统（包括但不仅限于 Ubuntu、Centos、macOS）遇到的“缺失头文件式安装依赖包失败”问题。
解决思路：`luarocks` 支持自定义编译时依赖目录（来自此[链接](https://github.com/luarocks/luarocks/wiki/Config-file-format))，使用第三方工具安装缺失的依赖，并将其文件路径添加到 `luarocks` 的变量表中。这是一种通用的解决方法，适用于在各种常见操作系统（包括但不仅限于 Ubuntu、Centos、macOS）遇到的“缺失头文件式安装依赖包失败”问题。
这边暂给出 macOS 上的具体解决步骤，其他操作系统的解决方案类似：
这边暂给出 macOS 上的具体解决步骤，其他操作系统的解决方案类似：
1. 使用 `brew install openldap` 命令将 `openldap` 安装到本地；
2. 使用 `brew --prefix openldap` 命令找到本地安装目录；
3. 将路径添加到项目配置文件中（选择两种方法中的一种即可）：
1. 方法一：通过 `luarocks config` 手动设置 `LDAP_DIR` 变量, 比如 `luarocks config variables.LDAP_DIR /opt/homebrew/cellar/openldap/2.6.1`；
1. 方法一：通过 `luarocks config` 手动设置 `LDAP_DIR` 变量，比如 `luarocks config variables.LDAP_DIR /opt/homebrew/cellar/openldap/2.6.1`；
2. 方法二：当然你也可以选择直接更改 luarocks 的默认配置文件，执行 `cat ~/.luarocks/config-5.1.lua` 命令，然后在文件中添加 `openldap` 的安装目录；
3. 参考配置文件示例如下：
variables = {
@ -150,13 +150,13 @@ sudo yum install ./apisix/*.rpm
make undeps
```
请注意，该操作将完整**删除**相关文件。
请注意，该操作将完整**删除**相关文件。
#### 通过源码包安装 LTS 版本
目前 Apache APISIX 的 LTS 版本为 `2.10.4`，将“[通过源码包安装](#通过源码包安装)”中的 `APISIX_VERSION` 设置成 `2.10.4` ，其他步骤按顺序进行即可。
## 步骤2：安装 etcd
## 步骤 2 安装 etcd
如果你只通过 RPM、Docker 或源代码安装了 Apache APISIX，而没有安装 etcd，则需要这一步。
@ -179,7 +179,7 @@ brew install etcd
brew services start etcd
```
## 步骤3：管理 Apache APISIX 服务
## 步骤 3 管理 Apache APISIX 服务
我们可以在 Apache APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `apisix help` 命令查看所有命令和对应的功能。
@ -237,7 +237,7 @@ apisix stop
apisix help
```
## 步骤4：运行测试案例
## 步骤 4 运行测试案例
1. 安装 `perl` 的包管理器 `cpanminus`。
@ -257,9 +257,9 @@ apisix help
4. 有两种方法运行测试：
- 追加当前目录到perl模块目录： `export PERL5LIB=.:$PERL5LIB`，然后运行 `make test` 命令。
- 追加当前目录到 perl 模块目录： `export PERL5LIB=.:$PERL5LIB`，然后运行 `make test` 命令。
- 或指定 NGINX 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`。
- 或指定 NGINX 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`。
<!--
#
@ -271,9 +271,9 @@ apisix help
#
-->
:::note 说明
部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
:::
:::note 说明
部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
:::
### 问题排查
@ -299,7 +299,7 @@ prove -Itest-nginx/lib -r t/plugin/openid-connect.t
关于测试用例的更多细节，参见 [测试框架](https://github.com/apache/apisix/blob/master/docs/en/latest/internal/testing-framework.md)
## 步骤5：修改 Admin API key
## 步骤 5 修改 Admin API key
您需要修改 Admin API 的 key，以保护 Apache APISIX。
@ -311,7 +311,7 @@ apisix:
admin_key
-
name: "admin"
key: abcdefghabcdefgh # 将原有的 key 修改为abcdefghabcdefgh
key: abcdefghabcdefgh # 将原有的 key 修改为 abcdefghabcdefgh
role: admin
```
@ -347,13 +347,13 @@ Content-Type: text/html
{"node":{...},"action":"get"}
```
## 步骤6：为 Apache APISIX 构建 OpenResty
## 步骤 6 为 Apache APISIX 构建 OpenResty
有些功能需要引入额外的 NGINX 模块到 OpenResty 当中。
如果您需要这些功能，您可以构建 APISIX OpenResty。
您可以根据 [api7/apisix-build-tools](https://github.com/api7/apisix-build-tools) 里面的代码，配置自己的构建环境，并完成 APISIX OpenResty 的构建。
## 步骤7：为 Apache APISIX 添加 systemd 配置文件
## 步骤 7 为 Apache APISIX 添加 systemd 配置文件
如果您使用的操作系统是 CentOS 7，且在步骤 2 中通过 RPM 包安装 Apache APISIX，配置文件已经自动安装到位，你可以直接运行以下命令：

4
docs/zh/latest/mtls.md
View File

@ -66,7 +66,7 @@ curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /
### 如何配置
你需要构建 [APISIX-OpenResty](./how-to-build.md#步骤6：为-apache-apisix-构建-openresty)，并且需要在配置文件中设定 `etcd.tls` 来使 ETCD 的双向认证功能正常工作。
你需要构建 [APISIX-OpenResty](./how-to-build.md#步骤-6-为-apache-apisix-构建-openresty)，并且需要在配置文件中设定 `etcd.tls` 来使 ETCD 的双向认证功能正常工作。
```yaml
etcd:
@ -154,7 +154,7 @@ curl --resolve 'mtls.test.com:<APISIX_HTTPS_PORT>:<APISIX_URL>' "https://<APISIX
在配置 upstream 资源时，可以使用参数 `tls.client_cert` 和 `tls.client_key` 来配置 APISIX 用于与上游进行通讯时使用的证书。可参考 [Upstream API 文档](./admin-api.md#upstream)。
该功能需要 APISIX 运行在 [APISIX-OpenResty](./how-to-build.md#步骤6：为-apache-apisix-构建-openresty) 上。
该功能需要 APISIX 运行在 [APISIX-OpenResty](./how-to-build.md#步骤-6-为-apache-apisix-构建-openresty) 上。
下面是一个与配置 SSL 时相似的 Python 脚本，可为一个已存在的 upstream 资源配置双向认证。如果需要，可修改 API 地址和 API Key。

12
docs/zh/latest/plugin-develop.md
View File

@ -42,7 +42,7 @@ Apache APISIX 提供了两种方式来添加新的功能。
│   └── 3rd-party.lua
```
接着，在 `conf/config.yaml` 文件中添加如下的配置:
接着，在 `conf/config.yaml` 文件中添加如下的配置：
```yaml
apisix:
@ -50,11 +50,11 @@ apisix:
extra_lua_path: "/path/to/example/?.lua"
```
现在使用 `require "apisix.plugins.3rd-party"` 会加载你自己的插件， 比如 `require "apisix.plugins.jwt-auth"`会加载 `jwt-auth` 插件.
现在使用 `require "apisix.plugins.3rd-party"` 会加载你自己的插件， 比如 `require "apisix.plugins.jwt-auth"`会加载 `jwt-auth` 插件。
可能你会想覆盖一个文件中的函数，你可以在 `conf/config.yaml` 文件中配置 `lua_module_hook` 来使你的 hook 生效。
你的配置可以像下面这样:
你的配置可以像下面这样：
```yaml
apisix:
@ -101,7 +101,7 @@ local _M = {
}
```
注：新插件的优先级（ priority 属性 ）不能与现有插件的优先级相同，您可以使用 [control API](./control-api.md#get-v1schema) 的 `/v1/schema` 方法查看所有插件的优先级。另外，同一个阶段里面，优先级( priority )值大的插件，会优先执行，比如 `example-plugin` 的优先级是 0 ，`ip-restriction` 的优先级是 3000 ，所以在每个阶段，会先执行 `ip-restriction` 插件，再去执行 `example-plugin` 插件。这里的“阶段”的定义，参见后续的 [确定执行阶段](#确定执行阶段) 这一节。对于你的插件，建议采用 1 到 99 之间的优先级。
注：新插件的优先级（ priority 属性 ）不能与现有插件的优先级相同，您可以使用 [control API](./control-api.md#get-v1schema) 的 `/v1/schema` 方法查看所有插件的优先级。另外，同一个阶段里面，优先级 ( priority ) 值大的插件，会优先执行，比如 `example-plugin` 的优先级是 0 ，`ip-restriction` 的优先级是 3000 ，所以在每个阶段，会先执行 `ip-restriction` 插件，再去执行 `example-plugin` 插件。这里的“阶段”的定义，参见后续的 [确定执行阶段](#确定执行阶段) 这一节。对于你的插件，建议采用 1 到 99 之间的优先级。
在 __conf/config-default.yaml__ 配置文件中，列出了启用的插件（都是以插件名指定的）：
@ -350,7 +350,7 @@ end
## 注册公共接口
插件可以注册暴露给公网的接口。以 jwt-auth 插件为例，这个插件为了让客户端能够签名，注册了 `GET /apisix/plugin/jwt/sign` 这个接口:
插件可以注册暴露给公网的接口。以 jwt-auth 插件为例，这个插件为了让客户端能够签名，注册了 `GET /apisix/plugin/jwt/sign` 这个接口：
```lua
local function gen_token()
@ -408,7 +408,7 @@ curl -i -X GET "http://127.0.0.1:9090/v1/plugin/example-plugin/hello"
## 注册自定义变量
我们可以在APISIX的许多地方使用变量。例如，在 http-logger 中自定义日志格式，用它作为 `limit-*` 插件的键。在某些情况下，内置的变量是不够的。因此，APISIX允许开发者在全局范围内注册他们的变量，并将它们作为普通的内置变量使用。
我们可以在 APISIX 的许多地方使用变量。例如，在 http-logger 中自定义日志格式，用它作为 `limit-*` 插件的键。在某些情况下，内置的变量是不够的。因此，APISIX 允许开发者在全局范围内注册他们的变量，并将它们作为普通的内置变量使用。
例如，让我们注册一个叫做 `a6_labels_zone` 的变量来获取路由中 `zone` 标签的值。

6
docs/zh/latest/plugins/api-breaker.md
View File

@ -29,15 +29,15 @@ title: api-breaker
由代码逻辑自动按**触发不健康状态**的次数递增运算：
每当上游服务返回 `unhealthy.http_statuses` 配置中的状态码(比如：500)，达到 `unhealthy.failures` 次时(比如：3 次)，认为上游服务处于不健康状态。
每当上游服务返回 `unhealthy.http_statuses` 配置中的状态码（比如：500），达到 `unhealthy.failures` 次时 (比如：3 次)，认为上游服务处于不健康状态。
第一次触发不健康状态，**熔断 2 秒**。
然后，2 秒过后重新开始转发请求到上游服务，如果继续返回 `unhealthy.http_statuses` 状态码，记数再次达到 `unhealthy.failures` 次时，**熔断 4 秒**（倍数方式）。
依次类推，2, 4, 8, 16, 32, 64, ..., 256, 最大到 300。 300 是 `max_breaker_sec` 的最大值，允许自定义修改。
依次类推，2, 4, 8, 16, 32, 64, ..., 256，最大到 300。 300 是 `max_breaker_sec` 的最大值，允许自定义修改。
在不健康状态时，当转发请求到上游服务并返回 `healthy.http_statuses` 配置中的状态码(比如：200)，达到 `healthy.successes` 次时(比如：3 次)，认为上游服务恢复健康状态。
在不健康状态时，当转发请求到上游服务并返回 `healthy.http_statuses` 配置中的状态码（比如：200），达到 `healthy.successes` 次时 (比如：3 次)，认为上游服务恢复健康状态。
## 属性

8
docs/zh/latest/plugins/authz-casbin.md
View File

@ -25,7 +25,7 @@ title: authz-casbin
`authz-casbin` 是一个基于 [Lua Casbin](https://github.com/casbin/lua-casbin/) 的访问控制插件，该插件支持基于各种访问控制模型的授权场景。
有关如何创建鉴权模型和鉴权策略的详细文档, 请参阅 [Casbin](https://casbin.org/docs/en/supported-models)。
有关如何创建鉴权模型和鉴权策略的详细文档，请参阅 [Casbin](https://casbin.org/docs/en/supported-models)。
## 属性
@ -167,7 +167,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
## 测试插件
首先定义测试鉴权模型:
首先定义测试鉴权模型：
```conf
[request_definition]
@ -186,7 +186,7 @@ e = some(where (p.eft == allow))
m = (g(r.sub, p.sub) || keyMatch(r.sub, p.sub)) && keyMatch(r.obj, p.obj) && keyMatch(r.act, p.act)
```
然后添加测试鉴权策略:
然后添加测试鉴权策略：
```conf
p, *, /, GET
@ -202,7 +202,7 @@ g, alice, admin
curl -i http://127.0.0.1:9080/ -X GET
```
未经授权的用户如 `bob` 访问除 `/` 以外的任何其他页面将得到一个 403 错误:
未经授权的用户如 `bob` 访问除 `/` 以外的任何其他页面将得到一个 403 错误：
```shell
curl -i http://127.0.0.1:9080/res -H 'user: bob' -X GET

17
docs/zh/latest/plugins/authz-keycloak.md
View File

@ -28,20 +28,19 @@ title: authz-keycloak
## 属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ----------------------- | ------------- | ------ | ----------- | --------------------------- | ----------------------------------------------------------------------------------------------- |
| ----------------------- | ------------- | ------ | ----------- | --------------------------- |----------------------|
| token_endpoint | string | 必须 | | | 接受 OAuth2 兼容 token 的接口，需要支持 `urn:ietf:params:oauth:grant-type:uma-ticket` 授权类型 |
| grant_type | string | 可选 | "urn:ietf:params:oauth:grant-type:uma-ticket" | ["urn:ietf:params:oauth:grant-type:uma-ticket"] | |
| audience | string | 可选 | | | 客户端应用访问相应的资源服务器时所需提供的身份信息。当 permissions 参数有值时这个参数是必填的。 |
| permissions | array[string] | 可选 | | | 描述客户端应用所需访问的资源和权限范围的字符串。格式必须为：`RESOURCE_ID#SCOPE_ID` |
| timeout | integer | 可选 | 3000 | [1000, ...] | 与身份认证服务器的 http 连接的超时时间 |
| access_token_expires_in | integer | 可选 | 300 | [1, ...] | access token 的过期时间(秒)
| access_token_expires_leeway | integer | 可选 | 0 | [0, ...] | access token 提前更新时间（秒，如果设置了此值，允许在该时间段内使用相同的 access token 令牌来解决潜在的网络并发问题） |
| refresh_token_expires_in | integer | 可选 | 3600 | [1, ...] | refresh token 的过期时间(秒) |
| refresh_token_expires_leeway| integer | 可选 | 0 | [0, ...] | refresh token 提前更新时间（秒，如果设置了此值，允许在该时间段内使用相同的 refresh token 令牌来解决潜在的网络并发问题） |
| access_token_expires_in | integer | 可选 | 300 | [1, ...] | access token 的过期时间（秒）|
| access_token_expires_leeway | integer | 可选 | 0 | [0, ...] | access token 提前更新时间（秒，如果设置了此值，允许在该时间段内使用相同的 access token 令牌来解决潜在的网络并发问题）|
| refresh_token_expires_in | integer | 可选 | 3600 | [1, ...] | refresh token 的过期时间（秒）|
| refresh_token_expires_leeway| integer | 可选 | 0 | [0, ...] | refresh token 提前更新时间（秒，如果设置了此值，允许在该时间段内使用相同的 refresh token 令牌来解决潜在的网络并发问题）|
| ssl_verify | boolean | 可选 | true | [0, ...] | 验证 SSL 证书与主机名是否匹配 |
| policy_enforcement_mode | string | 可选 | "ENFORCING" | ["ENFORCING", "PERMISSIVE"] | |
| access_denied_redirect_uri | string | 可选 | | [1, 2048] |未授权的用户不会返回 `"error_description":"not_authorized"`，而是会定重定向至给定的 uri，如 "http://127.0.0.1/test"
|
| access_denied_redirect_uri | string | 可选 | | [1, 2048] | 未授权的用户不会返回 `"error_description":"not_authorized"`，而是会定重定向至给定的 uri，如 "http://127.0.0.1/test"|
### 策略执行模式
@ -49,7 +48,7 @@ title: authz-keycloak
**Enforcing**
- （默认）如果资源没有绑定任何访问策略，请求默认会被拒绝。
- 默认模式，如果资源没有绑定任何访问策略，请求默认会被拒绝。
**Permissive**
@ -57,7 +56,7 @@ title: authz-keycloak
## 如何启用
创建一个 `route` 对象，并在该 `route` 对象上启用 `authz-keycloak` 插件, `${realm}` 是 `Keycloak` 中的 `realm` 名称：
创建一个 `route` 对象，并在该 `route` 对象上启用 `authz-keycloak` 插件，`${realm}` 是 `Keycloak` 中的 `realm` 名称：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

4
docs/zh/latest/plugins/batch-requests.md
View File

@ -69,7 +69,7 @@ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/batch-requests -H 'X-API
插件会为 `apisix` 创建一个 `/apisix/batch-requests` 的接口来处理你的批量请求。
### 接口请求参数:
### 接口请求参数：
| 参数名 | 类型 | 可选项 | 默认值 | 有效值 | 描述 |
| -------- | --------------------------- | ------ | ------ | ------ | -------------------------------- |
@ -133,7 +133,7 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/br -H 'X-API-KEY: edd1c9f034335
}'
```
之后，你就可以将要访问的请求信息传到网关的批量请求接口( `/apisix/batch-requests` )了，网关会以 [http pipeline](https://en.wikipedia.org/wiki/HTTP_pipelining) 的方式自动帮你完成请求。
之后，你就可以将要访问的请求信息传到网关的批量请求接口（`/apisix/batch-requests`）了，网关会以 [http pipeline](https://en.wikipedia.org/wiki/HTTP_pipelining) 的方式自动帮你完成请求。
```shell
curl --location --request POST 'http://127.0.0.1:9080/apisix/batch-requests' \

12
docs/zh/latest/plugins/clickhouse-logger.md
View File

@ -23,7 +23,7 @@ title: clickhouse-logger
## 描述
`clickhouse-logger` 是一个插件，可将Log数据请求推送到clickhouse服务器。
`clickhouse-logger` 是一个插件，可将 Log 数据请求推送到 clickhouse 服务器。
## 属性
@ -32,8 +32,8 @@ title: clickhouse-logger
| endpoint_addr | string | 必须 | | | `clickhouse` 服务器的 endpoint。 |
| database | string | 必须 | | | 使用的数据库。 |
| logtable | string | 必须 | | | 写入的表名 。 |
| user | string | 必须 | | | clickhouse的用户。 |
| password | string | 必须 | | | clickhouse的密码 。 |
| user | string | 必须 | | | clickhouse 的用户。 |
| password | string | 必须 | | | clickhouse 的密码 。 |
| timeout | integer | 可选 | 3 | [1,...] | 发送请求后保持连接活动的时间。 |
| name | string | 可选 | "clickhouse logger" | | 标识 logger 的唯一标识符。 |
| ssl_verify | boolean | 可选 | true | [true,false] | 验证证书。 |
@ -68,7 +68,7 @@ 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
@ -96,7 +96,7 @@ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/clickhouse-logger -H 'X-
}'
```
创建clickhouse log table
创建 clickhouse log table
```sql
CREATE TABLE default.test (
@ -108,7 +108,7 @@ CREATE TABLE default.test (
) ENGINE = MergeTree()
```
在clickhouse上执行`select * from default.test;`，将得到类似下面的数据：
在 clickhouse 上执行`select * from default.test;`，将得到类似下面的数据：
```
┌─host──────┬─client_ip─┬─route_id─┬─@timestamp────────────────┐

18
docs/zh/latest/plugins/consumer-restriction.md
View File

@ -28,13 +28,13 @@ title: consumer-restriction
## 属性
| 参数名 | 类型 | 可选项 | 默认值 | 有效值 | 描述 |
| --------- | ------------- | ------ | -----------------| --------------------------------| ----------------------------------------------------------|
| type | string | 可选 | consumer_name | ["consumer_name", "service_id", "route_id"] | 根据不同的对象做相应的限制,支持 `consumer_name`、`service_id`、`route_id`。 |
| --------- | ------------- | ------ | -----------------| --------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| type | string | 可选 | consumer_name | ["consumer_name", "service_id", "route_id"] | 根据不同的对象做相应的限制，支持 `consumer_name`、`service_id`、`route_id`。 |
| whitelist | array[string] | 必选 | | | 与`blacklist`二选一，只能单独启用白名单或黑名单，两个不能一起使用。 |
| blacklist | array[string] | 必选 | | | 与`whitelist`二选一，只能单独启用白名单或黑名单，两个不能一起使用。 |
| rejected_code | integer | 可选 | 403 | [200,...] | 当请求被拒绝时，返回的 HTTP 状态码。|
| rejected_msg | String | 可选 | | | 当请求被拒绝时，返回的消息内容。|
| allowed_by_methods | array[object] | 可选 | | | 为用户设置允许的HTTP methods列表 , HTTP methods 可以为 `["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE"]` |
| rejected_code | integer | 可选 | 403 | [200,...] | 当请求被拒绝时，返回的 HTTP 状态码。 |
| rejected_msg | String | 可选 | | | 当请求被拒绝时，返回的消息内容。 |
| allowed_by_methods | array[object] | 可选 | | | 为用户设置允许的 HTTP methods 列表 , HTTP methods 可以为 `["GET"，"POST"，"PUT"，"DELETE"，"PATCH"，"HEAD"，"OPTIONS"，"CONNECT"，"TRACE"]` |
对于 `type` 字段是个枚举类型，它可以是 `consumer_name` 或 `service_id` 。分别代表以下含义：
@ -45,7 +45,7 @@ title: consumer-restriction
### 如何限制 `consumer_name`
下面是一个示例，在指定的 route 上开启了 `consumer-restriction` 插件，限制 consumer 访问:
下面是一个示例，在指定的 route 上开启了 `consumer-restriction` 插件，限制 consumer 访问：
```shell
curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
@ -92,7 +92,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
**测试插件**
jack1 访问:
jack1 访问：
```shell
curl -u jack2019:123456 http://127.0.0.1:9080/index.html -i
@ -100,7 +100,7 @@ HTTP/1.1 200 OK
...
```
jack2 访问:
jack2 访问：
```shell
curl -u jack2020:123456 http://127.0.0.1:9080/index.html -i
@ -207,7 +207,7 @@ curl http://127.0.0.1:9080/apisix/admin/services/2 -H 'X-API-KEY: edd1c9f034335f
}'
```
2、在 `consumer` 上绑定 `consumer-restriction` 插件(需要与一个授权插件配合才能绑定),并添加 `service_id` 白名单列表
2、在 `consumer` 上绑定 `consumer-restriction` 插件 (需要与一个授权插件配合才能绑定),并添加 `service_id` 白名单列表
```shell
curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

4
docs/zh/latest/plugins/cors.md
View File

@ -35,7 +35,7 @@ title: cors
| expose_headers | string | 可选 | "*" | | 允许跨域访问时响应方携带哪些非 `CORS 规范` 以外的 Header， 多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示允许任意 Header 。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许任意 Header，但请注意这样存在安全隐患。 |
| max_age | integer | 可选 | 5 | | 浏览器缓存 CORS 结果的最大时间，单位为秒，在这个时间范围内浏览器会复用上一次的检查结果，`-1` 表示不缓存。请注意各个浏览器允许的最大时间不同，详情请参考 [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age#Directives)。 |
| allow_credential | boolean | 可选 | false | | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。根据 CORS 规范，如果设置该选项为 `true`，那么将不能在其他选项中使用 `*`。 |
| allow_origins_by_regex | array | 可选 | nil | | 使用正则表达式数组来匹配允许跨域访问的 Origin，如[".*\.test.com"] 可以匹配任何test.com的子域名`*`。 |
| allow_origins_by_regex | array | 可选 | nil | | 使用正则表达式数组来匹配允许跨域访问的 Origin，如 [".*\.test.com"] 可以匹配任何 test.com 的子域名`*`。 |
| allow_origins_by_metadata | array | 可选 | nil | | 通过引用插件元数据的 `allow_origins` 配置允许跨域访问的 Origin。比如当元数据为 `"allow_origins": {"EXAMPLE": "https://example.com"}` 时，配置 `["EXAMPLE"]` 将允许 Origin `https://example.com` 的访问 |
> **提示**
@ -71,7 +71,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
## 测试插件
请求下接口，发现接口已经返回了 `CORS` 相关的header，代表插件生效
请求下接口，发现接口已经返回了 `CORS` 相关的 header，代表插件生效
```shell
curl http://127.0.0.1:9080/hello -v

6
docs/zh/latest/plugins/csrf.md
View File

@ -30,9 +30,9 @@ title: csrf
## 属性
| Name | Type | Requirement | Default | Valid | Description |
| ---------------- | ------- | ----------- | ------- | ----- | ------------------------------------------------------------ |
| ---------------- | ------- | ----------- | ------- | ----- |---------------------|
| name | string | optional | `apisix-csrf-token` | | 生成的 Cookie 中的 token 的名字，需要使用这个名字在请求头携带 Cookie 中的内容 |
| expires | number | optional | `7200` | | CSRF Cookie 的过期时间(秒) |
| expires | number | optional | `7200` | | CSRF Cookie 的过期时间（秒）|
| key | string | required | | | 加密 token 的秘钥 |
**注意：当 expires 设置为 0 时插件将忽略检查 Token 是否过期**
@ -100,7 +100,7 @@ const instance = axios.create({
});
```
你还需要确保你的请求携带了Cookie。
你还需要确保你的请求携带了 Cookie。
使用 curl 发送请求：

10
docs/zh/latest/plugins/dubbo-proxy.md
View File

@ -27,7 +27,7 @@ title: dubbo-proxy
## 要求
如果你正在使用 `OpenResty`, 你需要编译它来支持 `dubbo`, 参考 [如何编译](../how-to-build.md#步骤6：为-apache-apisix-构建-openresty)。
如果你正在使用 `OpenResty`, 你需要编译它来支持 `dubbo`, 参考 [如何编译](../how-to-build.md#步骤-6-为-apache-apisix-构建-openresty)。
## 运行时属性
@ -35,7 +35,7 @@ title: dubbo-proxy
| ------------ | ------ | ----------- | -------- | ------------ | -------------------------------------------------------------------- |
| service_name | string | 必选 | | | dubbo 服务名字 |
| service_version | string | 必选 | | | dubbo 服务版本 |
| method | string | 可选 | uri路径 | | dubbo 服务方法 |
| method | string | 可选 | uri 路径 | | dubbo 服务方法 |
## 静态属性
@ -45,7 +45,7 @@ title: dubbo-proxy
## 如何启用
首先，在 `config.yaml` 中启用 `dubbo-proxy` 插件:
首先，在 `config.yaml` 中启用 `dubbo-proxy` 插件：
```
# Add this in config.yaml
@ -56,7 +56,7 @@ plugins:
然后重载 `APISIX`。
这里有个例子，在指定的路由中启用 `dubbo-proxy` 插件:
这里有个例子，在指定的路由中启用 `dubbo-proxy` 插件：
```shell
curl http://127.0.0.1:9080/apisix/admin/upstreams/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -135,7 +135,7 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335
现在 `dubbo-proxy` 插件就已经被禁用了。 此方法同样适用于其他插件。
如果你想彻底禁用 `dubbo-proxy` 插件，
你需要在 `config.yaml` 中注释掉以下内容:
你需要在 `config.yaml` 中注释掉以下内容：
```yaml
plugins:

4
docs/zh/latest/plugins/echo.md
View File

@ -23,7 +23,7 @@ title: echo
## 描述
echo 可以帮助用户尽可能全面地了解如何开发APISIX插件。
echo 可以帮助用户尽可能全面地了解如何开发 APISIX 插件。
该插件展示了如何在常见的 phase 中实现相应的功能，常见的 phase 包括：init, rewrite, access, balancer, header filter, body filter 以及 log。
@ -64,7 +64,7 @@ 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

18
docs/zh/latest/plugins/error-log-logger.md
View File

@ -36,25 +36,25 @@ title: error-log-logger
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| -------------------------------- | ------- | ----- | ------------------------------ | ---------------- | -------------------------------------------------------------------------|
| tcp.host | string | 必须 | | | TCP 服务的IP地址或主机名 |
| tcp.host | string | 必须 | | | TCP 服务的 IP 地址或主机名 |
| tcp.port | integer | 必须 | | [0,...] | 目标端口 |
| tcp.tls | boolean | 可选 | false | | 用于控制是否执行SSL验证 |
| tcp.tls | boolean | 可选 | false | | 用于控制是否执行 SSL 验证 |
| tcp.tls_server_name | string | 可选 | | | TLS 服务名称标记 |
| skywalking.endpoint_addr | string | 可选 | http://127.0.0.1:12900/v3/logs | | Skywalking 的 HTTP endpoint 地址，例如：http://127.0.0.1:12800 |
| skywalking.service_name | string | 可选 | APISIX | | skywalking 上报的 service 名称 |
| skywalking.service_instance_name | String | 可选 | APISIX Instance Name | | skywalking 上报的 service 实例名, 如果期望直接获取本机主机名则设置为 `$hostname` |
| skywalking.service_instance_name | String | 可选 | APISIX Instance Name | | skywalking 上报的 service 实例名，如果期望直接获取本机主机名则设置为 `$hostname` |
| clickhouse.endpoint_addr | String | 可选 | http://127.0.0.1:8213 | | clickhouse 的 HTTP endpoint 地址，例如 http://127.0.0.1:8213 |
| clickhouse.user | String | 可选 | default | | clickhouse 的用户名 |
| clickhouse.password | String | 可选 | | | clickhouse 的密码 |
| clickhouse.database | String | 可选 | | | clickhouse 的用于接收 log 的数据库 |
| clickhouse.logtable | String | 可选 | | | clickhouse 的用于接收 log 的表 |
| host | string | 可选 | | | (`弃用`，替换成`tcp.host`) TCP 服务的IP地址或主机名 |
| host | string | 可选 | | | (`弃用`，替换成`tcp.host`) TCP 服务的 IP 地址或主机名 |
| port | integer | 可选 | | [0,...] | (`弃用`，替换成`tcp.port`) 目标端口 |
| tls | boolean | 可选 | false | | (`弃用`，替换成`tcp.tls`) 用于控制是否执行SSL验证 |
| tls | boolean | 可选 | false | | (`弃用`，替换成`tcp.tls`) 用于控制是否执行 SSL 验证 |
| tls_server_name | string | 可选 | | | (`弃用`，替换成`tcp.tls_server_name`) TLS 服务名称标记 |
| timeout | integer | 可选 | 3 | [1,...] | 连接和发送数据超时间（以秒为单位） |
| keepalive | integer | 可选 | 30 | [1,...] | 复用连接时，连接保持的时间（以秒为单位） |
| level | string | 可选 | WARN | | 进行错误日志筛选的级别，缺省WARN，取值["STDERR", "EMERG", "ALERT", "CRIT", "ERR", "ERROR", "WARN", "NOTICE", "INFO", "DEBUG"]，其中 ERR 与 ERROR 级别一致 |
| timeout | integer | 可选 | 3 | [1,...] | 连接和发送数据超时间（以秒为单位）|
| keepalive | integer | 可选 | 30 | [1,...] | 复用连接时，连接保持的时间（以秒为单位）|
| level | string | 可选 | WARN | | 进行错误日志筛选的级别，缺省 WARN，取值 ["STDERR", "EMERG", "ALERT", "CRIT", "ERR", "ERROR", "WARN", "NOTICE", "INFO", "DEBUG"]，其中 ERR 与 ERROR 级别一致 |
本插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解或自定义批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。
@ -121,7 +121,7 @@ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/error-log-logger -H 'X-A
## 如何设置接收日志的 clickhouse 数据库
插件将 error log 作为一个字符串发送到 clickhouse 表的 `data` 字段。
*TODO 将error log 作为一个字符串保持到clickhouse数据库的data字段，未来我们将会增加更多的字段。*
*TODO 将 error log 作为一个字符串保持到 clickhouse 数据库的 data 字段，未来我们将会增加更多的字段。*
步骤：更新插件属性
```shell

12
docs/zh/latest/plugins/fault-injection.md
View File

@ -59,7 +59,7 @@ title: fault-injection
### 启用插件
示例1：为特定路由启用 `fault-injection` 插件，并指定 `abort` 参数：
示例 1：为特定路由启用 `fault-injection` 插件，并指定 `abort` 参数：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -98,7 +98,7 @@ Fault Injection!
> http status 返回 `200` 并且响应 `body` 为 `Fault Injection!`，表示该插件已启用。
示例2：为特定路由启用 `fault-injection` 插件，并指定 `delay` 参数：
示例 2：为特定路由启用 `fault-injection` 插件，并指定 `delay` 参数：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -139,7 +139,7 @@ user 0m0.007s
sys 0m0.010s
```
示例3：为特定路由启用 `fault-injection` 插件，并指定 abort 参数的 vars 规则。
示例 3：为特定路由启用 `fault-injection` 插件，并指定 abort 参数的 vars 规则。
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -197,7 +197,7 @@ Server: APISIX/2.2
Fault Injection!
```
示例4：为特定路由启用 `fault-injection` 插件，并指定 delay 参数的 vars 规则。
示例 4：为特定路由启用 `fault-injection` 插件，并指定 delay 参数的 vars 规则。
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -262,7 +262,7 @@ user 0m0.004s
sys 0m0.004s
```
示例5：为特定路由启用 `fault-injection` 插件，并指定 abort 和 delay 参数的 vars 规则。
示例 5：为特定路由启用 `fault-injection` 插件，并指定 abort 和 delay 参数的 vars 规则。
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -372,7 +372,7 @@ user 0m0.001s
sys 0m0.005s
```
示例6：为特定路由启用 `fault-injection` 插件，并指定 abort 参数的 vars 规则（`or` 的关系）。
示例 6：为特定路由启用 `fault-injection` 插件，并指定 abort 参数的 vars 规则（`or` 的关系）。
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

2
docs/zh/latest/plugins/file-logger.md
View File

@ -55,7 +55,7 @@ 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

8
docs/zh/latest/plugins/forward-auth.md
View File

@ -33,8 +33,8 @@ Forward Auth 巧妙地将认证和授权逻辑移到了一个专门的外部服
| -- | -- | -- | -- | -- | -- |
| host | string | 必须 | | | 设置 `authorization` 服务的地址 (eg. https://localhost:9188) |
| ssl_verify | boolean | 可选 | true | | 是否验证证书 |
| request_method | string | 可选 | GET | ["GET","POST"] | `client` 请求 `authorization` 服务的方法。当设置为 POST时，会将 request body 转发至`authorization` 服务。 |
| request_headers | array[string] | 可选 | | | 设置需要由 `client` 转发到 `authorization` 服务的请求头。未设置时，只有 Apache APISIX 的(X-Forwarded-XXX)会被转发到 `authorization` 服务。 |
| request_method | string | 可选 | GET | ["GET","POST"] | `client` 请求 `authorization` 服务的方法。当设置为 POST 时，会将 request body 转发至`authorization` 服务。 |
| request_headers | array[string] | 可选 | | | 设置需要由 `client` 转发到 `authorization` 服务的请求头。未设置时，只有 Apache APISIX 的 (X-Forwarded-XXX) 会被转发到 `authorization` 服务。 |
| upstream_headers | array[string] | 可选 | | | 认证通过时，设置 `authorization` 服务转发至 `upstream` 的请求头。如果不设置则不转发任何请求头。
| client_headers | array[string] | 可选 | | | 认证失败时，由 `authorization` 服务向 `client` 发送的响应头。如果不设置则不转发任何响应头。 |
| timeout | integer | 可选 | 3000ms | [1, 60000]ms | `authorization` 服务请求超时时间 |
@ -51,7 +51,7 @@ request_headers 属性中转发到 `authorization` 服务中的 Apache APISIX
## 示例
首先, 你需要设置一个认证服务。这里使用的是 Apache APISIX 无服务器插件模拟的示例。
首先，你需要设置一个认证服务。这里使用的是 Apache APISIX 无服务器插件模拟的示例。
```shell
curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/auth' \
@ -81,7 +81,7 @@ curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/auth' \
}'
```
下一步, 我们创建一个测试路由。
下一步，我们创建一个测试路由。
```shell
curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/1' \

14
docs/zh/latest/plugins/google-cloud-logging.md
View File

@ -36,14 +36,14 @@ title: google-cloud-logging
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| auth_config | 半可选 | | 必须配置 `auth_config` 或 `auth_file` 之一 |
| auth_config.private_key | 必选 | | 谷歌服务帐号的私钥参数 |
| auth_config.project_id | 必选 | | 谷歌服务帐号的项目ID |
| auth_config.token_uri | 可选 | https://oauth2.googleapis.com/token | 请求谷歌服务帐户的令牌的URI |
| auth_config.entries_uri | 可选 | https://logging.googleapis.com/v2/entries:write | 谷歌日志服务写入日志条目的API |
| auth_config.scopes | 可选 | ["https://www.googleapis.com/auth/logging.read","https://www.googleapis.com/auth/logging.write","https://www.googleapis.com/auth/logging.admin","https://www.googleapis.com/auth/cloud-platform"] | 谷歌服务账号的访问范围, 参考: [OAuth 2.0 Scopes for Google APIs](https://developers.google.com/identity/protocols/oauth2/scopes#logging) |
| auth_file | 半可选 | | 谷歌服务账号JSON文件的路径（必须配置 `auth_config` 或 `auth_file` 之一） |
| ssl_verify | 可选 | true | 启用 `SSL` 验证, 配置根据 [OpenResty文档](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake) 选项|
| auth_config.project_id | 必选 | | 谷歌服务帐号的项目 ID |
| auth_config.token_uri | 可选 | https://oauth2.googleapis.com/token | 请求谷歌服务帐户的令牌的 URI |
| auth_config.entries_uri | 可选 | https://logging.googleapis.com/v2/entries:write | 谷歌日志服务写入日志条目的 API |
| auth_config.scopes | 可选 | ["https://www.googleapis.com/auth/logging.read","https://www.googleapis.com/auth/logging.write","https://www.googleapis.com/auth/logging.admin","https://www.googleapis.com/auth/cloud-platform"] | 谷歌服务账号的访问范围，参考：[OAuth 2.0 Scopes for Google APIs](https://developers.google.com/identity/protocols/oauth2/scopes#logging) |
| auth_file | 半可选 | | 谷歌服务账号 JSON 文件的路径（必须配置 `auth_config` 或 `auth_file` 之一）|
| ssl_verify | 可选 | true | 启用 `SSL` 验证，配置根据 [OpenResty 文档](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake) 选项 |
| resource | 可选 | {"type": "global"} | 谷歌监控资源，参考： [MonitoredResource](https://cloud.google.com/logging/docs/reference/v2/rest/v2/MonitoredResource) |
| log_id | 可选 | apisix.apache.org%2Flogs | 谷歌日志ID，参考： [LogEntry](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry) |
| log_id | 可选 | apisix.apache.org%2Flogs | 谷歌日志 ID，参考： [LogEntry](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry) |
本插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解或自定义批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。

12
docs/zh/latest/plugins/grpc-transcode.md
View File

@ -31,7 +31,7 @@ HTTP(s) -> APISIX -> gRPC server
* `content`: `.proto` 或 `.pb` 文件的内容
### 添加proto
### 添加 proto
路径中最后的数字，会被用作 proto 的 id 做唯一标识，比如下面示例的 proto `id` 是 `1` ：
@ -104,7 +104,7 @@ print(resp.status_code)
print(resp.text)
```
创建proto：
创建 proto：
```bash
chmod +x ./upload_pb.pb
@ -127,7 +127,7 @@ chmod +x ./upload_pb.pb
### 使用 grpc-transcode 插件
在指定 route 中，代理 grpc 服务接口:
在指定 route 中，代理 grpc 服务接口：
* 注意： 这个 route 对应的 upstream 的属性 `scheme` 必须设置为 `grpc`
* 代理 grpc 服务例子可参考：[grpc_server_example](https://github.com/api7/grpc_server_example)
@ -175,7 +175,7 @@ Proxy-Connection: keep-alive
## 使用 grpc-transcode 插件的 pb_option 选项
在指定 route 中，代理 grpc 服务接口:
在指定 route 中，代理 grpc 服务接口：
### 选项清单
@ -183,7 +183,7 @@ Proxy-Connection: keep-alive
* enum_as_name
* enum_as_value
* 64位整型
* 64 位整型
* int64_as_number
* int64_as_string
* int64_as_hexstring
@ -194,7 +194,7 @@ Proxy-Connection: keep-alive
* use_default_values
* use_default_metatable
* Hooks开关
* Hooks 开关
* enable_hooks
* disable_hooks

2
docs/zh/latest/plugins/grpc-web.md
View File

@ -59,7 +59,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
## 禁用插件
只需删除插件配置中 `grpc-web` 的JSON配置即可。 APISIX 插件是热加载的，所以不需要重启 APISIX。
只需删除插件配置中 `grpc-web` 的 JSON 配置即可。 APISIX 插件是热加载的，所以不需要重启 APISIX。
```bash
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

2
docs/zh/latest/plugins/gzip.md
View File

@ -25,7 +25,7 @@ title: gzip
`gzip` 插件能动态设置 `Nginx` 的压缩行为。
**该插件要求 `APISIX` 运行在 [APISIX-OpenResty](../how-to-build.md#步骤6：为-apache-apisix-构建-openresty) 上。**
**该插件要求 `APISIX` 运行在 [APISIX-OpenResty](../how-to-build.md#步骤-6-为-apache-apisix-构建-openresty) 上。**
## 属性

16
docs/zh/latest/plugins/hmac-auth.md
View File

@ -37,7 +37,7 @@ title: hmac-auth
| clock_skew | integer | 可选 | 0 | | 签名允许的时间偏移，以秒为单位的计时。比如允许时间偏移 10 秒钟，那么就应设置为 `10`。特别地，`0` 表示不对 `Date` 进行检查。 |
| signed_headers | array[string] | 可选 | | | 限制加入加密计算的 headers ，指定后客户端请求只能在此范围内指定 headers ，此项为空时将把所有客户端请求指定的 headers 加入加密计算。如： ["User-Agent", "Accept-Language", "x-custom-a"] |
| keep_headers | boolean | 可选 | false | [ true, false ] | 认证成功后的 http 请求中是否需要保留 `X-HMAC-SIGNATURE`、`X-HMAC-ALGORITHM` 和 `X-HMAC-SIGNED-HEADERS` 的请求头。true: 表示保留 http 请求头，false: 表示移除 http 请求头。 |
| encode_uri_param | boolean | 可选 | true | [ true, false ] | 是否对签名中的 uri 参数进行编码,例如: `params1=hello%2Cworld` 进行了编码，`params2=hello,world` 没有进行编码。true: 表示对签名中的 uri 参数进行编码，false: 不对签名中的 uri 参数编码。 |
| encode_uri_param | boolean | 可选 | true | [ true, false ] | 是否对签名中的 uri 参数进行编码，例如：`params1=hello%2Cworld` 进行了编码，`params2=hello,world` 没有进行编码。true: 表示对签名中的 uri 参数进行编码，false: 不对签名中的 uri 参数编码。 |
| validate_request_body | boolean | 可选 | false | [ true, false ] | 是否对请求 body 做签名校验。|
| max_req_body | integer | 可选 | 512 * 1024 | | 最大允许的 body 大小。|
@ -88,7 +88,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
1. **HTTP Method**：指 HTTP 协议中定义的 GET、PUT、POST 等请求方法，必须使用全大写的形式。
2. **HTTP URI**：要求必须以“/”开头，不以“/”开头的需要补充上，空路径为“/”。
3. **Date**：请求头中的 Date （ GMT 格式 ）。
3. **Date**：请求头中的 Date（ GMT 格式 ）。
4. **canonical_query_string**：是对于 URL 中的 query（ query 即 URL 中 ? 后面的 key1=valve1&key2=valve2 字符串）进行编码后的结果。
5. **signed_headers_string**：是从请求头中获取客户端指定的字段，并按顺序拼接字符串的结果。
@ -98,12 +98,12 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
* 将 query 根据&分隔符拆开成若干项，每一项是 key=value 或者只有 key 的形式。
* 根据 uri 参数是否编码，有下面两种情况：
* `encode_uri_param` 为 true 时：
* 对拆开后的每一项进行编码处理，分以下两种情况:
* 对拆开后的每一项进行编码处理，分以下两种情况：
* 当该项只有 key 时，转换公式为 url_encode(key) + "=" 的形式。
* 当该项是 key=value 的形式时，转换公式为 url_encode(key) + "=" + url_encode(value) 的形式。这里 value 可以是空字符串。
* 将每一项转换后，以 key 按照字典顺序（ ASCII 码由小到大）排序，并使用 & 符号连接起来，生成相应的 canonical_query_string 。
* `encode_uri_param` 为 false 时:
* 对拆开后的每一项进行编码处理，分以下两种情况:
* `encode_uri_param` 为 false 时：
* 对拆开后的每一项进行编码处理，分以下两种情况：
* 当该项只有 key 时，转换公式为 key + "=" 的形式。
* 当该项是 key=value 的形式时，转换公式为 key + "=" + value 的形式。这里 value 可以是空字符串。
* 将每一项转换后，以 key 按照字典顺序（ ASCII 码由小到大）排序，并使用 & 符号连接起来，生成相应的 canonical_query_string 。
@ -185,7 +185,7 @@ X-HMAC-DIGEST: base64(hmac-sha(<body>))
当没有请求 body 时，插件会计算长度为 0 的空字符串的 hmac-sha 值。
**注:**当开启 body 校验时，为了计算请求 body 的 `hmac-sha` 值，插件会把 body 加载到内存中，在请求 body 较大的情况下，可能会造成较高的内存消耗。插件提供了 `max_req_body`（默认值 512KB） 配置项来配置最大允许的 body 大小，body 超过此大小的请求会被拒绝。
**注：**当开启 body 校验时，为了计算请求 body 的 `hmac-sha` 值，插件会把 body 加载到内存中，在请求 body 较大的情况下，可能会造成较高的内存消耗。插件提供了 `max_req_body`（默认值 512KB）配置项来配置最大允许的 body 大小，body 超过此大小的请求会被拒绝。
### 使用生成好的签名进行请求尝试
@ -239,7 +239,7 @@ Accept-Ranges: bytes
<html lang="cn">
```
**注:**
**注：**
1. **ACCESS_KEY, SIGNATURE, ALGORITHM, DATE, SIGNED_HEADERS 分别代表对应的变量**
2. **SIGNED_HEADERS 为客户端指定的加入加密计算的 headers。若存在多个 headers 需以 ";" 分割：`x-custom-header-a;x-custom-header-b`**
@ -319,7 +319,7 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f
以 HMAC SHA256 为例，介绍一下各种语言的签名生成示例。需要注意各种语言中对签名字符串的换行符的处理方式，这很容易导致出现 `{"message":"Invalid signature"}` 的问题。
示例入参说明:
示例入参说明：
| Variable | Value |
| -------- | -------------------------- |

4
docs/zh/latest/plugins/http-logger.md
View File

@ -37,7 +37,7 @@ title: http-logger
| name | string | 可选 | "http logger" | | 标识 logger 的唯一标识符。 |
| include_req_body | boolean | 可选 | false | [false, true] | 是否包括请求 body。false： 表示不包含请求的 body ； true： 表示包含请求的 body 。 |
| include_resp_body| boolean | 可选 | false | [false, true] | 是否包括响应体。包含响应体，当为`true`。 |
| include_resp_body_expr | array | 可选 | | | 是否采集响体, 基于[lua-resty-expr](https://github.com/api7/lua-resty-expr)。 该选项需要开启 `include_resp_body`|
| include_resp_body_expr | array | 可选 | | | 是否采集响体，基于 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 该选项需要开启 `include_resp_body`|
| concat_method | string | 可选 | "json" | ["json", "new_line"] | 枚举类型： `json`、`new_line`。**json**: 对所有待发日志使用 `json.encode` 编码。**new_line**: 对每一条待发日志单独使用 `json.encode` 编码并使用 "\n" 连接起来。 |
| ssl_verify | boolean | optional | false | [false, true] | 是否验证证书。 |
@ -67,7 +67,7 @@ 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

6
docs/zh/latest/plugins/ip-restriction.md
View File

@ -31,14 +31,14 @@ title: ip-restriction
| --------- | ------------- | ------ | ------ | ------ | -------------------------------- |
| whitelist | array[string] | 可选 | | | 加入白名单的 IP 地址或 CIDR 范围 |
| blacklist | array[string] | 可选 | | | 加入黑名单的 IP 地址或 CIDR 范围 |
| message | string | 可选 | Your IP address is not allowed. | [1, 1024] | 在未允许的IP访问的情况下返回的信息 |
| message | string | 可选 | Your IP address is not allowed. | [1, 1024] | 在未允许的 IP 访问的情况下返回的信息 |
只能单独启用白名单或黑名单，两个不能一起使用。
`message` 可以由用户自定义。
## 如何启用
下面是一个示例，在指定的 route 上开启了 `ip-restriction` 插件:
下面是一个示例，在指定的 route 上开启了 `ip-restriction` 插件：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -61,7 +61,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
当未允许的IP访问时，默认返回 `{"message":"Your IP address is not allowed"}`。如果你想使用自定义的 `message`，可以在插件部分进行配置:
当未允许的 IP 访问时，默认返回 `{"message":"Your IP address is not allowed"}`。如果你想使用自定义的 `message`，可以在插件部分进行配置：
```json
"plugins": {

8
docs/zh/latest/plugins/jwt-auth.md
View File

@ -52,9 +52,9 @@ router 端配置：
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ---- | ------ | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------- |
| header | string | 可选| authorization | | 设置我们从哪个 header 获取 token。 |
| query | string | 可选 | jwt | | 设置我们从哪个 query string 获取 token，优先级低于header |
| cookie | string | 可选 | jwt | | 设置我们从哪个 cookie 获取 token，优先级低于query |
| header | string | 可选 | authorization | | 设置我们从哪个 header 获取 token。 |
| query | string | 可选 | jwt | | 设置我们从哪个 query string 获取 token，优先级低于 header |
| cookie | string | 可选 | jwt | | 设置我们从哪个 cookie 获取 token，优先级低于 query |
## 接口
@ -138,7 +138,7 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f1
在这里，插件在 Consumer 配置中提到的 Consumer 用户 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 JWT 验证。如果在该路径中没有找到密钥，该插件将记录一个错误，并且无法执行 JWT 验证。
2. RS256 RSA 密钥对, 包括公钥和私钥都存粗在 Vault 中。
2. RS256 RSA 密钥对，包括公钥和私钥都存粗在 Vault 中。
```shell
curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

6
docs/zh/latest/plugins/kafka-logger.md
View File

@ -23,7 +23,7 @@ title: kafka-logger
## 描述
`kafka-logger` 是一个插件，可用作ngx_lua nginx 模块的 Kafka 客户端驱动程序。
`kafka-logger` 是一个插件，可用作 ngx_lua nginx 模块的 Kafka 客户端驱动程序。
它可以将接口请求日志以 JSON 的形式推送给外部 Kafka 集群。如果在短时间内没有收到日志数据，请放心，它会在我们的批处理处理器中的计时器功能到期后自动发送日志。
@ -43,9 +43,9 @@ title: kafka-logger
| name | string | 可选 | "kafka logger" | | batch processor 的唯一标识。 |
| meta_format | enum | 可选 | "default" | ["default"，"origin"] | `default`：获取请求信息以默认的 JSON 编码方式。`origin`：获取请求信息以 HTTP 原始请求方式。[具体示例](#meta_format-参考示例)|
| include_req_body | boolean | 可选 | false | [false, true] | 是否包括请求 body。false： 表示不包含请求的 body ；true： 表示包含请求的 body。注意：如果请求 body 没办法完全放在内存中，由于 Nginx 的限制，我们没有办法把它记录下来。|
| include_req_body_expr | array | 可选 | | | 当 `include_req_body` 开启时, 基于 [lua-resty-expr](https://github.com/api7/lua-resty-expr) 表达式的结果进行记录。如果该选项存在，只有在表达式为真的时候才会记录请求 body。 |
| include_req_body_expr | array | 可选 | | | 当 `include_req_body` 开启时，基于 [lua-resty-expr](https://github.com/api7/lua-resty-expr) 表达式的结果进行记录。如果该选项存在，只有在表达式为真的时候才会记录请求 body。 |
| include_resp_body| boolean | 可选 | false | [false, true] | 是否包括响应体。包含响应体，当为`true`。 |
| include_resp_body_expr | array | 可选 | | | 是否采集响体, 基于[lua-resty-expr](https://github.com/api7/lua-resty-expr)。 该选项需要开启 `include_resp_body`|
| include_resp_body_expr | array | 可选 | | | 是否采集响体，基于 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 该选项需要开启 `include_resp_body`|
| cluster_name | integer | 可选 | 1 | [0,...] | kafka 集群的名称。当有两个或多个 kafka 集群时，可以指定不同的名称。只适用于 producer_type 是 async 模式。|
本插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解或自定义批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。

6
docs/zh/latest/plugins/key-auth.md
View File

@ -39,8 +39,8 @@ router 端配置：
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ---- | ------ | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------- |
| header | string | 可选| apikey | | 设置我们从哪个 header 获取 key。 |
| query | string | 可选 | apikey | | 设置我们从哪个 query string 获取 key，优先级低于 `header` |
| header | string | 可选 | apikey | | 设置我们从哪个 header 获取 key。 |
| query | string | 可选 | apikey | | 设置我们从哪个 querystring 获取 key，优先级低于 header |
## 如何启用
@ -96,7 +96,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
## 测试插件
下面是一个正常通过 `key-auth` 验证的请求:
下面是一个正常通过 `key-auth` 验证的请求：
```shell
$ curl http://127.0.0.2:9080/index.html -H 'apikey: auth-one' -i

6
docs/zh/latest/plugins/limit-conn.md
View File

@ -28,16 +28,16 @@ title: limit-conn
## 属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ------------------ | ------- | -------- | ------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ------------------ | ------- | -------- | ------ | ----------------------------------------------------------------------------------------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| conn | integer | required | | conn > 0 | 允许的最大并发请求数。超过 `conn` 的限制、但是低于 `conn` + `burst` 的请求，将被延迟处理。 |
| burst | integer | required | | burst >= 0 | 允许被延迟处理的并发请求数。 |
| default_conn_delay | number | required | | default_conn_delay > 0 | 默认的典型连接(或请求)的处理延迟时间。 |
| default_conn_delay | number | required | | default_conn_delay > 0 | 默认的典型连接（或请求）的处理延迟时间。 |
| only_use_default_delay | boolean | optional | false | [true,false] | 延迟时间的严格模式。 如果设置为`true`的话，将会严格按照设置的时间来进行延迟 |
| 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 | optional | 503 | [200,...,599] | 当请求超过 `conn` + `burst` 这个阈值时，返回的 HTTP 状态码 |
| rejected_msg | string | 可选 | | 非空 | 当请求超过 `conn` + `burst` 这个阈值时，返回的响应体。 |
| allow_degradation | boolean | 可选 | false | | 当插件功能临时不可用时是否允许请求继续。当值设置为 true 时则自动允许请求继续，默认值是 false。|
| allow_degradation | boolean | 可选 | false | | 当插件功能临时不可用时是否允许请求继续。当值设置为 true 时则自动允许请求继续，默认值是 false。 |
### 如何启用

6
docs/zh/latest/plugins/limit-count.md
View File

@ -38,14 +38,14 @@ title: limit-count
| rejected_msg | string | 可选 | | 非空 | 当请求超过阈值被拒绝时，返回的响应体。 |
| policy | string | 可选 | "local" | ["local", "redis", "redis-cluster"] | 用于检索和增加限制的速率限制策略。可选的值有：`local`(计数器被以内存方式保存在节点本地，默认选项) 和 `redis`(计数器保存在 Redis 服务节点上，从而可以跨节点共享结果，通常用它来完成全局限速)；以及`redis-cluster`，跟 redis 功能一样，只是使用 redis 集群方式。 |
| allow_degradation | boolean | 可选 | false | | 当限流插件功能临时不可用时（例如，Redis 超时）是否允许请求继续。当值设置为 true 时则自动允许请求继续，默认值是 false。|
| show_limit_quota_header | boolean | 可选 | true | | 是否在响应头中显示 `X-RateLimit-Limit` 和 `X-RateLimit-Remaining` （限制的总请求数和剩余还可以发送的请求数），默认值是 true。 |
| show_limit_quota_header | boolean | 可选 | true | | 是否在响应头中显示 `X-RateLimit-Limit` 和 `X-RateLimit-Remaining`（限制的总请求数和剩余还可以发送的请求数），默认值是 true。 |
| group | string | 可选 | | 非空 | 配置同样的 group 的 Route 将共享同样的限流计数器 |
| redis_host | string | `redis` 必须 | | | 当使用 `redis` 限速策略时，该属性是 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,...] | 当使用 `redis` 或者 `redis-cluster` 限速策略时，该属性是 Redis 服务节点以毫秒为单位的超时时间 |
| redis_cluster_nodes | array | 当 policy 为 `redis-cluster` 时必填| | | 当使用 `redis-cluster` 限速策略时，该属性是 Redis 集群服务节点的地址列表（至少需要两个地址）。 |
| redis_cluster_nodes | array | 当 policy 为 `redis-cluster` 时必填 | | | 当使用 `redis-cluster` 限速策略时，该属性是 Redis 集群服务节点的地址列表（至少需要两个地址）。 |
| redis_cluster_name | string | 当 policy 为 `redis-cluster` 时必填 | | | 当使用 `redis-cluster` 限速策略时，该属性是 Redis 集群服务节点的名称。 |
## 如何使用
@ -211,7 +211,7 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335
}'
```
如果使用 `redis-cluster` 策略:
如果使用 `redis-cluster` 策略：
```shell
curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

14
docs/zh/latest/plugins/limit-req.md
View File

@ -29,19 +29,19 @@ title: limit-req
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ------------- | ------- | ------ | ------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| rate | integer | 必须 | | rate > 0 | 指定的请求速率（以秒为单位），请求速率超过 `rate` 但没有超过 （`rate` + `burst`）的请求会被加上延时。 |
| burst | integer | 必须 | | burst >= 0 | t请求速率超过 （`rate` + `burst`）的请求会被直接拒绝。 |
| 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)。 |
| rate | integer | 必须 | | rate > 0 | 指定的请求速率（以秒为单位），请求速率超过 `rate` 但没有超过（`rate` + `burst`）的请求会被加上延时。 |
| burst | integer | 必须 | | burst >= 0 | t 请求速率超过（`rate` + `burst`）的请求会被直接拒绝。 |
| 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 | | 如果 nodelay 为 true， 请求速率超过 `rate` 但没有超过 （`rate` + `burst`）的请求不会加上延迟, 如果是 false，则会加上延迟。 |
| nodelay | boolean | 可选 | false | | 如果 nodelay 为 true， 请求速率超过 `rate` 但没有超过（`rate` + `burst`）的请求不会加上延迟，如果是 false，则会加上延迟。 |
| allow_degradation | boolean | 可选 | false | | 当限速插件功能临时不可用时是否允许请求继续。当值设置为 true 时则自动允许请求继续，默认值是 false。|
## 示例
### 如何在`route`或`service`上使用
这里以`route`为例(`service`的使用是同样的方法)，在指定的 `route` 上启用 `limit-req` 插件，并设置 `key_type` 为 `var`。
这里以`route`为例 (`service`的使用是同样的方法)，在指定的 `route` 上启用 `limit-req` 插件，并设置 `key_type` 为 `var`。
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -137,9 +137,9 @@ Server: APISIX web server
### 如何在 `consumer`上使用
consumer上开启 `limit-req` 插件，需要与授权插件一起配合使用，这里以 key-auth 授权插件为例。
consumer 上开启 `limit-req` 插件，需要与授权插件一起配合使用，这里以 key-auth 授权插件为例。
1、将 `limit-req` 插件绑定到consumer上
1、将 `limit-req` 插件绑定到 consumer 上
```shell
curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

4
docs/zh/latest/plugins/mocking.md
View File

@ -110,7 +110,7 @@ Mock API 插件，绑定该插件后将随机返回指定格式的`mock`数据
## 如何启用
这里以`route`为例(`service`的使用是同样的方法)，在指定的 `route` 上启用 `mocking` 插件。
这里以`route`为例 (`service`的使用是同样的方法)，在指定的 `route` 上启用 `mocking` 插件。
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -190,7 +190,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}
```
curl访问将返回如下结果：
curl 访问将返回如下结果：
```shell
$ curl http://127.0.0.1:9080/test-mock -i

4
docs/zh/latest/plugins/mqtt-proxy.md
View File

@ -57,7 +57,7 @@ title: mqtt-proxy
然后把 MQTT 请求发送到 9100 端口即可。
下面是一个示例，在指定的 route 上开启了 `mqtt-proxy` 插件:
下面是一个示例，在指定的 route 上开启了 `mqtt-proxy` 插件：
```shell
curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -81,7 +81,7 @@ curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f03
在 Docker 与 MacOS 结合使用的情况下，`host.docker.internal` 是 `host` 的正确参数。
这个插件暴露了一个变量 `mqtt_client_id`，我们可以用它来通过客户端 ID 进行负载均衡。比如说:
这个插件暴露了一个变量 `mqtt_client_id`，我们可以用它来通过客户端 ID 进行负载均衡。比如说：
```shell
curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

2
docs/zh/latest/plugins/node-status.md
View File

@ -84,7 +84,7 @@ Server: APISIX web server
| waiting | 当前等待客户端请求的空闲连接数 |
| accepted | 已经接受的客户端连接总数 |
| writing | 当前正在写给客户端响应的连接数 |
| handled | 已经处理的连接总数,通常等于 accepted |
| handled | 已经处理的连接总数，通常等于 accepted |
| active | 当前活跃的客户端连接数 |
| reading | 当前正在读取请求头的连接数 |
| id | APISIX uid 信息，保存在 apisix/conf/apisix.uid |

2
docs/zh/latest/plugins/openid-connect.md
View File

@ -93,7 +93,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
curl -i -X GET http://127.0.0.1:9080/get -H "Host: httpbin.org" -H "Authorization: Bearer {replace_jwt_token}"
```
当 Oauth 2 授权服务器返回结果里面除了 token 之外还有过期时间, token 将在 APISIX 中缓存直至过期。
当 Oauth 2 授权服务器返回结果里面除了 token 之外还有过期时间，token 将在 APISIX 中缓存直至过期。
具体细节参见：
1. [lua-resty-openidc](https://github.com/zmartzone/lua-resty-openidc) 的文档和代码。

4
docs/zh/latest/plugins/opentelemetry.md
View File

@ -55,7 +55,7 @@ plugins:
然后重载 APISIX。
下面是一个示例，在指定的 route 上开启了 opentelemetry 插件:
下面是一个示例，在指定的 route 上开启了 opentelemetry 插件：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -99,7 +99,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
| batch_span_processor.max_export_batch_size | integer | 256 | 一批 span 的数量，每次上报的 span 数量 |
| batch_span_processor.inactive_timeout | number | 2 | 每隔多长时间检查是否有一批 span 可以上报，单位秒 |
配置示例:
配置示例：
```yaml
plugin_attr:

20
docs/zh/latest/plugins/prometheus.md
View File

@ -63,7 +63,7 @@ plugin_attr:
`prometheus` 插件可以使用空 {} 开启。
注意，多个路由/服务可以设置为相同的名称，因此当设置 `prefer_name` 为 `true` 时，注意规范命名否则容易引起误解。
例子如下:
例子如下：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -99,20 +99,20 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
curl -i http://127.0.0.1:9091/apisix/prometheus/metrics
```
把该 uri 地址配置到 prometheus 中去,就会自动完成指标数据提取.
把该 uri 地址配置到 prometheus 中去，就会自动完成指标数据提取。
例子如下:
例子如下：
```yaml
scrape_configs:
- job_name: "apisix"
scrape_interval: 15s # 这个值会跟Prometheus QL中rate函数的时间范围有关系, rate函数中的时间范围应该至少两倍于该值.
scrape_interval: 15s # 这个值会跟 Prometheus QL 中 rate 函数的时间范围有关系，rate 函数中的时间范围应该至少两倍于该值。
metrics_path: "/apisix/prometheus/metrics"
static_configs:
- targets: ["127.0.0.1:9091"]
```
我们也可以在 prometheus 控制台中去检查状态:
我们也可以在 prometheus 控制台中去检查状态：
![checking status on prometheus dashboard](../../../assets/images/plugin/prometheus01.png)
@ -126,7 +126,7 @@ scrape_configs:
| ---------- | ------ | ---------------------------- | -------------- |
| export_uri | string | "/apisix/prometheus/metrics" | 暴露指标的 uri |
配置示例:
配置示例：
```yaml
plugin_attr:
@ -140,7 +140,7 @@ plugin_attr:
下载 [Grafana dashboard 元数据](https://github.com/apache/apisix/blob/master/docs/assets/other/json/apisix-grafana-dashboard.json) 并导入到 Grafana 中。
你可以到 [Grafana 官方](https://grafana.com/grafana/dashboards/11719) 下载 `Grafana` 元数据.
你可以到 [Grafana 官方](https://grafana.com/grafana/dashboards/11719) 下载 `Grafana` 元数据。
![Grafana chart-1](../../../assets/images/plugin/grafana-1.png)
@ -168,7 +168,7 @@ plugin_attr:
| 名称 | 描述 |
| -------------| ------------- |
| type | 带宽的类型(`ingress` 或 `egress`)。 |
| type | 带宽的类型 (`ingress` 或 `egress`)。 |
| route | 请求匹配的 route 的 `route_id`，未匹配，则默认为空字符串。 |
| service | 与请求匹配的 route 的 `service_id`。当路由缺少 service_id 时，则默认为 `$host`。 |
| consumer | 与请求匹配的 consumer 的 `consumer_name`。未匹配，则默认为空字符串。 |
@ -176,7 +176,7 @@ plugin_attr:
* `etcd reachability`: APISIX 连接 etcd 的可用性，用 0 和 1 来表示，`1` 表示可用，`0` 表示不可用。
* `Connections`: 各种的 Nginx 连接指标，如 active（正处理的活动连接数），reading（nginx 读取到客户端的 Header 信息数），writing（nginx 返回给客户端的 Header 信息数），已建立的连接数。
* `Batch process entries`: 批处理未发送数据计数器，当你使用了批处理发送插件，比如：sys logger, http logger, sls logger, tcp logger, udp logger and zipkin, 那么你将会在此指标中看到批处理当前尚未发送的数据的数量。
* `Batch process entries`: 批处理未发送数据计数器，当你使用了批处理发送插件，比如：sys logger, http logger, sls logger, tcp logger, udp logger and zipkin，那么你将会在此指标中看到批处理当前尚未发送的数据的数量。
* `Latency`: 每个服务的请求用时和 APISIX 处理耗时的直方图。具有的维度：
| 名称 | 描述 |
@ -188,7 +188,7 @@ plugin_attr:
* `Info`: 当前 APISIX 节点信息。
这里是 APISIX 的原始的指标数据集:
这里是 APISIX 的原始的指标数据集：
```shell
$ curl http://127.0.0.1:9091/apisix/prometheus/metrics

12
docs/zh/latest/plugins/proxy-cache.md
View File

@ -36,9 +36,9 @@ title: proxy-cache
| ------------------ | -------------- | ------ | ------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| cache_strategy | string | 可选 | disk | ["disk","memory"] | 缓存策略，指定缓存数据存储在磁盘还是内存中 |
| cache_zone | string | 可选 | disk_cache_one | | 指定使用哪个缓存区域，不同的缓存区域可以配置不同的路径，在 conf/config.yaml 文件中可以预定义使用的缓存区域。当不使用默认值时，指定的缓存区域与 conf/config.yaml 文件中预定义的缓存区域不一致，缓存无效。 |
| cache_key | array[string] | 可选 | ["$host", "$request_uri"] | | 缓存key，可以使用变量。例如：["$host", "$uri", "-cache-id"] |
| cache_key | array[string] | 可选 | ["$host", "$request_uri"] | | 缓存 key，可以使用变量。例如：["$host", "$uri", "-cache-id"] |
| cache_bypass | array[string] | 可选 | | | 是否跳过缓存检索，即不在缓存中查找数据，可以使用变量，需要注意当此参数的值不为空或非'0'时将会跳过缓存的检索。例如：["$arg_bypass"] |
| cache_method | array[string] | 可选 | ["GET", "HEAD"] | ["GET", "POST", "HEAD"] | 根据请求method决定是否需要缓存 |
| cache_method | array[string] | 可选 | ["GET", "HEAD"] | ["GET", "POST", "HEAD"] | 根据请求 method 决定是否需要缓存 |
| cache_http_status | array[integer] | 可选 | [200, 301, 404] | [200, 599] | 根据响应码决定是否需要缓存 |
| hide_cache_headers | boolean | 可选 | false | | 是否将 Expires 和 Cache-Control 响应头返回给客户端 |
| cache_control | boolean | 可选 | false | | 是否遵守 HTTP 协议规范中的 Cache-Control 的行为 |
@ -47,13 +47,13 @@ title: proxy-cache
注：变量以$开头，也可以使用变量和字符串的结合，但是需要以数组的形式分开写，最终变量被解析后会和字符串拼接在一起。
在 `conf/config.yaml` 文件中的配置示例:
在 `conf/config.yaml` 文件中的配置示例：
```yaml
proxy_cache: # 代理缓存配置
cache_ttl: 10s # 如果上游未指定缓存时间，则为默认缓存时间
zones: # 缓存的参数
- name: disk_cache_one # 缓存名称(缓存区域)，管理员可以通过admin api中的 cache_zone 字段指定要使用的缓存区域
- name: disk_cache_one # 缓存名称 (缓存区域)，管理员可以通过 admin api 中的 cache_zone 字段指定要使用的缓存区域
memory_size: 50m # 共享内存的大小，用于存储缓存索引
disk_size: 1G # 磁盘大小，用于存储缓存数据
disk_path: "/tmp/disk_cache_one" # 存储缓存数据的路径
@ -129,7 +129,7 @@ hello
示例二：自定义 cache_zone 参数为 `disk_cache_two`
1、在 `conf/config.yaml` 文件中的指定缓存区域等信息:
1、在 `conf/config.yaml` 文件中的指定缓存区域等信息：
```yaml
proxy_cache:
@ -204,7 +204,7 @@ hello
> 响应头 `Apisix-Cache-Status` 值变为了 HIT，说明数据已经被缓存
示例3：指定 cache_zone 为 `invalid_disk_cache` 与 `conf/config.yaml` 文件中指定的缓存区域 `disk_cache_one` 不一致。
示例 3：指定 cache_zone 为 `invalid_disk_cache` 与 `conf/config.yaml` 文件中指定的缓存区域 `disk_cache_one` 不一致。
```shell
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

2
docs/zh/latest/plugins/proxy-control.md
View File

@ -25,7 +25,7 @@ title: proxy-control
`proxy-control` 能够动态地控制 Nginx 代理的行为。
**这个插件需要APISIX在 [APISIX-OpenResty](../how-to-build.md#步骤6：为-apache-apisix-构建-openresty)上运行。**
**这个插件需要 APISIX 在 [APISIX-OpenResty](../how-to-build.md#步骤-6-为-apache-apisix-构建-openresty) 上运行。**
## 属性

6
docs/zh/latest/plugins/proxy-mirror.md
View File

@ -31,7 +31,7 @@ title: proxy-mirror
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ---- | ------ | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------- |
| host | string | 必须 | | | 指定镜像服务地址，例如：http://127.0.0.1:9797（地址中需要包含 schema ：http或https，不能包含 path 部分） |
| host | string | 必须 | | | 指定镜像服务地址，例如：http://127.0.0.1:9797（地址中需要包含 schema ：http 或 https，不能包含 path 部分）|
| path | string | 可选 | | | 指定镜像请求的路径。如不指定，当前路径将被使用。 |
| sample_ratio | number | 可选 | 1 | [0.00001, 1] | 镜像请求采样率 |
@ -39,7 +39,7 @@ title: proxy-mirror
### 启用插件
示例1：为特定路由启用 `proxy-mirror` 插件：
示例 1：为特定路由启用 `proxy-mirror` 插件：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -96,7 +96,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
这时该插件已被禁用。
## 指定mirror子请求的超时时间
## 指定 mirror 子请求的超时时间
我们可以在 `conf/config.yaml` 的 `plugin_attr` 中指定子请求的超时时间。这在连接复用的场景下 mirror 流量到一个非常慢的后端服务时非常有用。

8
docs/zh/latest/plugins/proxy-rewrite.md
View File

@ -31,14 +31,14 @@ proxy-rewrite 是上游代理信息重写插件，支持对 `scheme`、`uri`、`
| --------- | ------------- | ----------- | ------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| scheme | string | 可选 | "http" | ["http", "https"] | 不推荐使用。应该在 Upstream 的 scheme 字段设置上游的 scheme。
| uri | string | 可选 | | | 转发到上游的新 `uri` 地址。 |
| method | string | 可选 | | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS","MKCOL", "COPY", "MOVE", "PROPFIND", "PROPFIND","LOCK", "UNLOCK", "PATCH", "TRACE"] | 将route的请求方法代理为该请求方法。 |
| regex_uri | array[string] | 可选 | | | 转发到上游的新 `uri` 地址, 使用正则表达式匹配来自客户端的uri，当匹配成功后使用模板替换转发到上游的uri, 未匹配成功时将客户端请求的uri转发至上游。当 `uri` 和 `regex_uri` 同时存在时，`uri` 优先被使用。例如：["^/iresty/(.*)/(.*)/(.*)","/$1-$2-$3"] 第一个元素代表匹配来自客户端请求的uri正则表达式，第二个元素代表匹配成功后转发到上游的uri模板。 |
| method | string | 可选 | | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS","MKCOL", "COPY", "MOVE", "PROPFIND", "PROPFIND","LOCK", "UNLOCK", "PATCH", "TRACE"] | 将 route 的请求方法代理为该请求方法。 |
| regex_uri | array[string] | 可选 | | | 转发到上游的新 `uri` 地址，使用正则表达式匹配来自客户端的 uri，当匹配成功后使用模板替换转发到上游的 uri，未匹配成功时将客户端请求的 uri 转发至上游。当 `uri` 和 `regex_uri` 同时存在时，`uri` 优先被使用。例如：["^/iresty/(.*)/(.*)/(.*)","/$1-$2-$3"] 第一个元素代表匹配来自客户端请求的 uri 正则表达式，第二个元素代表匹配成功后转发到上游的 uri 模板。 |
| host | string | 可选 | | | 转发到上游的新 `host` 地址，例如：`iresty.com` 。 |
| headers | object | 可选 | | | 转发到上游的新 `headers`，可以设置多个。头信息如果存在将重写，不存在则添加。想要删除某个 header 的话，把对应的值设置为空字符串即可。支持使用 Nginx 的变量，需要以 `$` 开头，如 `client_addr: $remote_addr` ：表示请求头 `client_addr` 为客户端IP。 |
| headers | object | 可选 | | | 转发到上游的新 `headers`，可以设置多个。头信息如果存在将重写，不存在则添加。想要删除某个 header 的话，把对应的值设置为空字符串即可。支持使用 Nginx 的变量，需要以 `$` 开头，如 `client_addr: $remote_addr` ：表示请求头 `client_addr` 为客户端 IP。 |
## 如何启用
下面是一个示例，在指定的 route 上开启了 `proxy-rewrite` 插件:
下面是一个示例，在指定的 route 上开启了 `proxy-rewrite` 插件：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

2
docs/zh/latest/plugins/real-ip.md
View File

@ -27,7 +27,7 @@ title: real-ip
它工作方式和 `Nginx` 里 `ngx_http_realip_module` 模块一样，并且更为灵活。
**该插件要求 `APISIX` 运行在 [APISIX-OpenResty](../how-to-build.md#步骤6：为-apache-apisix-构建-openresty) 上。**
**该插件要求 `APISIX` 运行在 [APISIX-OpenResty](../how-to-build.md#步骤-6-为-apache-apisix-构建-openresty) 上。**
## 属性

6
docs/zh/latest/plugins/redirect.md
View File

@ -31,10 +31,10 @@ URI 重定向插件。
| ------------- | ------- | ----------- | ------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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` 模板。 |
| 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重复 |
| 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`，`uri` 或 `regex_uri` 三个中只能配置一个。

8
docs/zh/latest/plugins/referer-restriction.md
View File

@ -39,7 +39,7 @@ title: referer-restriction
## 如何启用
下面是一个示例，在指定的 route 上开启了 `referer-restriction` 插件:
下面是一个示例，在指定的 route 上开启了 `referer-restriction` 插件：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -65,7 +65,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
## 测试插件
带 `Referer: http://xx.com/x` 请求:
带 `Referer: http://xx.com/x` 请求：
```shell
$ curl http://127.0.0.1:9080/index.html -H 'Referer: http://xx.com/x'
@ -73,7 +73,7 @@ HTTP/1.1 200 OK
...
```
带 `Referer: http://yy.com/x` 请求:
带 `Referer: http://yy.com/x` 请求：
```shell
$ curl http://127.0.0.1:9080/index.html -H 'Referer: http://yy.com/x'
@ -82,7 +82,7 @@ HTTP/1.1 403 Forbidden
{"message":"Your referer host is not allowed"}
```
不带 `Referer` 请求:
不带 `Referer` 请求：
```shell
$ curl http://127.0.0.1:9080/index.html

24
docs/zh/latest/plugins/request-id.md
View File

@ -30,7 +30,7 @@ title: request-id
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ------------------- | ------- | -------- | -------------- | ------ | ------------------------------ |
| header_name | string | 可选 | "X-Request-Id" | | Request ID header name |
| include_in_response | boolean | 可选 | true | | 是否需要在返回头中包含该唯一ID |
| include_in_response | boolean | 可选 | true | | 是否需要在返回头中包含该唯一 ID |
| algorithm | string | 可选 | "uuid" | ["uuid", "snowflake"] | ID 生成算法 |
## 如何启用
@ -64,10 +64,10 @@ X-Request-Id: fe32076a-d0a5-49a6-a361-6c244c1df956
......
```
### 使用 snowflake 算法生成ID
### 使用 snowflake 算法生成 ID
> 支持使用 snowflake 算法来生成ID。
> 在决定使用 snowflake 时，请优先阅读一下文档。因为一旦启用配置信息则不可随意调整配置信息。否则可能会导致生成重复ID。
> 支持使用 snowflake 算法来生成 ID。
> 在决定使用 snowflake 时，请优先阅读一下文档。因为一旦启用配置信息则不可随意调整配置信息。否则可能会导致生成重复 ID。
snowflake 算法默认是不启用的，需要在 `conf/config.yaml` 中开启配置。
@ -87,16 +87,16 @@ plugin_attr:
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ------------------- | ------- | -------- | -------------- | ------ | ------------------------------ |
| enable | boolean | 可选 | false | | 当设置为true时， 启用snowflake算法。 |
| snowflake_epoc | integer | 可选 | 1609459200000 | | 起始时间戳（单位： 毫秒） |
| enable | boolean | 可选 | false | | 当设置为 true 时， 启用 snowflake 算法。 |
| snowflake_epoc | integer | 可选 | 1609459200000 | | 起始时间戳（单位： 毫秒）|
| data_machine_bits | integer | 可选 | 12 | | 最多支持机器（进程）数量 `1 << data_machine_bits` |
| sequence_bits | integer | 可选 | 10 | | 每个节点每毫秒内最多产生ID数量 `1 << sequence_bits` |
| sequence_bits | integer | 可选 | 10 | | 每个节点每毫秒内最多产生 ID 数量 `1 << sequence_bits` |
| data_machine_ttl | integer | 可选 | 30 | | `etcd` 中 `data_machine` 注册有效时间（单位： 秒）|
| data_machine_interval | integer | 可选 | 10 | | `etcd` 中 `data_machine` 续约间隔时间（单位： 秒）|
- snowflake_epoc 默认起始时间为 `2021-01-01T00:00:00Z`, 按默认配置可以支持 `69年` 大约可以使用到 `2090-09-07 15:47:35Z`
- data_machine_bits 对应的是 snowflake 定义中的 WorkerID 和 DatacenterID 的集合，插件会为每一个进程分配一个唯一ID，最大支持进程数为 `pow(2, data_machine_bits)`。默认占 `12 bits` 最多支持 `4096` 个进程。
- sequence_bits 默认占 `10 bits`, 每个进程每毫秒最多生成 `1024` 个ID
- snowflake_epoc 默认起始时间为 `2021-01-01T00:00:00Z`, 按默认配置可以支持 `69 年` 大约可以使用到 `2090-09-07 15:47:35Z`
- data_machine_bits 对应的是 snowflake 定义中的 WorkerID 和 DatacenterID 的集合，插件会为每一个进程分配一个唯一 ID，最大支持进程数为 `pow(2, data_machine_bits)`。默认占 `12 bits` 最多支持 `4096` 个进程。
- sequence_bits 默认占 `10 bits`, 每个进程每毫秒最多生成 `1024` 个 ID
#### 配置示例
@ -104,9 +104,9 @@ plugin_attr:
- snowflake 原版配置
> - 起始时间 2014-10-20T15:00:00.000Z， 精确到毫秒为单位。大约可以使用 `69年`
> - 起始时间 2014-10-20T15:00:00.000Z， 精确到毫秒为单位。大约可以使用 `69 年`
> - 最多支持 `1024` 个进程
> - 每个进程每毫秒最多产生 `4096` 个ID
> - 每个进程每毫秒最多产生 `4096` 个 ID
```yaml
plugin_attr:

18
docs/zh/latest/plugins/request-validation.md
View File

@ -29,7 +29,7 @@ title: request-validation
## 属性
> 注意, `header_schema` 与 `body_schema` 至少填写其中一个
> 注意，`header_schema` 与 `body_schema` 至少填写其中一个
| Name | Type | Requirement | Default | Valid | Description |
| ---------------- | ------ | ----------- | ------- | ----- | --------------------------------- |
@ -100,7 +100,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
## 示例
**枚举（Enums）验证:**
**枚举（Enums）验证：**
```json
{
@ -118,7 +118,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
```
**布尔（Boolean）验证:**
**布尔（Boolean）验证：**
```json
{
@ -135,7 +135,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
```
**数字范围（Number or Integer）验证:**
**数字范围（Number or Integer）验证：**
```json
{
@ -153,7 +153,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
```
**字符串长度（String）验证:**
**字符串长度（String）验证：**
```json
{
@ -171,7 +171,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
```
**正则表达式（Regex）验证:**
**正则表达式（Regex）验证：**
```json
{
@ -190,7 +190,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
```
**数组（Array）验证:**
**数组（Array）验证：**
```json
{
@ -214,7 +214,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
```
**多字段组合（Multiple Fields）验证:**
**多字段组合（Multiple Fields）验证：**
```json
{
@ -247,7 +247,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}
```
**自定义拒绝信息:**
**自定义拒绝信息：**
```json
{

6
docs/zh/latest/plugins/response-rewrite.md
View File

@ -27,9 +27,9 @@ title: response-rewrite
使用场景：
1、可以设置 `Access-Control-Allow-*` 等 header 信息，来实现 CORS （跨域资源共享）的功能。
1. 可以设置 `Access-Control-Allow-*` 等 header 信息，来实现 CORS（跨域资源共享）的功能。
2、另外也可以通过配置 status_code 和 header 里面的 Location 来实现重定向，当然如果只是需要重定向功能，最好使用 [redirect](redirect.md) 插件。
2. 另外也可以通过配置 status_code 和 header 里面的 Location 来实现重定向，当然如果只是需要重定向功能，最好使用 [redirect](redirect.md) 插件。
## 属性
@ -82,7 +82,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
curl -X GET -i http://127.0.0.1:9080/test/index.html
```
如果看到返回的头部信息和内容都被修改了，即表示 `response-rewrite` 插件生效了,`vars` 将确保仅覆盖状态为 200 的响应。
如果看到返回的头部信息和内容都被修改了，即表示 `response-rewrite` 插件生效了，`vars` 将确保仅覆盖状态为 200 的响应。
```shell
HTTP/1.1 200 OK

12
docs/zh/latest/plugins/rocketmq-logger.md
View File

@ -40,14 +40,14 @@ title: rocketmq-logger
| tag | string | 可选 | | | 发送消息的 tags 。 |
| timeout | integer | 可选 | 3 | [1,...] | 发送数据的超时时间。 |
| use_tls | boolean | 可选 | false | | 是否开启 TLS 加密。 |
| access_key | string | 可选 | "" | | ACL认证的 access key ，空字符串表示不开启 ACL 。 |
| secret_key | string | 可选 | "" | | ACL认证的 secret key 。 |
| access_key | string | 可选 | "" | | ACL 认证的 access key ，空字符串表示不开启 ACL 。 |
| secret_key | string | 可选 | "" | | ACL 认证的 secret key 。 |
| name | string | 可选 | "rocketmq logger" | | batch processor 的唯一标识。 |
| meta_format | enum | 可选 | "default" | ["default"，"origin"] | `default`：获取请求信息以默认的 JSON 编码方式。`origin`：获取请求信息以 HTTP 原始请求方式。[具体示例](#meta_format-参考示例)|
| include_req_body | boolean | 可选 | false | [false, true] | 是否包括请求 body 。false ： 表示不包含请求的 body ；true ： 表示包含请求的 body 。注意：如果请求 body 没办法完全放在内存中，由于 Nginx 的限制，我们没有办法把它记录下来。|
| include_req_body_expr | array | 可选 | | | 当 `include_req_body` 开启时, 基于 [lua-resty-expr](https://github.com/api7/lua-resty-expr) 表达式的结果进行记录。如果该选项存在，只有在表达式为真的时候才会记录请求 body 。 |
| include_req_body_expr | array | 可选 | | | 当 `include_req_body` 开启时，基于 [lua-resty-expr](https://github.com/api7/lua-resty-expr) 表达式的结果进行记录。如果该选项存在，只有在表达式为真的时候才会记录请求 body 。 |
| include_resp_body| boolean | 可选 | false | [false, true] | 是否包括响应体。包含响应体，当为 `true` 。 |
| include_resp_body_expr | array | 可选 | | | 是否采集响体, 基于[lua-resty-expr](https://github.com/api7/lua-resty-expr)。 该选项需要开启 `include_resp_body` |
| include_resp_body_expr | array | 可选 | | | 是否采集响体，基于 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 该选项需要开启 `include_resp_body` |
本插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解或自定义批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。
@ -118,7 +118,7 @@ title: rocketmq-logger
### Nameserver 列表
配置多个nameserver地址如下：
配置多个 nameserver 地址如下：
```json
[
@ -152,7 +152,7 @@ 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

2
docs/zh/latest/plugins/server-info.md
View File

@ -64,7 +64,7 @@ plugins: # plugin list
| 名称 | 类型 | 默认值 | 描述 |
| --------------- | ------- | ------ | --------------------------------------------------------------- |
| report_ttl | integer | 36 | etcd 中服务信息保存的 TTL（单位：秒，最大值：86400，最小值：3） |
| report_ttl | integer | 36 | etcd 中服务信息保存的 TTL（单位：秒，最大值：86400，最小值：3）|
下面的例子将 `report_ttl` 修改成了 1 分钟：

2
docs/zh/latest/plugins/serverless.md
View File

@ -68,7 +68,7 @@ ngx.say(count)
### 启动插件
下面是一个示例，在指定的 route 上开启了 serverless 插件:
下面是一个示例，在指定的 route 上开启了 serverless 插件：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

2
docs/zh/latest/plugins/skywalking-logger.md
View File

@ -64,7 +64,7 @@ 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

16
docs/zh/latest/plugins/skywalking.md
View File

@ -46,7 +46,7 @@ plugins:
然后重载 APISIX，这样会创建一个后台定时器，向 SkyWalking OAP 服务定期上报数据。
下面是一个示例，在指定的 route 上开启了 SkyWalking 插件:
下面是一个示例，在指定的 route 上开启了 SkyWalking 插件：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -80,11 +80,11 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
| 名称 | 类型 | 默认值 | 描述 |
| ------------ | ------ | -------- | ----------------------------------------------------- |
| service_name | string | "APISIX" | SkyWalking 上报的 service 名称 |
| service_instance_name | string | "APISIX Instance Name" | SkyWalking 上报的 service 实例名, 如果期望直接获取本机主机名则设置为 `$hostname` |
| service_instance_name | string | "APISIX Instance Name" | SkyWalking 上报的 service 实例名，如果期望直接获取本机主机名则设置为 `$hostname` |
| endpoint_addr | string | "http://127.0.0.1:12800" | SkyWalking 的 HTTP endpoint 地址，例如：http://127.0.0.1:12800 |
| report_interval | integer | 使用 SkyWalking 客户端内置的值 | 上报时间间隔，单位是秒|
| report_interval | integer | 使用 SkyWalking 客户端内置的值 | 上报时间间隔，单位是秒 |
配置示例:
配置示例：
```yaml
plugin_attr:
@ -98,9 +98,9 @@ plugin_attr:
### 运行 SkyWalking 实例
#### 例子:
#### 例子：
1. 启动 SkyWalking OAP 服务:
1. 启动 SkyWalking OAP 服务：
- SkyWalking 默认使用 H2 存储，可直接启动
```shell
@ -114,7 +114,7 @@ plugin_attr:
sudo docker run -d --name elasticsearch -p 9200:9200 -p 9300:9300 --restart always -e "discovery.type=single-node" elasticsearch:6.7.2
```
2. 【可选】安装 ElasticSearch 管理界面 elasticsearch-hq
2.【可选】安装 ElasticSearch 管理界面 elasticsearch-hq
```shell
sudo docker run -d --name elastic-hq -p 5000:5000 --restart always elastichq/elasticsearch-hq
@ -138,7 +138,7 @@ plugin_attr:
![plugin_skywalking](../../../assets/images/plugin/skywalking-3.png)
3. 测试示例:
3. 测试示例：
- 通过访问 APISIX，访问上游服务
```bash

22
docs/zh/latest/plugins/sls-logger.md
View File

@ -23,7 +23,7 @@ title: sls-logger
## 描述
`sls-logger` 是使用 [RF5424](https://tools.ietf.org/html/rfc5424) 标准将日志数据以JSON格式发送到 [阿里云日志服务](https://help.aliyun.com/document_detail/112903.html?spm=a2c4g.11186623.6.763.21321b47wcwt1u)。
`sls-logger` 是使用 [RF5424](https://tools.ietf.org/html/rfc5424) 标准将日志数据以 JSON 格式发送到 [阿里云日志服务](https://help.aliyun.com/document_detail/112903.html?spm=a2c4g.11186623.6.763.21321b47wcwt1u)。
该插件提供了将 Log Data 作为批处理推送到阿里云日志服务器的功能。如果您没有收到日志数据，请放心一些时间，它会在我们的批处理处理器中的计时器功能到期后自动发送日志。
@ -32,17 +32,17 @@ title: sls-logger
## 属性
|属性名称 |必选项 |描述|
| 属性名称 | 必选项 | 描述 |
|--------- |--------|-----------|
| host |必要的| TCP 服务的 IP 地址或主机名，请参考：[阿里云日志服务列表](https://help.aliyun.com/document_detail/29008.html?spm=a2c4g.11186623.2.14.49301b4793uX0z#reference-wgx-pwq-zdb)，建议配置 IP 取代配置域名。|
| port |必要的| 目标端口，阿里云日志服务默认端口为 10009。|
| timeout |可选的|发送数据超时间。|
| project |必要的|日志服务 Project 名称，请提前在阿里云日志服务中创建 Project。|
| logstore | 必须的 |日志服务 Logstore 名称，请提前在阿里云日志服务中创建 Logstore。|
| host | 必要的 | TCP 服务的 IP 地址或主机名，请参考：[阿里云日志服务列表](https://help.aliyun.com/document_detail/29008.html?spm=a2c4g.11186623.2.14.49301b4793uX0z#reference-wgx-pwq-zdb)，建议配置 IP 取代配置域名。|
| port | 必要的 | 目标端口，阿里云日志服务默认端口为 10009。|
| timeout | 可选的 | 发送数据超时间。|
| project | 必要的 | 日志服务 Project 名称，请提前在阿里云日志服务中创建 Project。|
| logstore | 必须的 | 日志服务 Logstore 名称，请提前在阿里云日志服务中创建 Logstore。|
| access_key_id | 必须的 | AccessKey ID。建议使用阿里云子账号 AK，详情请参见 [授权](https://help.aliyun.com/document_detail/47664.html?spm=a2c4g.11186623.2.15.49301b47lfvxXP#task-xsk-ttc-ry)。|
| access_key_secret | 必须的 | AccessKey Secret。建议使用阿里云子账号 AK，详情请参见 [授权](https://help.aliyun.com/document_detail/47664.html?spm=a2c4g.11186623.2.15.49301b47lfvxXP#task-xsk-ttc-ry)。|
| include_req_body | 可选的| 是否包含请求体。|
|name| 可选的|批处理名字。|
| include_req_body | 可选的 | 是否包含请求体。|
|name| 可选的 | 批处理名字。|
本插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解或自定义批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。
@ -75,12 +75,12 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
```
```
注释:这里的 100.100.99.135 是阿里云华北 3 内外地址。
注释：这里的 100.100.99.135 是阿里云华北 3 内外地址。
```
## 测试插件
* 成功的情况:
* 成功的情况：
```shell
$ curl -i http://127.0.0.1:9080/hello

8
docs/zh/latest/plugins/splunk-hec-logging.md
View File

@ -33,11 +33,11 @@ title: splunk-hec-logging
| 名称 | 是否必需 | 默认值 | 描述 |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| endpoint | 必选 | | Splunk HEC 端点配置信息 |
| endpoint.uri | 必选 | | Splunk HEC 事件收集API |
| endpoint.uri | 必选 | | Splunk HEC 事件收集 API |
| endpoint.token | 必选 | | Splunk HEC 身份令牌 |
| endpoint.channel | 可选 | | Splunk HEC 发送渠道标识，参考：[About HTTP Event Collector Indexer Acknowledgment](https://docs.splunk.com/Documentation/Splunk/8.2.3/Data/AboutHECIDXAck) |
| endpoint.timeout | 可选 | 10 | Splunk HEC 数据提交超时时间（以秒为单位） |
| ssl_verify | 可选 | true | 启用 `SSL` 验证, 参考：[OpenResty文档](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake) |
| endpoint.timeout | 可选 | 10 | Splunk HEC 数据提交超时时间（以秒为单位）|
| ssl_verify | 可选 | true | 启用 `SSL` 验证，参考：[OpenResty 文档](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake) |
本插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解或自定义批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。
@ -109,7 +109,7 @@ HTTP/1.1 200 OK
hello, world
```
* 登录Splunk控制台检索查看日志
* 登录 Splunk 控制台检索查看日志
![splunk hec search view](../../../assets/images/plugin/splunk-hec-admin-cn.png)

10
docs/zh/latest/plugins/syslog.md
View File

@ -31,13 +31,13 @@ title: syslog
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ---------------- | ------- | ------ | ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| host | string | 必须 | | | IP地址或主机名 |
| host | string | 必须 | | | IP 地址或主机名 |
| port | integer | 必须 | | | 目标上游端口 |
| name | string | 可选 | "sys logger" | | |
| timeout | integer | 可选 | 3 | [1, ...] | 上游发送数据超时 |
| tls | boolean | 可选 | false | | 用于控制是否执行SSL验证 |
| flush_limit | integer | 可选 | 4096 | [1, ...] | 如果缓冲的消息的大小加上当前消息的大小达到（> =）此限制（以字节为单位），则缓冲的日志消息将被写入日志服务器。默认为4096（4KB） |
| drop_limit | integer | 可选 | 1048576 | | 如果缓冲的消息的大小加上当前消息的大小大于此限制（以字节为单位），则由于缓冲区大小有限，当前的日志消息将被丢弃。默认为1048576（1MB） |
| tls | boolean | 可选 | false | | 用于控制是否执行 SSL 验证 |
| flush_limit | integer | 可选 | 4096 | [1, ...] | 如果缓冲的消息的大小加上当前消息的大小达到（> =）此限制（以字节为单位），则缓冲的日志消息将被写入日志服务器。默认为 4096（4KB）|
| drop_limit | integer | 可选 | 1048576 | | 如果缓冲的消息的大小加上当前消息的大小大于此限制（以字节为单位），则由于缓冲区大小有限，当前的日志消息将被丢弃。默认为 1048576（1MB）|
| sock_type | string | 可选 | "tcp" | ["tcp","udp"] | 用于传输层的 IP 协议类型。 |
| max_retry_times | integer | 可选 | | [1, ...] | 已废弃。请改用 `max_retry_count`。连接到日志服务器失败或将日志消息发送到日志服务器失败后的最大重试次数。 |
| retry_interval | integer | 可选 | | [0, ...] | 已废弃。请改用 `retry_delay`。重试连接到日志服务器或重试向日志服务器发送日志消息之前的时间延迟（以毫秒为单位）。 |
@ -72,7 +72,7 @@ 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

2
docs/zh/latest/plugins/tcp-logger.md
View File

@ -73,7 +73,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
## 测试插件
* 成功的情况:
* 成功的情况：
```shell
$ curl -i http://127.0.0.1:9080/hello

28
docs/zh/latest/plugins/traffic-split.md
View File

@ -30,21 +30,21 @@ traffic-split 插件使用户可以逐步引导各个上游之间的流量百分
## 属性
| 参数名 | 类型 | 可选项 | 默认值 | 有效值 | 描述 |
| ---------------------- | --------------| ------ | ------ | ------ | -------------------- |
| ---------------------- | --------------| ------ | ------ | ------ |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| rules.match | array[object] | 可选 | | | 匹配规则列表，默认为空且规则将被无条件执行。 |
| rules.match.vars | array[array] | 可选 | | | 由一个或多个{var, operator, val}元素组成的列表，类似这样：{{var, operator, val}, {var, operator, val}, ...}}。例如：{"arg_name", "==", "json"}，表示当前请求参数 name 是 json。这里的 var 与 Nginx 内部自身变量命名是保持一致，所以也可以使用 request_uri、host 等；对于 operator 部分，目前已支持的运算符有 ==、~=、~~、>、<、in、has 和 ! 。操作符的具体用法请看 [lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) 的 `operator-list` 部分。 |
| rules.weighted_upstreams | array[object] | 可选 | | | 上游配置规则列表。 |
| weighted_upstreams.upstream_id | string / integer | 可选 | | | 通过上游 id 绑定对应上游。 |
| weighted_upstreams.upstream | object | 可选 | | | 上游配置信息。 |
| upstream.type | enum | 可选 | roundrobin | [roundrobin, chash] | roundrobin 支持权重的负载，chash 一致性哈希，两者是二选一。 |
| upstream.hash_on | enum | 可选 | vars | | `hash_on` 支持的类型有 `vars`（Nginx 内置变量），`header`（自定义 header），`cookie`，`consumer`，`vars_combinations`，默认值为 `vars`。更多详细信息请参考 [upstream](../admin-api.md#upstream) 用法。|
| upstream.hash_on | enum | 可选 | vars | | `hash_on` 支持的类型有 `vars`（Nginx 内置变量），`header`（自定义 header），`cookie`，`consumer`，`vars_combinations`，默认值为 `vars`。更多详细信息请参考 [upstream](../admin-api.md#upstream) 用法。 |
| upstream.key | string | 可选 | | | 该选项只有类型是 `chash` 才有效。根据 `key` 来查找对应的 node `id`，相同的 `key` 在同一个对象中，永远返回相同 id。更多详细信息请参考 [upstream](../admin-api.md#upstream) 用法。 |
| upstream.nodes | object | 可选 | | | 哈希表，内部元素的 key 是上游机器地址 列表，格式为地址 + Port，其中地址部 分可以是 IP 也可以是域名，⽐如 192.168.1.100:80、foo.com:80 等。 value 则是节点的权重，特别的，当权重 值为 0 有特殊含义，通常代表该上游节点 失效，永远不希望被选中。 |
| upstream.timeout | object | 可选 | 15 | | 设置连接、发送消息、接收消息的超时时间(时间单位：秒，都默认为 15 秒)。 |
| upstream.pass_host | enum | 可选 | "pass" | ["pass", "node", "rewrite"] | `pass`: 将客户端的 host 透传给上游； `node`: 使用 `upstream` node 中配置的 host； `rewrite`: 使用配置项 `upstream_host` 的值 |
| upstream.timeout | object | 可选 | 15 | | 设置连接、发送消息、接收消息的超时时间（时间单位：秒，都默认为 15 秒）。 |
| upstream.pass_host | enum | 可选 | "pass" | ["pass", "node", "rewrite"] | `pass`：将客户端的 host 透传给上游； `node`：使用 `upstream` node 中配置的 host； `rewrite`：使用配置项 `upstream_host` 的值 |
| upstream.name | string | 可选 | | | 标识上游服务名称、使⽤场景等。 |
| upstream.upstream_host | string | 可选 | | | 只在 pass_host 配置为 rewrite 时有效。 |
| weighted_upstreams.weight | integer | 可选 | weight = 1 | | 根据 `weight` 值做流量划分，多个 weight 之间使用 roundrobin 算法划分。|
| weighted_upstreams.weight | integer | 可选 | weight = 1 | | 根据 `weight` 值做流量划分，多个 weight 之间使用 roundrobin 算法划分。 |
目前在 `weighted_upstreams.upstream` 的配置中，不支持的字段有：
service_name、discovery_type、checks、retries、retry_timeout、desc、scheme、labels、create_time 和 update_time。但是你可以通过 `weighted_upstreams.upstream_id` 绑定 `upstream` 对象来实现他们。
@ -190,7 +190,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
**插件测试:**
**插件测试：**
请求 5 次，3 次请求命中插件 1981 端口的 upstream, 2 次请求命中 `route` 的 1980 端口 upstream。
@ -212,7 +212,7 @@ world 1981
### 蓝绿发布
通过请求头获取 `match` 规则参数(也可以通过请求参数获取 NGINX 变量)，在 `match` 规则匹配通过后，表示所有请求都命中到插件配置的 upstream ，否则所有请求只命中 `route` 上配置的 upstream 。
通过请求头获取 `match` 规则参数 (也可以通过请求参数获取 NGINX 变量)，在 `match` 规则匹配通过后，表示所有请求都命中到插件配置的 upstream ，否则所有请求只命中 `route` 上配置的 upstream 。
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -281,7 +281,7 @@ hello 1980
`match` 中可以设置多个 `vars` 规则，`vars` 中的多个表达式之间是 `and` 的关系， 多个 `vars` 规则之间是 `or` 的关系；只要其中一个 vars 规则通过，则整个 `match` 通过。
**示例1：只配置了一个 `vars` 规则， `vars` 中的多个表达式是 `and` 的关系。在 `weighted_upstreams` 中根据 `weight` 值将流量按 3:2 划分，其中只有 `weight` 值的部分表示 `route` 上的 upstream 所占的比例。 当 `match` 匹配不通过时，所有的流量只会命中 route 上的 upstream 。**
**示例 1：只配置了一个 `vars` 规则， `vars` 中的多个表达式是 `and` 的关系。在 `weighted_upstreams` 中根据 `weight` 值将流量按 3:2 划分，其中只有 `weight` 值的部分表示 `route` 上的 upstream 所占的比例。 当 `match` 匹配不通过时，所有的流量只会命中 route 上的 upstream 。**
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -332,7 +332,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
**插件测试：**
>1、在 `match` 规则校验通过后, 60% 的请求命中到插件的 1981 端口的 upstream, 40% 的请求命中到 `route` 的 1980 端口的 upstream。
>1、在 `match` 规则校验通过后，60% 的请求命中到插件的 1981 端口的 upstream, 40% 的请求命中到 `route` 的 1980 端口的 upstream。
match 规则校验成功， 命中端口为 `1981` 的 upstream。
@ -358,7 +358,7 @@ hello 1980
在请求 5 次后，3 次命中 `1981` 端口的服务，2 次命中 `1980` 端口的服务。
>2、`match` 规则校验失败(缺少请求头 `apisix-key` ), 响应都为默认 upstream 的数据 `hello 1980`。
>2、`match` 规则校验失败 (缺少请求头 `apisix-key` ), 响应都为默认 upstream 的数据 `hello 1980`。
```shell
$ curl 'http://127.0.0.1:9080/index.html?name=jack' -H 'user-id:30' -i
@ -369,7 +369,7 @@ Content-Type: text/html; charset=utf-8
hello 1980
```
**示例2：配置多个 `vars` 规则， `vars` 中的多个表达式是 `and` 的关系， 多个 `vars` 之间是 `or` 的关系。根据 `weighted_upstreams` 中的 `weight` 值将流量按 3:2 划分，其中只有 `weight` 值的部分表示 route 上的 upstream 所占的比例。 当 `match` 匹配不通过时，所有的流量只会命中 route 上的 upstream 。**
**示例 2：配置多个 `vars` 规则， `vars` 中的多个表达式是 `and` 的关系， 多个 `vars` 之间是 `or` 的关系。根据 `weighted_upstreams` 中的 `weight` 值将流量按 3:2 划分，其中只有 `weight` 值的部分表示 route 上的 upstream 所占的比例。 当 `match` 匹配不通过时，所有的流量只会命中 route 上的 upstream 。**
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -427,7 +427,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
**测试插件：**
>1、两个 `vars` 的表达式匹配成功， `match` 规则校验通过后, 60% 的请求命中到插件的1981端口 upstream, 40% 的请求命中到 `route` 的1980端口upstream。
>1、两个 `vars` 的表达式匹配成功， `match` 规则校验通过后，60% 的请求命中到插件的 1981 端口 upstream, 40% 的请求命中到 `route` 的 1980 端口 upstream。
```shell
$ curl 'http://127.0.0.1:9080/index.html?name=jack&name2=rose' -H 'user-id:30' -H 'user-id2:22' -H 'apisix-key: hello' -H 'apisix-key2: world' -i
@ -449,7 +449,7 @@ hello 1980
在请求 5 次后，3 次命中 `1981` 端口的服务，2 次命中 `1980` 端口的服务。
>2、第二个 `vars` 的表达式匹配失败（缺少 `name2` 请求参数），`match` 规则校验通过后, 60% 的请求命中到插件的 1981 端口 upstream, 40% 的请求流量命中到 `route` 的 1980 端口 upstream。
>2、第二个 `vars` 的表达式匹配失败（缺少 `name2` 请求参数），`match` 规则校验通过后，60% 的请求命中到插件的 1981 端口 upstream, 40% 的请求流量命中到 `route` 的 1980 端口 upstream。
```shell
$ curl 'http://127.0.0.1:9080/index.html?name=jack' -H 'user-id:30' -H 'user-id2:22' -H 'apisix-key: hello' -H 'apisix-key2: world' -i
@ -471,7 +471,7 @@ hello 1980
在请求 5 次后，3 次命中 `1981` 端口的服务，2 次命中 `1980` 端口的服务。
>3、两个 `vars` 的表达式校验失败（缺少 `name` 和 `name2` 请求参数），`match` 规则校验失败, 响应都为默认 `route` 的 upstream 数据 `hello 1980`。
>3、两个 `vars` 的表达式校验失败（缺少 `name` 和 `name2` 请求参数），`match` 规则校验失败，响应都为默认 `route` 的 upstream 数据 `hello 1980`。
```shell
$ curl 'http://127.0.0.1:9080/index.html?name=jack' -i

4
docs/zh/latest/plugins/ua-restriction.md
View File

@ -38,7 +38,7 @@ title: ua-restriction
## 如何启用
下面是一个示例，在指定的 route 上开启了 `ua-restriction` 插件:
下面是一个示例，在指定的 route 上开启了 `ua-restriction` 插件：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -66,7 +66,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
当未允许的 User-Agent 访问时，默认返回 `{"message":"Not allowed"}`。如果你想使用自定义的 `message`，可以在插件部分进行配置:
当未允许的 User-Agent 访问时，默认返回 `{"message":"Not allowed"}`。如果你想使用自定义的 `message`，可以在插件部分进行配置：
```json
"plugins": {

2
docs/zh/latest/plugins/udp-logger.md
View File

@ -71,7 +71,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
## 测试插件
* 成功的情况:
* 成功的情况：
```shell
$ curl -i http://127.0.0.1:9080/hello

2
docs/zh/latest/plugins/uri-blocker.md
View File

@ -29,7 +29,7 @@ title: uri-blocker
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ------------- | ------------- | ------ | ------ | ---------- | ------------------------------------------------------------------- |
| block_rules | array[string] | 必须 | | | 正则过滤数组。它们都是正则规则，如果当前请求 URI 命中任何一个，请将响应代码设置为 rejected_code 以退出当前用户请求。例如: `["root.exe", "root.m+"]`。 |
| block_rules | array[string] | 必须 | | | 正则过滤数组。它们都是正则规则，如果当前请求 URI 命中任何一个，请将响应代码设置为 rejected_code 以退出当前用户请求。例如：`["root.exe", "root.m+"]`。 |
| rejected_code | integer | 可选 | 403 | [200, ...] | 当请求 URI 命中 `block_rules` 中的任何一个时，将返回的 HTTP 状态代码。 |
| rejected_msg | string | 可选 | | 非空 | 当请求 URI 命中 `block_rules` 中的任何一个时，将返回的 HTTP 响应体。 |
| case_insensitive | boolean | 可选 | false | | 是否忽略大小写。当值为 true 时，在匹配请求 URI 时将忽略大小写。默认值是 false 。 |

24
docs/zh/latest/plugins/wolf-rbac.md
View File

@ -23,16 +23,16 @@ title: wolf-rbac
## 描述
`wolf-rbac` 是一个认证及授权(rbac)插件，它需要与 `consumer` 一起配合才能工作。同时需要添加 `wolf-rbac` 到一个 `service` 或 `route` 中。
rbac 功能由 [wolf](https://github.com/iGeeky/wolf) 提供, 有关 `wolf` 的更多信息, 请参考 [wolf 文档](https://github.com/iGeeky/wolf)。
`wolf-rbac` 是一个认证及授权 (rbac) 插件，它需要与 `consumer` 一起配合才能工作。同时需要添加 `wolf-rbac` 到一个 `service` 或 `route` 中。
rbac 功能由 [wolf](https://github.com/iGeeky/wolf) 提供，有关 `wolf` 的更多信息，请参考 [wolf 文档](https://github.com/iGeeky/wolf)。
## 属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ------------- | ------ | ------ | ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| server | string | 可选 | "http://127.0.0.1:12180" | | 设置 `wolf-server` 的访问地址 |
| appid | string | 可选 | "unset" | | 设置应用 id, 该应用 id, 需要是在 `wolf-console` 中已经添加的应用 id |
| header_prefix | string | 可选 | "X-" | | 自定义 http 头的前缀。`wolf-rbac`在鉴权成功后, 会在请求头(用于传给后端)及响应头(用于传给前端)中添加 3 个头: `X-UserId`, `X-Username`, `X-Nickname` |
| appid | string | 可选 | "unset" | | 设置应用 id，该应用 id，需要是在 `wolf-console` 中已经添加的应用 id |
| header_prefix | string | 可选 | "X-" | | 自定义 http 头的前缀。`wolf-rbac`在鉴权成功后，会在请求头 (用于传给后端) 及响应头 (用于传给前端) 中添加 3 个头：`X-UserId`, `X-Username`, `X-Nickname` |
## 接口
@ -46,11 +46,11 @@ rbac 功能由 [wolf](https://github.com/iGeeky/wolf) 提供, 有关 `wolf` 的
## 依赖项
### 安装 wolf, 并启动服务
### 安装 wolf，并启动服务
[Wolf 快速起步](https://github.com/iGeeky/wolf/blob/master/quick-start-with-docker/README-CN.md)
### 添加应用, 管理员, 普通用户, 权限, 资源 及给用户授权.
### 添加应用，管理员，普通用户，权限，资源 及给用户授权
[Wolf 管理使用](https://github.com/iGeeky/wolf/blob/master/docs/usage.md)
@ -78,7 +78,7 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f
然后在 consumer 页面中添加 wolf-rbac 插件：
![enable wolf-rbac plugin](../../../assets/images/plugin/wolf-rbac-2.png)
注意: 上面填写的 `appid` 需要在 wolf 控制台中已经存在的.
注意：上面填写的 `appid` 需要在 wolf 控制台中已经存在的。
2. 创建 Route 或 Service 对象，并开启 `wolf-rbac` 插件。
@ -119,10 +119,10 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/wal -H 'X-API-KEY: edd1c9f03433
#### 首先进行登录获取 `wolf-rbac` token:
下面的 `appid`, `username`, `password` 必须为 wolf 系统中真实存在的.
`authType` 为认证类型, `1` 为密码认证, `2` 为 `LDAP` 认证. 默认为 `1`. `wolf` 从 0.5.0 版本开始支持了 `LDAP` 认证.
下面的 `appid`, `username`, `password` 必须为 wolf 系统中真实存在的。
`authType` 为认证类型，`1` 为密码认证，`2` 为 `LDAP` 认证。默认为 `1`. `wolf` 从 0.5.0 版本开始支持了 `LDAP` 认证。
* 以 POST application/json 方式登陆.
* 以 POST application/json 方式登陆。
```shell
curl http://127.0.0.1:9080/apisix/plugin/wolf-rbac/login -i \
@ -158,7 +158,7 @@ HTTP/1.1 401 Unauthorized
{"message":"Missing rbac token in request"}
```
* token 放到请求头(Authorization)中：
* token 放到请求头 (Authorization) 中：
```shell
curl http://127.0.0.1:9080/ -H"Host: www.baidu.com" \
@ -169,7 +169,7 @@ HTTP/1.1 200 OK
<!DOCTYPE html>
```
* token 放到请求头(x-rbac-token)中：
* token 放到请求头 (x-rbac-token) 中：
```shell
curl http://127.0.0.1:9080/ -H"Host: www.baidu.com" \

8
docs/zh/latest/plugins/zipkin.md
View File

@ -23,7 +23,7 @@ title: zipkin
## 描述
[Zipkin](https://github.com/openzipkin/zipkin) 是一个开源的分布调用链追踪系统。该插件基于[Zipkin API规范](https://zipkin.io/pages/instrumenting.html)，支持收集跟踪信息，并上报 Zipkin Collector。
[Zipkin](https://github.com/openzipkin/zipkin) 是一个开源的分布调用链追踪系统。该插件基于[Zipkin API 规范](https://zipkin.io/pages/instrumenting.html)，支持收集跟踪信息，并上报 Zipkin Collector。
> 它还能够与适配了 Zipkin [v1](https://zipkin.io/zipkin-api/zipkin-api.yaml)/[v2](https://zipkin.io/zipkin-api/zipkin2-api.yaml) 的 [Apache SkyWalking](https://skywalking.apache.org/docs/main/latest/en/setup/backend/zipkin-trace/#zipkin-receiver) 和 [Jaeger](https://www.jaegertracing.io/docs/1.31/getting-started/#migrating-from-zipkin)。当然，它也能够与其它支持 Zipkin v1/v2 数据格式的调用链追踪系统集成。
@ -61,7 +61,7 @@ request
## 如何启用
下面是一个示例，在指定的 route 上开启了 zipkin 插件:
下面是一个示例，在指定的 route 上开启了 zipkin 插件：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@ -99,7 +99,7 @@ e.g. 用 docker:
docker run -d -p 9411:9411 openzipkin/zipkin
```
测试示例:
测试示例：
```shell
curl http://127.0.0.1:9080/index.html
@ -186,7 +186,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
现在就已经移除了 Zipkin 插件了。其他插件的开启和移除也是同样的方法。
## 上游服务是Golang的示例代码
## 上游服务是 Golang 的示例代码
```golang
func GetTracer(serviceName string, port int, enpoitUrl string, rate float64) *zipkin.Tracer {

10
docs/zh/latest/router-radixtree.md
View File

@ -55,7 +55,7 @@ title: 路由 RadixTree
完全匹配 -> 深度前缀匹配
以下是规则:
以下是规则：
```text
/blog/foo/*
@ -110,7 +110,7 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/2 -H 'X-API-KEY: edd1c9f034335f
}'
```
测试:
测试：
```shell
curl http://127.0.0.1:1980/hello
@ -151,7 +151,7 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/2 -H 'X-API-KEY: edd1c9f034335f
}'
```
测试:
测试：
```shell
$ curl http://127.0.0.1:9080/hello -H 'host: localhost.com'
@ -168,7 +168,7 @@ $ curl http://127.0.0.1:9080/hello
{"error_msg":"404 Route Not Found"}
```
`host` 规则匹配，请求命中对应的上游，`host` 不匹配，请求返回404消息。
`host` 规则匹配，请求命中对应的上游，`host` 不匹配，请求返回 404 消息。
#### 5. 参数匹配
@ -194,7 +194,7 @@ apisix:
### 如何通过 Nginx 内置变量过滤路由
具体参数及使用方式请查看 [radixtree#new](https://github.com/api7/lua-resty-radixtree#new) 文档，下面是一个简单的示例:
具体参数及使用方式请查看 [radixtree#new](https://github.com/api7/lua-resty-radixtree#new) 文档，下面是一个简单的示例：
```shell
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '

8
docs/zh/latest/stream-proxy.md
View File

@ -23,9 +23,9 @@ title: TCP/UDP 动态代理
众多的闻名的应用和服务，像 LDAP、 MYSQL 和 RTMP ，选择 TCP 作为通信协议。 但是像 DNS、 syslog 和 RADIUS 这类非事务性的应用，他们选择了 UDP 协议。
APISIX 可以对 TCP/UDP 协议进行代理并实现动态负载均衡。 在 nginx 世界，称 TCP/UDP 代理为 stream 代理，在 APISIX 这里我们也遵循了这个声明.
APISIX 可以对 TCP/UDP 协议进行代理并实现动态负载均衡。 在 nginx 世界，称 TCP/UDP 代理为 stream 代理，在 APISIX 这里我们也遵循了这个声明。
## 如何开启 Stream 代理?
## 如何开启 Stream 代理
在 `conf/config.yaml` 配置文件设置 `stream_proxy` 选项， 指定一组需要进行动态代理的 IP 地址。默认情况不开启 stream 代理。
@ -53,9 +53,9 @@ apisix:
- 9100
```
## 如何设置 route ?
## 如何设置 route
简例如下:
简例如下：
```shell
curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '