hailin
/
rwadurian
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor(api-gateway): 将 Kong 独立为解耦模块 

- 将 Kong 从 services/docker-compose.yml 移到 api-gateway/docker-compose.yml
- 添加 api-gateway/deploy.sh 一键部署脚本
- 完善 api-gateway/README.md 文档，包含完整架构图和部署流程
- Kong 使用外部网络连接 services，实现解耦部署

架构变更:
- services: 只包含微服务，不依赖 Kong
- api-gateway: 独立的 Kong 网关，可选部署

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Developer 2025-12-03 00:38:49 -08:00
parent 7d9d5eeffe
commit de2e2d0428
4 changed files with 555 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

273
backend/api-gateway/README.md
View File

@ -2,133 +2,231 @@
RWADurian 项目的 API 网关，基于 Kong 实现。
## 架构
## 架构概览
```
用户请求
↓
Nginx (SSL/负载均衡)
↓ rwaapi.szaiai.com:443
Kong API Gateway
↓ :8000
各微服务
├── identity-service :3000
├── wallet-service :3001
├── backup-service :3002
├── planting-service :3003
├── referral-service :3004
├── reward-service :3005
├── mpc-service :3006
├── leaderboard-service:3007
├── reporting-service :3008
├── authorization-service:3009
├── admin-service :3010
└── presence-service :3011
┌─────────────────────────────────────┐
│ 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/
├── kong.yml # Kong 声明式配置
├── README.md # 本文档
├── docker-compose.yml # Kong Docker Compose 配置
├── deploy.sh # 一键部署脚本
├── kong.yml # Kong 声明式路由配置
├── README.md # 本文档
└── nginx/
├── rwaapi.szaiai.com.conf # Nginx 配置
└── install.sh # 一键安装脚本
├── rwaapi.szaiai.com.conf # Nginx 配置 (SSL)
└── install.sh # Nginx 安装脚本
```
## API 路由
## 快速开始
| 路径 | 服务 | 说明 |
|------|------|------|
| `/api/v1/auth/*` | identity-service | 认证相关 |
| `/api/v1/users/*` | identity-service | 用户管理 |
| `/api/v1/wallets/*` | wallet-service | 钱包管理 |
| `/api/v1/backups/*` | backup-service | 备份服务 |
| `/api/v1/plantings/*` | planting-service | 种植管理 |
| `/api/v1/trees/*` | planting-service | 树木管理 |
| `/api/v1/referrals/*` | referral-service | 推荐系统 |
| `/api/v1/rewards/*` | reward-service | 奖励系统 |
| `/api/v1/mpc/*` | mpc-service | 多方计算 |
| `/api/v1/leaderboard/*` | leaderboard-service | 排行榜 |
| `/api/v1/reports/*` | reporting-service | 报表统计 |
| `/api/v1/statistics/*` | reporting-service | 数据统计 |
| `/api/v1/authorization/*` | authorization-service | 授权管理 |
| `/api/v1/permissions/*` | authorization-service | 权限管理 |
| `/api/v1/roles/*` | authorization-service | 角色管理 |
| `/api/v1/versions/*` | admin-service | 版本管理 |
| `/api/v1/admin/*` | admin-service | 后台管理 |
| `/api/v1/presence/*` | presence-service | 在线状态 |
## 部署
### 1. 启动 Kong (包含在 services 的 docker-compose.yml 中)
### 1. 先启动后端微服务
```bash
cd backend/services
./deploy.sh up
```
### 2. 配置 Nginx + SSL
### 2. 启动 Kong API Gateway
```bash
cd backend/api-gateway/nginx
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
```
### 3. 验证
## 部署脚本命令
```bash
# 检查 Kong 状态
curl http://localhost:8001/status
./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 路由表
| 路径 | 目标服务 | 端口 | 说明 |
|------|----------|------|------|
| `/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
```
## Kong 管理
### 服务依赖关系
### 查看配置
```
1. Infrastructure (PostgreSQL, Redis, Kafka)
↓
2. Application Services (identity, wallet, admin, etc.)
↓
3. Kong API Gateway
↓
4. Nginx (SSL 终结)
```
## 管理命令
### 查看 Kong 状态
```bash
# 查看所有服务
curl http://localhost:8001/services
# 查看运行中的容器
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 容器
docker exec -it rwa-kong sh
# 编辑 kong.yml 后重载
docker exec rwa-kong kong reload
# 重载配置
kong reload
# 或使用部署脚本
./deploy.sh reload
```
## 插件
### 查看日志
已启用的全局插件：
```bash
# Kong 日志
docker logs -f rwa-kong
| 插件 | 功能 |
|------|------|
| cors | 跨域支持 |
| rate-limiting | 请求限流 (100/分钟, 5000/小时) |
| file-log | 请求日志 |
| request-size-limiting | 请求大小限制 (50MB) |
# 或使用部署脚本
./deploy.sh logs
```
## 故障排除
### 1. Kong 无法连接数据库
### 1. Kong 无法启动
```bash
# 检查 kong-db 状态
# 检查数据库连接
docker logs rwa-kong-db
# 手动运行迁移
@ -139,7 +237,7 @@ docker exec -it rwa-kong kong migrations bootstrap
```bash
# 检查 kong.yml 语法
docker exec -it rwa-kong kong config parse /etc/kong/kong.yml
docker exec rwa-kong kong config parse /etc/kong/kong.yml
# 重启 Kong
docker restart rwa-kong
@ -147,5 +245,24 @@ docker restart rwa-kong
### 3. 502 Bad Gateway
- 检查目标服务是否运行: `docker ps`
- 检查服务网络连通性: `docker exec rwa-kong curl http://admin-service:3010/api/v1/health`
```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

253
backend/api-gateway/deploy.sh Normal file
View File

@ -0,0 +1,253 @@
#!/bin/bash
# =============================================================================
# RWADurian API Gateway (Kong) - 部署脚本
# =============================================================================
# Usage:
# ./deploy.sh up # 启动网关
# ./deploy.sh down # 停止网关
# ./deploy.sh restart # 重启网关
# ./deploy.sh logs # 查看日志
# ./deploy.sh status # 查看状态
# ./deploy.sh health # 健康检查
# ./deploy.sh reload # 重载 Kong 配置
# ./deploy.sh routes # 查看所有路由
# =============================================================================
set -e
# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'
# 项目信息
PROJECT_NAME="rwa-api-gateway"
KONG_ADMIN_URL="http://localhost:8001"
KONG_PROXY_URL="http://localhost:8000"
# 切换到脚本所在目录
cd "$(dirname "$0")"
# 日志函数
log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
log_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
# 检查 Docker
check_docker() {
if ! command -v docker &> /dev/null; then
log_error "Docker 未安装"
exit 1
fi
if ! docker info &> /dev/null; then
log_error "Docker 服务未运行"
exit 1
fi
}
# 检查 Docker Compose
check_docker_compose() {
if docker compose version &> /dev/null; then
COMPOSE_CMD="docker compose"
elif command -v docker-compose &> /dev/null; then
COMPOSE_CMD="docker-compose"
else
log_error "Docker Compose 未安装"
exit 1
fi
}
# 检查 services 网络是否存在
check_network() {
if ! docker network inspect services_rwa-network &> /dev/null; then
log_warn "services_rwa-network 网络不存在"
log_info "请先启动后端服务: cd ../services && ./deploy.sh up"
exit 1
fi
}
# 启动服务
cmd_up() {
log_info "启动 Kong API Gateway..."
check_network
$COMPOSE_CMD up -d
log_info "等待 Kong 启动..."
sleep 10
# 检查状态
if docker ps | grep -q rwa-kong; then
log_success "Kong API Gateway 启动成功!"
echo ""
echo "服务地址:"
echo " Proxy: http://localhost:8000"
echo " Admin API: http://localhost:8001"
echo " Admin GUI: http://localhost:8002"
echo ""
echo "查看路由: ./deploy.sh routes"
else
log_error "Kong 启动失败，查看日志: ./deploy.sh logs"
exit 1
fi
}
# 停止服务
cmd_down() {
log_info "停止 Kong API Gateway..."
$COMPOSE_CMD down
log_success "Kong 已停止"
}
# 重启服务
cmd_restart() {
log_info "重启 Kong API Gateway..."
$COMPOSE_CMD restart
log_success "Kong 已重启"
}
# 查看日志
cmd_logs() {
$COMPOSE_CMD logs -f
}
# 查看状态
cmd_status() {
log_info "Kong API Gateway 状态:"
$COMPOSE_CMD ps
}
# 健康检查
cmd_health() {
log_info "Kong 健康检查..."
# 检查 Kong 状态
response=$(curl -s $KONG_ADMIN_URL/status 2>/dev/null)
if [ $? -eq 0 ]; then
log_success "Kong Admin API 正常"
echo "$response" | python3 -m json.tool 2>/dev/null || echo "$response"
else
log_error "Kong Admin API 不可用"
exit 1
fi
}
# 重载配置
cmd_reload() {
log_info "重载 Kong 配置..."
docker exec rwa-kong kong reload
log_success "配置已重载"
}
# 查看所有路由
cmd_routes() {
log_info "Kong 路由列表:"
curl -s $KONG_ADMIN_URL/routes | python3 -m json.tool 2>/dev/null || curl -s $KONG_ADMIN_URL/routes
}
# 查看所有服务
cmd_services() {
log_info "Kong 服务列表:"
curl -s $KONG_ADMIN_URL/services | python3 -m json.tool 2>/dev/null || curl -s $KONG_ADMIN_URL/services
}
# 测试 API
cmd_test() {
log_info "测试 API 路由..."
echo ""
echo "测试 /api/v1/versions (admin-service):"
curl -s -o /dev/null -w " HTTP Status: %{http_code}\n" $KONG_PROXY_URL/api/v1/versions
echo ""
echo "测试 /api/v1/auth (identity-service):"
curl -s -o /dev/null -w " HTTP Status: %{http_code}\n" $KONG_PROXY_URL/api/v1/auth
}
# 清理
cmd_clean() {
log_info "清理 Kong 容器和数据..."
$COMPOSE_CMD down -v --remove-orphans
docker image prune -f
log_success "清理完成"
}
# 显示帮助
show_help() {
echo ""
echo "RWADurian API Gateway (Kong) 部署脚本"
echo ""
echo "用法: ./deploy.sh [命令]"
echo ""
echo "命令:"
echo " up 启动 Kong 网关"
echo " down 停止 Kong 网关"
echo " restart 重启 Kong 网关"
echo " logs 查看日志"
echo " status 查看状态"
echo " health 健康检查"
echo " reload 重载 Kong 配置"
echo " routes 查看所有路由"
echo " services 查看所有服务"
echo " test 测试 API 路由"
echo " clean 清理容器和数据"
echo " help 显示帮助"
echo ""
echo "注意: 需要先启动 backend/services 才能启动 Kong"
echo ""
}
# 主函数
main() {
check_docker
check_docker_compose
case "${1:-help}" in
up)
cmd_up
;;
down)
cmd_down
;;
restart)
cmd_restart
;;
logs)
cmd_logs
;;
status)
cmd_status
;;
health)
cmd_health
;;
reload)
cmd_reload
;;
routes)
cmd_routes
;;
services)
cmd_services
;;
test)
cmd_test
;;
clean)
cmd_clean
;;
help|--help|-h)
show_help
;;
*)
log_error "未知命令: $1"
show_help
exit 1
;;
esac
}
main "$@"

107
backend/api-gateway/docker-compose.yml Normal file
View File

@ -0,0 +1,107 @@
# =============================================================================
# Kong API Gateway - Docker Compose
# =============================================================================
# Usage:
# ./deploy.sh up # 启动 Kong 网关
# ./deploy.sh down # 停止 Kong 网关
# ./deploy.sh logs # 查看日志
# ./deploy.sh status # 查看状态
# =============================================================================
services:
# ===========================================================================
# Kong Database
# ===========================================================================
kong-db:
image: postgres:16-alpine
container_name: rwa-kong-db
environment:
POSTGRES_USER: kong
POSTGRES_PASSWORD: ${KONG_PG_PASSWORD:-kong_password}
POSTGRES_DB: kong
volumes:
- kong_db_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U kong"]
interval: 5s
timeout: 5s
retries: 10
restart: unless-stopped
networks:
- rwa-network
# ===========================================================================
# Kong Migrations (只运行一次)
# ===========================================================================
kong-migrations:
image: kong:3.5-alpine
container_name: rwa-kong-migrations
command: kong migrations bootstrap
environment:
KONG_DATABASE: postgres
KONG_PG_HOST: kong-db
KONG_PG_USER: kong
KONG_PG_PASSWORD: ${KONG_PG_PASSWORD:-kong_password}
KONG_PG_DATABASE: kong
depends_on:
kong-db:
condition: service_healthy
restart: on-failure
networks:
- rwa-network
# ===========================================================================
# Kong API Gateway
# ===========================================================================
kong:
image: kong:3.5-alpine
container_name: rwa-kong
environment:
KONG_DATABASE: postgres
KONG_PG_HOST: kong-db
KONG_PG_USER: kong
KONG_PG_PASSWORD: ${KONG_PG_PASSWORD:-kong_password}
KONG_PG_DATABASE: kong
KONG_PROXY_ACCESS_LOG: /dev/stdout
KONG_ADMIN_ACCESS_LOG: /dev/stdout
KONG_PROXY_ERROR_LOG: /dev/stderr
KONG_ADMIN_ERROR_LOG: /dev/stderr
KONG_ADMIN_LISTEN: 0.0.0.0:8001
KONG_ADMIN_GUI_URL: http://localhost:8002
KONG_DECLARATIVE_CONFIG: /etc/kong/kong.yml
ports:
- "8000:8000" # Proxy HTTP
- "8443:8443" # Proxy HTTPS
- "8001:8001" # Admin API
- "8002:8002" # Admin GUI
volumes:
- ./kong.yml:/etc/kong/kong.yml:ro
depends_on:
kong-db:
condition: service_healthy
kong-migrations:
condition: service_completed_successfully
healthcheck:
test: ["CMD", "kong", "health"]
interval: 30s
timeout: 10s
retries: 5
start_period: 30s
restart: unless-stopped
networks:
- rwa-network
# ===========================================================================
# Volumes
# ===========================================================================
volumes:
kong_db_data:
driver: local
# ===========================================================================
# Networks - 使用外部网络连接到 services
# ===========================================================================
networks:
rwa-network:
external: true
name: services_rwa-network

79
backend/services/docker-compose.yml
View File

@ -93,83 +93,6 @@ services:
networks:
- rwa-network
# ===========================================================================
# API Gateway - Kong
# ===========================================================================
kong-db:
image: postgres:16-alpine
container_name: rwa-kong-db
environment:
POSTGRES_USER: kong
POSTGRES_PASSWORD: ${KONG_PG_PASSWORD:-kong_password}
POSTGRES_DB: kong
volumes:
- kong_db_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U kong"]
interval: 5s
timeout: 5s
retries: 10
restart: unless-stopped
networks:
- rwa-network
kong-migrations:
image: kong:3.5-alpine
container_name: rwa-kong-migrations
command: kong migrations bootstrap
environment:
KONG_DATABASE: postgres
KONG_PG_HOST: kong-db
KONG_PG_USER: kong
KONG_PG_PASSWORD: ${KONG_PG_PASSWORD:-kong_password}
KONG_PG_DATABASE: kong
depends_on:
kong-db:
condition: service_healthy
restart: on-failure
networks:
- rwa-network
kong:
image: kong:3.5-alpine
container_name: rwa-kong
environment:
KONG_DATABASE: postgres
KONG_PG_HOST: kong-db
KONG_PG_USER: kong
KONG_PG_PASSWORD: ${KONG_PG_PASSWORD:-kong_password}
KONG_PG_DATABASE: kong
KONG_PROXY_ACCESS_LOG: /dev/stdout
KONG_ADMIN_ACCESS_LOG: /dev/stdout
KONG_PROXY_ERROR_LOG: /dev/stderr
KONG_ADMIN_ERROR_LOG: /dev/stderr
KONG_ADMIN_LISTEN: 0.0.0.0:8001
KONG_ADMIN_GUI_URL: http://localhost:8002
KONG_DECLARATIVE_CONFIG: /etc/kong/kong.yml
ports:
- "8000:8000" # Proxy HTTP
- "8443:8443" # Proxy HTTPS
- "8001:8001" # Admin API
- "8002:8002" # Admin GUI
volumes:
- ../api-gateway/kong.yml:/etc/kong/kong.yml:ro
depends_on:
kong-db:
condition: service_healthy
kong-migrations:
condition: service_completed_successfully
healthcheck:
test: ["CMD", "kong", "health"]
interval: 30s
timeout: 10s
retries: 5
start_period: 30s
restart: unless-stopped
networks:
- rwa-network
# ===========================================================================
# Application Services
# ===========================================================================
@ -619,8 +542,6 @@ volumes:
driver: local
redis_data:
driver: local
kong_db_data:
driver: local
# ===========================================================================
# Networks