You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2021/07/09 07:47:30 UTC
[GitHub] [apisix] yzeng25 opened a new pull request #4577: docs: update CN how-to-build document
yzeng25 opened a new pull request #4577:
URL: https://github.com/apache/apisix/pull/4577
### What this PR does / why we need it:
<!--- Why is this change required? What problem does it solve? -->
This PR provides updates on the 'how-to-build' document in Chinese:
1. Changed the order of installation methods listed in ”2. 安装 Apache APISIX“, because the order was not the same as what were listed in the description, it should be in this order: 1. "通过源码包安装" --> 2. "通过RPM 包安装" --> 3. "通过Docker安装"--> 4. "通过Helm Chart安装". **In addition, it seems like the other method "Luarocks" is missing.**
2. Refactored steps in"通过源码包安装", the steps were blended in two code blocks, they could be split to 5 steps and be clearer.
3. Wrapped up hyperlinks for Docker installation ("通过 Docker 安装") and Helm Chart installation sections(("通过 Helm Chart 安装") for better user experience.
4. Refactored "管理（启动、关闭等）APISIX 服务". Described the difference between `make quit` and `make stop`, and suggested to use `make quit` rather than `make stop`.
5. Other minor mistakes fixes: removals of `$` sign in the beginning of each code block, changes of '```' to '```shell' in the beginning of each code block.
TODO:
1. Update CN how-to-build document based on review comments.
2. Update EN how-to-build document based CN how-to-build document.
3. Update EN how-to-build document based on review comments again.
<!--- If it fixes an open issue, please link to the issue here. -->
### Pre-submission checklist:
* [ ] Did you explain what problem does this PR solve? Or what new features have been added?
* [ ] Have you added corresponding test cases?
* [ ] Have you modified the corresponding document?
* [ ] Is this PR backward compatible? **If it is not backward compatible, please discuss on the [mailing list](https://github.com/apache/apisix/tree/master#community) first**
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667621813
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
* 追加当前目录到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`
* 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
-### 疑难排解测试
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
+
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
* Linux 默认安装路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
+ * MacOS X 通过 homebrew 默认安装路径：
* export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API token
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 token，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的token修改为abcdefghabcdefgh
role: admin
```
当我们需要访问 Admin API 时，就可以使用上面记录的 key 作为 token 了。
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
HTTP/1.1 200 OK
Date: Fri, 28 Feb 2020 07:48:04 GMT
Content-Type: text/plain
... ...
{"node":{...},"action":"get"}
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh-invalid -i
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh-invalid -i
HTTP/1.1 401 Unauthorized
Date: Fri, 28 Feb 2020 08:17:58 GMT
Content-Type: text/html
... ...
{"node":{...},"action":"get"}
```
-## 6. 为 APISIX 构建 OpenResty
+## 步骤6：为 APISIX 构建 OpenResty
-有些功能需要你引入额外的 Nginx 模块到 OpenResty 当中。
-如果你需要这些功能，你可以用[这个脚本](https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-openresty.sh)
-构建 OpenResty。
+有些功能需要引入额外的 Nginx 模块到 OpenResty 当中。如果您需要这些功能，你可以用[这个脚本](https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-openresty.sh)构建 OpenResty。
-## 7. 为 APISIX 添加 systemd 配置文件
+## 步骤7：为 APISIX 添加 systemd 配置文件
-如果通过 rpm 包安装 APISIX，配置文件已经自动安装到位，你可以直接运行
+如果您使用的操作系统是 CentOS 7，且在步骤 2 中通过 RPM 包安装 APISIX，配置文件已经自动安装到位，你可以直接运行以下命令：
-```
-$ systemctl start apisix
-$ systemctl stop apisix
-$ systemctl enable apisix
+```shell
+systemctl start apisix
+systemctl stop apisix
Review comment:
ok :)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667598535
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
Review comment:
Do we need to attach this link for further downloading?
https://apisix.apache.org/downloads/
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
Review comment:
should we use `ETCD` instead of `etcd`?
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
Review comment:
```suggestion
### 启动 Apache APISIX
```
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
* 追加当前目录到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`
* 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
-### 疑难排解测试
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
+
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
* Linux 默认安装路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
+ * MacOS X 通过 homebrew 默认安装路径：
* export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API token
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 token，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的token修改为abcdefghabcdefgh
Review comment:
```suggestion
key: abcdefghabcdefgh # 将原有的 token 修改为abcdefghabcdefgh
```
Why use token here? 🤔 it's a key from that field
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
Review comment:
```suggestion
优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 Apache APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
```
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
Review comment:
```suggestion
### 停止运行 Apache APISIX
```
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
* 追加当前目录到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`
* 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
-### 疑难排解测试
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
+
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
* Linux 默认安装路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
+ * MacOS X 通过 homebrew 默认安装路径：
* export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API token
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 token，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的token修改为abcdefghabcdefgh
role: admin
```
当我们需要访问 Admin API 时，就可以使用上面记录的 key 作为 token 了。
Review comment:
🤔 Why not use `Ket` directly?
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
Review comment:
```suggestion
3. 然后克隆最新的源码，请使用我们 fork 出来的版本：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667615863
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
Review comment:
ditto
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r668460434
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
Review comment:
> NGINX needs uppercase
Fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] spacewander merged pull request #4577: docs: update CN and EN how-to-build document
Posted by GitBox <gi...@apache.org>.
spacewander merged pull request #4577:
URL: https://github.com/apache/apisix/pull/4577
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN and EN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r669337981
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 NGINX 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 上的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 NGINX 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的目录。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache APISIX Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache APISIX Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
+
+3. 解压 Apache APISIX Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 目录
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 Apache APISIX 服务
+
+我们可以在 Apache APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-你需要先下载 Apache Release 源码包：
+### 初始化依赖
+
+运行以下命令初始化 NGINX 配置文件和 etcd。
```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+# initialize NGINX config file and etcd
+make init
```
-安装运行时依赖的 Lua 库：
+### 启动 Apache APISIX
+运行以下命令启动 Apache APISIX。
+
+```shell
+# start Apache APISIX server
+make run
```
-cd apisix-2.7
-make deps
-```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 停止运行 Apache APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 Apache APISIX。建议您优先选择优雅停机的方式停止 Apache APISIX，因为这种停止方式能够保证 Apache APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 Apache APISIX，在这种情况下，Apache APISIX 接收到但未完成的请求会随着强制停机一并停止。
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+执行优雅停机的命令如下所示：
```shell
-# init nginx config file and etcd
-$ make init
+# stop Apache APISIX server gracefully
+make quit
+```
-# start APISIX server
-$ make run
+执行强制停机的命令如下所示：
-# stop APISIX server gracefully
-$ make quit
+```shell
+# stop Apache APISIX server immediately
+make stop
+```
+
+### 查看其他操作
-# stop APISIX server immediately
-$ make stop
+运行 `make help` 命令，查看返回结果，获取其他操作的命令和描述。
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
- * 追加当前目录到perl模块目录： `export PERL5LIB=.:$PERL5LIB`
- * 直接运行：`make test`
- * 指定 nginx 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`
- * 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
-### 疑难排解测试
+3. 运行 `git clone` 命令，将最新的源码克隆到本地，请使用我们 fork 出来的版本：
-**配置 Nginx 路径**
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
-* export PATH=/usr/local/openresty/nginx/sbin:$PATH
+ - 追加当前目录到perl模块目录： `export PERL5LIB=.:$PERL5LIB`，然后运行 `make test` 命令。
+
+ - 或指定 NGINX 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`。
+
+ :::note 说明
+ 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
+ :::
+
+### 问题排查
+
+**配置 NGINX 路径**
+
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
+
+确保将 Openresty 设置为默认的 NGINX，并按如下所示导出路径：
+
+* `export PATH=/usr/local/openresty/nginx/sbin:$PATH`
* Linux 默认安装路径：
- * export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
- * export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
+ * `export PATH=/usr/local/openresty/nginx/sbin:$PATH`
+ * MacOS 通过 homebrew 默认安装路径：
+ * `export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH`
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API key
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 key，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的 key 修改为abcdefghabcdefgh
role: admin
```
-当我们需要访问 Admin API 时，就可以使用上面记录的 key 作为 token 了。
+当我们需要访问 Admin API 时，就可以使用上面记录的 key 了，如下所示：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
+```
+
+返回结果中的状态码 200 说明访问成功，如下所示：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
HTTP/1.1 200 OK
Date: Fri, 28 Feb 2020 07:48:04 GMT
Content-Type: text/plain
... ...
{"node":{...},"action":"get"}
+```
+
+在这个时候，如果您输入的 key 与 `conf/config.yaml` 中 `apisix.admin_key` 的值不匹配，例如，我们已知正确的 key 是 `abcdefghabcdefgh`，但是我们选择输入一个错误的 key，例如 `wrong-key`，如下所示：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=wrong-key -i
+```
+
+返回结果中的状态码 `401` 说明访问失败，原因是输入的 `key` 有误，未通过认证，触发 `Unauthorized` 错误，如下所示：
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh-invalid -i
+```shell
HTTP/1.1 401 Unauthorized
Date: Fri, 28 Feb 2020 08:17:58 GMT
Content-Type: text/html
... ...
{"node":{...},"action":"get"}
```
-## 6. 为 APISIX 构建 OpenResty
+## 步骤6：为 Apache APISIX 构建 OpenResty
-有些功能需要你引入额外的 Nginx 模块到 OpenResty 当中。
-如果你需要这些功能，你可以用[这个脚本](https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-openresty.sh)
-构建 OpenResty。
+有些功能需要引入额外的 NGINX 模块到 OpenResty 当中。如果您需要这些功能，你可以用[这个脚本](https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-openresty.sh)构建 OpenResty。
-## 7. 为 APISIX 添加 systemd 配置文件
+## 步骤7：为 Apache APISIX 添加 systemd 配置文件
-如果通过 rpm 包安装 APISIX，配置文件已经自动安装到位，你可以直接运行
+如果您使用的操作系统是 CentOS 7，且在步骤 2 中通过 RPM 包安装 Apache APISIX，配置文件已经自动安装到位，你可以直接运行以下命令：
-```
-$ systemctl start apisix
-$ systemctl stop apisix
-$ systemctl enable apisix
+```shell
+systemctl start apisix
+systemctl stop apisix
```
-如果通过其他方法安装，可以参考[配置文件模板](https://github.com/api7/apisix-build-tools/blob/master/usr/lib/systemd/system/apisix.service)进行修改，并将其放置在 `/usr/lib/systemd/system/apisix.service`。
+如果通过其他方法安装，可以参考[配置文件模板](https://github.com/api7/apisix-build-tools/blob/master/usr/lib/systemd/system/apisix.service)进行修改，并将其放置在 `/usr/lib/systemd/system/apisix.service`路径下。
Review comment:
fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r668465254
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 Apache APISIX 服务
+
+我们可以在 Apache APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-你需要先下载 Apache Release 源码包：
+### 初始化依赖
+
+运行以下命令初始化 Nginx 配置文件和 etcd。
```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+# init nginx config file and etcd
+make init
```
-安装运行时依赖的 Lua 库：
+### 启动 Apache APISIX
+运行以下命令启动 Apache APISIX。
+
+```shell
+# start Apache APISIX server
+make run
```
-cd apisix-2.7
-make deps
-```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 停止运行 Apache APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 Apache APISIX。建议您优先选择优雅停机的方式停止 Apache APISIX，因为这种停止方式能够保证 Apache APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 Apache APISIX，在这种情况下，Apache APISIX 接收到但未完成的请求会随着强制停机一并停止。
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+执行优雅停机的命令如下所示：
```shell
-# init nginx config file and etcd
-$ make init
+# stop Apache APISIX server gracefully
+make quit
+```
+
+执行强制停机的命令如下所示：
-# start APISIX server
-$ make run
+```shell
+# stop Apache APISIX server immediately
+make stop
+```
-# stop APISIX server gracefully
-$ make quit
+### 查看其他操作
-# stop APISIX server immediately
-$ make stop
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
- * 追加当前目录到perl模块目录： `export PERL5LIB=.:$PERL5LIB`
- * 直接运行：`make test`
- * 指定 nginx 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`
- * 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-### 疑难排解测试
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 运行 `git clone` 命令，将最新的源码克隆到本地，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+
+ - 追加当前目录到perl模块目录： `export PERL5LIB=.:$PERL5LIB`，然后运行 `make test` 命令。
+
+ - 或指定 Nginx 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`。
+
+ :::note 说明
+ 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
+ :::
+
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
-* export PATH=/usr/local/openresty/nginx/sbin:$PATH
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
+
+* `export PATH=/usr/local/openresty/nginx/sbin:$PATH`
* Linux 默认安装路径：
- * export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
- * export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
+ * `export PATH=/usr/local/openresty/nginx/sbin:$PATH`
+ * MacOS 通过 homebrew 默认安装路径：
+ * `export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH`
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API key
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 key，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的 key 修改为abcdefghabcdefgh
role: admin
```
-当我们需要访问 Admin API 时，就可以使用上面记录的 key 作为 token 了。
+当我们需要访问 Admin API 时，就可以使用上面记录的 key 了，如下所示：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
+```
+
+返回结果中的状态码 200 说明访问成功，如下所示：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
HTTP/1.1 200 OK
Date: Fri, 28 Feb 2020 07:48:04 GMT
Content-Type: text/plain
... ...
{"node":{...},"action":"get"}
+```
+
+在这个时候，如果您输入的 key 与 `conf/config.yaml` 中 `apisix.admin_key` 的值不匹配，例如，我们已知正确的 key 是 `abcdefghabcdefgh`，但是我们选择输入一个错误的 key，例如 `wrong-key`，如下所示：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=wrong-key -i
+```
+
+返回结果中的状态码 `401` 说明访问失败，原因是输入的 `key` 有误，触发 `Unauthorized` 错误，如下所示：
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh-invalid -i
+```shell
HTTP/1.1 401 Unauthorized
Date: Fri, 28 Feb 2020 08:17:58 GMT
Content-Type: text/html
... ...
{"node":{...},"action":"get"}
```
-## 6. 为 APISIX 构建 OpenResty
+## 步骤6：为 Apache APISIX 构建 OpenResty
-有些功能需要你引入额外的 Nginx 模块到 OpenResty 当中。
-如果你需要这些功能，你可以用[这个脚本](https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-openresty.sh)
-构建 OpenResty。
+有些功能需要引入额外的 Nginx 模块到 OpenResty 当中。如果您需要这些功能，你可以用[这个脚本](https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-openresty.sh)构建 OpenResty。
Review comment:
fixed
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 Apache APISIX 服务
+
+我们可以在 Apache APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-你需要先下载 Apache Release 源码包：
+### 初始化依赖
+
+运行以下命令初始化 Nginx 配置文件和 etcd。
```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+# init nginx config file and etcd
+make init
```
-安装运行时依赖的 Lua 库：
+### 启动 Apache APISIX
+运行以下命令启动 Apache APISIX。
+
+```shell
+# start Apache APISIX server
+make run
```
-cd apisix-2.7
-make deps
-```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 停止运行 Apache APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 Apache APISIX。建议您优先选择优雅停机的方式停止 Apache APISIX，因为这种停止方式能够保证 Apache APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 Apache APISIX，在这种情况下，Apache APISIX 接收到但未完成的请求会随着强制停机一并停止。
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+执行优雅停机的命令如下所示：
```shell
-# init nginx config file and etcd
-$ make init
+# stop Apache APISIX server gracefully
+make quit
+```
+
+执行强制停机的命令如下所示：
-# start APISIX server
-$ make run
+```shell
+# stop Apache APISIX server immediately
+make stop
+```
-# stop APISIX server gracefully
-$ make quit
+### 查看其他操作
-# stop APISIX server immediately
-$ make stop
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
- * 追加当前目录到perl模块目录： `export PERL5LIB=.:$PERL5LIB`
- * 直接运行：`make test`
- * 指定 nginx 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`
- * 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-### 疑难排解测试
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 运行 `git clone` 命令，将最新的源码克隆到本地，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+
+ - 追加当前目录到perl模块目录： `export PERL5LIB=.:$PERL5LIB`，然后运行 `make test` 命令。
+
+ - 或指定 Nginx 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`。
+
+ :::note 说明
+ 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
+ :::
+
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
-* export PATH=/usr/local/openresty/nginx/sbin:$PATH
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
+
+* `export PATH=/usr/local/openresty/nginx/sbin:$PATH`
* Linux 默认安装路径：
- * export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
- * export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
+ * `export PATH=/usr/local/openresty/nginx/sbin:$PATH`
+ * MacOS 通过 homebrew 默认安装路径：
+ * `export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH`
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API key
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 key，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的 key 修改为abcdefghabcdefgh
role: admin
```
-当我们需要访问 Admin API 时，就可以使用上面记录的 key 作为 token 了。
+当我们需要访问 Admin API 时，就可以使用上面记录的 key 了，如下所示：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
+```
+
+返回结果中的状态码 200 说明访问成功，如下所示：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
HTTP/1.1 200 OK
Date: Fri, 28 Feb 2020 07:48:04 GMT
Content-Type: text/plain
... ...
{"node":{...},"action":"get"}
+```
+
+在这个时候，如果您输入的 key 与 `conf/config.yaml` 中 `apisix.admin_key` 的值不匹配，例如，我们已知正确的 key 是 `abcdefghabcdefgh`，但是我们选择输入一个错误的 key，例如 `wrong-key`，如下所示：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=wrong-key -i
+```
+
+返回结果中的状态码 `401` 说明访问失败，原因是输入的 `key` 有误，触发 `Unauthorized` 错误，如下所示：
Review comment:
fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r668461613
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
Review comment:
ok, fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r668601056
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 NGINX 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 上的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 NGINX 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的目录。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache APISIX Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache APISIX Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
+
+3. 解压 Apache APISIX Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 目录
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 Apache APISIX 服务
+
+我们可以在 Apache APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-你需要先下载 Apache Release 源码包：
+### 初始化依赖
+
+运行以下命令初始化 NGINX 配置文件和 etcd。
```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+# init NGINX config file and etcd
+make init
```
-安装运行时依赖的 Lua 库：
+### 启动 Apache APISIX
+运行以下命令启动 Apache APISIX。
+
+```shell
+# start Apache APISIX server
+make run
```
-cd apisix-2.7
-make deps
-```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 停止运行 Apache APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 Apache APISIX。建议您优先选择优雅停机的方式停止 Apache APISIX，因为这种停止方式能够保证 Apache APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 Apache APISIX，在这种情况下，Apache APISIX 接收到但未完成的请求会随着强制停机一并停止。
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+执行优雅停机的命令如下所示：
```shell
-# init nginx config file and etcd
-$ make init
+# stop Apache APISIX server gracefully
+make quit
+```
-# start APISIX server
-$ make run
+执行强制停机的命令如下所示：
-# stop APISIX server gracefully
-$ make quit
+```shell
+# stop Apache APISIX server immediately
+make stop
+```
+
+### 查看其他操作
-# stop APISIX server immediately
-$ make stop
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
Review comment:
fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667605619
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
* 追加当前目录到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`
* 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
-### 疑难排解测试
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
+
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
* Linux 默认安装路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
+ * MacOS X 通过 homebrew 默认安装路径：
* export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API token
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 token，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的token修改为abcdefghabcdefgh
role: admin
```
当我们需要访问 Admin API 时，就可以使用上面记录的 key 作为 token 了。
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
Review comment:
Will do.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r668463018
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
Review comment:
fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] tao12345666333 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
tao12345666333 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r668543422
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 NGINX 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 上的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 NGINX 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的目录。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache APISIX Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache APISIX Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
+
+3. 解压 Apache APISIX Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 目录
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 Apache APISIX 服务
+
+我们可以在 Apache APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-你需要先下载 Apache Release 源码包：
+### 初始化依赖
+
+运行以下命令初始化 NGINX 配置文件和 etcd。
```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+# init NGINX config file and etcd
+make init
```
-安装运行时依赖的 Lua 库：
+### 启动 Apache APISIX
+运行以下命令启动 Apache APISIX。
+
+```shell
+# start Apache APISIX server
+make run
```
-cd apisix-2.7
-make deps
-```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 停止运行 Apache APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 Apache APISIX。建议您优先选择优雅停机的方式停止 Apache APISIX，因为这种停止方式能够保证 Apache APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 Apache APISIX，在这种情况下，Apache APISIX 接收到但未完成的请求会随着强制停机一并停止。
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+执行优雅停机的命令如下所示：
```shell
-# init nginx config file and etcd
-$ make init
+# stop Apache APISIX server gracefully
+make quit
+```
-# start APISIX server
-$ make run
+执行强制停机的命令如下所示：
-# stop APISIX server gracefully
-$ make quit
+```shell
+# stop Apache APISIX server immediately
+make stop
+```
+
+### 查看其他操作
-# stop APISIX server immediately
-$ make stop
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
Review comment:
```suggestion
运行 `make help` 命令，查看返回结果，获取其他操作的命令和描述。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r668463155
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 Apache APISIX 服务
+
+我们可以在 Apache APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-你需要先下载 Apache Release 源码包：
+### 初始化依赖
+
+运行以下命令初始化 Nginx 配置文件和 etcd。
Review comment:
fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#issuecomment-878889576
I will convert it back once EN document is ready. Thanks guys!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667614171
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
Review comment:
Good call, will do!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667616510
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
* 追加当前目录到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`
* 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
-### 疑难排解测试
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
+
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
* Linux 默认安装路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
+ * MacOS X 通过 homebrew 默认安装路径：
* export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API token
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 token，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的token修改为abcdefghabcdefgh
Review comment:
Well I guess key gets encrypted, then it becomes a token... Anyways, I will change all 'token'/'tokens' to 'key' to avoid confusion.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] tao12345666333 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
tao12345666333 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r668423836
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
+
+3. 解压 Apache Release 源码包：
Review comment:
ditto
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 Apache APISIX 服务
+
+我们可以在 Apache APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-你需要先下载 Apache Release 源码包：
+### 初始化依赖
+
+运行以下命令初始化 Nginx 配置文件和 etcd。
Review comment:
```suggestion
运行以下命令初始化 NGINX 配置文件和 etcd。
```
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
Review comment:
NGINX needs uppercase
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
Review comment:
Linux 环境下，通常术语不用 “文件夹” 而是用 “目录”
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
Review comment:
Apache APISIX Release
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
Review comment:
目录
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
Review comment:
```suggestion
通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 NGINX 和 etcd，请参照各自对应的文档。
```
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 Apache APISIX 服务
+
+我们可以在 Apache APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-你需要先下载 Apache Release 源码包：
+### 初始化依赖
+
+运行以下命令初始化 Nginx 配置文件和 etcd。
```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+# init nginx config file and etcd
+make init
```
-安装运行时依赖的 Lua 库：
+### 启动 Apache APISIX
+运行以下命令启动 Apache APISIX。
+
+```shell
+# start Apache APISIX server
+make run
```
-cd apisix-2.7
-make deps
-```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 停止运行 Apache APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 Apache APISIX。建议您优先选择优雅停机的方式停止 Apache APISIX，因为这种停止方式能够保证 Apache APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 Apache APISIX，在这种情况下，Apache APISIX 接收到但未完成的请求会随着强制停机一并停止。
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+执行优雅停机的命令如下所示：
```shell
-# init nginx config file and etcd
-$ make init
+# stop Apache APISIX server gracefully
+make quit
+```
+
+执行强制停机的命令如下所示：
-# start APISIX server
-$ make run
+```shell
+# stop Apache APISIX server immediately
+make stop
+```
-# stop APISIX server gracefully
-$ make quit
+### 查看其他操作
-# stop APISIX server immediately
-$ make stop
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
- * 追加当前目录到perl模块目录： `export PERL5LIB=.:$PERL5LIB`
- * 直接运行：`make test`
- * 指定 nginx 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`
- * 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-### 疑难排解测试
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 运行 `git clone` 命令，将最新的源码克隆到本地，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+
+ - 追加当前目录到perl模块目录： `export PERL5LIB=.:$PERL5LIB`，然后运行 `make test` 命令。
+
+ - 或指定 Nginx 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`。
+
+ :::note 说明
+ 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
+ :::
+
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
-* export PATH=/usr/local/openresty/nginx/sbin:$PATH
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
+
+* `export PATH=/usr/local/openresty/nginx/sbin:$PATH`
* Linux 默认安装路径：
- * export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
- * export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
+ * `export PATH=/usr/local/openresty/nginx/sbin:$PATH`
+ * MacOS 通过 homebrew 默认安装路径：
+ * `export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH`
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API key
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 key，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的 key 修改为abcdefghabcdefgh
role: admin
```
-当我们需要访问 Admin API 时，就可以使用上面记录的 key 作为 token 了。
+当我们需要访问 Admin API 时，就可以使用上面记录的 key 了，如下所示：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
+```
+
+返回结果中的状态码 200 说明访问成功，如下所示：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
HTTP/1.1 200 OK
Date: Fri, 28 Feb 2020 07:48:04 GMT
Content-Type: text/plain
... ...
{"node":{...},"action":"get"}
+```
+
+在这个时候，如果您输入的 key 与 `conf/config.yaml` 中 `apisix.admin_key` 的值不匹配，例如，我们已知正确的 key 是 `abcdefghabcdefgh`，但是我们选择输入一个错误的 key，例如 `wrong-key`，如下所示：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=wrong-key -i
+```
+
+返回结果中的状态码 `401` 说明访问失败，原因是输入的 `key` 有误，触发 `Unauthorized` 错误，如下所示：
Review comment:
```suggestion
返回结果中的状态码 `401` 说明访问失败，原因是输入的 `key` 有误，未通过认证，触发 `Unauthorized` 错误，如下所示：
```
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
Review comment:
ditto
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
Review comment:
```suggestion
Apache APISIX 的运行环境需要依赖 NGINX 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 上的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
```
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 Apache APISIX 服务
+
+我们可以在 Apache APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-你需要先下载 Apache Release 源码包：
+### 初始化依赖
+
+运行以下命令初始化 Nginx 配置文件和 etcd。
```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+# init nginx config file and etcd
+make init
```
-安装运行时依赖的 Lua 库：
+### 启动 Apache APISIX
+运行以下命令启动 Apache APISIX。
+
+```shell
+# start Apache APISIX server
+make run
```
-cd apisix-2.7
-make deps
-```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 停止运行 Apache APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 Apache APISIX。建议您优先选择优雅停机的方式停止 Apache APISIX，因为这种停止方式能够保证 Apache APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 Apache APISIX，在这种情况下，Apache APISIX 接收到但未完成的请求会随着强制停机一并停止。
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+执行优雅停机的命令如下所示：
```shell
-# init nginx config file and etcd
-$ make init
+# stop Apache APISIX server gracefully
+make quit
+```
+
+执行强制停机的命令如下所示：
-# start APISIX server
-$ make run
+```shell
+# stop Apache APISIX server immediately
+make stop
+```
-# stop APISIX server gracefully
-$ make quit
+### 查看其他操作
-# stop APISIX server immediately
-$ make stop
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
- * 追加当前目录到perl模块目录： `export PERL5LIB=.:$PERL5LIB`
- * 直接运行：`make test`
- * 指定 nginx 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`
- * 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-### 疑难排解测试
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 运行 `git clone` 命令，将最新的源码克隆到本地，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+
+ - 追加当前目录到perl模块目录： `export PERL5LIB=.:$PERL5LIB`，然后运行 `make test` 命令。
+
+ - 或指定 Nginx 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`。
+
+ :::note 说明
+ 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
+ :::
+
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
-* export PATH=/usr/local/openresty/nginx/sbin:$PATH
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
+
+* `export PATH=/usr/local/openresty/nginx/sbin:$PATH`
* Linux 默认安装路径：
- * export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
- * export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
+ * `export PATH=/usr/local/openresty/nginx/sbin:$PATH`
+ * MacOS 通过 homebrew 默认安装路径：
+ * `export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH`
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API key
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 key，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的 key 修改为abcdefghabcdefgh
role: admin
```
-当我们需要访问 Admin API 时，就可以使用上面记录的 key 作为 token 了。
+当我们需要访问 Admin API 时，就可以使用上面记录的 key 了，如下所示：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
+```
+
+返回结果中的状态码 200 说明访问成功，如下所示：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
HTTP/1.1 200 OK
Date: Fri, 28 Feb 2020 07:48:04 GMT
Content-Type: text/plain
... ...
{"node":{...},"action":"get"}
+```
+
+在这个时候，如果您输入的 key 与 `conf/config.yaml` 中 `apisix.admin_key` 的值不匹配，例如，我们已知正确的 key 是 `abcdefghabcdefgh`，但是我们选择输入一个错误的 key，例如 `wrong-key`，如下所示：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=wrong-key -i
+```
+
+返回结果中的状态码 `401` 说明访问失败，原因是输入的 `key` 有误，触发 `Unauthorized` 错误，如下所示：
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh-invalid -i
+```shell
HTTP/1.1 401 Unauthorized
Date: Fri, 28 Feb 2020 08:17:58 GMT
Content-Type: text/html
... ...
{"node":{...},"action":"get"}
```
-## 6. 为 APISIX 构建 OpenResty
+## 步骤6：为 Apache APISIX 构建 OpenResty
-有些功能需要你引入额外的 Nginx 模块到 OpenResty 当中。
-如果你需要这些功能，你可以用[这个脚本](https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-openresty.sh)
-构建 OpenResty。
+有些功能需要引入额外的 Nginx 模块到 OpenResty 当中。如果您需要这些功能，你可以用[这个脚本](https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-openresty.sh)构建 OpenResty。
Review comment:
NGINX
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r668462321
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
Review comment:
fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667593106
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
* 追加当前目录到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`
* 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
-### 疑难排解测试
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
+
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
* Linux 默认安装路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
+ * MacOS X 通过 homebrew 默认安装路径：
Review comment:
Got it. Fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667647026
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
Review comment:
Fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667620501
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
Review comment:
Fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on a change in pull request #4577: docs: update CN and EN how-to-build document
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r669335662
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 NGINX 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 上的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 NGINX 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的目录。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache APISIX Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache APISIX Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
+
+3. 解压 Apache APISIX Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 目录
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 Apache APISIX 服务
+
+我们可以在 Apache APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-你需要先下载 Apache Release 源码包：
+### 初始化依赖
+
+运行以下命令初始化 NGINX 配置文件和 etcd。
```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+# initialize NGINX config file and etcd
+make init
```
-安装运行时依赖的 Lua 库：
+### 启动 Apache APISIX
+运行以下命令启动 Apache APISIX。
+
+```shell
+# start Apache APISIX server
+make run
```
-cd apisix-2.7
-make deps
-```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 停止运行 Apache APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 Apache APISIX。建议您优先选择优雅停机的方式停止 Apache APISIX，因为这种停止方式能够保证 Apache APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 Apache APISIX，在这种情况下，Apache APISIX 接收到但未完成的请求会随着强制停机一并停止。
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+执行优雅停机的命令如下所示：
```shell
-# init nginx config file and etcd
-$ make init
+# stop Apache APISIX server gracefully
+make quit
+```
-# start APISIX server
-$ make run
+执行强制停机的命令如下所示：
-# stop APISIX server gracefully
-$ make quit
+```shell
+# stop Apache APISIX server immediately
+make stop
+```
+
+### 查看其他操作
-# stop APISIX server immediately
-$ make stop
+运行 `make help` 命令，查看返回结果，获取其他操作的命令和描述。
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
- * 追加当前目录到perl模块目录： `export PERL5LIB=.:$PERL5LIB`
- * 直接运行：`make test`
- * 指定 nginx 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`
- * 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
-### 疑难排解测试
+3. 运行 `git clone` 命令，将最新的源码克隆到本地，请使用我们 fork 出来的版本：
-**配置 Nginx 路径**
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
-* export PATH=/usr/local/openresty/nginx/sbin:$PATH
+ - 追加当前目录到perl模块目录： `export PERL5LIB=.:$PERL5LIB`，然后运行 `make test` 命令。
+
+ - 或指定 NGINX 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`。
+
+ :::note 说明
+ 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
+ :::
+
+### 问题排查
+
+**配置 NGINX 路径**
+
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
+
+确保将 Openresty 设置为默认的 NGINX，并按如下所示导出路径：
+
+* `export PATH=/usr/local/openresty/nginx/sbin:$PATH`
* Linux 默认安装路径：
- * export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
- * export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
+ * `export PATH=/usr/local/openresty/nginx/sbin:$PATH`
+ * MacOS 通过 homebrew 默认安装路径：
+ * `export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH`
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API key
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 key，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的 key 修改为abcdefghabcdefgh
role: admin
```
-当我们需要访问 Admin API 时，就可以使用上面记录的 key 作为 token 了。
+当我们需要访问 Admin API 时，就可以使用上面记录的 key 了，如下所示：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
+```
+
+返回结果中的状态码 200 说明访问成功，如下所示：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
HTTP/1.1 200 OK
Date: Fri, 28 Feb 2020 07:48:04 GMT
Content-Type: text/plain
... ...
{"node":{...},"action":"get"}
+```
+
+在这个时候，如果您输入的 key 与 `conf/config.yaml` 中 `apisix.admin_key` 的值不匹配，例如，我们已知正确的 key 是 `abcdefghabcdefgh`，但是我们选择输入一个错误的 key，例如 `wrong-key`，如下所示：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=wrong-key -i
+```
+
+返回结果中的状态码 `401` 说明访问失败，原因是输入的 `key` 有误，未通过认证，触发 `Unauthorized` 错误，如下所示：
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh-invalid -i
+```shell
HTTP/1.1 401 Unauthorized
Date: Fri, 28 Feb 2020 08:17:58 GMT
Content-Type: text/html
... ...
{"node":{...},"action":"get"}
```
-## 6. 为 APISIX 构建 OpenResty
+## 步骤6：为 Apache APISIX 构建 OpenResty
-有些功能需要你引入额外的 Nginx 模块到 OpenResty 当中。
-如果你需要这些功能，你可以用[这个脚本](https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-openresty.sh)
-构建 OpenResty。
+有些功能需要引入额外的 NGINX 模块到 OpenResty 当中。如果您需要这些功能，你可以用[这个脚本](https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-openresty.sh)构建 OpenResty。
-## 7. 为 APISIX 添加 systemd 配置文件
+## 步骤7：为 Apache APISIX 添加 systemd 配置文件
-如果通过 rpm 包安装 APISIX，配置文件已经自动安装到位，你可以直接运行
+如果您使用的操作系统是 CentOS 7，且在步骤 2 中通过 RPM 包安装 Apache APISIX，配置文件已经自动安装到位，你可以直接运行以下命令：
-```
-$ systemctl start apisix
-$ systemctl stop apisix
-$ systemctl enable apisix
+```shell
+systemctl start apisix
+systemctl stop apisix
```
-如果通过其他方法安装，可以参考[配置文件模板](https://github.com/api7/apisix-build-tools/blob/master/usr/lib/systemd/system/apisix.service)进行修改，并将其放置在 `/usr/lib/systemd/system/apisix.service`。
+如果通过其他方法安装，可以参考[配置文件模板](https://github.com/api7/apisix-build-tools/blob/master/usr/lib/systemd/system/apisix.service)进行修改，并将其放置在 `/usr/lib/systemd/system/apisix.service`路径下。
Review comment:
```suggestion
如果通过其他方法安装，可以参考[配置文件模板](https://github.com/api7/apisix-build-tools/blob/master/usr/lib/systemd/system/apisix.service)进行修改，并将其放置在 `/usr/lib/systemd/system/apisix.service` 路径下。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r668462922
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,219 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+ 您也可以通过 Apache APISIX 官网下载 Apache Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考[Apache APISIX 官网-下载页](https://apisix.apache.org/zh/downloads)。
Review comment:
fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667623199
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
* 追加当前目录到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`
Review comment:
Update: I put it in this way:
4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
- 追加当前目录到perl模块目录： `export PERL5LIB=.:$PERL5LIB`，然后运行 `make test` 命令。
- 或指定 Nginx 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`。
:::note 说明
部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
:::
First 2 bullet points are parallel, it is an 'either-or' choice. then add a note to inform user how to build it compeletly.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667611759
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
Review comment:
It is called `etcd` on their official website https://etcd.io/, so `etcd` is a fair choice.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#issuecomment-878268012
👍
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667592600
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
* 追加当前目录到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`
Review comment:
Yes, these **bullet points** should be **steps** under Step 4, right?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] Yiyiyimu commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
Yiyiyimu commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r666992998
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
* 追加当前目录到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`
Review comment:
I think this way is an alternative to `make test`, so maybe we need another structure here rather than a list
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
* 追加当前目录到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`
* 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
-### 疑难排解测试
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
+
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
* Linux 默认安装路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
+ * MacOS X 通过 homebrew 默认安装路径：
* export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API token
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 token，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的token修改为abcdefghabcdefgh
role: admin
```
当我们需要访问 Admin API 时，就可以使用上面记录的 key 作为 token 了。
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
Review comment:
We need to split the command and the output, if we remove the leading `$`, or it could be confusing
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
* 追加当前目录到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`
* 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
-### 疑难排解测试
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
+
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
* Linux 默认安装路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
+ * MacOS X 通过 homebrew 默认安装路径：
* export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API token
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 token，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的token修改为abcdefghabcdefgh
role: admin
```
当我们需要访问 Admin API 时，就可以使用上面记录的 key 作为 token 了。
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
HTTP/1.1 200 OK
Date: Fri, 28 Feb 2020 07:48:04 GMT
Content-Type: text/plain
... ...
{"node":{...},"action":"get"}
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh-invalid -i
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh-invalid -i
HTTP/1.1 401 Unauthorized
Date: Fri, 28 Feb 2020 08:17:58 GMT
Content-Type: text/html
... ...
{"node":{...},"action":"get"}
```
-## 6. 为 APISIX 构建 OpenResty
+## 步骤6：为 APISIX 构建 OpenResty
-有些功能需要你引入额外的 Nginx 模块到 OpenResty 当中。
-如果你需要这些功能，你可以用[这个脚本](https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-openresty.sh)
-构建 OpenResty。
+有些功能需要引入额外的 Nginx 模块到 OpenResty 当中。如果您需要这些功能，你可以用[这个脚本](https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-openresty.sh)构建 OpenResty。
-## 7. 为 APISIX 添加 systemd 配置文件
+## 步骤7：为 APISIX 添加 systemd 配置文件
-如果通过 rpm 包安装 APISIX，配置文件已经自动安装到位，你可以直接运行
+如果您使用的操作系统是 CentOS 7，且在步骤 2 中通过 RPM 包安装 APISIX，配置文件已经自动安装到位，你可以直接运行以下命令：
-```
-$ systemctl start apisix
-$ systemctl stop apisix
-$ systemctl enable apisix
+```shell
+systemctl start apisix
+systemctl stop apisix
Review comment:
We could remove this line if the need is to enable apisix (I made the mistake last time 😿
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
* 追加当前目录到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`
* 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
-### 疑难排解测试
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
+
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
* Linux 默认安装路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
+ * MacOS X 通过 homebrew 默认安装路径：
Review comment:
It should be called MacOS right now
Ref: https://en.wikipedia.org/wiki/MacOS
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667615825
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
Review comment:
Replaced all 'APISIX' with 'Apache APISIX'
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667626612
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
* 追加当前目录到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`
* 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
-### 疑难排解测试
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
+
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
* Linux 默认安装路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
+ * MacOS X 通过 homebrew 默认安装路径：
* export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API token
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 token，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的token修改为abcdefghabcdefgh
role: admin
```
当我们需要访问 Admin API 时，就可以使用上面记录的 key 作为 token 了。
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
+curl http://127.0.0.1:9080/apisix/admin/routes?api_key=abcdefghabcdefgh -i
Review comment:
As discussed in Slack channel, this code block should be subdivided as follow:
line 178-186：Remain the same, Change the original token to abcdefghabcdefgh
line 190-191 and line 197-198：input command lines
line 192-196 and line 199-204：output messages
Points to be clear:
1. In line 198, the same command as 191 is entered, but with an `invalid` suffix, I changed this part to `wrong-key` to make it more obvious.
2. `$` and code block problem: referencing to https://istio.io/latest/docs/setup/getting-started/#install. Their copy button does not copy down `$`, but ours does. I would rather spilt code blocks to 'inputs' and 'outputs', rather than putting them in a whole chunk. Like you said, the `$` here is to show where is the beginning of the code blocks. We should keep them. But split the command and the output is a much better choice IMO.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on a change in pull request #4577: docs: update CN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#discussion_r667616639
##########
File path: docs/zh/latest/how-to-build.md
##########
@@ -21,146 +21,200 @@ title: 如何构建 Apache APISIX
#
-->
-## 1. 安装依赖
+## 步骤1：安装依赖
-Apache APISIX 的运行环境需要 Nginx 和 etcd，
+Apache APISIX 的运行环境需要依赖 Nginx 和 etcd，所以在安装 Apache APISIX 前，请根据您使用的操作系统安装对应的依赖。我们提供了 **CentOS7** 、**Fedora 31 & 32** 、**Ubuntu 16.04 & 18.04** 、 **Debian 9 & 10** 和 **MacOS X** 的依赖安装操作步骤，详情请参考[安装依赖](install-dependencies.md)。
-所以在安装前，请根据不同的操作系统来[安装依赖](install-dependencies.md)。
+通过 Docker 或 Helm Chart 安装 Apache APISIX 时，已经包含了所需的 Nginx 和 etcd，请参照各自对应的文档。
-通过 Docker / Helm Chart 安装时可能已经包含了所需的 Nginx 和 etcd。
-请参照各自对应的文档。
+## 步骤2：安装 Apache APISIX
-## 2. 安装 Apache APISIX
+你可以通过源码包、RPM 包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。
-你可以通过源码包、Docker、Helm Chart 等多种方式来安装 Apache APISIX。
+### 通过源码包安装
+
+1. 创建一个名为 `apisix-2.7` 的文件夹。
+
+ ```shell
+ mkdir apisix-2.7
+ ```
+
+2. 下载 Apache Release 源码包：
+
+ ```shell
+ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
+ ```
+
+3. 解压 Apache Release 源码包：
+
+ ```shell
+ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
+ ```
+
+4. 安装运行时依赖的 Lua 库：
+
+ ```shell
+ # 切换到 apisix-2.7 文件夹
+ cd apisix-2.7
+ # 创建依赖
+ make deps
+ ```
### 通过 RPM 包安装（CentOS 7）
+这种安装方式适用于 CentOS 7 操作系统，请运行以下命令安装 Apache APISIX。
+
```shell
sudo yum install -y https://github.com/apache/apisix/releases/download/2.7/apisix-2.7-0.x86_64.rpm
```
### 通过 Docker 安装
-见 https://hub.docker.com/r/apache/apisix
+详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。
### 通过 Helm Chart 安装
-见 https://github.com/apache/apisix-helm-chart
+详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。
-### 通过源码包安装
+## 步骤3：管理 APISIX 服务
-你需要先下载 Apache Release 源码包：
+我们可以在 APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `make help` 命令查看所有命令和对应的功能。
-```shell
-$ mkdir apisix-2.7
-$ wget https://downloads.apache.org/apisix/2.7/apache-apisix-2.7-src.tgz
-$ tar zxvf apache-apisix-2.7-src.tgz -C apisix-2.7
-```
+### 初始化依赖
-安装运行时依赖的 Lua 库：
+运行以下命令初始化 Nginx 配置文件和 etcd。
-```
-cd apisix-2.7
-make deps
+```shell
+# init nginx config file and etcd
+make init
```
-## 3. 管理（启动、关闭等）APISIX 服务
+### 启动 APISIX
-我们可以在 apisix 的目录下用 `make run` 命令来启动服务，或者用 `make stop` 方式关闭服务。
+运行以下命令启动 APISIX。
```shell
-# init nginx config file and etcd
-$ make init
-
# start APISIX server
-$ make run
+make run
+```
+
+### 停止运行 APISIX
+
+优雅停机 `make quit` 和强制停机 `make stop`都可以停止运行 APISIX。建议您优先选择优雅停机的方式停止 APISIX，因为这种停止方式能够保证 APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 APISIX，在这种情况下，APISIX 接收到但未完成的请求会随着强制停机一并停止。
+执行优雅停机的命令如下所示：
+
+```shell
# stop APISIX server gracefully
-$ make quit
+make quit
+```
+执行强制停机的命令如下所示：
+
+```shell
# stop APISIX server immediately
-$ make stop
+make stop
+```
+### 查看其他操作
+
+运行`make help` 命令，查看返回结果，获取其他操作的命令和描述。
+
+```shell
# more actions find by `help`
-$ make help
+make help
```
-## 4. 运行测试案例
+## 步骤4：运行测试案例
+
+1. 安装 `perl` 的包管理器 `cpanminus`。
+
+2. 然后通过 `cpanm` 来安装 test-nginx 的依赖：
-1. 先安装 perl 的包管理器 cpanminus
-2. 然后通过 cpanm 来安装 test-nginx 的依赖：`sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)`
-3. 然后 clone 最新的源码：`git clone https://github.com/iresty/test-nginx.git`。注意使用我们 fork 出来的版本。
-4. 通过 perl 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 然后 clone 最新的源码，请使用我们 fork 出来的版本：
+
+ ```shell
+ git clone https://github.com/iresty/test-nginx.git
+ ```
+
+4. 通过 `perl` 的 `prove` 命令来加载 test-nginx 的库，并运行 `/t` 目录下的测试案例集：
* 追加当前目录到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`
* 部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，可以参考 `ci/linux_openresty_common_runner.sh`。
-### 疑难排解测试
+### 问题排查
**配置 Nginx 路径**
-如果遇到问题 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf`
-确保将openresty设置为默认的nginx并按如下所示导出路径。
+出现`Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错的解决方法如下：
+
+确保将 Openresty 设置为默认的 Nginx，并按如下所示导出路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
* Linux 默认安装路径：
* export PATH=/usr/local/openresty/nginx/sbin:$PATH
- * OSx 通过homebrew默认安装路径：
+ * MacOS X 通过 homebrew 默认安装路径：
* export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
**运行单个测试用例**
-- 使用以下命令运行指定的测试用例：
- - prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+## 步骤5：修改 Admin API token
-## 5. 更新 Admin API 的 token ，保护 Apache APISIX
+您需要修改 Admin API 的 token，以保护 Apache APISIX。
-修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务。例如下面例子：
+请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示：
```yaml
apisix:
# ... ...
admin_key
-
name: "admin"
- key: abcdefghabcdefgh
+ key: abcdefghabcdefgh # 将原有的token修改为abcdefghabcdefgh
role: admin
```
当我们需要访问 Admin API 时，就可以使用上面记录的 key 作为 token 了。
Review comment:
Changed to `key`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] yzeng25 commented on pull request #4577: docs: update CN and EN how-to-build document
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on pull request #4577:
URL: https://github.com/apache/apisix/pull/4577#issuecomment-878941738
PR is ready for re-review.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org