Apache APISIX 源码编译与开发环境搭建指南
项目地址: https://gitcode.com/gh_mirrors/api/apisix 前言
Apache APISIX 是一个高性能、可扩展的云原生 API 网关，基于 OpenResty 和 etcd 构建。对于开发者而言，从源码构建 APISIX 是深入了解其工作原理、进行二次开发或贡献代码的必要步骤。本文将详细介绍如何从源码构建 APISIX 并搭建完整的开发环境。
环境准备
在开始构建之前，需要确保系统满足以下基本要求：
- 操作系统：支持 Linux 和 macOS
- 基础依赖：
- Git（用于获取源码）
- GNU Make（构建工具）
- GCC/G++（编译工具链）
获取 APISIX 源码
APISIX 的源码可以通过两种方式获取：
方法一：通过 Git 克隆（推荐）
# 指定要构建的版本分支
APISIX_BRANCH='release/3.12.0'
# 克隆指定分支的源码（浅克隆节省时间）
git clone --depth 1 --branch ${APISIX_BRANCH} https://gitbox.apache.org/repos/asf/apisix.git apisix-${APISIX_BRANCH}
方法二：下载源码包
可以从官方网站获取源码包，但需要注意：
- 官网源码包不包含测试用例
- 缺少 Git 版本信息
安装 OpenResty
APISIX 运行依赖于 OpenResty，需要先安装：
# 对于基于 Debian 的系统
sudo apt-get install -y openresty
# 对于基于 RHEL 的系统
sudo yum install -y openresty
# 对于 macOS 系统
brew install openresty/brew/openresty
安装完成后，建议将 OpenResty 的可执行文件目录加入 PATH 环境变量：
export PATH=/usr/local/openresty/bin:$PATH
构建 APISIX
进入源码目录并执行构建：
cd apisix-${APISIX_BRANCH}
# 安装运行时依赖
make deps
# 安装 APISIX
make install
构建过程会：
- 通过 LuaRocks 安装所有必要的 Lua 依赖
- 安装 apisix 和 apisix-runtime 命令行工具
常见构建问题解决
在构建过程中可能会遇到缺少头文件的错误，如 LDAP/PCRE/openssl 等，解决方法如下：
- 安装缺失的开发库（以 macOS 为例）：
brew install openldap pcre openssl
- 配置 LuaRocks 的搜索路径：
luarocks config variables.LDAP_DIR $(brew --prefix openldap)
luarocks config variables.PCRE_DIR $(brew --prefix pcre)
luarocks config variables.OPENSSL_DIR $(brew --prefix openssl)
安装 etcd
APISIX 使用 etcd 作为配置存储，需要单独安装：
Linux 系统安装
ETCD_VERSION='3.4.18'
wget https://downloads.apache.org/etcd/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 &
macOS 系统安装
brew install etcd
brew services start etcd
初始化与运行 APISIX
初始化配置
apisix init
此命令会：
- 生成默认的 config.yaml 配置文件
- 初始化 etcd 数据结构
测试配置
apisix test
检查生成的 nginx.conf 配置语法是否正确
启动 APISIX
apisix start
管理 APISIX 服务
-
优雅停止（处理完现有请求）：
apisix quit -
强制停止：
apisix stop
构建 APISIX-Runtime
某些高级功能需要定制化的 OpenResty 运行时环境，可以通过以下步骤构建：
- 获取构建工具
- 根据需求选择模块
- 执行构建脚本
具体构建过程因需求而异，建议参考官方构建工具文档。
运行测试用例
APISIX 提供了完整的测试套件，运行测试需要：
- 安装 Perl 和测试依赖：
# 安装 cpanminus
sudo apt-get install -y cpanminus
# 安装测试依赖
sudo cpanm --notest Test::Nginx IPC::Run
- 获取 test-nginx 框架：
git clone https://gitbox.apache.org/repos/asf/incubator-test-nginx.git
- 设置环境变量：
export PERL5LIB=.:$PERL5LIB
- 运行全部测试：
make test
- 运行单个测试文件：
prove -Itest-nginx/lib -r t/plugin/openid-connect.t
卸载 APISIX
如需完全移除 APISIX，可以执行：
make uninstall && make undeps
注意：此操作会删除所有相关文件，包括配置和依赖项。
结语
通过源码构建 APISIX 虽然步骤较多，但能让开发者更深入地理解系统架构和运行机制。本文详细介绍了从获取源码到运行测试的全过程，希望能帮助开发者顺利搭建 APISIX 开发环境。在实际开发中，建议结合官方文档和社区资源，以获得最佳开发体验。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
