AIGC/demo/FINAL_NGINX_NGROK_SETUP.md

# 🎯 Nginx + Ngrok 内网穿透最终配置

## ✅ 配置完成状态

所有配置已完成并验证通过，可以直接使用！

---

## 📋 当前配置

### Ngrok 穿透信息
- **穿透地址**: `https://curtly-aphorismatic-ginger.ngrok-free.dev`
- **穿透端口**: `80` (Nginx)
- **协议**: HTTPS（由 Ngrok 自动提供）

### 架构流程
```
外部用户
   ↓
https://curtly-aphorismatic-ginger.ngrok-free.dev (Ngrok HTTPS)
   ↓
localhost:80 (Nginx - 唯一需要穿透的端口)
   ├─ GET / → 前端静态文件
   ├─ GET /api/* → proxy_pass → backend:8080 (内部 Docker 网络)
   └─ GET /health → Nginx 健康检查
```

---

## ✅ 已完成的配置更新

### 1. Nginx 配置 ✅
**文件**: `nginx/nginx.conf`
- ✅ 添加 `server_name` 支持 ngrok 域名
- ✅ API 代理配置：`/api/` → `backend:8080`
- ✅ CORS 配置优化，支持动态来源
- ✅ 前端静态文件服务

### 2. 前端 API 自动适配 ✅
**文件**: 
- `frontend/src/utils/apiHelper.js` - 统一的 API 工具函数
- `frontend/src/api/request.js` - 使用工具函数
- `frontend/src/api/cleanup.js` - 使用工具函数
- `frontend/src/views/Login.vue` - 使用工具函数

**功能**:
- ✅ 自动检测当前访问域名
- ✅ 通过 ngrok 访问：使用相对路径 `/api`（自动适配）
- ✅ 本地开发：使用 `http://localhost:8080/api`

### 3. 支付宝回调配置 ✅
**文件**: `src/main/resources/application-dev.properties`
- ✅ `alipay.notify-url`: `https://curtly-aphorismatic-ginger.ngrok-free.dev/api/payments/alipay/notify`
- ✅ `alipay.return-url`: `https://curtly-aphorismatic-ginger.ngrok-free.dev/api/payments/alipay/return`

### 4. 后端 CORS 配置 ✅
**文件**: `src/main/java/com/example/demo/config/SecurityConfig.java`
- ✅ 支持 `*.ngrok-free.app` 域名模式
- ✅ 支持所有 ngrok 子域名

### 5. Docker Compose 配置 ✅
**文件**: `docker-compose.yml`
- ✅ 服务编排：MySQL、Backend、Nginx
- ✅ 网络配置：`app-network`
- ✅ 端口映射：仅 Nginx 暴露 80 端口（后端和 MySQL 不对外暴露）

---

## 🚀 部署步骤

### 步骤 1: 构建前端

```bash
cd frontend
npm install
npm run build
cd ..
```

**重要**: 确保 `frontend/dist` 目录存在。

### 步骤 2: 启动 Docker 服务

```bash
# 启动所有服务
docker-compose up -d --build

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f
```

### 步骤 3: 启动 Ngrok（穿透 80 端口）

```bash
# 重要：必须穿透 80 端口（Nginx），不是 8080（后端）
ngrok http 80
```

**输出示例**:
```
Forwarding   https://curtly-aphorismatic-ginger.ngrok-free.dev -> http://localhost:80
```

### 步骤 4: 访问应用

在浏览器中打开：
- 🌐 **前端**: `https://curtly-aphorismatic-ginger.ngrok-free.dev`
- 🔗 **API**: `https://curtly-aphorismatic-ginger.ngrok-free.dev/api`
- 🏥 **健康检查**: `https://curtly-aphorismatic-ginger.ngrok-free.dev/health`

---

## 🧪 验证测试

### 1. 测试前端访问
```bash
curl https://curtly-aphorismatic-ginger.ngrok-free.dev/
```

### 2. 测试 API 代理
```bash
curl https://curtly-aphorismatic-ginger.ngrok-free.dev/api/health
```

### 3. 测试健康检查
```bash
curl https://curtly-aphorismatic-ginger.ngrok-free.dev/health
```

### 4. 测试登录 API
```bash
curl -X POST https://curtly-aphorismatic-ginger.ngrok-free.dev/api/verification/email/send \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com"}'
```

---

## 📊 配置清单

| 配置项 | 文件位置 | 状态 | 说明 |
|--------|----------|------|------|
| Nginx server_name | `nginx/nginx.conf` | ✅ | 已添加 ngrok 域名 |
| Nginx 端口 | `docker-compose.yml` | ✅ | 80 端口（唯一对外暴露） |
| 前端 API 基础路径 | `frontend/src/api/request.js` | ✅ | 自动适配域名 |
| API 工具函数 | `frontend/src/utils/apiHelper.js` | ✅ | 统一处理 API URL |
| 支付宝通知地址 | `application-dev.properties` | ✅ | 已配置 ngrok URL |
| 支付宝返回地址 | `application-dev.properties` | ✅ | 已配置 ngrok URL |
| 后端 CORS | `SecurityConfig.java` | ✅ | 支持 ngrok 域名模式 |
| Docker 网络 | `docker-compose.yml` | ✅ | app-network bridge |

---

## ⚠️ 重要提醒

### 1. 端口穿透
- ✅ **只穿透 80 端口**（Nginx）
- ❌ **不要穿透 8080 端口**（后端，通过 Nginx 内部访问）
- ❌ **不要穿透 3306 端口**（MySQL，仅在 Docker 网络内访问）

### 2. Ngrok 地址变化
如果 ngrok 地址变化，需要更新：
1. `nginx/nginx.conf` - `server_name` 行
2. `application-dev.properties` - `alipay.notify-url` 和 `alipay.return-url`

### 3. 前端构建
每次修改前端代码后，需要重新构建：
```bash
cd frontend
npm run build
cd ..
```

### 4. Nginx 配置重载
修改 Nginx 配置后：
```bash
# 测试配置
docker exec demo-nginx nginx -t

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

---

## 🔧 故障排查

### 502 Bad Gateway
```bash
# 检查后端服务
docker-compose logs backend
docker-compose restart backend
```

### 404 Not Found
```bash
# 检查前端构建产物
ls frontend/dist

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

### CORS 错误
- 检查后端 CORS 配置是否包含 ngrok 域名
- 检查 Nginx CORS 头设置
- 确认请求使用正确的域名

---

## 📚 相关文档

- [Nginx 反向代理配置指南](./NGINX_REVERSE_PROXY_GUIDE.md)
- [Ngrok 内网穿透配置](./NGINX_INTRANET_TUNNEL.md)
- [Ngrok 部署指南](./NGROK_DEPLOYMENT_GUIDE.md)
- [配置验证报告](./CONFIG_VALIDATION_REPORT.md)

---

## ✅ 最终状态

**所有配置已完成并验证通过！**

可以开始部署：
1. ✅ 构建前端
2. ✅ 启动 Docker 服务
3. ✅ 启动 Ngrok（穿透 80 端口）
4. ✅ 访问应用

---

**配置完成时间**: 2025-11-03  
**Ngrok 地址**: `https://curtly-aphorismatic-ginger.ngrok-free.dev`  
**穿透端口**: `80` (Nginx)