源码安装 APISIX

如果你希望为 APISIX 做出贡献或配置开发环境，你可以参考本教程。

如果你想通过其他方式安装 APISIX，你可以参考安装指南。

源码安装 APISIX - 图1note

如果你想为特定的环境或打包 APISIX，请参考 apisix-build-tools。

源码安装 APISIX

首先，你可以通过以下命令安装依赖项：

  1. curl https://raw.githubusercontent.com/apache/apisix/master/utils/install-dependencies.sh -sL | bash -

然后，创建一个目录并设置环境变量 APISIX_VERSION：

  1. APISIX_VERSION='3.1.0'
  2. mkdir apisix-${APISIX_VERSION}

现在，你可以运行以下命令，从 Github 克隆 APISIX 源码：

  1. git clone --depth 1 --branch ${APISIX_VERSION} https://github.com/apache/apisix.git apisix-${APISIX_VERSION}

你可以从下载页面下载源码包。但是官网的源码包缺少测试用例，可能会对你后续操作产生困扰。

另外，你也可以在该页面找到 APISIX Dashboard 和 APISIX Ingress Controller 的源码包。

然后切换到 APISIX 源码的目录，创建依赖项并安装 APISIX，命令如下所示：

  1. cd apisix-${APISIX_VERSION}
  2. make deps
  3. make install

该命令将安装 APISIX 运行时依赖的 Lua 库和 apisix 命令。

源码安装 APISIX - 图2note

如果你在运行 make deps 时收到类似 Could not find header file for LDAP/PCRE/openssl 的错误消息，请使用此解决方案。

luarocks 支持自定义编译时依赖项（请参考：配置文件格式）。你可以使用第三方工具安装缺少的软件包并将其安装目录添加到 luarocks 变量表中。此方法适用于 macOS、Ubuntu、CentOS 和其他类似操作系统。

此处仅给出 macOS 的具体解决步骤，其他操作系统的解决方案类似：

  1. 安装 openldap：

    1. brew install openldap

  2. 使用以下命令命令找到本地安装目录：

    1. brew --prefix openldap

  3. 将路径添加到项目配置文件中（选择两种方法中的一种即可）：

    1. 你可以使用 luarocks config 命令设置 LDAP_DIR：

      1. luarocks config variables.LDAP_DIR /opt/homebrew/cellar/openldap/2.6.1

    2. 你还可以更改 luarocks 的默认配置文件。打开 ~/.luaorcks/config-5.1.lua 文件并添加以下内容：

      1. 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，可以执行以下命令卸载：

  1. make uninstall && make undeps
源码安装 APISIX - 图3danger

该操作将删除所有相关文件。

安装 etcd

APISIX 默认使用 etcd 来保存和同步配置。在运行 APISIX 之前，你需要在你的机器上安装 etcd。

  • Linux
  • macOS
  1. ETCD_VERSION='3.4.18'
  2. wget https://github.com/etcd-io/etcd/releases/download/v${ETCD_VERSION}/etcd-v${ETCD_VERSION}-linux-amd64.tar.gz
  3. tar -xvf etcd-v${ETCD_VERSION}-linux-amd64.tar.gz && \
  4.   cd etcd-v${ETCD_VERSION}-linux-amd64 && \
  5.   sudo cp -a etcd etcdctl /usr/bin/
  6. nohup etcd >/tmp/etcd.log 2>&1 &
  1. brew install etcd
  2. brew services start etcd

管理 APISIX 服务

运行以下命令初始化 NGINX 配置文件和 etcd。

  1. apisix init
源码安装 APISIX - 图4tip

你可以运行 apisix help 命令，查看返回结果，获取其他操作命令及其描述。

运行以下命令测试配置文件，APISIX 将根据 config.yaml 生成 nginx.conf，并检查 nginx.conf 的语法是否正确。

  1. apisix test

最后，你可以使用以下命令运行 APISIX。

  1. apisix start

如果需要停止 APISIX，你可以使用 apisix quit 或者 apisix stop 命令。

apisix quit 将正常关闭 APISIX，该指令确保在停止之前完成所有收到的请求。

  1. apisix quit

apisix stop 命令会强制关闭 APISIX 并丢弃所有请求。

  1. apisix stop

为 APISIX 构建 APISIX-Base

APISIX 的一些特性需要在 OpenResty 中引入额外的 NGINX 模块。

如果要使用这些功能，你需要构建一个自定义的 OpenResty 发行版（APISIX-Base）。请参考 apisix-build-tools 配置你的构建环境并进行构建。

运行测试用例

以下步骤展示了如何运行 APISIX 的测试用例：

  1. 安装 perl 的包管理器 cpanminus。

  2. 通过 cpanm 来安装 test-nginx 的依赖：

    1. sudo cpanm --notest Test::Nginx IPC::Run > build.log 2>&1 || (cat build.log && exit 1)

  3. 将 test-nginx 源码克隆到本地：

    1. git clone https://github.com/openresty/test-nginx.git

  4. 运行以下命令将当前目录添加到 Perl 的模块目录：

    1. export PERL5LIB=.:$PERL5LIB

    你可以通过运行以下命令指定 NGINX 二进制路径：

    1. TEST_NGINX_BINARY=/usr/local/bin/openresty prove -Itest-nginx/lib -r t

  5. 运行测试：

    1. make test
源码安装 APISIX - 图5note

部分测试需要依赖外部服务和修改系统配置。如果想要完整地构建测试环境，请参考 ci/linux_openresty_common_runner.sh。

故障排查

以下是运行 APISIX 测试用例的常见故障排除步骤。

出现 Error unknown directive "lua_package_path" in /API_ASPIX/apisix/t/servroot/conf/nginx.conf 报错，是因为默认的 NGINX 安装路径未找到，解决方法如下：

  • Linux 默认安装路径：

    1. export PATH=/usr/local/openresty/nginx/sbin:$PATH

  • macOS 通过 homebrew 的默认安装路径：

    1. export PATH=/usr/local/opt/openresty/nginx/sbin:$PATH

运行指定的测试用例

使用以下命令运行指定的测试用例：

  1. prove -Itest-nginx/lib -r t/plugin/openid-connect.t

如果你想要了解更多信息，请参考 testing framework。