AIGC/demo/NGINX_REVERSE_PROXY_GUIDE.md

Nginx 反向代理配置指南

📋 概述

本项目已配置使用 Nginx 作为反向代理服务器，实现以下功能：

• 前端静态文件服务（Vue.js 构建产物）
• API 请求代理到后端 Spring Boot 服务
• 负载均衡和健康检查
• Gzip 压缩优化
• WebSocket 支持

🏗️ 架构

用户请求
   ↓
Nginx (端口 80)
   ├─ / → 前端静态文件 (dist/)
   └─ /api/ → 代理到后端 (backend:8080)

📁 文件结构

demo/
├── nginx/
│   ├── nginx.conf          # Nginx 主配置文件
│   ├── Dockerfile          # Nginx 容器镜像
│   └── docker-compose.yml  # 独立 Nginx 部署（可选）
├── docker-compose.yml      # 完整的服务编排（包含 Nginx）
└── Dockerfile.backend       # 后端服务镜像

🚀 快速开始

方式一：使用 Docker Compose（推荐）

# 1. 构建前端
cd frontend
npm install
npm run build
cd ..

# 2. 启动所有服务（包括 Nginx）
docker-compose up -d

# 3. 访问应用
# 前端: http://localhost
# 后端API: http://localhost/api

方式二：独立部署 Nginx

# 1. 构建前端
cd frontend
npm install
npm run build
cd ..

# 2. 启动后端服务
java -jar target/demo-0.0.1-SNAPSHOT.jar --spring.profiles.active=prod

# 3. 启动 Nginx（在 nginx 目录下）
cd nginx
docker-compose up -d

⚙️ Nginx 配置详解

主要配置项

1. 上游服务器配置

upstream backend {
    server backend:8080;  # 后端服务地址（Docker 服务名）
    keepalive 32;
}

2. 前端静态文件服务

location / {
    try_files $uri $uri/ /index.html;  # SPA 路由支持
}

3. API 代理配置

location /api/ {
    proxy_pass http://backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

功能特性

✅ 静态资源缓存

• 图片、CSS、JS 等静态资源缓存 30 天
• 提升页面加载速度

✅ Gzip 压缩

• 自动压缩文本文件（HTML、CSS、JS、JSON）
• 减少传输数据量

✅ WebSocket 支持

• 支持 WebSocket 连接（/ws/ 路径）
• 自动处理升级协议

✅ 健康检查

• /health 端点用于健康检查
• 便于监控和负载均衡

✅ CORS 处理

• 自动处理跨域请求
• 支持预检请求（OPTIONS）

🔧 配置修改

修改端口

编辑 docker-compose.yml：

nginx:
  ports:
    - "8080:80"  # 外部端口:容器端口

修改后端地址

编辑 nginx/nginx.conf：

upstream backend {
    server your-backend-host:8080;  # 修改为实际后端地址
}

添加 SSL/HTTPS

1. 将 SSL 证书放在 nginx/ssl/ 目录
2. 修改 nginx.conf 添加 HTTPS 配置：

server {
    listen 443 ssl;
    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
    # ... 其他配置
}

📝 环境变量配置

生产环境变量

创建 .env 文件或设置环境变量：

# 数据库配置
MYSQL_ROOT_PASSWORD=your_password
MYSQL_DATABASE=aigc_platform

# Spring Boot 配置
SPRING_PROFILES_ACTIVE=prod
SPRING_DATASOURCE_URL=jdbc:mysql://mysql:3306/aigc_platform

🔍 故障排查

检查 Nginx 日志

# 查看 Nginx 容器日志
docker logs demo-nginx

# 查看错误日志
docker exec demo-nginx cat /var/log/nginx/error.log

# 查看访问日志
docker exec demo-nginx cat /var/log/nginx/access.log

测试配置

# 检查 Nginx 配置语法
docker exec demo-nginx nginx -t

# 重新加载配置（不中断服务）
docker exec demo-nginx nginx -s reload

常见问题

1. 502 Bad Gateway

• 原因：后端服务未启动或无法连接
• 解决：检查后端服务状态 docker ps

2. 404 Not Found（前端路由）

• 原因：缺少 try_files 配置
• 解决：确保配置了 try_files $uri $uri/ /index.html;

3. CORS 错误

• 原因：代理头设置不正确
• 解决：检查 proxy_set_header 配置

🧪 测试

测试前端访问

curl http://localhost/

测试 API 代理

curl http://localhost/api/health

测试健康检查

curl http://localhost/health

📊 性能优化

1. 启用 HTTP/2

listen 443 ssl http2;

2. 增加缓存

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:10m;
location /api/ {
    proxy_cache api_cache;
    proxy_cache_valid 200 5m;
}

3. 限制请求速率

limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;
location /api/ {
    limit_req zone=api_limit burst=20;
}

🔐 安全建议

1. 隐藏 Nginx 版本

server_tokens off;

2. 限制请求大小

client_max_body_size 100M;

3. 使用 HTTPS

• 配置 SSL 证书
• 启用 HSTS

4. IP 白名单（如需要）

location /admin/ {
    allow 192.168.1.0/24;
    deny all;
}

📚 相关文档

• Nginx 官方文档
• Docker Compose 文档
• Vue.js 部署指南

🎯 下一步

1. ✅ 配置已完成
2. 构建前端：cd frontend && npm run build
3. 启动服务：docker-compose up -d
4. 访问应用：http://localhost

---

注意：首次部署前请确保：

• 前端已构建（frontend/dist 目录存在）
• 数据库已初始化
• 环境变量已配置