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),仅供参考

相关新闻

Mastra Elysia 服务器适配器(@mastra/elysia)实战指南:在 Elysia 应用中挂载 Agent、Workflow 与流式 API

Mastra Elysia 服务器适配器(@mastra/elysia)实战指南:在 Elysia 应用中挂载 Agent、Workflow 与流式 API

Mastra Elysia 服务器适配器(mastra/elysia)实战指南:在 Elysia 应用中挂载 Agent、Workflow 与流式 API 【免费下载链接】mastra Mastra is the modern TypeScript framework for AI-powered applications and agents. 项目地址: https://…

2026/10/22 15:25:19 阅读更多 →
DQN强化学习实战:从Q-learning到PyTorch实现CartPole全解析

DQN强化学习实战:从Q-learning到PyTorch实现CartPole全解析

DQN(Deep Q-Network)这个名字,在强化学习圈子里基本就是“入门必修课”的代名词。2013年DeepMind第一次拿它打Atari游戏,2015年发Nature,用一套算法硬刚49款游戏,其中过半超越人类职业玩家。这个成绩在当时…

2026/11/22 12:35:54 阅读更多 →
Getting Hired 求职课程指南:以结构化流程开启 Web 开发者求职之路

Getting Hired 求职课程指南:以结构化流程开启 Web 开发者求职之路

Getting Hired 求职课程指南:以结构化流程开启 Web 开发者求职之路 【免费下载链接】curriculum The open curriculum for learning web development 项目地址: https://gitcode.com/GitHub_Trending/cu/curriculum Getting Hired 课程是《The Odin Project …

2026/10/25 12:56:49 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/21 23:27:35 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/21 23:27:35 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/21 23:27:35 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/21 23:27:35 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/21 23:27:36 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/21 23:27:37 阅读更多 →

日新闻

周新闻

月新闻