【架构实战】APISIX落地实战：云原生时代的动态网关

一、那次"改个路由要重启网关"的事故

2022年，我们的网关还是Nginx + Lua手写的那一套。

某次大促前，运营临时要调整灰度比例：把 5% 的流量切到新版本。

我改了 Nginx 配置，执行nginx -s reload。

结果：全站 RT 抖动了 200ms，长连接瞬间断开一片，监控告警刷屏。

技术总监冲过来：“你就改个路由比例，怎么把连接都搞断了？”

那一刻我意识到：传统 Nginx 的 reload 不是无损的，网关的"动态能力"才是命门。

后来我们调研了一圈网关，最终选了Apache APISIX。

今天分享我们1年 APISIX 落地实战——它凭什么成为云原生时代的网关首选，又有哪些坑。

二、APISIX 是什么：不止是网关

2.1 出身与定位

APISIX = Apache 顶级项目，基于 Nginx + OpenResty + etcd 的云原生 API 网关。

它不是从零造轮子，而是站在OpenResty的肩膀上：

Nginx（高性能 Web 服务器） └── OpenResty（Nginx + LuaJIT） └── APISIX（Lua 插件 + etcd 配置中心）

核心卖点：配置变更毫秒级生效，无需 reload，连接不中断。

2.2 核心架构：数据面 + 控制面分离

┌─────────────────────────────────────────┐ │ 控制面（Admin API） │ │ 通过 Admin API / Dashboard 写配置 │ └───────────────────┬─────────────────────┘ │ 写入 ▼ ┌──────────┐ │ etcd │ ← 配置存储（强一致） └──────────┘ │ Watch 推送 ▼ ┌─────────────────────────────────────────┐ │ 数据面（APISIX 节点，多个） │ │ Nginx Worker 热加载路由/插件配置 │ │ 处理真实流量：路由/限流/鉴权/观测 │ └─────────────────────────────────────────┘

关键点：etcd 是唯一配置源，所有 APISIX 节点 watch etcd，配置变更秒级同步到所有节点。

2.3 与其他网关对比

三、为什么选 APISIX：动态能力的价值

3.1 热更新不重启

这是 APISIX 最打动我的能力。

# 传统 Nginx：改配置 → reload（断连接）vinginx.conf nginx-sreload# 连接抖动、长连接断开# APISIX：改配置 → Admin API（无损）curl-XPUT http://127.0.0.1:9180/apisix/admin/routes/1\-H'X-API-KEY: xxx'\-d'{"uri":"/api/*","upstream":{"nodes":{"10.0.0.1:8080":1}}}'# 毫秒生效，连接零中断

业务价值：大促期间调整灰度比例、紧急封禁某个 IP、临时限流——都不用动生产连接。

3.2 插件化：能力即插即用

APISIX 把限流、鉴权、熔断、可观测性全部做成插件，按需挂载：

{"uri":"/api/order/*","plugins":{"limit-req":{"rate":100,"burst":50},"prometheus":{},"key-auth":{"key":"secret"}},"upstream":{"nodes":{"10.0.0.1:8080":1}}}

一个路由可挂多个插件，插件可热插拔。

3.3 性能

APISIX 官方 benchmark：单核 QPS 1.8 万+，延迟 P99 < 1ms。

我们生产实测：4 核 8G 的 APISIX 节点，扛住3 万 QPS，CPU 才 40%。

四、APISIX 核心概念

理解这 5 个对象是入门关键：

Route（路由） → 匹配规则（uri/method/host），决定请求去哪 │ ├── 关联 Service（服务，可选，路由分组） │ └── 关联 Upstream（上游，后端节点列表 + 负载均衡） Consumer（消费者）→ 代表一个调用方（如某个 App），用于鉴权/限流隔离 Plugin（插件） → 挂在 Route/Service/Consumer 上的能力

一句话：Route 决定"谁能访问什么、怎么处理"，Upstream 决定"打到哪个后端"。

五、实战：部署与基础配置

5.1 Docker Compose 快速起

# docker-compose.ymlversion:"3"services:apisix:image:apache/apisix:3.9-centosports:-"9080:9080"# 代理端口-"9180:9180"# Admin API 端口volumes:-./config.yaml:/usr/local/apisix/conf/config.yaml:rodepends_on:-etcdetcd:image:bitnami/etcd:3.5environment:ETCD_ENABLE_V2:"true"ALLOW_NONE_AUTHENTICATION:"yes"ETCD_ADVERTISE_CLIENT_URLS:http://etcd:2379ETCD_LISTEN_CLIENT_URLS:http://0.0.0.0:2379

5.2 创建上游（Upstream）

curl-XPUT http://127.0.0.1:9180/apisix/admin/upstreams/1\-H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'\-H'Content-Type: application/json'\-d'{ "name": "order-service", "type": "roundrobin", "nodes": { "10.0.0.1:8080": 10, "10.0.0.2:8080": 10, "10.0.0.3:8080": 5 }, "checks": { "active": { "http_path": "/health", "healthy": {"interval": 5, "successes": 2}, "unhealthy": {"interval": 5, "failures": 3} } } }'

权重说明：10.0.0.1:8080权重 10，10.0.0.3:8080权重 5 → 前者分到的流量是后者 2 倍。

5.3 创建路由（Route）

