Apache APISIX 在 Mac 上快速构建开发环境基于 Docker 挂载源码的完整实践指南【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix本文面向希望在 macOS 上快速入门 Apache APISIX 二次开发与测试的开发者介绍一种基于 Docker 的开发环境构建方案将 APISIX 源码目录挂载进容器在容器内完成依赖安装、运行时编译与测试用例执行。读完本文你将掌握从拉取源码、构建开发镜像、启动 Etcd到make deps、make run以及运行指定测试用例的完整闭环流程并能独立解决容器环境下最常见的 socket 绑定报错问题。一、为什么在 Mac 上推荐用 Docker 构建开发环境Apache APISIX 是一款云原生 API 网关其运行时依赖 OpenResty、LuaRocks 及大量 Lua 依赖对操作系统的依赖较为敏感。在 macOS 上直接编译这套依赖链不仅耗时还容易踩到 Homebrew 版本与 OpenResty 补丁不兼容的坑。本教程的思路是在容器内构建和运行 Apache APISIX同时把宿主机上的 APISIX 源码目录挂载进容器实现宿主机写代码、容器内编译测试的开发体验。由于源码是实时挂载的你在宿主机上的任何修改都会立即反映到容器中无需重新构建镜像即可迭代。需要说明的是Docker 方案适合快速开始入门阶段开发的场景。官方在依赖安装文档中列出的受支持操作系统主要是 Linux 发行版如 CentOS 7、Fedora 31 32、Ubuntu 16.04 18.04、Debian 9 10、Arch Linux。如果你希望获得更完整的开发体验Linux-based 虚拟机或直接使用 Linux 系统作为开发环境是更好的选择。二、实现思路源码挂载 容器内构建整个方案可以拆解为四个关键环节构建开发镜像镜像内预装Test::Nginx测试框架APISIX 测试套件的核心依赖与常用开发工具启动 EtcdAPISIX 默认将配置存储在 Etcd 中需要一个独立的 Etcd 实例挂载源码启动容器开发容器与 Etcd 均使用宿主网络--nethost并将宿主机当前目录即 APISIX 源码挂载到容器内的/apisix容器内初始化与运行通过make deps安装 Lua 依赖用make run启动网关用prove执行测试用例。三、完整实现步骤3.1 拉取源码并构建开发镜像首先获取 APISIX 源码并进入仓库根目录git clone https://gitcode.com/GitHub_Trending/ap/apisix.git cd apisix接着构建开发镜像镜像名与标签可自行定义本文沿用官方教程的apisix-dev-envdocker build -t apisix-dev-env -f example/build-dev-image.dockerfile .这个构建过程依赖仓库根目录下的 example/build-dev-image.dockerfile。它的内容非常精简我们可以逐段拆解FROM ubuntu:20.04 # Install Test::Nginx RUN apt update RUN apt install -y cpanminus make RUN cpanm --notest Test::Nginx # Install development utils RUN apt install -y sudo git gawk curl nano vim inetutils-ping WORKDIR /apisix ENV PERL5LIB.:$PERL5LIB ENTRYPOINT [tail, -f, /dev/null]关键点说明基础镜像ubuntu:20.04镜像仅承担开发环境职责不打包任何 APISIX 运行时——运行时在容器启动后通过挂载进来的源码现场构建Test::NginxAPISIX 的测试用例基于 OpenResty 社区著名的Test::Nginx测试框架编写通过cpanm --notest安装跳过其自带的测试以加速镜像构建WORKDIR /apisix将容器工作目录固定为/apisix与后续源码挂载点保持一致ENV PERL5LIB.:$PERL5LIB让 Perl 在当前目录即/apisix下查找测试依赖这是prove能顺利加载测试库的关键ENTRYPOINT [tail, -f, /dev/null]容器启动后保持前台驻留避免因没有前台进程而立即退出这是开发沙箱型镜像的常见手法。3.2 启动 EtcdAPISIX 依赖 Etcd 保存路由、上游、插件等配置数据。启动一个独立 Etcd 容器并使用宿主网络docker run -d --name etcd-apisix --nethost pachyderm/etcd:v3.5.2使用--nethost后Etcd 直接监听宿主机的 2379/2380 端口容器内 APISIX 访问127.0.0.1:2379即可连接无需额外的端口映射与容器间网络配置。3.3 挂载源码并启动开发容器将宿主机当前目录APISIX 源码根目录以读写方式挂载到容器内的/apisix同样使用宿主网络docker run -d --name apisix-dev-env --nethost -v $(pwd):/apisix:rw apisix-dev-env:latest-v $(pwd):/apisix:rw是这套方案的核心宿主机与容器共享同一份源码你在宿主机编辑的任何文件都会实时同步到容器内。3.4 构建运行时并配置测试环境进入容器先安装 APISIX 的全部 Lua 依赖再建立nginx软链接docker exec -it apisix-dev-env make deps docker exec -it apisix-dev-env ln -s /usr/bin/openresty /usr/bin/nginx这里展开说明两条命令背后的实现make deps对应 Makefile 中的deps目标它先调用install-runtime安装 OpenResty 运行时再通过 LuaRocks 读取apisix-master-0.rockspec声明文件以--only-deps方式安装全部依赖到deps目录。该目标对 LuaRocks 版本有硬性校验要求 LuaRocks 3.x版本不符会直接报错退出ln -s /usr/bin/openresty /usr/bin/nginx是为兼容性建立的软链接。APISIX 的若干脚本与测试工具会直接调用nginx命令而镜像内只安装了 OpenResty因此需要此链接保证nginx命令可解析。四、启动与停止 APISIX依赖安装完成后即可通过以下命令启动和停止网关docker exec -it apisix-dev-env make run docker exec -it apisix-dev-env make stop这两条命令分别对应 Makefile 中的run与stop目标make run先执行runtime目标确保运行时就绪随后调用apisix start启动网关make stop调用apisix stop立即停止网关。启动成功后你可以在宿主机直接访问127.0.0.1:9080APISIX 的 HTTP 入口与127.0.0.1:9180Admin API 入口验证网关运行状态。五、常见问题排查worker_events.sock绑定失败如果执行make run时收到如下错误nginx: [emerg] bind() to unix:/apisix/logs/worker_events.sock failed (95: Operation not supported)其原因是 Docker Desktop 在 macOS 上默认使用的文件共享实现virtiofs不支持 Unix domain socket 的创建与绑定而 APISIX 内部通过worker_events.sock实现 worker 进程间事件通信因此在源码挂载目录/apisix/logs下创建 socket 时失败。解决办法是调整 Docker Desktop 的File Sharing设置将文件共享方式修改为gRPC FUSE或osxfs修改设置后重启 Docker Desktop 与apisix-dev-env容器重新执行make run即可正常启动。六、运行指定测试用例APISIX 的测试用例全部位于 t/ 目录下采用Test::Nginx框架编写.t后缀。运行单个用例的方式如下docker exec -it apisix-dev-env prove t/admin/routes.t以t/admin/routes.t为例它覆盖了 Admin API 路由管理的核心场景。prove会从当前目录/apisix按PERL5LIB配置加载测试库并执行用例。如需跑全量测试可以直接使用make test其底层等价于prove -I../test-nginx/lib -I./ -r -s t/即递归-r执行t/下所有用例。日常开发中建议先针对单个.t文件运行定位到具体模块后再做全量回归能显著缩短调试周期。七、开发提效小结与注意事项源码实时同步由于$(pwd)挂载进容器宿主机修改代码后直接在容器内make run或重跑prove即可无需重建镜像Etcd 数据持久化本文的 Etcd 容器未挂载数据卷重启容器后配置数据会丢失。若需保留配置可为 Etcd 增加数据卷挂载适用边界本方案定位是快速入门开发追求更贴近生产的开发体验时建议改用 Linux 虚拟机或原生 Linux 环境参考依赖安装文档中列出的受支持发行版进行部署端口占用--nethost模式下网关与 Etcd 直接占用宿主机端口需确保 9080、9180、2379 等端口未被占用。通过以上流程你可以在 Mac 上获得一套可运行、可调试、可测试的 APISIX 开发环境后续即可专注于插件开发、路由配置与测试用例编写。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Apache APISIX 在 Mac 上快速构建开发环境：基于 Docker 挂载源码的完整实践指南
Apache APISIX 在 Mac 上快速构建开发环境基于 Docker 挂载源码的完整实践指南【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix本文面向希望在 macOS 上快速入门 Apache APISIX 二次开发与测试的开发者介绍一种基于 Docker 的开发环境构建方案将 APISIX 源码目录挂载进容器在容器内完成依赖安装、运行时编译与测试用例执行。读完本文你将掌握从拉取源码、构建开发镜像、启动 Etcd到make deps、make run以及运行指定测试用例的完整闭环流程并能独立解决容器环境下最常见的 socket 绑定报错问题。一、为什么在 Mac 上推荐用 Docker 构建开发环境Apache APISIX 是一款云原生 API 网关其运行时依赖 OpenResty、LuaRocks 及大量 Lua 依赖对操作系统的依赖较为敏感。在 macOS 上直接编译这套依赖链不仅耗时还容易踩到 Homebrew 版本与 OpenResty 补丁不兼容的坑。本教程的思路是在容器内构建和运行 Apache APISIX同时把宿主机上的 APISIX 源码目录挂载进容器实现宿主机写代码、容器内编译测试的开发体验。由于源码是实时挂载的你在宿主机上的任何修改都会立即反映到容器中无需重新构建镜像即可迭代。需要说明的是Docker 方案适合快速开始入门阶段开发的场景。官方在依赖安装文档中列出的受支持操作系统主要是 Linux 发行版如 CentOS 7、Fedora 31 32、Ubuntu 16.04 18.04、Debian 9 10、Arch Linux。如果你希望获得更完整的开发体验Linux-based 虚拟机或直接使用 Linux 系统作为开发环境是更好的选择。二、实现思路源码挂载 容器内构建整个方案可以拆解为四个关键环节构建开发镜像镜像内预装Test::Nginx测试框架APISIX 测试套件的核心依赖与常用开发工具启动 EtcdAPISIX 默认将配置存储在 Etcd 中需要一个独立的 Etcd 实例挂载源码启动容器开发容器与 Etcd 均使用宿主网络--nethost并将宿主机当前目录即 APISIX 源码挂载到容器内的/apisix容器内初始化与运行通过make deps安装 Lua 依赖用make run启动网关用prove执行测试用例。三、完整实现步骤3.1 拉取源码并构建开发镜像首先获取 APISIX 源码并进入仓库根目录git clone https://gitcode.com/GitHub_Trending/ap/apisix.git cd apisix接着构建开发镜像镜像名与标签可自行定义本文沿用官方教程的apisix-dev-envdocker build -t apisix-dev-env -f example/build-dev-image.dockerfile .这个构建过程依赖仓库根目录下的 example/build-dev-image.dockerfile。它的内容非常精简我们可以逐段拆解FROM ubuntu:20.04 # Install Test::Nginx RUN apt update RUN apt install -y cpanminus make RUN cpanm --notest Test::Nginx # Install development utils RUN apt install -y sudo git gawk curl nano vim inetutils-ping WORKDIR /apisix ENV PERL5LIB.:$PERL5LIB ENTRYPOINT [tail, -f, /dev/null]关键点说明基础镜像ubuntu:20.04镜像仅承担开发环境职责不打包任何 APISIX 运行时——运行时在容器启动后通过挂载进来的源码现场构建Test::NginxAPISIX 的测试用例基于 OpenResty 社区著名的Test::Nginx测试框架编写通过cpanm --notest安装跳过其自带的测试以加速镜像构建WORKDIR /apisix将容器工作目录固定为/apisix与后续源码挂载点保持一致ENV PERL5LIB.:$PERL5LIB让 Perl 在当前目录即/apisix下查找测试依赖这是prove能顺利加载测试库的关键ENTRYPOINT [tail, -f, /dev/null]容器启动后保持前台驻留避免因没有前台进程而立即退出这是开发沙箱型镜像的常见手法。3.2 启动 EtcdAPISIX 依赖 Etcd 保存路由、上游、插件等配置数据。启动一个独立 Etcd 容器并使用宿主网络docker run -d --name etcd-apisix --nethost pachyderm/etcd:v3.5.2使用--nethost后Etcd 直接监听宿主机的 2379/2380 端口容器内 APISIX 访问127.0.0.1:2379即可连接无需额外的端口映射与容器间网络配置。3.3 挂载源码并启动开发容器将宿主机当前目录APISIX 源码根目录以读写方式挂载到容器内的/apisix同样使用宿主网络docker run -d --name apisix-dev-env --nethost -v $(pwd):/apisix:rw apisix-dev-env:latest-v $(pwd):/apisix:rw是这套方案的核心宿主机与容器共享同一份源码你在宿主机编辑的任何文件都会实时同步到容器内。3.4 构建运行时并配置测试环境进入容器先安装 APISIX 的全部 Lua 依赖再建立nginx软链接docker exec -it apisix-dev-env make deps docker exec -it apisix-dev-env ln -s /usr/bin/openresty /usr/bin/nginx这里展开说明两条命令背后的实现make deps对应 Makefile 中的deps目标它先调用install-runtime安装 OpenResty 运行时再通过 LuaRocks 读取apisix-master-0.rockspec声明文件以--only-deps方式安装全部依赖到deps目录。该目标对 LuaRocks 版本有硬性校验要求 LuaRocks 3.x版本不符会直接报错退出ln -s /usr/bin/openresty /usr/bin/nginx是为兼容性建立的软链接。APISIX 的若干脚本与测试工具会直接调用nginx命令而镜像内只安装了 OpenResty因此需要此链接保证nginx命令可解析。四、启动与停止 APISIX依赖安装完成后即可通过以下命令启动和停止网关docker exec -it apisix-dev-env make run docker exec -it apisix-dev-env make stop这两条命令分别对应 Makefile 中的run与stop目标make run先执行runtime目标确保运行时就绪随后调用apisix start启动网关make stop调用apisix stop立即停止网关。启动成功后你可以在宿主机直接访问127.0.0.1:9080APISIX 的 HTTP 入口与127.0.0.1:9180Admin API 入口验证网关运行状态。五、常见问题排查worker_events.sock绑定失败如果执行make run时收到如下错误nginx: [emerg] bind() to unix:/apisix/logs/worker_events.sock failed (95: Operation not supported)其原因是 Docker Desktop 在 macOS 上默认使用的文件共享实现virtiofs不支持 Unix domain socket 的创建与绑定而 APISIX 内部通过worker_events.sock实现 worker 进程间事件通信因此在源码挂载目录/apisix/logs下创建 socket 时失败。解决办法是调整 Docker Desktop 的File Sharing设置将文件共享方式修改为gRPC FUSE或osxfs修改设置后重启 Docker Desktop 与apisix-dev-env容器重新执行make run即可正常启动。六、运行指定测试用例APISIX 的测试用例全部位于 t/ 目录下采用Test::Nginx框架编写.t后缀。运行单个用例的方式如下docker exec -it apisix-dev-env prove t/admin/routes.t以t/admin/routes.t为例它覆盖了 Admin API 路由管理的核心场景。prove会从当前目录/apisix按PERL5LIB配置加载测试库并执行用例。如需跑全量测试可以直接使用make test其底层等价于prove -I../test-nginx/lib -I./ -r -s t/即递归-r执行t/下所有用例。日常开发中建议先针对单个.t文件运行定位到具体模块后再做全量回归能显著缩短调试周期。七、开发提效小结与注意事项源码实时同步由于$(pwd)挂载进容器宿主机修改代码后直接在容器内make run或重跑prove即可无需重建镜像Etcd 数据持久化本文的 Etcd 容器未挂载数据卷重启容器后配置数据会丢失。若需保留配置可为 Etcd 增加数据卷挂载适用边界本方案定位是快速入门开发追求更贴近生产的开发体验时建议改用 Linux 虚拟机或原生 Linux 环境参考依赖安装文档中列出的受支持发行版进行部署端口占用--nethost模式下网关与 Etcd 直接占用宿主机端口需确保 9080、9180、2379 等端口未被占用。通过以上流程你可以在 Mac 上获得一套可运行、可调试、可测试的 APISIX 开发环境后续即可专注于插件开发、路由配置与测试用例编写。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考