309 lines
12 KiB
Markdown
309 lines
12 KiB
Markdown
# API Gateway - Kong
|
||
|
||
RWADurian 项目的 API 网关，基于 Kong 实现。
|
||
|
||
## 分布式部署架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||
│ 服务器 192.168.1.100 (网关服务器) │
|
||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||
│ │ Nginx │ │ Nginx │ │ Nginx │ │
|
||
│ │ rwaadmin:443 │ │ rwaapi:443 │ │ update:443 │ │
|
||
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
|
||
│ │ │ │ │
|
||
│ ▼ ▼ ▼ │
|
||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||
│ │ Admin Web │ │ Kong Gateway │ │ Mobile Upgrade │ │
|
||
│ │ (Next.js) │ │ │ │ (Next.js) │ │
|
||
│ │ :3000 │ │ :8000 │ │ :3020 │ │
|
||
│ └─────────────────┘ └────────┬────────┘ └─────────────────┘ │
|
||
└─────────────────────────────────┼───────────────────────────────────────────────┘
|
||
│
|
||
通过外部 IP (192.168.1.111) 访问
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||
│ 服务器 192.168.1.111 (后端服务器) │
|
||
│ │
|
||
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
|
||
│ │identity-service│ │wallet-service │ │backup-service │ │planting-service│ │
|
||
│ │ :3000 │ │ :3001 │ │ :3002 │ │ :3003 │ │
|
||
│ └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ │
|
||
│ │
|
||
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
|
||
│ │referral-service│ │reward-service │ │ mpc-service │ │leaderboard │ │
|
||
│ │ :3004 │ │ :3005 │ │ :3006 │ │ :3007 │ │
|
||
│ └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ │
|
||
│ │
|
||
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
|
||
│ │reporting-svc │ │authorization │ │ admin-service │ ┌───────────────┐ │
|
||
│ │ :3008 │ │ :3009 │ │ :3010 │ │presence-service│ │
|
||
│ └───────────────┘ └───────────────┘ └───────────────┘ │ :3011 │ │
|
||
│ └───────────────┘ │
|
||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ Infrastructure │ │
|
||
│ │ PostgreSQL / Redis / Kafka / Zookeeper │ │
|
||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 特点
|
||
|
||
- **与后端服务解耦**: Kong 独立部署，不依赖后端服务的 Docker 网络
|
||
- **分布式支持**: Kong 通过外部 IP 地址访问后端服务，支持跨服务器部署
|
||
- **可选部署**: 不部署 Kong 也不影响后端服务运行
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
api-gateway/
|
||
├── docker-compose.yml # Kong Docker Compose 配置
|
||
├── deploy.sh # 一键部署脚本
|
||
├── kong.yml # Kong 声明式路由配置
|
||
├── README.md # 本文档
|
||
└── nginx/
|
||
├── rwaapi.szaiai.com.conf # Nginx 配置 (SSL)
|
||
└── install.sh # Nginx 安装脚本
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 先启动后端微服务
|
||
|
||
```bash
|
||
cd backend/services
|
||
./deploy.sh up
|
||
```
|
||
|
||
### 2. 启动 Kong API Gateway
|
||
|
||
```bash
|
||
cd backend/api-gateway
|
||
chmod +x deploy.sh
|
||
./deploy.sh up
|
||
```
|
||
|
||
### 3. 配置 Nginx + SSL (生产环境)
|
||
|
||
```bash
|
||
cd nginx
|
||
sudo chmod +x install.sh
|
||
sudo ./install.sh
|
||
```
|
||
|
||
## 部署脚本命令
|
||
|
||
```bash
|
||
./deploy.sh up # 启动 Kong 网关
|
||
./deploy.sh down # 停止 Kong 网关
|
||
./deploy.sh restart # 重启 Kong 网关
|
||
./deploy.sh logs # 查看日志
|
||
./deploy.sh status # 查看状态
|
||
./deploy.sh health # 健康检查
|
||
./deploy.sh reload # 重载 Kong 配置
|
||
./deploy.sh routes # 查看所有路由
|
||
./deploy.sh services # 查看所有服务
|
||
./deploy.sh test # 测试 API 路由
|
||
./deploy.sh clean # 清理容器和数据
|
||
```
|
||
|
||
## API 路由表
|
||
|
||
| 路径 | 目标服务 | 端口 | 说明 |
|
||
|------|----------|------|------|
|
||
| `/api/v1/auth/*` | identity-service | 3000 | 认证登录 |
|
||
| `/api/v1/users/*` | identity-service | 3000 | 用户管理 |
|
||
| `/api/v1/wallets/*` | wallet-service | 3001 | 钱包管理 |
|
||
| `/api/v1/backups/*` | backup-service | 3002 | 备份服务 |
|
||
| `/api/v1/plantings/*` | planting-service | 3003 | 种植管理 |
|
||
| `/api/v1/trees/*` | planting-service | 3003 | 树木管理 |
|
||
| `/api/v1/referrals/*` | referral-service | 3004 | 推荐系统 |
|
||
| `/api/v1/rewards/*` | reward-service | 3005 | 奖励系统 |
|
||
| `/api/v1/mpc/*` | mpc-service | 3006 | 多方计算 |
|
||
| `/api/v1/leaderboard/*` | leaderboard-service | 3007 | 排行榜 |
|
||
| `/api/v1/reports/*` | reporting-service | 3008 | 报表 |
|
||
| `/api/v1/statistics/*` | reporting-service | 3008 | 统计 |
|
||
| `/api/v1/authorization/*` | authorization-service | 3009 | 授权 |
|
||
| `/api/v1/permissions/*` | authorization-service | 3009 | 权限 |
|
||
| `/api/v1/roles/*` | authorization-service | 3009 | 角色 |
|
||
| `/api/v1/versions/*` | admin-service | 3010 | 版本管理 |
|
||
| `/api/v1/admin/*` | admin-service | 3010 | 后台管理 |
|
||
| `/api/v1/presence/*` | presence-service | 3011 | 在线状态 |
|
||
|
||
## Kong 端口说明
|
||
|
||
| 端口 | 说明 |
|
||
|------|------|
|
||
| 8000 | Proxy HTTP - API 请求入口 |
|
||
| 8443 | Proxy HTTPS - API 请求入口 (SSL) |
|
||
| 8001 | Admin API - 管理接口 |
|
||
| 8002 | Admin GUI - 管理界面 |
|
||
|
||
## 全局插件
|
||
|
||
| 插件 | 说明 |
|
||
|------|------|
|
||
| cors | 跨域支持，允许前端访问 |
|
||
| rate-limiting | 请求限流 (100/分钟, 5000/小时) |
|
||
| file-log | 请求日志记录 |
|
||
| request-size-limiting | 请求大小限制 (50MB) |
|
||
|
||
## 生产环境部署
|
||
|
||
### 分布式部署流程
|
||
|
||
**服务器规划:**
|
||
- 192.168.1.100: 网关服务器 (Nginx + Kong + 前端)
|
||
- 192.168.1.111: 后端服务器 (微服务 + 基础设施)
|
||
|
||
**步骤 1: 在后端服务器 (192.168.1.111) 部署微服务**
|
||
|
||
```bash
|
||
# 克隆代码
|
||
git clone <repo> /opt/rwadurian
|
||
cd /opt/rwadurian
|
||
|
||
# 配置环境变量
|
||
cp backend/services/.env.example backend/services/.env
|
||
# 编辑 .env 文件
|
||
|
||
# 启动基础设施和微服务
|
||
cd backend/services
|
||
./deploy.sh up
|
||
|
||
# 确保防火墙开放端口 3000-3011
|
||
```
|
||
|
||
**步骤 2: 在网关服务器 (192.168.1.100) 部署 Kong**
|
||
|
||
```bash
|
||
# 克隆代码
|
||
git clone <repo> /opt/rwadurian
|
||
cd /opt/rwadurian
|
||
|
||
# 修改 kong.yml 中的后端服务器 IP（如有变化）
|
||
# 默认配置为 192.168.1.111
|
||
|
||
# 启动 Kong API Gateway
|
||
cd backend/api-gateway
|
||
./deploy.sh up
|
||
|
||
# 配置 Nginx + SSL
|
||
cd nginx
|
||
sudo ./install.sh
|
||
|
||
# 验证
|
||
curl https://rwaapi.szaiai.com/api/v1/versions
|
||
```
|
||
|
||
### 修改后端服务器 IP
|
||
|
||
如果后端服务器 IP 不是 192.168.1.111，需要修改 `kong.yml`:
|
||
|
||
```bash
|
||
# 批量替换 IP 地址
|
||
sed -i 's/192.168.1.111/YOUR_BACKEND_IP/g' kong.yml
|
||
```
|
||
|
||
### 服务依赖关系
|
||
|
||
```
|
||
后端服务器 (192.168.1.111):
|
||
1. Infrastructure (PostgreSQL, Redis, Kafka)
|
||
↓
|
||
2. Application Services (identity, wallet, admin, etc.)
|
||
|
||
网关服务器 (192.168.1.100):
|
||
3. Kong API Gateway (通过 IP 访问后端)
|
||
↓
|
||
4. Nginx (SSL 终结)
|
||
```
|
||
|
||
## 管理命令
|
||
|
||
### 查看 Kong 状态
|
||
|
||
```bash
|
||
# 查看运行中的容器
|
||
docker ps | grep kong
|
||
|
||
# 查看 Kong 健康状态
|
||
curl http://localhost:8001/status
|
||
|
||
# 查看所有路由
|
||
curl http://localhost:8001/routes
|
||
|
||
# 查看所有服务
|
||
curl http://localhost:8001/services
|
||
|
||
# 查看所有插件
|
||
curl http://localhost:8001/plugins
|
||
```
|
||
|
||
### 重载配置
|
||
|
||
```bash
|
||
# 编辑 kong.yml 后重载
|
||
docker exec rwa-kong kong reload
|
||
|
||
# 或使用部署脚本
|
||
./deploy.sh reload
|
||
```
|
||
|
||
### 查看日志
|
||
|
||
```bash
|
||
# Kong 日志
|
||
docker logs -f rwa-kong
|
||
|
||
# 或使用部署脚本
|
||
./deploy.sh logs
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### 1. Kong 无法启动
|
||
|
||
```bash
|
||
# 检查数据库连接
|
||
docker logs rwa-kong-db
|
||
|
||
# 手动运行迁移
|
||
docker exec -it rwa-kong kong migrations bootstrap
|
||
```
|
||
|
||
### 2. 路由不生效
|
||
|
||
```bash
|
||
# 检查 kong.yml 语法
|
||
docker exec rwa-kong kong config parse /etc/kong/kong.yml
|
||
|
||
# 重启 Kong
|
||
docker restart rwa-kong
|
||
```
|
||
|
||
### 3. 502 Bad Gateway
|
||
|
||
```bash
|
||
# 检查目标服务是否运行
|
||
docker ps | grep rwa-
|
||
|
||
# 检查网络连通性
|
||
docker exec rwa-kong curl http://admin-service:3010/api/v1/health
|
||
|
||
# 检查 Kong 日志
|
||
docker logs rwa-kong --tail 100
|
||
```
|
||
|
||
### 4. 跨域问题
|
||
|
||
检查 kong.yml 中的 cors 插件配置，确保 origins 包含前端域名。
|
||
|
||
## 安全建议
|
||
|
||
1. **生产环境**: 不要暴露 8001 (Admin API) 到公网
|
||
2. **HTTPS**: 使用 Nginx 做 SSL 终结
|
||
3. **限流**: 根据实际流量调整 rate-limiting 配置
|
||
4. **日志**: 定期清理 /tmp/kong-access.log
|