SylviaBABY commented on code in PR #7002: URL: https://github.com/apache/apisix/pull/7002#discussion_r867310732
########## docs/zh/latest/how-to-build.md: ########## @@ -21,345 +26,220 @@ title: 如何构建 Apache APISIX # --> -## 步骤 1 安装 Apache APISIX +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -你可以通过 RPM 仓库、Docker、Helm Chart、源码包、源码包（LTS 版本）等多种方式来安装 Apache APISIX。请在以下选项中选择其中一种执行。 +本文将介绍如何在你的环境中安装并运行 APISIX。 -### 通过 RPM 仓库安装（CentOS） +关于如何快速运行 Apache APISIX，请参考 [入门指南](./getting-started.md)。 -> 这种安装方式适用于 CentOS 7 和 CentOS 8 操作系统。 +## 安装 etcd -如果尚未安装 OpenResty 的官方 RPM 仓库，请使用以下命令自动安装 OpenResty 和 Apache APISIX 的 RPM 仓库。 +APISIX 使用 [etcd](https://github.com/etcd-io/etcd) 作为配置中心，来保存和同步配置。在安装 APISIX 之前，你需要在你的主机上安装 etcd。 -```shell -sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm -``` +如果你在安装 APISIX 时选择 Docker 或 Hlem 安装，etcd 将会自动安装。如果你选择其他方法或者需要手动安装 APISIX，请参考以下步骤安装 etcd： -如果已安装 OpenResty 的官方 RPM 仓库，请使用以下命令自动安装 Apache APISIX 的 RPM 仓库。 +<Tabs + groupId="os" + defaultValue="linux" + values={[ + {label: 'Linux', value: 'linux'}, + {label: 'macOS', value: 'mac'}, + ]}> +<TabItem value="linux"> ```shell -sudo yum-config-manager --add-repo https://repos.apiseven.com/packages/centos/apache-apisix.repo -``` - -请运行以下命令安装 Apache APISIX。 - -```shell -# 查看仓库中最新的 apisix 软件包的信息 -sudo yum info -y apisix - -# 显示仓库中现有的 apisix 软件包 -sudo yum --showduplicates list apisix - -# 安装最新的 apisix 软件包 -sudo yum install apisix - -# 安装指定版本（本例中为 2.10.3 版本）的 apisix 软件包 -sudo yum install apisix-2.10.3-0.el7 +ETCD_VERSION='3.4.18' +wget https://github.com/etcd-io/etcd/releases/download/v${ETCD_VERSION}/etcd-v${ETCD_VERSION}-linux-amd64.tar.gz +tar -xvf etcd-v${ETCD_VERSION}-linux-amd64.tar.gz && \ + cd etcd-v${ETCD_VERSION}-linux-amd64 && \ + sudo cp -a etcd etcdctl /usr/bin/ +nohup etcd >/tmp/etcd.log 2>&1 & ``` -### 通过 RPM 包离线安装（CentOS） - -下载 APISIX 离线 RPM 包到 `./apisix` 文件夹 - -```shell -sudo mkdir -p apisix -sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm -sudo yum clean all && yum makecache -sudo yum install -y --downloadonly --downloaddir=./apisix apisix -``` +</TabItem> -拷贝 `./apisix` 文件夹到目标主机，使用以下命令安装 Apache APISIX。 +<TabItem value="mac"> ```shell -sudo yum install ./apisix/*.rpm +brew install etcd +brew services start etcd ``` -### 通过 Docker 安装 - -详情请参考：[使用 Docker 安装 Apache APISIX](https://hub.docker.com/r/apache/apisix)。 - -### 通过 Helm Chart 安装 - -详情请参考：[使用 Helm Chart 安装 Apache APISIX](https://github.com/apache/apisix-helm-chart)。 - -### 通过源码包安装 +</TabItem> +</Tabs> -注意：如果你想针对特定平台打包 Apache APISIX，请更新 [apisix-build-tools](https://github.com/api7/apisix-build-tools) -以下步骤仅用于设置 Apache APISIX 的开发环境。 +## 安装 APISIX -1. 安装依赖 +你可以选择以下任意一种方式安装 APISIX： - ```shell - curl https://raw.githubusercontent.com/apache/apisix/master/utils/install-dependencies.sh -sL | bash - - ``` +<Tabs + groupId="install-method" + defaultValue="docker" + values={[ + {label: 'Docker', value: 'docker'}, + {label: 'Helm', value: 'helm'}, + {label: 'RPM', value: 'rpm'}, + ]}> +<TabItem value="docker"> -2. 创建一个名为 `apisix-2.13.0` 的目录。 +使用此方法安装 APISIX，你需要安装 [Docker](https://www.docker.com/) 和 [Docker Compose](https://docs.docker.com/compose/). - ```shell - APISIX_VERSION='2.13.0' - mkdir apisix-${APISIX_VERSION} - ``` +首先下载 [apisix-docker](https://github.com/apache/apisix-docker) 仓库。 -3. 下载 Apache APISIX Release 源码包： - - ```shell - wget https://downloads.apache.org/apisix/${APISIX_VERSION}/apache-apisix-${APISIX_VERSION}-src.tgz - ``` - -您也可以通过 Apache APISIX 官网下载 Apache APISIX Release 源码包。 Apache APISIX 官网也提供了 Apache APISIX、APISIX Dashboard 和 APISIX Ingress Controller 的源码包，详情请参考 [Apache APISIX 官网 - 下载页](https://apisix.apache.org/zh/downloads)。 +```shell +git clone https://github.com/apache/apisix-docker.git +cd apisix-docker/example +``` -4. 解压 Apache APISIX Release 源码包： +然后，使用 `docker-compose` 启用 APISIX。 - ```shell - tar zxvf apache-apisix-${APISIX_VERSION}-src.tgz -C apisix-${APISIX_VERSION} - ``` +<Tabs + groupId="cpu-arch" + defaultValue="x86" + values={[ + {label: 'x86', value: 'x86'}, + {label: 'ARM/M1', value: 'arm'}, + ]}> +<TabItem value="x86"> -5. 安装运行时依赖的 Lua 库： +```shell +docker-compose -p docker-apisix up -d +``` - ```shell - # 切换到 apisix-${APISIX_VERSION} 目录 - cd apisix-${APISIX_VERSION} - # 安装依赖 - LUAROCKS_SERVER=https://luarocks.cn make deps - ``` +</TabItem> -**注意**：使用 `make deps` 安装 `lualdap`、`PCRE`、`openssl` 等依赖包失败，错误信息如： `Could not find header file for LDAP/PCRE/openssl`，可使用本方法解决。 +<TabItem value="arm"> -解决思路：`luarocks` 支持自定义编译时依赖目录（来自此[链接](https://github.com/luarocks/luarocks/wiki/Config-file-format))，使用第三方工具安装缺失的依赖，并将其文件路径添加到 `luarocks` 的变量表中。这是一种通用的解决方法，适用于在各种常见操作系统（包括但不仅限于 Ubuntu、Centos、macOS）遇到的“缺失头文件式安装依赖包失败”问题。 +```shell +docker-compose -p docker-apisix -f docker-compose-arm64.yml up -d +``` -这边暂给出 macOS 上的具体解决步骤，其他操作系统的解决方案类似： +</TabItem> +</Tabs> - 1. 使用 `brew install openldap` 命令将 `openldap` 安装到本地； - 2. 使用 `brew --prefix openldap` 命令找到本地安装目录； - 3. 将路径添加到项目配置文件中（选择两种方法中的一种即可）： - 1. 方法一：通过 `luarocks config` 手动设置 `LDAP_DIR` 变量，比如 `luarocks config variables.LDAP_DIR /opt/homebrew/cellar/openldap/2.6.1`； - 2. 方法二：当然你也可以选择直接更改 luarocks 的默认配置文件，执行 `cat ~/.luarocks/config-5.1.lua` 命令，然后在文件中添加 `openldap` 的安装目录； - 3. 参考配置文件示例如下： - variables = { - LDAP_DIR = "/opt/homebrew/cellar/openldap/2.6.1", - LDAP_INCDIR = "/opt/homebrew/cellar/openldap/2.6.1/include", - } +</TabItem> - `/opt/homebrew/cellar/openldap/` 是 `brew` 在 macOS(Apple Silicon) 上安装 `openldap` 的默认位置。 - `/usr/local/opt/openldap/` 是 `brew` 在 macOS(Intel) 上安装 `openldap` 的默认位置。 +<TabItem value="helm"> -6. 如果您不再需要 Apache APISIX 运行时，您可以执行卸载，如： +通过 Helm 安装 APISIX，请执行以下命令： ```shell - # 卸载依赖 - make undeps +helm repo add apisix https://charts.apiseven.com +helm repo update +helm install apisix apisix/apisix --create-namespace --namespace apisix ``` -请注意，该操作将完整**删除**相关文件。 +你可以从 [apisix-helm-chart](https://github.com/apache/apisix-helm-chart) 仓库找到其他组件。 -#### 通过源码包安装 LTS 版本 +</TabItem> -目前 Apache APISIX 的 LTS 版本为 `2.13.0`，将“[通过源码包安装](#通过源码包安装)”中的 `APISIX_VERSION` 设置成该版本号，其他步骤按顺序进行即可。 +<TabItem value="rpm"> -## 步骤 2 安装 etcd +该安装方法适用于 CentOS 7 和 CentOS 8。 -如果你只通过 RPM、Docker 或源代码安装了 Apache APISIX，而没有安装 etcd，则需要这一步。 +### 通过 RPM 仓库安装 -你可以通过 Docker 或者二进制等方式安装 etcd。以下命令通过二进制方式在 Linux 上安装 etcd。 +如果当前系统**没有安装 OpenResty**，请使用以下命令来安装 OpenResty 和 APISIX 仓库： ```shell -ETCD_VERSION='3.4.18' -wget https://github.com/etcd-io/etcd/releases/download/v${ETCD_VERSION}/etcd-v${ETCD_VERSION}-linux-amd64.tar.gz -tar -xvf etcd-v${ETCD_VERSION}-linux-amd64.tar.gz && \ - cd etcd-v${ETCD_VERSION}-linux-amd64 && \ - sudo cp -a etcd etcdctl /usr/bin/ -nohup etcd >/tmp/etcd.log 2>&1 & -``` - -以下命令在 Mac 上安装 etcd: - -```shell -brew install etcd -# start etcd server -brew services start etcd +sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm ``` -## 步骤 3 管理 Apache APISIX 服务 - -我们可以在 Apache APISIX 的目录下使用命令初始化依赖、启动服务和停止服务，也可以通过 `apisix help` 命令查看所有命令和对应的功能。 - -### 初始化依赖 - -运行以下命令初始化 NGINX 配置文件和 etcd。 +如果已安装 OpenResty 的官方 RPM 仓库，请使用以下命令安装 APISIX 的 RPM 仓库： ```shell -# initialize NGINX config file and etcd -apisix init +sudo yum-config-manager --add-repo https://repos.apiseven.com/packages/centos/apache-apisix.repo ``` -### 测试配置文件 - -运行以下命令测试配置文件。 APISIX 将根据 `config.yaml` 生成 `nginx.conf`，并检查 `nginx.conf` 的语法是否正确。 +完成上述操作后使用以下命令安装 APISIX： ```shell -# generate `nginx.conf` from `config.yaml` and test it -apisix test +sudo yum install apisix ``` -### 启动 Apache APISIX +:::tip -运行以下命令启动 Apache APISIX。 +你也可以安装指定版本的 APISIX（本示例为 APISIX v2.13.1 LTS 版本）： ```shell -# start Apache APISIX server -apisix start +sudo yum install apisix-2.13.1 ``` -### 停止运行 Apache APISIX +::: -优雅停机 `apisix quit` 和强制停机 `apisix stop` 都可以停止运行 Apache APISIX。建议您优先选择优雅停机的方式停止 Apache APISIX，因为这种停止方式能够保证 Apache APISIX 完成了已经接受到的请求之后再停止；而强制停机则是立即停止 Apache APISIX，在这种情况下，Apache APISIX 接收到但未完成的请求会随着强制停机一并停止。 +### 通过 RPM 包离线安装： -执行优雅停机的命令如下所示： +下载 APISIX 离线 RPM 包到 `apisix` 文件夹： ```shell -# stop Apache APISIX server gracefully -apisix quit +sudo mkdir -p apisix +sudo yum install -y https://repos.apiseven.com/packages/centos/apache-apisix-repo-1.0-1.noarch.rpm +sudo yum clean all && yum makecache +sudo yum install -y --downloadonly --downloaddir=./apisix apisix ``` -执行强制停机的命令如下所示： +然后将 `apisix` 文件夹复制到目标主机并运行以下命令： ```shell -# stop Apache APISIX server immediately -apisix stop +sudo yum install ./apisix/*.rpm ``` -### 查看其他操作 +### 管理 APISIX 服务 -运行 `apisix help` 命令，查看返回结果，获取其他操作的命令和描述。 +APISIX 安装完成后，你可以运行以下命令初始化 NGINX 配置文件和 etcd： ```shell -# more actions find by `help` -apisix help +apisix init ``` -## 步骤 4 运行测试案例 - -1. 安装 `perl` 的包管理器 `cpanminus`。 - -详情请参考：[安装包管理器 `cpanmius`](https://metacpan.org/pod/App::cpanminus#INSTALLATION)。 - -2. 然后通过 `cpanm` 来安装 test-nginx 的依赖： +使用以下命令启动 APISIX： - ```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/openresty/test-nginx.git - ``` - -4. 有两种方法运行测试： - -- 追加当前目录到 perl 模块目录： `export PERL5LIB=.:$PERL5LIB`，然后运行 `make test` 命令。 +```shell +apisix start +``` -- 或指定 NGINX 二进制路径：`TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t`。 +:::tip - <!-- - # - # In addition to the basic Markdown syntax, we use remark-admonitions - # alongside MDX to add support for admonitions. Admonitions are wrapped - # by a set of 3 colons. - # Please refer to https://docusaurus.io/docs/next/markdown-features/admonitions - # for more detail. - # - --> +你可以运行 `apisix help` 命令，通过查看返回结果，获取其他操作的命令及描述。 -:::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，并按如下所示导出路径： +</TabItem> +</Tabs> -* `export PATH=/usr/local/openresty/nginx/sbin:$PATH` - * Linux 默认安装路径： - * `export PATH=/usr/local/openresty/nginx/sbin:$PATH` - * MacOS 通过 homebrew 默认安装路径： - * `export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH` +## 后续操作 -**运行单个测试用例** +### 更新 Admin API key -使用以下命令运行指定的测试用例： - -```shell -prove -Itest-nginx/lib -r t/plugin/openid-connect.t -``` +建议修改 Admin API 的 key，保护 APISIX 的安全。 -关于测试用例的更多细节，参见 [测试框架](https://github.com/apache/apisix/blob/master/docs/en/latest/internal/testing-framework.md) +请参考如下信息更新配置文件： -## 步骤 5 修改 Admin API key - -您需要修改 Admin API 的 key，以保护 Apache APISIX。 - -请修改 `conf/config.yaml` 中的 `apisix.admin_key` 并重启服务，如下所示： - -```yaml +```yaml title="conf/config.yaml" apisix: - # ... ... admin_key - name: "admin" - key: abcdefghabcdefgh # 将原有的 key 修改为 abcdefghabcdefgh + key: newsupersecurekey # 请修改 key 的值 role: admin ``` -当我们需要访问 Admin API 时，就可以使用上面记录的 key 了，如下所示： +更新完成后，你可以使用新的 key 访问 Admin API： ```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=newsupersecurekey -i ``` -返回结果中的状态码 200 说明访问成功，如下所示： - -```shell -HTTP/1.1 200 OK -Date: Fri, 28 Feb 2020 07:48:04 GMT -Content-Type: text/plain -... ... -{"node":{...},"action":"get"} -``` +### 为 APISIX 添加 systemd 配置文件 -在这个时候，如果您输入的 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` 错误，如下所示： - -```shell -HTTP/1.1 401 Unauthorized -Date: Fri, 28 Feb 2020 08:17:58 GMT -Content-Type: text/html -... ... -{"node":{...},"action":"get"} -``` - -## 步骤 6 为 Apache APISIX 构建 OpenResty - -有些功能需要引入额外的 NGINX 模块到 OpenResty 当中。 -如果您需要这些功能，您可以构建 APISIX OpenResty。 -您可以根据 [api7/apisix-build-tools](https://github.com/api7/apisix-build-tools) 里面的代码，配置自己的构建环境，并完成 APISIX OpenResty 的构建。 - -## 步骤 7 为 Apache APISIX 添加 systemd 配置文件 - -如果使用的操作系统为 CentOS，且在步骤 2 中通过 RPM 包安装 Apache APISIX，配置文件已经自动安装到位，你可以直接运行以下命令： +如果你是通过 RPM 包安装 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` 路径下。 +如果你是通过其他方法安装的 APISIX，可以参考[配置文件模板](https://github.com/api7/apisix-build-tools/blob/master/usr/lib/systemd/system/apisix.service)进行修改，并将其添加在 `/usr/lib/systemd/system/apisix.service` 路径下 Review Comment: ```suggestion 如果你是通过其他方法安装的 APISIX，可以参考[配置文件模板](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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
