rwadurian/backend/api-gateway

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. 配置环境变量

cd backend/api-gateway

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

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

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

# 修改数据库密码（生产环境必须）
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：

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

3. 先启动后端微服务

在后端服务器上执行：

cd backend/services
./deploy.sh up

4. 启动 Kong API Gateway

在网关服务器上执行：

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

5. 验证部署

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

# 健康检查
./deploy.sh health

# 查看路由
./deploy.sh routes

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

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

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 为强密码

生成安全密码

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

# 生成 Grafana 密码
openssl rand -base64 24

部署命令

基础操作

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

配置管理

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

健康检查与监控

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

监控栈管理

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

清理

./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)

监控

启动监控栈

# 启动 Prometheus + Grafana
./deploy.sh monitoring up

访问监控服务

启动后可以访问：

• Grafana: http://localhost:3030

  • 用户名: admin
  • 密码: 在 .env 中配置 (GRAFANA_ADMIN_PASSWORD)

• Prometheus: http://localhost:9099

• Kong 指标: http://localhost:8001/metrics

查看指标

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

配置告警 (可选)

在 Grafana 中可以配置告警规则，监控：

• 请求率
• 错误率 (4xx, 5xx)
• 延迟 (p50, p95, p99)
• Kong 健康状态

Grafana 通过 Nginx/域名访问配置

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

1. 编辑 .env 文件，设置正确的访问 URL：

   GRAFANA_ROOT_URL=https://monitor.szaiai.com
   

2. 重启监控服务使配置生效：

   ./deploy.sh monitoring down
   ./deploy.sh monitoring up
   

3. 验证配置：

   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+：

# 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

或者重新运行安装脚本（会使用更新后的配置）：

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: 在后端服务器部署微服务

# 克隆代码
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

# 克隆代码
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 (可选)

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 状态

# 查看运行中的容器
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

重载配置

# 编辑 kong.yml 后重载
docker exec rwa-kong kong reload

# 或使用部署脚本
./deploy.sh reload

查看日志

# Kong 日志
docker logs -f rwa-kong

# 或使用部署脚本
./deploy.sh logs

故障排除

1. Kong 无法启动

# 检查数据库连接
docker logs rwa-kong-db

# 手动运行迁移
docker exec -it rwa-kong kong migrations bootstrap

2. 路由不生效

# 检查 kong.yml 语法
docker exec rwa-kong kong config parse /etc/kong/kong.yml

# 重启 Kong
docker restart rwa-kong

3. 502 Bad Gateway

# 检查目标服务是否运行
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