# APISIX API 网关完整搭建指南：从零到生产就绪
## 前言
Apache APISIX 是一个动态、实时、高性能的 API 网关，提供丰富的流量管理功能。本文将详细介绍如何使用 Docker Compose 搭建一个完整的 APISIX 网关环境，包含 Web 管理界面和示例服务。
## 架构概览
我们的 APISIX 网关架构包含以下组件：
- **APISIX Gateway**: 核心 API 网关服务
- **APISIX Dashboard**: Web 管理界面
- **etcd**: 配置中心和数据存储
- **示例上游服务**: 用于测试的 Nginx 服务
## 环境准备
### 系统要求
- Docker 20.10+
- Docker Compose 2.0+
- 可用端口：9080, 9081, 9082, 9100, 9180, 9443, 9091, 9092, 2379, 2380
### 目录结构
```
gateway/
├── docker-compose.yml # Docker Compose 主配置文件
├── apisix_conf/
│ └── config.yaml # APISIX 主配置文件
├── dashboard_conf/
│ └── conf.yaml # Dashboard 配置文件
├── etcd_conf/
│ └── etcd.conf.yml # etcd 配置文件
├── upstream/
│ ├── web1.conf # 示例上游服务1配置
│ └── web2.conf # 示例上游服务2配置
└── README.md # 部署说明文档
```
## 详细配置解析
### 1. Docker Compose 配置
```yaml
version: "3"
services:
# APISIX API Gateway
apisix:
image: apache/apisix:${APISIX_IMAGE_TAG:-3.14.1-debian}
restart: always
volumes:
- ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro
depends_on:
- etcd
ports:
- "9180:9180/tcp" # Admin API port
- "9080:9080/tcp" # HTTP Gateway port
- "9091:9091/tcp" # Prometheus metrics port
- "9443:9443/tcp" # HTTPS Gateway port
- "9092:9092/tcp" # Admin API HTTPS port
networks:
apisix:
environment:
- APISIX_STAND_ALONE=false
# APISIX Dashboard
dashboard:
image: apache/apisix-dashboard:${APISIX_DASHBOARD_VERSION:-3.0.1-alpine}
restart: always
volumes:
- ./dashboard_conf/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml:ro
depends_on:
- etcd
ports:
- "9100:9000/tcp" # Dashboard port
networks:
apisix:
# etcd configuration center
etcd:
image: bitnami/etcd:3.5.11
restart: always
volumes:
- etcd_data:/bitnami/etcd
- ./etcd_conf/etcd.conf.yml:/opt/bitnami/etcd/conf/etcd.conf.yml:ro
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"
ETCD_DATA_DIR: "/bitnami/etcd"
ports:
- "2379:2379/tcp"
- "2380:2380/tcp"
networks:
apisix:
# Example upstream service 1
web1:
image: nginx:1.19.0-alpine
restart: always
volumes:
- ./upstream/web1.conf:/etc/nginx/nginx.conf:ro
ports:
- "9081:80/tcp"
environment:
- NGINX_PORT=80
networks:
apisix:
# Example upstream service 2
web2:
image: nginx:1.19.0-alpine
restart: always
volumes:
- ./upstream/web2.conf:/etc/nginx/nginx.conf:ro
ports:
- "9082:80/tcp"
environment:
- NGINX_PORT=80
networks:
apisix:
networks:
apisix:
driver: bridge
volumes:
etcd_data:
driver: local
```
**关键配置说明：**
- **APISIX**: 使用官方镜像，配置为传统模式（非独立模式）
- **Dashboard**: 提供 Web 管理界面，端口映射为 9100
- **etcd**: 作为配置中心，启用 v2 API 支持
- **示例服务**: 两个 Nginx 服务用于测试路由功能
### 2. APISIX 核心配置
```yaml
apisix:
node_listen: 9080 # APISIX 监听端口
enable_ipv6: false
enable_admin: true
enable_admin_cors: true
enable_debug: false
enable_dev_mode: false
enable_reuseport: true
config_center: etcd
nginx_config:
error_log: "/dev/stderr"
error_log_level: "warn"
deployment:
role: traditional
role_traditional:
config_provider: etcd
admin:
admin_key:
- name: "admin"
key: edd1c9f034335f136f87ad84b625c8f1
role: admin
allow_admin:
- 0.0.0.0/0
etcd:
host:
- "http://etcd:2379"
prefix: "/apisix"
timeout: 30
plugin_attr:
prometheus:
export_addr:
ip: "0.0.0.0"
port: 9091
```
**配置要点：**
- **传统模式**: 使用 etcd 作为配置提供者
- **管理 API**: 启用管理接口，默认 API Key 为 `edd1c9f034335f136f87ad84b625c8f1`
- **etcd 连接**: 连接到 etcd 服务的 2379 端口
- **Prometheus**: 启用指标导出功能
### 3. Dashboard 配置
```yaml
conf:
listen:
host: 0.0.0.0
port: 9100 # Dashboard 监听端口
etcd:
endpoints:
- http://etcd:2379
log:
error_log:
level: warn
file_path: logs/error.log
authentication:
secret: secret
expire_time: 3600 # JWT token 过期时间（秒）
users:
- username: admin # 默认管理员用户
password: admin
- username: user
password: user
plugin_attr:
prometheus:
export_addr:
ip: "0.0.0.0"
port: 9091
```
**安全配置：**
- **默认用户**: admin/admin 和 user/user
- **JWT 过期时间**: 3600 秒（1小时）
- **etcd 连接**: 连接到 etcd 服务
### 4. 示例上游服务配置
**web1.conf:**
```nginx
events {
worker_connections 1024;
}
http {
server {
listen 80;
server_name localhost;
location / {
return 200 'Hello from Web Service 1!\n';
add_header Content-Type text/plain;
}
location /health {
return 200 'OK';
add_header Content-Type text/plain;
}
}
}
```
**web2.conf:**
```nginx
events {
worker_connections 1024;
}
http {
server {
listen 80;
server_name localhost;
location / {
return 200 'Hello from Web Service 2!\n';
add_header Content-Type text/plain;
}
location /health {
return 200 'OK';
add_header Content-Type text/plain;
}
}
}
```
## 部署步骤
### 1. 创建项目目录
```bash
mkdir gateway
cd gateway
```
### 2. 创建配置文件
按照上述配置创建各个配置文件，确保目录结构正确。
### 3. 启动服务
```bash
# 启动所有服务
docker-compose up -d
# 查看服务状态
docker-compose ps
```
### 4. 验证部署
```bash
# 检查 APISIX Admin API
curl "http://127.0.0.1:9180/apisix/admin/services/" \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
# 检查示例服务
curl http://127.0.0.1:9081/
curl http://127.0.0.1:9082/
```
### 5. 访问 Dashboard
打开浏览器访问：`http://localhost:9100`
使用默认账号登录：
- 用户名：`admin`
- 密码：`admin`
## 服务端口说明
| 服务 | 端口 | 说明 |
|------|------|------|
| APISIX Gateway HTTP | 9080 | API 网关 HTTP 端口 |
| APISIX Gateway HTTPS | 9443 | API 网关 HTTPS 端口 |
| APISIX Admin API | 9180 | 管理 API 端口 |
| APISIX Admin HTTPS | 9092 | 管理 API HTTPS 端口 |
| APISIX Metrics | 9091 | Prometheus 指标端口 |
| Dashboard | 9100 | Web 管理界面端口 |
| etcd | 2379 | etcd 客户端端口 |
| etcd | 2380 | etcd 节点通信端口 |
| web1 | 9081 | 示例服务1端口 |
| web2 | 9082 | 示例服务2端口 |
## 使用示例
### 1. 通过 Dashboard 创建路由
1. 登录 Dashboard (`http://localhost:9100`)
2. 进入 "路由" 页面
3. 点击 "创建" 按钮
4. 配置路由规则：
- **路径**: `/web1/*`
- **上游**: `web1:80`
- **负载均衡**: `roundrobin`
### 2. 通过 Admin API 创建路由
```bash
curl -X POST "http://127.0.0.1:9180/apisix/admin/routes/1" \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
-H 'Content-Type: application/json' \
-d '{
"uri": "/web1/*",
"upstream": {
"type": "roundrobin",
"nodes": {
"web1:80": 1
}
}
}'
```
### 3. 测试路由
```bash
# 测试 web1 路由
curl http://127.0.0.1:9080/web1/
# 测试 web2 路由
curl http://127.0.0.1:9080/web2/
```
# APISIX Gateway 部署指南
这是一个完整的 APISIX API 网关部署配置，包含 Dashboard 管理界面，但不包含监控组件（Grafana、Prometheus）。
## 目录结构
```
gateway/
├── docker-compose.yml # Docker Compose 主配置文件
├── apisix_conf/
│ └── config.yaml # APISIX 主配置文件
├── dashboard_conf/
│ └── conf.yaml # Dashboard 配置文件
├── etcd_conf/
│ └── etcd.conf.yml # etcd 配置文件
├── upstream/
│ ├── web1.conf # 示例上游服务1配置
│ └── web2.conf # 示例上游服务2配置
└── README.md # 本说明文档
```
## 服务组件
- **APISIX**: API 网关核心服务
- **Dashboard**: Web 管理界面
- **etcd**: 配置中心
- **web1/web2**: 示例上游服务
## 端口映射
| 服务 | 端口 | 说明 |
|------|------|------|
| APISIX Admin API | 9180 | 管理 API 端口 |
| APISIX Gateway HTTP | 9080 | HTTP 网关端口 |
| APISIX Gateway HTTPS | 9443 | HTTPS 网关端口 |
| APISIX Metrics | 9091 | Prometheus 指标端口 |
| APISIX Admin HTTPS | 9092 | 管理 API HTTPS 端口 |
| Dashboard | 9000 | Web 管理界面端口 |
| etcd | 2379 | etcd 客户端端口 |
| etcd | 2380 | etcd 节点通信端口 |
| web1 | 9081 | 示例服务1端口 |
| web2 | 9082 | 示例服务2端口 |
## 快速部署
### 1. 启动服务
```bash
cd gateway
docker-compose up -d
```
### 2. 验证服务状态
```bash
# 检查所有服务状态
docker-compose ps
# 检查 APISIX 是否正常运行
curl "http://127.0.0.1:9180/apisix/admin/services/" \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
### 3. 访问 Dashboard
打开浏览器访问：`http://localhost:9000`
**默认登录信息：**
- 用户名：`admin`
- 密码：`admin`
## 配置说明
### APISIX 配置
主要配置项：
- `node_listen: 9080`: API 网关监听端口
- `admin_key`: 管理 API 密钥
- `etcd`: etcd 连接配置
### Dashboard 配置
主要配置项：
- `listen.port: 9000`: Dashboard 监听端口
- `etcd.endpoints`: etcd 连接地址
- `authentication.users`: 登录用户配置
## 使用示例
### 1. 创建路由
通过 Dashboard 或 Admin API 创建路由：
```bash
curl -X POST "http://127.0.0.1:9180/apisix/admin/routes/1" \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
-H 'Content-Type: application/json' \
-d '{
"uri": "/web1/*",
"upstream": {
"type": "roundrobin",
"nodes": {
"web1:80": 1
}
}
}'
```
### 2. 测试路由
```bash
# 测试 web1 路由
curl http://127.0.0.1:9080/web1/
# 测试 web2 路由
curl http://127.0.0.1:9080/web2/
```
### 3. 查看指标
```bash
# 查看 Prometheus 指标
curl http://127.0.0.1:9091/apisix/prometheus/metrics
```
## 常用命令
### 服务管理
```bash
# 启动服务
docker-compose up -d
# 停止服务
docker-compose down
# 重启服务
docker-compose restart
# 查看日志
docker-compose logs -f apisix
docker-compose logs -f dashboard
```
### 配置重载
```bash
# 重载 APISIX 配置
docker-compose exec apisix apisix reload
```
## 安全建议
1. **修改默认密码**: 更改 Dashboard 的默认用户名和密码
2. **修改 API Key**: 更改 APISIX Admin API 的默认密钥
3. **网络隔离**: 在生产环境中使用防火墙限制端口访问
4. **HTTPS**: 启用 HTTPS 进行安全通信
## 故障排除
### 常见问题
1. **端口冲突**: 确保所需端口未被占用
2. **etcd 连接失败**: 检查 etcd 服务是否正常启动
3. **Dashboard 无法访问**: 检查防火墙设置和端口映射
### 日志查看
```bash
# 查看所有服务日志
docker-compose logs
# 查看特定服务日志
docker-compose logs apisix
docker-compose logs dashboard
docker-compose logs etcd
```
## 扩展功能
如需添加监控功能，可以参考项目根目录下的 `example/docker-compose.yml` 文件，添加 Prometheus 和 Grafana 服务。
## 许可证
Licensed under the Apache License, Version 2.0: [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
## 相关资源
- [Apache APISIX 官方文档](https://apisix.apache.org/docs/)
- [APISIX Dashboard 文档](https://apisix.apache.org/docs/dashboard/)
- [etcd 官方文档](https://etcd.io/docs/)
- [Docker Compose 文档](https://docs.docker.com/compose/)
---
*本文基于 Apache APISIX 3.14.1 版本编写，配置和功能可能会随版本更新而变化。*