curl-XPUT http://127.0.0.1:9180/apisix/admin/routes/1\-H'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'\-H'Content-Type: application/json'\-d'{ "uri": "/api/order/*", "name": "order-route", "methods": ["GET", "POST"], "upstream_id": "1", "plugins": { "limit-req": { "rate": 100, "burst": 50, "key": "remote_addr", "rejected_code": 429 } } }'

配置完成后，访问http://127.0.0.1:9080/api/order/123即被代理到后端。

六、核心插件实战

6.1 限流：limit-req

"limit-req":{"rate":100,// 每秒允许 100 个请求"burst":50,// 突发允许 50 个"key":"remote_addr","rejected_code":429}

漏桶算法：平滑限制请求速率，保护后端不被打垮。

6.2 鉴权：key-auth

# 1. 创建 Consumercurl-XPUT http://127.0.0.1:9180/apisix/admin/consumers/1\-H'X-API-KEY: xxx'\-d'{"username":"app-android","plugins":{"key-auth":{"key":"android-secret"}}}'# 2. 路由挂 key-auth 插件"plugins":{"key-auth":{"key":"android-secret"}}

调用方请求需带?apikey=android-secret或 HeaderAuthorization: android-secret。

6.3 可观测性：prometheus

"plugins":{"prometheus":{}}

开启后，APISIX 暴露/apisix/prometheus/metrics指标端点，Prometheus 抓取即可，配合 Grafana 看板监控 QPS、延迟、错误率。

七、动态路由与灰度发布

7.1 用 APISIX 做金丝雀发布

场景：新版本 v2 先放 10% 流量。

# 主路由：90% 流量到 v1curl-XPUT.../routes/100\-d'{"uri":"/api/*","upstream_id":"v1","vars":[["weight","<=","90"]]}'# 灰度路由：10% 流量到 v2curl-XPUT.../routes/101\-d'{"uri":"/api/*","upstream_id":"v2","vars":[["weight",">","90"]]}'

关键：通过vars里的weight变量做分流，无需重启，秒级调整灰度比例。

7.2 基于请求头的灰度

"vars":[["http_user_tag","==","beta"]]

带User-Tag: beta的请求走新版本，用于内部员工/白名单灰度。

八、与 Kong 的对比决策

早上我们聊了 Kong，这里直接对比：

我们的结论：

• 追求极致动态 + 性能 + 国内支持→ APISIX
• 团队已用 Kong + 企业版预算→ 继续 Kong

两者都是好网关，选 APISIX 主要是看中 etcd 的毫秒级同步和免 reload。

九、APISIX 的常见坑

9.1 坑1：etcd 单点

症状：etcd 挂了，新配置无法下发。

解决：etcd 必须集群部署（3/5 节点），否则网关配置中心成单点。

9.2 坑2：Admin API 暴露公网

症状：被人通过 Admin API 改了路由，流量被劫持。

解决：

• Admin API只监听内网
• 启用admin_key强密钥
• 加网络策略/IP 白名单

9.3 坑3：插件顺序影响结果

症状：限流没生效，因为插件执行顺序问题。

解决：APISIX 插件有默认执行顺序，敏感插件（限流、鉴权）排前面，用priority字段控制。

9.4 坑4：Lua 脚本写错导致 500

症状：自定义插件语法错误，整条路由 500。

解决：自定义插件先在测试环境充分验证；优先用内置插件。

9.5 坑5：版本升级不兼容

症状：3.x 升级后部分配置字段变更。

解决：升级前读CHANGELOG，用 Dashboard 导出配置做备份。

十、我们的落地策略

渐进式迁移路径：

阶段1：APISIX 旁路部署，镜像流量验证 └── 不影响生产，对比 Nginx 行为 阶段2：非核心接口切到 APISIX └── 订单查询、商品详情等读接口 阶段3：核心接口全量切换 └── 下单、支付（配好健康检查 + 限流） 阶段4：下线旧 Nginx 网关 └── 统一流量入口

落地后的收益：

十一、总结

APISIX 是云原生时代网关的优选，动态能力 + 高性能 + 插件生态三位一体。

关键要点：

1. 配置中心用 etcd：毫秒级同步，免 reload
2. 动态生效是命门：大促调整、紧急封禁零中断
3. 插件化能力：限流/鉴权/观测即插即用
4. Admin API 要收好：内网 + 强密钥
5. etcd 要集群：避免配置中心单点
6. 渐进式迁移：旁路验证 → 非核心 → 核心 → 下线
7. 与 Kong 各有优势：看中动态选 APISIX

APISIX 的哲学：

网关的本质不是"转发流量"，而是"动态治理流量"。

核心原则：

• 动态优先：能热更新就不要 reload
• 配置外置：etcd 兜底，节点无状态
• 能力插件化：少写代码，多用生态
• 安全第一：Admin API 严控
• 可观测：没有监控的网关是黑盒

最后的话：

APISIX 让我彻底告别了"改个路由要 reload、reload 就抖一次"的噩梦。

如果你的系统还在用传统 Nginx 手写转发，又饱受 reload 抖动之苦——

APISIX 值得一试。

但记住：工具再好，架构思维更重要——网关只是入口，动态治理、可观测、安全才是目标。

今日思考：
你们用的是什么网关？Nginx、Kong、APISIX 还是自研？踩过哪些坑？欢迎分享！

作者：架构实战团队
日期：2026-07-25
标签：#APISIX #API网关 #云原生 #动态路由 #架构实战