Apache APISIX 3.12 完整安装与使用实战：从零到生产环境-北京尧图网络

先聊一个大家装网关时特别容易纠结的问题到底该选 Nginx 手写配置还是直接用云厂商自带网关又或者自己搭一套开源方案我的答案很直接如果团队还没深度绑定云平台、又想要一个能上生产、能看配置、能写插件的流量入口Apache APISIX 基本是绕不开的选项。这篇文章要讲的是 APISIX 3.12 的完整安装和使用流程从零开始把每个命令、每个参数背后的原因都拆开讲清楚。我会用自己实跑过的环境作为例子把那些文档里不会写、出了问题才发现的坑一次性列出来。这篇内容不是“快速跑个 demo”那么浅而是按照真实上线逻辑来走先装依赖、再编译安装、接着配 etcd、创建第一个路由、挂 upstream、上插件、接 HTTPS最后再把常见故障排查了一遍。适合刚接触 API 网关的读者从零跟到底也适合准备把 APISIX 从测试环境搬到生产环境的同学做一次自查。3.12 这个版本整体语法和目录结构已经和 2.x 时代有肉眼可见的差异如果你之前只玩过 2.x这篇文章也能帮你快速对齐新版本的变化。1. 为什么是 APISIX 3.12版本选型与核心能力拆解1.1 网关到底解决了什么问题先别急着敲命令想清楚一件事你为什么要用网关。微服务也好、单体拆模块也好只要东西一多客户端要记的地址就多鉴权逻辑就分散限流、日志、熔断这些横切逻辑就不知道该放哪里。网关的本质是把“流量入口统一收口”然后把公共能力下沉让后端服务只关心自己的业务逻辑。拿生活里的小区门卫类比每个楼栋的住户不用各自操心来访登记门卫统一把外面的人和里面的人隔开该拦的拦、该放的放这就是网关的位置。APISIX 在做这件事时的核心优势有三点第一是极致的数据平面性能用的是 OpenResty 加 LuaJIT 这条路和 Nginx 系是同宗同源线上扛高并发心里有底第二是配置模型非常统一所有路由、插件、上游节点都能通过 Admin API 和 etcd 来管理配置文件你甚至可以做到“只读不写”第三是插件的热加载机制改插件参数不用 reload 整个网关进程线上流量抖动可以压到极小。3.12 版本在这些基础上把 Admin API 的权限模型、SSL 证书管理、上游健康检查的类型判断都做了一个比较大的完善和 2.x 相比更像一个“配置即代码”的成熟产品。1.2 3.12 版本的几个关键特性与适用场景先明确一个概念APISIX 3.x 的版本号已经把主版本拉到 3不再是 2.x 的小步快跑这意味着它的路由模型、插件 API、甚至一些默认端口都存在破坏性变更。以 3.12 为例路由规则的匹配表达式使用了新版 Router 引擎前缀匹配和变量表达式可以写得更细而且一个路由可以直接绑定多个 upstream这在灰度发布场景里非常顺手。再加上 Admin API 默认启用了更严格的 key 校验过去那种“内网裸奔、靠网络隔离兜底”的玩法就真的不推荐了。3.12 适合什么场景呢我实践下来的感受是如果你是中小团队后端服务比较杂有 Java、Go、Python 混着部署又不想每家自己搞一套鉴权和限流组件那 APISIX 3.12 几乎是开箱即用的基建。如果你已经在用 Nginx 或者 OpenResty想从手工维护 conf 文件的模式里跳出来换成可编程、可版本控制的网关3.12 的迁移路径也相对平滑。当然如果你只是想要点几下鼠标就能配置的纯图形化网关APISIX 自带的 dashboard 在这个版本里确实还差点意思更适合配好之后只做“查看”而不是“管理”。2. 环境准备与源码安装保姆级全过程2.1 依赖项清单及版本匹配说明APISIX 不是跑在裸 C 上的程序它基于 OpenResty所以先把底层运行环境想清楚。我的环境是 Ubuntu 22.04 LTS首先确保系统里装好了基础编译工具链、Perl、以及 PCRE、OpenSSL、YAML 的开发库。这些库的作用分别是PCRE 负责正则表达式的快速匹配OpenSSL 承担 TLS 会话和证书加解密YAML 库用来解析我们马上要写的 config.yaml。缺一个都不行等到编译阶段再补依赖会非常痛苦因为 APISIX 的模块链很长中途断掉不好排查。官方对版本的硬性建议是 etcd 至少 3.4.0OpenResty 至少 1.21.4.1。但我建议你在 3.12 上直接用更新的组合etcd 3.5.x 加上 OpenResty 1.25.3.x。为什么这么选APISIX 3.12 官方测试矩阵里就是围绕这个版本区间跑的规避一些已知 bug。你在自己环境里如果已经装了 OpenResty 老版本先别急着暴力卸载可以在openresty -v确认具体版本后再决定是升级还是重新编译一个新实例。2.2 下载编译安装两条命令背后的细节源码安装推荐从 Apache 官方渠道下载 apache-apisix-3.12.0-src.tgz不要随便从第三方镜像站拉压缩包因为网关会长期待在公网上供应链安全也是安全。下载后我习惯先做一个校验用官方发布的 SHA512 校验和对比一下避免包被篡改。比起直连下载国内网络环境用镜像站可能更快但你下载完必须自己比一下哈希不然心里不踏实。解压之后进入目录第一步是make deps这一步会下载项目依赖的全部 Lua 库并编译其中的 C 扩展。为什么这一步特别耗时因为 APISIX 用了一批 LuaRocks 包这些包之间还有依赖关系编译要逐个跑完。第一遍失败很常见原因大多是网络问题或者某个库的版本拉不下来。我建议在跑之前把系统代理和 DNS 都确认好必要时给 luarocks 配置一个国内镜像源不然反复跑make deps会耗尽你的耐心。第二步是make install把构建好的文件复制到系统目录。我的环境里安装完成后入口在/usr/local/apisix/bin/apisix所以为了让命令用着顺手我把它软链到了/usr/local/bin然后再执行apisix version验证版本输出。这里有个容易被忽略的点软链之后一定要确认执行的是新版本而不是系统里残留的老版本踩过一次教训排查了半天才发现 PATH 顺序有问题实际调的还是旧 apisix。2.3 配置文件最小可用配置admin key、监听端口、etcdAPISIX 3.12 的主要配置集中在/usr/local/apisix/conf/config.yaml。这个文件第一次打开你会看到一大串注释不要慌先只关注几个核心项。第一是监听端口node_listen默认是 9080HTTP和 9443HTTPS这是数据平面接收外部请求的入口第二是admin_listen默认是0.0.0.0:9180这是 Admin API 的控制端口注意这个端口绝对不要裸奔到公网第三是etcd部分APISIX 3.12 必须连接 etcd 才能正常工作默认配置指向127.0.0.1:2379。大于等于 3.12 的版本里Admin API 默认配置了一个admin_key你可以在apisix.router和admin段落里找到它。生产环境务必要改成你自己生成的一长串随机字符串并透传给所有需要调 Admin API 的服务。最后是apisix.plugins列表这个列表里列的才是能用的插件你需要把常用插件逐个打开比如limit-count、key-auth、cors、proxy-rewrite。不要想着“默认都开了”没有在配置文件里启用插件就是摆设。3. etcd 先行与第一个路由创建3.1 为什么必须要有 etcdAPISIX 在 3.x 里把配置分成两层一层是 config.yaml记录网关注启动时必须要读的能力配置另一层是运行时数据包括路由、服务、上游、证书等全部放进 etcd。为什么要把运行时数据放到 etcd 而不是本地文件道理和“共享状态不要落在单机磁盘”一样etcd 提供强一致性的 KV 分发APISIX 的所有节点只要连同一个 etcd就能读到完全一样的路由表某个节点挂了也不会出现“一部分机器走老规则、一部分走新规则”的情况。这就是配置中心的价值。所以安装完 APISIX 之后第一件事是把 etcd 起来。如果机器上没有 etcd最直接的方式是下载官方二进包直接跑。我习惯用 systemd 托管 etcd 进程写一个简单的 Unit 文件指定数据目录和监听端口。一个典型的单节点 etcd 启动参数大致是这样的etcd --data-dir/var/lib/etcd --listen-client-urlshttp://0.0.0.0:2379 --advertise-client-urlshttp://127.0.0.1:2379。注意advertise-client-urls要和 APISIX 能访问到的地址一致如果 APISIX 和 etcd 在同一台机器上用127.0.0.1是最稳妥的免得走网卡绕一圈。启动之后立刻验证连通性etcdctl endpoint health返回 healthy 表示服务就绪。这一步不要跳过很多人后面出现“路由创建成功但请求不到”的问题一半以上其实是 etcd 没通Admin API 返回的只是“把数据写进 etcd”的成功不代表数据平面已经拿到。3.2 启动、检查与第一个路由创建APISIX 常规操作只有几个命令apisix start启动、apisix stop停止、apisix reload重载。启动前建议先做一次配置校验apisix test会把 config.yaml 的语法过一遍有低级缩进错误直接暴露。启动完成后用curl -s http://127.0.0.1:9080/访问一下如果没有任何输出或者返回默认提示至少说明监听端口已经打开。动手创建第一个路由我习惯先在测试机上起一个简单的后端服务比如python3 -m http.server 8080然后通过 Admin API 把路由写进去。命令长这样curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/hello \ -H X-API-KEY: your-admin-key \ -d { uri: /hello, upstream: { type: roundrobin, nodes: { 127.0.0.1:8080: 1 } } }这里要理解的关键点是PUT方法带一个路由 ID上面的hello意思是“如果不存在就创建存在就整体覆盖”方便业务做幂等发布。返回的 JSON 里value字段是 etcd 里实际存的路由定义key字段是 etcd 的路径看懂这个返回结构后面排查问题就快很多。创建完路由后用curl http://127.0.0.1:9080/hello试试能看到 Python 服务返回的目录列表就说明链路通了。3.3 Admin API 的权限校验逻辑3.12 的 Admin API 默认要求带X-API-KEY请求头这个 key 对应 config.yaml 里 admin_key 的key字段。每次请求带这个头很烦但这是底线安全措施别贪方便把校验关掉。实际工作时我建议一个更好用的姿势把 Admin API 绑定到内网单独端口或者用防火墙限制 9180 端口只能从跳板机访问同时保留 key 校验。两层防护叠加就算内网被横向穿透别人也没法直接改网关配置。还有一个细节Admin API 的操作最好统一走 CI/CD 流水线把路由、上游、SSL 的 JSON 定义放到 Git 仓库里用脚本批量 PUT 上去。这套“配置即代码”的做法能让你随时回滚到任何一个历史版本。踩过这个坑的人都懂直接在控制台或者 curl 里随手改配置等到出问题时你根本不知道昨天谁改了什么。4. 负载均衡、路由进阶与常用插件的实操4.1 upstream权重与被动健康检查的配置逻辑真实场景下不会只往 upstream 里放一个节点所以我们要搞懂 APISIX 的负载均衡模型。upstream 的类型常用roundrobin也就是加权轮询每个节点后的数字就是权重。权重的作用不是“概率百分比”而是“相对比例”比如下面这个配置upstream: type: roundrobin nodes: 10.0.0.1:8080: 2 10.0.0.2:8080: 1意思是 10.0.0.1 分到的流量大概是 10.0.0.2 的两倍。这个模型非常直观扩缩容时只需要改 Admin API 里的 nodes 表不需要 reload。健康检查是 APISIX 3.12 里必须主动拥抱的能力默认情况是“被动检查”例如连续返回 5xx 多少次后把节点标记为不健康暂停转发。较新版本还支持主动健康检查网关按固定间隔主动探测生产环境我建议两者都开被动检查用来快速反应主动检查用来及时恢复。配置里passive.health_check. unhealthy相关字段都是时间窗口和次数比如http_failures: 3表示 3 次失败判定不健康interval: 10表示检查窗口是 10 秒。这些参数没有绝对标准按你的业务容忍度去调但我给一个起步参考失败次数 3、时间窗口 10 秒、恢复探测间隔 5 秒先把稳定性底线兜住。4.2 路由匹配规则与优先级路由是 APISIX 的“招牌”3.12 里路由匹配支持多种维度uri前缀匹配、host域名匹配、method方法匹配、vars变量表达式、priority优先级。默认情况下 APISIX 打分排序谁的匹配条件更精确谁先命中。举个实际例子curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/order \ -H X-API-KEY: your-admin-key \ -d { uri: /order/*, methods: [GET, POST], priority: 100, upstream: { type: roundrobin, nodes: { 127.0.0.1:8090: 1 } } }这里的uri: /order/*匹配所有/order/前缀的请求。如果你同时有两条路由一条是/order/*另一条是/order/special/*那后者的精度更高即使不写 priority 也会优先命中。当两条路由匹配精度一样时就看 priority 谁大了。我在实践中吃过一个亏新加路由忘记写 priority结果老的宽泛路由一直抢占流量业务方那边看到的现象就是灰度流量比例完全不对。所以强烈建议团队在路由命名和 priority 上形成一套纪律。另外 3.12 里可以使用vars做高级条件匹配比如按请求头或者 Cookie 分流vars: - - http_user_agent - ~~ - .*iPhone.*这个写法看起来有点别扭其实就是“用户代理匹配 iPhone 正则”。遇到这种复杂组合条件我建议先在本地用 curl 带请求头测通再上生产。不是因为语法难而是因为表达式写错不会报错只是路由一直不匹配排起来比直接报错麻烦多了。4.3 常用插件实操限流、鉴权、跨域插件是 APISIX 的另一大卖点。先看限流我生产里最常用的是limit-count它的逻辑是固定时间窗口内的计数限流比如“每分钟最多 1000 次”。配置里最关键的两个参数是time_window和max还有rejected_code建议设成 429 而不是默认的 503因为限流是主动拒绝不是服务不可用客户端看到 429 语义更准确。一个典型的路由加限流接口curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/limit \ -H X-API-KEY: your-admin-key \ -d { uri: /limit, plugins: { limit-count: { count: 10, time_window: 60, rejected_code: 429, policy: local } }, upstream: { type: roundrobin, nodes: { 127.0.0.1:8080: 1 } } }注意 ici 那个policy字段。local是单节点统计网关集群场景下会有误差redis模式把计数器放到 Redis适合多节点 APISIX 共用一套限流阈值。单机测试用 local 就没问题集群生产请直接上 redis。再看鉴权最简单的方案是key-auth。它要求你创建一个 Consumer给这个消费者分配一个 key然后在需要鉴权的路由上挂载key-auth插件客户端请求时必须带apikey: key请求头否则返回 401。这个方案适合内部服务调用key 本身相当于调用凭证但注意它不该用于面向 C 端用户的登录鉴权因为 key 会暴露在客户端里没有签名机制的话很容易被盗。跨域问题交给cors插件最干净。配置allow_origins为具体域名列表allow_methods为 GET/POST/PUT/DELETEallow_headers为实际业务用到的请求头。千万不要图省事用*全放开浏览器预检请求通过之后你的接口就被任何页面随意调用了。我的经验是跨域插件配置要跟着前端的发布清单走绑定具体源避免泛化规则引发数据被第三方页面读取的安全风险。5. HTTPS证书接入与强制跳转5.1 SSL资源配置网关是公网入口HTTPS 是门槛。APISIX 里证书不是直接放到配置文件里而是通过 Admin API 创建 SSL 资源对象然后用 SNI 字段绑定到特定域名。这点和其他网关不太一样好处是证书的增删改可以完全走 API和路由一样可版本控制。创建一个 SSL 资源需要把 PEM 格式的证书和私钥传上去借助 curl 读取文件内容拼成 JSON。命令行里用$(cat cert.pem)这种用法要注意文件不能太大普通单域名证书没问题。真正需要留意的是证书链的完整性很多证书签发机构会给你一个包含中间证书的 bundle 文件别只传站点证书那一张否则一部分安卓设备开 HTTPS 会直接报证书错误问题排查起来极其隐蔽因为桌面浏览器可能自动补全了中间证书。稳妥的做法是把站点证书和中间证书拼接后传输。创建完 SSL 资源再用curl https://yourdomain验证用openssl s_client -connect yourdomain:443查看证书链确保签发机构完整可信。这个动作我每次都会做就是因为上面吃的亏印象太深。5.2 HTTP到HTTPS自动跳转一个常见的需求是用户访问http://时自动跳转到https://。APISIX 3.12 里可以用redirect插件实现plugins: redirect: http_to_https: true把它挂在整个入口路由上网关收到 80 端口的 HTTP 请求后直接返回 301 跳转。这个配置的核心是要想好 301 和 308 的选择301 是永久重定向浏览器会缓存以后直接访问 HTTPS308 是永久重定向但保持请求方法不变化。POST 请求的场景要是用了 301某些客户端会把方法改成 GET导致业务出错所以如果你的 API 里有 POST/PUT跳转建议用redirect插件配置ret_code: 308。还有一个常见需求是“部分路径强制 HTTPS其他路径 HTTP 可访问”。这种场景下先用vars条件路由区分再单独在 HTTPS 路由上挂 redirect 插件不要让所有路径都一棍子打死。否则连健康检查的 HTTP 请求都被跳走负载均衡器那边的探活就会一直报错。6. 常见问题与排查实录6.1 安装阶段的高频问题装 APISIX 时最容易出问题的环节就是make deps。我遇到过两类情况一类是网络差导致 LuaRocks 包下载超时表现为进度条卡住然后报连接失败解决办法是换镜像或者给 luarocks 设置代理另一类是系统缺少编译依赖报错信息里出现pcre.h或openssl/ssl.h找不到那就需要把 2.1 小节里提到的开发包安装完整再重新执行。还有一个相当隐蔽的问题apisix start时报错“找不到 config.yaml 或读取失败”。原因往往是当前工作目录不对因为 apisix 命令默认会从当前目录或者安装目录找配置文件。我的建议是启动前先cd /usr/local/apisix再执行apisix start别在随机目录下直接敲命令。如果还报权限问题检查 apisix 运行用户对日志目录/usr/local/apisix/logs有没有写权限很多诡异故障都是这么来的。6.2 运行阶段的高频问题运行期最让人头疼的就是“Admin API 上路由已经存在但请求就是 404”。第一反应查一下 etcd 数据是否可见etcdctl get /apisix/routes如果 etcd 里有但数据平面 404大概率是 APISIX 没有成功同步配置此时可以先访问curl http://127.0.0.1:9090/apisix/admin/routes看数据平面自己视角里的路由列表等等9090 不是 Admin 默认端口别混淆。看一下 APISIX 内部状态最好直接确认 config.yaml 里 etcd 地址是否和实际启动的 etcd 一致。第二个高频场景是“改了插件配置但不生效”。记住 APISIX 的插件热加载不需要重启网关但你需要确保插件名称在 config.yaml 的plugins列表里。如果你新加的插件没在列表里Admin API 会拒绝写入或者写入后不执行。查这个只要打开配置文件找limit-count、key-auth等关键字就行缺了补上然后apisix reload。第三个高频问题是“为什么我的 upstream 节点明明只有一个却被负载均衡策略轮询得满头问号”。这其实不是问题roundrobin 只有一个节点时就是固定转发。如果你发现请求发到了不在列表里的地址那就要查一下是不是其他路由匹配到了尤其是路由匹配优先级搞乱的时候流量就会被“抢走”。排查方法很简单违规路由一条一条禁掉再 curl 测试看哪条路由命中。6.3 七条保命配置建议下面是我把 APISIX 3.12 从测试推到生产后沉淀下来的检查清单。每一条都对应过一次真实故障价值比教程本身还高。第一9180 端口必须限制来源。最简单的方式是用防火墙规则只允许内网管理网段访问同时保留 Admin key。第二给 etcd 加上认证。APISIX 连接 etcd 可以在 config.yaml 里配置用户名密码但前提是 etcd 端开了鉴权建议直接用 etcd 的 user 和 root 机制。第三路由和 SSL 资源必须纳入 Git 管理拒绝线上手改。第四先上线一套“全局限流”保住底线比如所有/api/*请求都先挂一个全局 limit-count防止某个新路由漏配限流就被打爆。第五日志轮转要提前配置。APISIX 跑久了 access.log 会膨胀到几个 Glogrotate 配不好磁盘满的锅只能自己背。第六健康检查别忘了超时配置。后端节点慢但不挂被动健康检查不会把它摘掉业务会一直感受超时。第七所有 change 操作写完后立刻用数据平面的实际请求验证一遍光看 Admin API 返回成功是不够的因为业务链路是否畅通只有数据平面知道。这些建议看起来都很基础但要真做到每一条都不落地已经是很多线上事故形成的条件了。我见过太多因为“图方便”临时跳过某个检查最后在凌晨两点被报警拉起来填坑的例子。最后说一句掏心窝的话网关这种东西安装只是 20% 的工作剩下 80% 都是在跟“请求为什么不按我预期走”作斗争。遇到问题不要下意识重启先顺着“客户端 → APISIX 路由匹配 → 插件命中 → upstream 节点 → 后端服务”这条链路逐段拆。多跑几次 etcd 清空重来你会对配置模型有比文档更深的体感。

Apache APISIX 3.12 完整安装与使用实战：从零到生产环境

相关推荐

3 个免费图像识别 API，零成本跑通视觉 AI

无法生成：‘rea‘缺乏有效技术语义与上下文

小场地游乐项目怎么选？沙盘赛车十几平就能开

更多资讯

冰封末日生存沙盒：4K画质优化与全流程通关攻略

怎么登报挂失？不用跑报社！文案模板与办理流程都在

企业AI工程化交付实战：Codex+WorkBuddy+Harness+RAG+Skills+MCP六维闭环

artcraft创意工具开发实战：从需求拆解到技术选型的完整指南

中文Word一键转公众号排版：本地AI智能美化工具

TongWeb集中管理文件名乱码排查：LANG环境变量与JVM字符集链路解析

今日更新

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？