Apache APISIX 从源码构建完整指南

Apache APISIX 从源码构建完整指南

apisix Apisix是一个基于Nginx的API网关，主要用于微服务架构中的API管理和服务发现。它的特点是高性能、轻量级、易于配置等。适用于API管理和负载均衡场景。 项目地址: https://gitcode.com/gh_mirrors/api/apisix

前言

Apache APISIX 作为云原生 API 网关，其源码构建过程对于开发者理解系统架构、进行二次开发或贡献代码至关重要。本文将详细介绍从源码构建 APISIX 的完整流程，包括环境准备、依赖安装、构建步骤以及常见问题解决方案。

环境准备

1. 源码获取

APISIX 提供了两种源码获取方式：

# 方式一：通过Git克隆特定分支
APISIX_BRANCH='release/3.11.0'
git clone --depth 1 --branch ${APISIX_BRANCH} https://github.com/apache/apisix.git apisix-${APISIX_BRANCH}

# 方式二：下载源码包（不包含测试用例）

2. 基础依赖安装

构建前必须安装以下基础组件：

• OpenResty：APISIX 基于 OpenResty 构建，需先完成安装
• LuaRocks：Lua 包管理工具
• 编译工具链：包括 gcc、make 等

构建流程

1. 安装依赖项

进入源码目录执行：

cd apisix-${APISIX_BRANCH}
make deps  # 安装Lua运行时依赖库

常见依赖问题解决

当出现类似Could not find header file for LDAP/PCRE/openssl错误时，需要手动配置开发库路径。以 macOS 上解决 openldap 问题为例：

# 安装openldap
brew install openldap

# 配置LuaRocks变量（Apple Silicon芯片）
luarocks config variables.LDAP_DIR /opt/homebrew/cellar/openldap/2.6.1

2. 安装APISIX

make install  # 安装apisix运行时和CLI工具

安装完成后会生成apisix命令行工具，可通过apisix help查看支持的命令。

依赖服务安装

etcd 安装与启动

APISIX 使用 etcd 作为配置存储中心，必须先行安装：

# Linux系统安装示例
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 &

服务管理

1. 初始化配置

apisix init  # 生成默认配置文件
apisix test  # 验证配置有效性

2. 启动与停止

# 正常启动
apisix start

# 优雅停止（处理完现有请求）
apisix quit

# 强制停止（立即终止）
apisix stop

高级构建选项

自定义运行时构建

某些高级功能需要定制 OpenResty 运行时环境：

1. 准备构建工具链
2. 添加必要的 Nginx 模块
3. 编译生成 apisix-runtime

具体构建方法参考官方构建工具文档。

测试套件执行

测试环境搭建

# 安装Perl包管理器
sudo cpanm --notest Test::Nginx IPC::Run

# 设置Perl模块路径
export PERL5LIB=.:$PERL5LIB

执行测试

# 运行全部测试
make test

# 运行单个测试用例
prove -Itest-nginx/lib -r t/plugin/openid-connect.t

常见问题排查

1. Lua模块路径问题

错误提示unknown directive "lua_package_path"时，需确认：

# 检查OpenResty路径
export PATH=/usr/local/openresty/nginx/sbin:$PATH

2. 测试依赖缺失

完整测试需要额外的外部服务支持，建议参考 CI 配置脚本搭建完整测试环境。

总结

本文详细介绍了 Apache APISIX 从源码构建的全流程，包括基础环境准备、依赖管理、服务启动和测试验证等关键步骤。对于开发者而言，掌握源码构建能力是深度参与项目开发的基础。在实际操作过程中，可能会遇到各种环境相关的问题，建议参考官方文档和社区资源获取最新解决方案。

apisix Apisix是一个基于Nginx的API网关，主要用于微服务架构中的API管理和服务发现。它的特点是高性能、轻量级、易于配置等。适用于API管理和负载均衡场景。 项目地址: https://gitcode.com/gh_mirrors/api/apisix