在微服务与云原生架构里，APISIX 作为 Apache 顶级项目的云原生 API 网关，正成为统一流量治理的事实标准。它基于 etcd 做配置同步、以 Nginx 为数据面，能在不重启进程的前提下动态下发路由、限流、鉴权等规则，本文带你从零把 APISIX 落到生产可用。
一、为什么需要 API 网关
当后端服务从单体拆分出几十个微服务后，客户端直连会暴露大量内部地址、难以统一鉴权与限流。API 网关把”路由、认证、限流、可观测”收口到一层，让业务服务只关心业务逻辑。相比传统 Nginx 需要 reload 才能变更配置，APISIX 借助 etcd 实现了秒级动态生效。
举个常见的坑：客户端 App 直接调用 20 个微服务，每个服务都要各自实现登录校验、接口鉴权、跨域处理与限流，任何一处疏漏都会变成安全或稳定性隐患。更糟的是，当某个服务要升级、拆分或下线时，所有调用方都得同步改地址。API 网关把这些横切关注点收口到边缘一层，后端只暴露内网地址，外部统一走网关，运维与安全的复杂度立刻下降一个量级。
二、核心架构：etcd + Nginx + 插件
APISIX 分为控制面与数据面：控制面通过 Admin API 接收配置并写入 etcd；数据面（基于 Nginx + Lua/OpenResty）监听 etcd 变更，热加载到内存。所有能力都以插件形式存在——限流、JWT、CORS、灰度、可观测等，可对任意路由按需启用。这种”配置与转发分离”的设计，让它在高并发下依然保持亚毫秒级延迟。
数据面本质是 OpenResty（Nginx + LuaJIT），插件逻辑运行在事件驱动模型上，不会阻塞 worker，这正是它高性能的关键。配置变更经 etcd watch 推送到每个节点，无需中心转发，水平扩展几乎没有上限；即便 etcd 短暂不可用，已加载的路由仍照常转发，只是暂时无法下发新配置。
三、APISIX 与 Kong、Envoy 怎么选
市面上的 API 网关不止 APISIX。Kong 同样基于 OpenResty，生态成熟但强功能多在企业版；Envoy 更偏向 Sidecar 与 Service Mesh 数据面，学习曲线陡；Spring Cloud Gateway 则绑定 Java 技术栈。APISIX 的优势在于纯动态配置、插件热加载与活跃的中文社区。
| 网关 | 配置方式 | 动态性 | 适用场景 |
| APISIX | etcd 动态 | 秒级热加载 | 云原生 / 多协议 |
| Kong | 数据库 / 声明式 | 部分动态 | 企业插件生态 |
| Envoy | xDS 动态 | 强 | Service Mesh |
| SC Gateway | 代码 / 配置 | 重启生效 | Java 单体栈 |
四、Docker Compose 一键拉起
本地验证最简单的方式是用 Docker Compose 同时拉起 APISIX 与 etcd。下面这份配置可直接照搬思路：
version: "3"
services:
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
ports:
- "2379:2379"
apisix:
image: apache/apisix:3.9-debian
depends_on:
- etcd
ports:
- "9080:9080" # 数据面入口
- "9180:9180" # Admin API
volumes:
- ./config.yaml:/usr/local/apisix/conf/config.yaml:ro五、配置第一条路由与上游
启动后，用 Admin API 创建一个上游（后端服务）并绑定路由。下面把 /api/hello 转发到本地 8080 服务：
# 创建上游
curl http://127.0.0.1:9180/apisix/admin/upstreams/1 \
-H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
"type": "roundrobin",
"nodes": { "127.0.0.1:8080": 1 }
}'
# 创建路由
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
"uri": "/api/hello",
"upstream_id": 1
}'访问 http://127.0.0.1:9080/api/hello 即可看到后端响应，全程无需重启。这与我们之前讲过的 Nomad 统一编排 思路一致——基础设施即声明。
六、插件实战：限流、JWT 与跨域
APISIX 目前内置 80+ 官方插件，覆盖认证、安全、流量与可观测。下面给路由加上”每分钟 100 次限流”与 JWT 鉴权：
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PATCH -d '
{
"plugins": {
"limit-req": {
"rate": 100, "burst": 50, "key": "remote_addr",
"rejected_code": 429
},
"jwt-auth": { "key": "user-key", "secret": "my-secret" },
"cors": {}
}
}'6.1 插件市场与自定义插件
除了内置插件，你还可用 Lua 编写自定义插件，针对业务做定制逻辑，例如按租户维度限流、注入请求头、做报文转换。插件以优先级链执行、顺序可调，这让复杂的边缘逻辑变得可组合。常见内置插件包括 key-auth、jwt-auth、openid、waf、limit-count、proxy-mirror、skywalking 等。
6.2 灰度发布与金丝雀
通过 traffic-split 插件可以把 10% 流量导向新版本上游，实现无损灰度：
{
"plugins": {
"traffic-split": {
"rules": [{
"weighted_upstreams": [
{ "upstream_id": 1, "weight": 90 },
{ "upstream_id": 2, "weight": 10 }
]
}]
}
}
}七、可观测性：对接 Prometheus 与 OTel
网关是流量的咽喉，可观测必不可少。启用 prometheus 插件后，APISIX 在 /apisix/prometheus/metrics 暴露指标，可直接接入你已有的 Prometheus + Grafana 监控；再叠加 opentelemetry 插件，即可把链路追踪接到 OpenTelemetry 可观测体系，一眼看清每个请求的跨服务路径。
此外 APISIX 还支持 skywalking、zipkin 等追踪后端，并可通过 error-log 插件把错误日志推送到外部日志系统。对于多集群场景，可以结合服务发现插件（nacos、consul、dns）自动维护上游节点，避免手动维护节点列表。
八、生产部署要点
| 维度 | 建议 |
| 高可用 | APISIX 无状态，多节点 + etcd 集群（至少 3 节点） |
| Admin 安全 | Admin API 只对内网开放，轮换 X-API-KEY，禁公网 9180 |
| TLS | 前置 Nginx 反向代理 做 SSL 终止与统一入口 |
| 配置管理 | 路由用声明式文件经 GitHub Actions 审核后下发 |
在 Kubernetes 中，APISIX 既可独立 Deployment 部署，也可使用官方 Ingress Controller，把 Ingress 资源直接翻译成网关路由，享受声明式运维。无论哪种形态，务必保证 etcd 的高可用，因为它是整个配置一致性的基石。
九、新手常见误区
| 误区 | 正确做法 |
| 把 Admin API 暴露公网 | 仅内网 + 网络策略 + Key 轮换 |
| etcd 单节点 | 生产用 3/5 节点集群，避免配置丢失 |
| 插件堆砌拖慢转发 | 按需启用，用 prometheus 指标评估开销 |
很多团队初期把 APISIX 当成”高级 Nginx”直接用，却忽略了它的配置中心角色。一旦 etcd 数据损坏或单点故障，新配置无法下发，虽然已加载的路由仍能转发，但失去动态能力。因此 etcd 的备份与监控和网关本身同等重要。
十、小结
APISIX 用”etcd 配置中心 + Nginx 数据面 + 插件化能力”的组合，把流量治理变得动态且可声明。落地建议：先用 Docker Compose 在测试环境跑通路由与插件，再用声明式配置接入 CI，最后在生产以多节点 + etcd 集群形态上线。循序渐进，你就能把 APISIX 真正变成团队的流量中枢，统一收口所有微服务的南北向流量。
如果你的团队已经在用 Kubernetes，直接上 APISIX Ingress Controller 会省力很多；若仍以虚拟机为主，独立部署 + 声明式配置同样能享受动态能力。无论如何，把 etcd 当”一等公民”来运维，是 APISIX 稳定运行的底线。
