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

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	Kong	Nginx	Spring Cloud Gateway
配置存储	etcd	PostgreSQL	文件	内存/配置中心
动态生效	✅ 毫秒级	✅（依赖DB轮询）	❌ 需 reload	⚠️ 部分
性能	极高（LuaJIT）	高	极高	中（JVM）
插件生态	丰富（80+）	丰富	需自写 Lua	中等
云原生	✅ 原生	✅	⚠️	⚠️
学习曲线	中	中	低	低

---

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

3.1 热更新不重启

这是 APISIX 最打动我的能力。

# 传统 Nginx：改配置 → reload（断连接）
vi nginx.conf
nginx -s reload   # 连接抖动、长连接断开

# APISIX：改配置 → Admin API（无损）
curl -X PUT 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.yml
version: "3"
services:
  apisix:
    image: apache/apisix:3.9-centos
    ports:
      - "9080:9080"   # 代理端口
      - "9180:9180"   # Admin API 端口
    volumes:
      - ./config.yaml:/usr/local/apisix/conf/config.yaml:ro
    depends_on:
      - etcd

  etcd:
    image: bitnami/etcd:3.5
    environment:
      ETCD_ENABLE_V2: "true"
      ALLOW_NONE_AUTHENTICATION: "yes"
      ETCD_ADVERTISE_CLIENT_URLS: http://etcd:2379
      ETCD_LISTEN_CLIENT_URLS: http://0.0.0.0:2379

5.2 创建上游（Upstream）

curl -X PUT 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 -X PUT 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. 创建 Consumer
curl -X PUT 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 或 Header Authorization: android-secret。

6.3 可观测性：prometheus

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

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

---

七、动态路由与灰度发布

7.1 用 APISIX 做金丝雀发布

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

# 主路由：90% 流量到 v1
curl -X PUT .../routes/100 \
  -d '{"uri":"/api/*","upstream_id":"v1","vars":[["weight","<=","90"]]}'

# 灰度路由：10% 流量到 v2
curl -X PUT .../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
配置存储	etcd（Watch 推送，毫秒级）	PostgreSQL（轮询，秒级）
动态生效	原生无损	依赖 DB 同步，略慢
性能	更高（LuaJIT 优化）	高
插件开发	Lua（上手略难）	Lua / 也支持
Dashboard	APISIX Dashboard（社区）	Kong Manager（企业版收费）
国内生态	中文文档丰富、社区活跃	英文为主
适用	云原生、高性能、强动态	企业级、插件多

我们的结论：

• 追求极致动态 + 性能 + 国内支持 → 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 网关
  └── 统一流量入口

落地后的收益：

指标	改造前（Nginx）	改造后（APISIX）
路由变更	reload（断连接）	毫秒热更新
灰度调整	改配置+reload	Admin API 秒级
限流/鉴权	自写 Lua	插件开箱即用
监控	缺	Prometheus 原生
大促稳定性	抖动	平稳

---

十一、总结

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网关 #云原生 #动态路由 #架构实战