# 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（推荐）

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

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

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

### 方式二：独立部署 Nginx

```bash
# 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. 上游服务器配置
```nginx
upstream backend {
    server backend:8080;  # 后端服务地址（Docker 服务名）
    keepalive 32;
}
```

#### 2. 前端静态文件服务
```nginx
location / {
    try_files $uri $uri/ /index.html;  # SPA 路由支持
}
```

#### 3. API 代理配置
```nginx
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`：
```yaml
nginx:
  ports:
    - "8080:80"  # 外部端口:容器端口
```

### 修改后端地址

编辑 `nginx/nginx.conf`：
```nginx
upstream backend {
    server your-backend-host:8080;  # 修改为实际后端地址
}
```

### 添加 SSL/HTTPS

1. 将 SSL 证书放在 `nginx/ssl/` 目录
2. 修改 `nginx.conf` 添加 HTTPS 配置：
```nginx
server {
    listen 443 ssl;
    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
    # ... 其他配置
}
```

## 📝 环境变量配置

### 生产环境变量

创建 `.env` 文件或设置环境变量：
```bash
# 数据库配置
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 日志
```bash
# 查看 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
```

### 测试配置
```bash
# 检查 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` 配置

## 🧪 测试

### 测试前端访问
```bash
curl http://localhost/
```

### 测试 API 代理
```bash
curl http://localhost/api/health
```

### 测试健康检查
```bash
curl http://localhost/health
```

## 📊 性能优化

### 1. 启用 HTTP/2
```nginx
listen 443 ssl http2;
```

### 2. 增加缓存
```nginx
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. 限制请求速率
```nginx
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;
location /api/ {
    limit_req zone=api_limit burst=20;
}
```

## 🔐 安全建议

1. **隐藏 Nginx 版本**
```nginx
server_tokens off;
```

2. **限制请求大小**
```nginx
client_max_body_size 100M;
```

3. **使用 HTTPS**
- 配置 SSL 证书
- 启用 HSTS

4. **IP 白名单**（如需要）
```nginx
location /admin/ {
    allow 192.168.1.0/24;
    deny all;
}
```

## 📚 相关文档

- [Nginx 官方文档](https://nginx.org/en/docs/)
- [Docker Compose 文档](https://docs.docker.com/compose/)
- [Vue.js 部署指南](https://router.vuejs.org/guide/essentials/history-mode.html)

## 🎯 下一步

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

---

**注意**：首次部署前请确保：
- 前端已构建（`frontend/dist` 目录存在）
- 数据库已初始化
- 环境变量已配置