You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2022/06/29 04:00:35 UTC
[apisix] branch master updated: docs: add building apisix Chinese doc. (#7318)
This is an automated email from the ASF dual-hosted git repository.
spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 5ca173747 docs: add building apisix Chinese doc. (#7318)
5ca173747 is described below
commit 5ca173747adda39f0aad904e543cc552d86f9a9e
Author: feihan <97...@users.noreply.github.com>
AuthorDate: Wed Jun 29 12:00:30 2022 +0800
docs: add building apisix Chinese doc. (#7318)
---
docs/en/latest/building-apisix.md | 2 +-
docs/zh/latest/building-apisix.md | 280 ++++++++++++++++++++++++++++++++++++++
docs/zh/latest/config.json | 10 ++
3 files changed, 291 insertions(+), 1 deletion(-)
diff --git a/docs/en/latest/building-apisix.md b/docs/en/latest/building-apisix.md
index fa08d72b5..1fd7246e6 100644
--- a/docs/en/latest/building-apisix.md
+++ b/docs/en/latest/building-apisix.md
@@ -33,7 +33,7 @@ import TabItem from '@theme/TabItem';
If you are looking to contribute to APISIX or setup a development environment, this guide is for you.
-If you are looking to install and run APISIX, check out the [Installation](/docs/apisix/how-to-build) docs.
+If you are looking to install and run APISIX, check out the [Installation](./installation-guide.md) docs.
:::note
diff --git a/docs/zh/latest/building-apisix.md b/docs/zh/latest/building-apisix.md
new file mode 100644
index 000000000..4d2aadba2
--- /dev/null
+++ b/docs/zh/latest/building-apisix.md
@@ -0,0 +1,280 @@
+---
+id: building-apisix
+title: 源码安装 APISIX
+keywords:
+ - API 网关
+ - Apache APISIX
+ - 贡献代码
+ - 构建 APISIX
+ - 源码安装 APISIX
+description: 本文介绍了如何在本地使用源码安装 API 网关 Apache APISIX 来构建开发环境。
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+如果你希望为 APISIX 做出贡献或配置开发环境，你可以参考本教程。
+
+如果你想通过其他方式安装 APISIX，你可以参考[安装指南](./installation-guide.md)。
+
+:::note
+
+如果你想为特定的环境或打包 APISIX，请参考 [apisix-build-tools](https://github.com/api7/apisix-build-tools)。
+
+:::
+
+## 源码安装 APISIX
+
+首先，你可以通过以下命令安装依赖项：
+
+```shell
+curl https://raw.githubusercontent.com/apache/apisix/master/utils/install-dependencies.sh -sL | bash -
+```
+
+然后，创建一个目录并设置环境变量 `APISIX_VERSION`：
+
+```shell
+APISIX_VERSION='2.14.1'
+mkdir apisix-${APISIX_VERSION}
+```
+
+现在，你可以运行以下命令来下载 APISIX 源码包：
+
+```shell
+wget https://downloads.apache.org/apisix/${APISIX_VERSION}/apache-apisix-${APISIX_VERSION}-src.tgz
+```
+
+你可以从[下载页面](https://apisix.apache.org/downloads/)下载源码包。你也可以在该页面找到 APISIX Dashboard 和 APISIX Ingress Controller 的源码包。
+
+下载源码包后，你可以将文件解压到之前创建的文件夹中：
+
+```shell
+tar zxvf apache-apisix-${APISIX_VERSION}-src.tgz -C apisix-${APISIX_VERSION}
+```
+
+然后切换到解压的目录，创建依赖项并安装 APISIX，如下所示：
+
+```shell
+cd apisix-${APISIX_VERSION}
+make deps
+make install
+```
+
+该命令将安装 APISIX 运行时依赖的 Lua 库和 `apisix` 命令。
+
+:::note
+
+如果你在运行 `make deps` 时收到类似 `Could not find header file for LDAP/PCRE/openssl` 的错误消息，请使用此解决方案。
+
+`luarocks` 支持自定义编译时依赖项（请参考：[配置文件格式](https://github.com/luarocks/luarocks/wiki/Config-file-format)）。你可以使用第三方工具安装缺少的软件包并将其安装目录添加到 `luarocks` 变量表中。此方法适用于 macOS、Ubuntu、CentOS 和其他类似操作系统。
+
+此处仅给出 macOS 的具体解决步骤，其他操作系统的解决方案类似：
+
+1. 安装 `openldap`：
+
+ ```shell
+ brew install openldap
+ ```
+
+2. 使用以下命令命令找到本地安装目录：
+
+ ```shell
+ brew --prefix openldap
+ ```
+
+3. 将路径添加到项目配置文件中（选择两种方法中的一种即可）：
+ 1. 你可以使用 `luarocks config` 命令设置 `LDAP_DIR`：
+
+ ```shell
+ luarocks config variables.LDAP_DIR /opt/homebrew/cellar/openldap/2.6.1
+ ```
+
+ 2. 你还可以更改 `luarocks` 的默认配置文件。打开 `~/.luaorcks/config-5.1.lua` 文件并添加以下内容：
+
+ ```shell
+ variables = { LDAP_DIR = "/opt/homebrew/cellar/openldap/2.6.1", LDAP_INCDIR = "/opt/homebrew/cellar/openldap/2.6.1/include", }
+ ```
+
+ `/opt/homebrew/cellar/openldap/` 是 `brew` 在 macOS(Apple Silicon) 上安装 `openldap` 的默认位置。`/usr/local/opt/openldap/` 是 brew 在 macOS(Intel) 上安装 openldap 的默认位置。
+
+:::
+
+如果你不再需要 APISIX，可以执行以下命令卸载：
+
+```shell
+make uninstall && make undeps
+```
+
+:::danger
+
+该操作将删除所有相关文件。
+
+:::
+
+## 安装 etcd
+
+APISIX 默认使用 [etcd](https://github.com/etcd-io/etcd) 来保存和同步配置。在运行 APISIX 之前，你需要在你的机器上安装 etcd。
+
+<Tabs
+ groupId="os"
+ defaultValue="linux"
+ values={[
+ {label: 'Linux', value: 'linux'},
+ {label: 'macOS', value: 'mac'},
+ ]}>
+<TabItem value="linux">
+
+```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 &
+```
+
+</TabItem>
+
+<TabItem value="mac">
+
+```shell
+brew install etcd
+brew services start etcd
+```
+
+</TabItem>
+</Tabs>
+
+## 管理 APISIX 服务
+
+运行以下命令初始化 NGINX 配置文件和 etcd。
+
+```shell
+apisix init
+```
+
+:::tip
+
+你可以运行 `apisix help` 命令，查看返回结果，获取其他操作命令及其描述。
+
+:::
+
+运行以下命令测试配置文件，APISIX 将根据 `config.yaml` 生成 `nginx.conf`，并检查 `nginx.conf` 的语法是否正确。
+
+```shell
+apisix test
+```
+
+最后，你可以使用以下命令运行 APISIX。
+
+```shell
+apisix start
+```
+
+如果需要停止 APISIX，你可以使用 `apisix quit` 或者 `apisix stop` 命令。
+
+`apisix quit` 将正常关闭 APISIX，该指令确保在停止之前完成所有收到的请求。
+
+```shell
+apisix quit
+```
+
+`apisix stop` 命令会强制关闭 APISIX 并丢弃所有请求。
+
+```shell
+apisix stop
+```
+
+## 为 APISIX 构建 APISIX-Base
+
+APISIX 的一些特性需要在 OpenResty 中引入额外的 NGINX 模块。
+
+如果要使用这些功能，你需要构建一个自定义的 OpenResty 发行版（APISIX-Base）。请参考 [apisix-build-tools](https://github.com/api7/apisix-build-tools) 配置你的构建环境并进行构建。
+
+## 运行测试用例
+
+以下步骤展示了如何运行 APISIX 的测试用例：
+
+1. 安装 `perl` 的包管理器 [cpanminus](https://metacpan.org/pod/App::cpanminus#INSTALLATION)。
+2. 通过 `cpanm` 来安装 [test-nginx](https://github.com/openresty/test-nginx) 的依赖：
+
+ ```shell
+ sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)
+ ```
+
+3. 将 `test-nginx` 源码克隆到本地：
+
+ ```shell
+ git clone https://github.com/openresty/test-nginx.git
+ ```
+
+4. 运行以下命令将当前目录添加到 Perl 的模块目录：
+
+ ```shell
+ export PERL5LIB=.:$PERL5LIB
+ ```
+
+ 你可以通过运行以下命令指定 NGINX 二进制路径：
+
+ ```shell
+ TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t
+ ```
+
+5. 运行测试：
+
+ ```shell
+ make test
+ ```
+
+:::note
+
+部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，请参考 [ci/linux_openresty_common_runner.sh](https://github.com/apache/apisix/blob/master/ci/linux_openresty_common_runner.sh)。
+
+:::
+
+### 故障排查
+
+以下是运行 APISIX 测试用例的常见故障排除步骤。
+
+出现 `Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf` 报错，是因为默认的 NGINX 安装路径未找到，解决方法如下：
+
+- Linux 默认安装路径：
+
+ ```shell
+ export PATH=/usr/local/openresty/nginx/sbin:$PATH
+ ```
+
+- macOS 通过 `homebrew` 的默认安装路径：
+
+ ```shell
+ export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH
+ ```
+
+### 运行指定的测试用例
+
+使用以下命令运行指定的测试用例：
+
+```shell
+prove -Itest-nginx/lib -r t/plugin/openid-connect.t
+```
+
+如果你想要了解更多信息，请参考 [testing framework](https://github.com/apache/apisix/blob/master/docs/en/latest/internal/testing-framework.md)。
diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json
index 1cb779f48..0832c0429 100644
--- a/docs/zh/latest/config.json
+++ b/docs/zh/latest/config.json
@@ -190,6 +190,16 @@
}
]
},
+ {
+ "type": "category",
+ "label": "Development",
+ "items": [
+ {
+ "type": "doc",
+ "id": "building-apisix"
+ }
+ ]
+ },
{
"type": "doc",
"id": "FAQ"