rwadurian/backend/api-gateway/README.md

# API Gateway - Kong Deployment Guide

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

## 目录

- [架构概览](#架构概览)
- [快速开始](#快速开始)
- [环境配置](#环境配置)
- [部署命令](#部署命令)
- [监控](#监控)
- [生产环境部署](#生产环境部署)
- [故障排除](#故障排除)

## 架构概览

### 分布式部署架构

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                                网关服务器                                         │
│  ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐                │
│  │     Nginx       │   │     Nginx       │   │     Nginx       │                │
│  │  (Admin Web)    │   │   (API SSL)     │   │ (Mobile Update) │                │
│  └────────┬────────┘   └────────┬────────┘   └────────┬────────┘                │
│           │                     │                     │                         │
│           ▼                     ▼                     ▼                         │
│  ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐                │
│  │   Admin Web     │   │  Kong Gateway   │   │ Mobile Upgrade  │                │
│  │   (Next.js)     │   │                 │   │   (Next.js)     │                │
│  │     :3000       │   │     :8000       │   │     :3020       │                │
│  └─────────────────┘   └────────┬────────┘   └─────────────────┘                │
└─────────────────────────────────┼───────────────────────────────────────────────┘
                                  │
                      通过网络访问后端服务器
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                                后端服务器                                         │
│                                                                                 │
│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐       │
│  │identity-service│ │wallet-service │ │backup-service │ │planting-service│      │
│  │    :3000      │ │    :3001      │ │    :3002      │ │    :3003      │       │
│  └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘       │
│                                                                                 │
│  └ ... 更多微服务 ...                                                             │
│                                                                                 │
│  ┌─────────────────────────────────────────────────────────────────────┐       │
│  │                      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/api-gateway

# 创建 .env 文件
cp .env.example .env

# 编辑 .env 并根据实际环境修改配置
nano .env  # 或使用你喜欢的编辑器
```

**重要**: 必须修改 `.env` 中的以下配置项：

```bash
# 修改数据库密码（生产环境必须）
KONG_PG_PASSWORD=your_secure_password_here

# 更新后端服务器 IP（根据实际部署修改）
BACKEND_SERVER_IP=192.168.1.111  # 改为实际后端服务器IP

# 如需监控，修改 Grafana 配置
GRAFANA_ADMIN_PASSWORD=secure_password
GRAFANA_ROOT_URL=https://monitor.yourdomain.com
```

### 2. 修改 Kong 路由配置

编辑 `kong.yml`，更新后端服务的 URL：

```bash
# 批量替换后端服务器 IP（如果不是 192.168.1.111）
sed -i 's/192.168.1.111/YOUR_BACKEND_IP/g' kong.yml
```

### 3. 先启动后端微服务

**在后端服务器上**执行：

```bash
cd backend/services
./deploy.sh up
```

### 4. 启动 Kong API Gateway

**在网关服务器上**执行：

```bash
cd backend/api-gateway
chmod +x deploy.sh
./deploy.sh up
```

### 5. 验证部署

```bash
# 检查Kong状态
./deploy.sh status

# 健康检查
./deploy.sh health

# 查看路由
./deploy.sh routes

# 测试API
curl http://localhost:8000/api/v1/versions
```

### 6. 配置 Nginx + SSL (生产环境，可选)

```bash
cd nginx
sudo chmod +x install.sh
sudo ./install.sh yourdomain.com
```

## 环境配置

所有配置通过 `.env` 文件管理。参考 `.env.example` 了解所有可用选项。

### 环境变量说明

| 变量名 | 说明 | 默认值 | 是否必需 |
|--------|------|--------|----------|
| `KONG_PG_PASSWORD` | Kong 数据库密码 | `kong_password` | 是 |
| `KONG_ADMIN_GUI_URL` | 管理界面URL | `http://localhost:8002` | 否 |
| `GRAFANA_ADMIN_PASSWORD` | Grafana 管理密码 | `admin123` | 否* |
| `GRAFANA_ROOT_URL` | Grafana 公开URL | `http://localhost:3030` | 否* |
| `NETWORK_NAME` | Docker 网络名称 | `api-gateway_rwa-network` | 否 |
| `BACKEND_SERVER_IP` | 后端服务器IP | `127.0.0.1` | 否 |

\* 仅在使用监控时需要

### Kong 数据库配置说明

Kong 使用 PostgreSQL 作为数据存储，数据库配置如下：

- **数据库用户名**: `kong` (硬编码，不可修改)
- **数据库名称**: `kong` (硬编码，不可修改)
- **数据库密码**: 通过 `.env` 中的 `KONG_PG_PASSWORD` 配置（**生产环境必须修改**）
- **数据库初始化**: Kong 容器启动时自动执行 `kong migrations bootstrap`，无需手动创建数据库或表结构

**重要提示**:
- Kong 的数据库用户名和数据库名都是固定为 `kong`，这是 Kong 的设计，无法通过环境变量修改
- 只有密码可以通过 `KONG_PG_PASSWORD` 自定义
- 生产环境部署时，务必修改 `KONG_PG_PASSWORD` 为强密码

### 生成安全密码

```bash
# 生成数据库密码
openssl rand -base64 32

# 生成 Grafana 密码
openssl rand -base64 24
```

## 部署命令

### 基础操作

```bash
./deploy.sh up        # 启动 Kong 网关
./deploy.sh down      # 停止 Kong 网关
./deploy.sh restart   # 重启 Kong 网关
./deploy.sh logs      # 查看日志 (实时)
./deploy.sh status    # 查看服务状态
```

### 配置管理

```bash
./deploy.sh reload    # 重载 Kong 配置 (从 kong.yml)
./deploy.sh sync      # 同步配置到数据库 (同 reload)
```

### 健康检查与监控

```bash
./deploy.sh health    # Kong 健康检查
./deploy.sh routes    # 查看所有路由
./deploy.sh services  # 查看所有服务
./deploy.sh test      # 测试 API 路由
./deploy.sh metrics   # 查看 Prometheus 指标
```

### 监控栈管理

```bash
./deploy.sh monitoring up    # 启动 Prometheus + Grafana
./deploy.sh monitoring down  # 停止监控服务
./deploy.sh monitoring install [domain]  # 完整安装 (Nginx+SSL+监控)
```

### 清理

```bash
./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
# 启动 Prometheus + Grafana
./deploy.sh monitoring up
```

### 访问监控服务

启动后可以访问：

- **Grafana**: http://localhost:3030
  - 用户名: `admin`
  - 密码: 在 `.env` 中配置 (`GRAFANA_ADMIN_PASSWORD`)

- **Prometheus**: http://localhost:9099

- **Kong 指标**: http://localhost:8001/metrics

### 查看指标

```bash
# 快速查看关键指标
./deploy.sh metrics
```

### 配置告警 (可选)

在 Grafana 中可以配置告警规则，监控：
- 请求率
- 错误率 (4xx, 5xx)
- 延迟 (p50, p95, p99)
- Kong 健康状态

### Grafana 通过 Nginx/域名访问配置

如果使用 `install-monitor.sh` 安装了 Nginx + SSL，需要配置 Grafana 允许通过域名访问：

1. **编辑 `.env` 文件**，设置正确的访问 URL：
   ```bash
   GRAFANA_ROOT_URL=https://monitor.szaiai.com
   ```

2. **重启监控服务**使配置生效：
   ```bash
   ./deploy.sh monitoring down
   ./deploy.sh monitoring up
   ```

3. **验证配置**：
   ```bash
   docker exec rwa-grafana env | grep GF_SERVER_ROOT_URL
   # 应该输出: GF_SERVER_ROOT_URL=https://monitor.szaiai.com
   ```

**常见错误**：
- 如果看到 "origin not allowed" 错误，说明 `GRAFANA_ROOT_URL` 与实际访问地址不匹配
- 修改 `.env` 后必须重启容器才能生效

**如果之前已安装 Nginx，需要更新配置**：

如果你之前运行过 `install-monitor.sh`，需要手动更新 Nginx 配置文件以支持 Grafana 10+：

```bash
# 1. 编辑 Nginx 配置文件
sudo nano /etc/nginx/sites-available/monitor.szaiai.com.conf

# 2. 在 Grafana location / 块中添加以下 headers:
#    proxy_set_header Host $http_host;
#    proxy_set_header X-Forwarded-Host $host;
#    proxy_set_header X-Forwarded-Port $server_port;
#    proxy_set_header Origin $scheme://$host;
#    proxy_buffering off;

# 3. 测试并重载 Nginx
sudo nginx -t
sudo systemctl reload nginx
```

或者重新运行安装脚本（会使用更新后的配置）：
```bash
cd ~/rwadurian/backend/api-gateway
sudo ./scripts/install-monitor.sh monitor.szaiai.com
```

## 生产环境部署

### 部署前检查清单

- [ ] 修改 `.env` 中的所有默认密码
- [ ] 更新 `.env` 中的 `BACKEND_SERVER_IP` 为实际后端服务器IP
- [ ] 更新 `kong.yml` 中的后端服务URL (替换IP地址)
- [ ] 配置 SSL/TLS 证书 (如使用 HTTPS)
- [ ] 设置 PostgreSQL 数据库备份
- [ ] 配置防火墙规则
- [ ] 启用监控栈
- [ ] 配置日志聚合

### 分布式部署流程

**服务器规划示例:**
- 服务器A: 网关服务器 (Nginx + Kong + 前端)
- 服务器B: 后端服务器 (微服务 + 基础设施)

**步骤 1: 在后端服务器部署微服务**

```bash
# 克隆代码
git clone <repo> /opt/rwadurian
cd /opt/rwadurian/backend/services

# 配置环境变量
cp .env.example .env
nano .env  # 配置生产环境参数

# 启动服务
./deploy.sh up

# 开放防火墙端口 3000-3011 (根据实际微服务数量)
sudo ufw allow 3000:3011/tcp
```

**步骤 2: 在网关服务器部署 Kong**

```bash
# 克隆代码
git clone <repo> /opt/rwadurian
cd /opt/rwadurian/backend/api-gateway

# 配置环境变量
cp .env.example .env
nano .env  # 配置 BACKEND_SERVER_IP 等参数

# 修改 kong.yml 中的后端服务器地址
nano kong.yml  # 更新服务URL中的IP地址
# 或使用 sed: sed -i 's/OLD_IP/NEW_IP/g' kong.yml

# 启动 Kong
./deploy.sh up

# 验证连接
./deploy.sh health
./deploy.sh test
```

**步骤 3: 配置 Nginx + SSL (可选)**

```bash
cd nginx
sudo ./install.sh yourdomain.com

# 验证HTTPS
curl https://yourdomain.com/api/v1/versions
```

### 服务依赖关系

```
后端服务器:
  1. Infrastructure (PostgreSQL, Redis, Kafka)
         ↓
  2. Application Services (微服务)

网关服务器:
  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