rwadurian/backend/api-gateway/README.md

# API Gateway - Kong

RWADurian 项目的 API 网关，基于 Kong 实现。

## 架构概览

```
                                    ┌─────────────────────────────────────┐
                                    │           RWA Backend               │
                                    └─────────────────────────────────────┘
                                                    │
                    ┌───────────────────────────────┼───────────────────────────────┐
                    │                               │                               │
                    ▼                               ▼                               ▼
        ┌───────────────────┐           ┌───────────────────┐           ┌───────────────────┐
        │  rwaadmin.szaiai  │           │  rwaapi.szaiai    │           │  update.szaiai    │
        │   (Admin Web)     │           │   (API Gateway)   │           │  (Mobile Upgrade) │
        │     :443          │           │     :443          │           │     :443          │
        └─────────┬─────────┘           └─────────┬─────────┘           └─────────┬─────────┘
                  │                               │                               │
                  │ Nginx                         │ Nginx                         │ Nginx
                  │                               │                               │
                  ▼                               ▼                               ▼
        ┌───────────────────┐           ┌───────────────────┐           ┌───────────────────┐
        │   Admin Web       │           │   Kong Gateway    │           │   Mobile Upgrade  │
        │   (Next.js)       │           │                   │           │   (Next.js)       │
        │     :3000         │           │     :8000         │           │     :3020         │
        └───────────────────┘           └─────────┬─────────┘           └───────────────────┘
                                                  │
                    ┌─────────────────────────────┼─────────────────────────────┐
                    │                             │                             │
                    ▼                             ▼                             ▼
        ┌───────────────────┐       ┌───────────────────┐       ┌───────────────────┐
        │ identity-service  │       │  admin-service    │       │ presence-service  │
        │     :3000         │       │     :3010         │       │     :3011         │
        └───────────────────┘       └───────────────────┘       └───────────────────┘
                │                           │                           │
                └───────────────────────────┼───────────────────────────┘
                                            │
                              ┌─────────────┴─────────────┐
                              │     Infrastructure        │
                              │  PostgreSQL / Redis /     │
                              │  Kafka / Zookeeper        │
                              └───────────────────────────┘
```

## 目录结构

```
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) |

## 生产环境部署

### 完整部署流程

```bash
# 1. 克隆代码到服务器
git clone <repo> /opt/rwadurian
cd /opt/rwadurian

# 2. 配置环境变量
cp backend/services/.env.example backend/services/.env
# 编辑 .env 文件，设置数据库密码、JWT 密钥等

# 3. 启动基础设施和微服务
cd backend/services
./deploy.sh up

# 4. 启动 Kong API Gateway
cd ../api-gateway
./deploy.sh up

# 5. 配置 Nginx + SSL
cd nginx
sudo ./install.sh

# 6. 验证
curl https://rwaapi.szaiai.com/api/v1/versions
```

### 服务依赖关系

```
1. Infrastructure (PostgreSQL, Redis, Kafka)
       ↓
2. Application Services (identity, wallet, admin, etc.)
       ↓
3. Kong API Gateway
       ↓
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