APISIX 入门指南：核心概念、Docker 部署与基础路由配置
Apache APISIX 是一个云原生、高性能、可扩展的 API 网关，常用于统一入口、动态路由、负载均衡、认证鉴权、限流熔断、日志采集、可观测性和灰度发布等场景。
这篇文章作为 APISIX 系列的入门篇，重点说明 APISIX 的核心概念、etcd 依赖、Docker 快速部署方式、Admin API 基础操作，以及 Route、Service、Upstream、Plugin 之间的关系。后续可以继续阅读：
- APISIX Dashboard 使用指南：路由、服务、上游与插件配置实践
- APISIX Mocking 插件实践：接口 Mock、临时降级与兜底响应
- APISIX kafka-logger 日志采集实践：写入 Kafka 并接入 Elasticsearch / Kibana
- APISIX proxy-mirror 流量镜像实践：灰度验证、监控分析与注意事项
APISIX 适合解决什么问题
在微服务系统中，如果每个服务都直接暴露给调用方，会带来很多问题：
- 调用方需要感知大量服务地址。
- 认证、限流、日志、安全策略分散在各个服务中。
- 服务升级和灰度发布缺少统一控制入口。
- 流量治理、观测和故障兜底难以标准化。
APISIX 可以作为统一流量入口，将这些通用能力沉淀在网关层：
| 能力 | 说明 |
|---|---|
| 动态路由 | 无需重启即可新增、修改、删除路由 |
| 负载均衡 | 将请求转发到多个上游节点 |
| 插件机制 | 通过插件实现认证、限流、日志、熔断、镜像等能力 |
| 服务治理 | 支持服务发现、灰度发布、请求改写、流量复制 |
| 可观测性 | 支持 Prometheus、日志插件、Tracing 等集成 |
| 云原生 | 可与 Kubernetes、Ingress、Service Mesh 等体系结合 |
核心架构
APISIX 可以简单理解为三部分：
Client
│
▼
APISIX Gateway
│
├── Route / Service / Upstream / Plugin
│
├── Admin API
│
└── etcd
│
▼
Backend Service
核心组件说明：
- APISIX Gateway：实际处理客户端请求的网关节点。
- etcd：保存路由、服务、上游、插件等配置数据。
- Admin API：用于动态管理 APISIX 配置。
- Route：定义请求匹配规则，例如 URI、Host、Method。
- Upstream：定义后端服务节点和负载均衡策略。
- Service：抽象一组可复用的服务配置。
- Plugin：在请求或响应生命周期中执行扩展逻辑。
APISIX 的重要特点是配置动态生效，很多场景不需要重启网关。
Route、Service、Upstream 的关系
初学 APISIX 最容易混淆 Route、Service 和 Upstream，可以这样理解：
| 对象 | 作用 | 示例 |
|---|---|---|
| Route | 决定什么请求进来 | /api/users/* |
| Upstream | 决定请求转发到哪里 | 10.0.0.1:8080、10.0.0.2:8080 |
| Service | 复用公共配置 | 某个业务服务的插件、上游和治理策略 |
| Plugin | 对请求进行扩展处理 | 限流、认证、日志、Mock、镜像 |
一种常见关系是：
Route -> Service -> Upstream -> Backend Nodes
也可以在 Route 上直接绑定 Upstream 和 Plugin，适合简单验证；生产环境建议尽量使用 Service 抽象公共配置。
快速部署方式
APISIX 支持多种部署方式：
- Docker / Docker Compose
- Kubernetes / Helm
- RPM / DEB 包
- 源码构建
入门验证建议优先使用 Docker 或 Docker Compose。生产环境需要重点关注：
- etcd 高可用部署。
- Admin API 访问控制。
- 网关节点无状态扩缩容。
- 日志、监控、告警和配置备份。
如果你还没有安装 Docker，可以参考：Docker Engine 与 Docker Compose V2 安装配置指南。
etcd 依赖说明
APISIX 使用 etcd 存储动态配置。etcd 在生产环境中非常关键，建议：
- 使用 3 节点或 5 节点 etcd 集群。
- 开启鉴权或内网访问控制。
- 定期备份 etcd 数据。
- 监控 etcd 延迟、磁盘、Leader 变更和健康状态。
- 不要把 etcd 直接暴露到公网。
本地测试可以使用单节点 etcd，生产环境不建议单节点。
Docker 快速启动示例
以下示例用于学习和本地验证，生产部署请结合官方文档和实际网络规划调整。
创建 Docker 网络：
docker network create apisix-net
启动 etcd：
docker run -d \
--name apisix-etcd \
--network apisix-net \
-e ALLOW_NONE_AUTHENTICATION=yes \
-e ETCD_ADVERTISE_CLIENT_URLS=http://apisix-etcd:2379 \
bitnami/etcd:3.5
启动 APISIX：
docker run -d \
--name apisix \
--network apisix-net \
-p 9080:9080 \
-p 9180:9180 \
apache/apisix:latest
说明：实际镜像版本建议固定为明确版本号，不建议生产环境直接使用
latest。
常见端口：
| 端口 | 作用 |
|---|---|
| 9080 | HTTP 网关入口 |
| 9443 | HTTPS 网关入口 |
| 9180 | Admin API |
| 9091 / 9092 | 控制 API / Prometheus 等内部能力，具体以配置为准 |
使用 Admin API 创建基础路由
下面通过 Admin API 创建一个最小路由。实际环境中 Admin API Key 请妥善保管，不要暴露在公网。
创建路由：
curl -i "http://127.0.0.1:9180/apisix/admin/routes/1" \
-H "X-API-KEY: your-admin-key" \
-X PUT \
-d '{
"uri": "/get",
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
访问验证：
curl -i "http://127.0.0.1:9080/get"
如果返回来自上游服务的响应，说明 APISIX 路由已经生效。
使用 Upstream 管理后端节点
当多个 Route 复用相同后端节点时，可以单独创建 Upstream：
curl -i "http://127.0.0.1:9180/apisix/admin/upstreams/1" \
-H "X-API-KEY: your-admin-key" \
-X PUT \
-d '{
"type": "roundrobin",
"nodes": {
"10.0.0.11:8080": 1,
"10.0.0.12:8080": 1
}
}'
Route 引用 Upstream：
curl -i "http://127.0.0.1:9180/apisix/admin/routes/2" \
-H "X-API-KEY: your-admin-key" \
-X PUT \
-d '{
"uri": "/api/*",
"upstream_id": "1"
}'
这样后续只需要维护 Upstream，就可以影响所有引用它的路由。
插件机制入门
APISIX 的插件可以绑定在不同层级：
- Global Rule：全局生效。
- Route：对某个路由生效。
- Service：对某个服务生效。
- Consumer：对某个消费者生效。
例如给路由增加限流插件：
{
"uri": "/api/*",
"plugins": {
"limit-count": {
"count": 100,
"time_window": 60,
"rejected_code": 429
}
},
"upstream_id": "1"
}
插件是 APISIX 的核心扩展点。Mock、日志写入 Kafka、流量镜像等能力本质上都是通过插件实现。
生产环境注意事项
Admin API 安全
Admin API 能修改网关配置，必须重点保护：
- 不要暴露到公网。
- 使用内网、防火墙、ACL 控制访问来源。
- 修改默认 Admin Key。
- 配置变更纳入审计和发布流程。
etcd 高可用
APISIX 配置依赖 etcd，生产环境建议：
- etcd 使用奇数节点集群。
- 配置独立磁盘和监控。
- 定期快照备份。
- 避免业务流量与 etcd 流量互相影响。
配置管理
不要只依赖手工 Dashboard 操作。更推荐：
- 使用 Admin API 自动化管理。
- 使用 APISIX Ingress Controller 管理 Kubernetes 入口。
- 使用 APISIX Declarative CLI / 配置文件方式做版本化管理。
- 对重要变更做灰度和回滚预案。
常见问题
1. 路由创建成功但访问 404
检查：
- 访问端口是否为网关入口端口，例如 9080。
- Route 的
uri是否匹配。 - Host、Method 等条件是否限制了请求。
- 配置是否写入正确 APISIX 实例连接的 etcd。
2. Admin API 返回 401
检查：
X-API-KEY是否正确。- Admin API Key 是否已修改。
- 请求是否经过代理导致请求头丢失。
3. 上游服务 502 / 504
检查：
- APISIX 容器是否能访问上游地址。
- 上游服务端口是否正确。
- DNS 解析是否正常。
- 上游服务响应是否超时。
总结
APISIX 入门时建议按这条主线理解：
- etcd 保存动态配置。
- Admin API / Dashboard / Ingress Controller 负责管理配置。
- Route 匹配请求。
- Upstream 定义后端节点。
- Service 复用公共治理配置。
- Plugin 实现认证、限流、日志、Mock、镜像等扩展能力。
掌握这些概念后，再去配置 Dashboard、Mocking、kafka-logger、proxy-mirror 等插件会更容易。