APISIX 网关 Docker 部署与使用

整理自实践过程（参考 macrozheng 教程与官方文档）。APISIX 是基于 Nginx + etcd 的云原生微服务 API 网关，支持动态路由与插件热加载。

核心概念

• 上游（Upstream）：可理解为虚拟主机，对多个目标服务做负载均衡。
• 路由（Route）：定义规则匹配客户端请求，执行插件后转发到指定上游。
• 消费者（Consumer）：API 的调用方，常用于身份认证。
• 服务（Service）：一组路由的抽象，通常与上游一一对应，路由与服务多对一。
• 插件（Plugin）：对请求的增强（限流、认证、黑名单等），可配置在消费者、服务、路由上。

Docker Compose 部署

官方提供 docker-compose 方案，下载 apisix-docker 的 example 目录即可。

cd /opt
git clone https://github.com/apache/apisix-docker.git
# 赋权限（否则 etcd 启动报 permission denied）
chmod -R 777 /opt/apisix-docker/example/
cd /opt/apisix-docker/example

# 确保端口未被占用（默认 9080/9091/9443/2379/9000）
netstat -antp | grep 9443

# 启动
docker-compose -p docker-apisix up -d

example 的 docker-compose 会启动 apisix、apisix-dashboard、etcd 三个核心服务，外加两个测试用 Nginx（web1/web2）。

验证与访问

# 查看 5 个容器是否都已启动
docker ps -a | grep apisix
docker ps -a | grep etcd
docker ps -a | grep dashboard

访问可视化管理 dashboard：http://<服务器IP>:9000，默认账号密码 admin/admin。

基本使用（路由转发）

1. 创建上游（Upstream）：设置名称、负载均衡算法、目标节点；
2. 创建路由（Route）：匹配客户端请求路径，选择上游；
3. 通过网关访问：http://<服务器IP>:9080/web1/。

进阶功能（插件）

• 身份认证（jwt-auth）：创建 Consumer → 启用 jwt-auth 插件并配置 key/secret → 创建匹配 /auth/* 的路由启用插件。获取 Token：http://<服务器IP>:9080/apisix/plugin/jwt/sign，请求头加 Authorization 携带 JWT 后访问。
• 限流（limit-count）：在路由上配置 limit-count，按 remote_addr 限流（如 30 秒内最多 2 次，超出返回 503）。
• 跨域（cors）：路由上启用 cors 插件并配置跨域策略。

常见问题

• 端口被占用：确保 9080/9091/9443/2379/9000 未被占用，必要时改 docker-compose.yml（不建议，易导致端口对应不上）。
• etcd permission denied（cannot access data directory）：对 example 目录 chmod -R 777。
• 容器持续重启/失败：docker logs -f <containerId> 查日志诊断。

docker-compose 常用操作

docker-compose pull
docker-compose -p docker-apisix up -d      # 创建并启动
docker-compose -p docker-apisix down       # 停止并删除
docker-compose -p docker-apisix start/stop # 启停服务