AIGC/demo/NGROK_DEPLOYMENT_GUIDE.md

# 🚀 Ngrok 内网穿透部署完整指南

## 📋 当前配置

**Ngrok 穿透地址**: `https://curtly-aphorismatic-ginger.ngrok-free.dev`  
**穿透端口**: `80` (Nginx)

## ✅ 已完成的配置

### 1. Nginx 反向代理配置 ✅
- ✅ `server_name` 已配置支持 ngrok 域名
- ✅ 前端静态文件服务
- ✅ API 代理到后端（`/api/` → `backend:8080`）
- ✅ CORS 配置已优化

### 2. 前端 API 自动适配 ✅
- ✅ 自动检测当前访问域名
- ✅ 通过 ngrok 访问：使用相对路径 `/api`
- ✅ 本地开发：使用 `http://localhost:8080/api`

### 3. 支付宝回调地址 ✅
- ✅ 通知地址：`https://curtly-aphorismatic-ginger.ngrok-free.dev/api/payments/alipay/notify`
- ✅ 返回地址：`https://curtly-aphorismatic-ginger.ngrok-free.dev/api/payments/alipay/return`

### 4. 后端 CORS 配置 ✅
- ✅ 支持 `*.ngrok-free.app` 域名模式
- ✅ 支持所有 ngrok 子域名

---

## 🚀 部署步骤

### 步骤 1: 构建前端

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

**重要**: 确保 `frontend/dist` 目录存在且包含构建产物。

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

```bash
# 启动所有服务（MySQL、后端、Nginx）
docker-compose up -d --build

# 查看服务状态
docker-compose ps

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

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

```bash
# 确保指向 Nginx 的 80 端口
ngrok http 80
```

**关键提示**:
- ✅ 正确：`ngrok http 80`（Nginx 端口）
- ❌ 错误：`ngrok http 8080`（后端端口，不需要）

### 步骤 4: 验证访问

访问 `https://curtly-aphorismatic-ginger.ngrok-free.dev` 测试：

1. **前端页面**: 应能正常加载
2. **API 请求**: 应能正常响应（通过 `/api/` 路径）
3. **健康检查**: `https://curtly-aphorismatic-ginger.ngrok-free.dev/health`

---

## 🔍 验证清单

### ✅ 服务状态检查

```bash
# 检查容器状态
docker-compose ps

# 应该看到：
# - demo-mysql (running)
# - demo-backend (running)
# - demo-nginx (running)
```

### ✅ Nginx 配置验证

```bash
# 测试 Nginx 配置语法
docker exec demo-nginx nginx -t

# 应该输出：
# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful
```

### ✅ 端口检查

```bash
# 检查 80 端口是否被 Nginx 监听
netstat -an | findstr :80

# 或使用 PowerShell
Get-NetTCPConnection -LocalPort 80 -ErrorAction SilentlyContinue
```

### ✅ Ngrok 隧道检查

```bash
# 检查 ngrok 进程
Get-Process -Name ngrok -ErrorAction SilentlyContinue

# 访问 ngrok 控制面板
# 浏览器打开: http://127.0.0.1:4040
```

---

## 🧪 功能测试

### 1. 测试前端访问

```bash
# 在浏览器中访问
https://curtly-aphorismatic-ginger.ngrok-free.dev

# 或使用 curl
curl https://curtly-aphorismatic-ginger.ngrok-free.dev/
```

### 2. 测试 API 代理

```bash
# 测试 API 请求（应该通过 Nginx 代理到后端）
curl https://curtly-aphorismatic-ginger.ngrok-free.dev/api/health

# 测试登录 API
curl -X POST https://curtly-aphorismatic-ginger.ngrok-free.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"test"}'
```

### 3. 测试健康检查

```bash
curl https://curtly-aphorismatic-ginger.ngrok-free.dev/health
```

---

## ⚠️ 常见问题

### 1. Ngrok 显示 "Tunnel not found"
**原因**: Ngrok 没有运行或端口错误  
**解决**: 
```bash
# 检查 ngrok 是否运行
Get-Process -Name ngrok

# 确保穿透的是 80 端口
ngrok http 80
```

### 2. 502 Bad Gateway
**原因**: 后端服务未启动或无法连接  
**解决**:
```bash
# 检查后端服务状态
docker-compose logs backend

# 重启后端服务
docker-compose restart backend
```

### 3. 前端页面显示但 API 请求失败
**原因**: API 代理配置问题  
**解决**:
```bash
# 检查 Nginx 配置
docker exec demo-nginx nginx -t

# 检查 Nginx 日志
docker-compose logs nginx

# 确认前端使用的是相对路径 /api，而不是绝对路径
```

### 4. CORS 错误
**原因**: CORS 配置问题  
**解决**:
- 检查后端 CORS 配置是否包含 ngrok 域名模式
- 检查 Nginx CORS 头设置
- 确认请求使用正确的域名（ngrok 地址）

---

## 📊 请求流程图

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

---

## 🔄 如果 Ngrok 地址变化

如果 ngrok 地址变为 `https://new-address.ngrok-free.dev`：

### 1. 更新 Nginx 配置
```bash
# 编辑 nginx/nginx.conf
# 修改 server_name 行：
server_name localhost new-address.ngrok-free.dev;
```

### 2. 更新支付宝回调地址
```bash
# 编辑 src/main/resources/application-dev.properties
alipay.notify-url=https://new-address.ngrok-free.dev/api/payments/alipay/notify
alipay.return-url=https://new-address.ngrok-free.dev/api/payments/alipay/return
```

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

# 或重启服务
docker-compose restart nginx backend
```

---

## 📝 当前配置状态

| 组件 | 配置项 | 状态 | 值 |
|------|--------|------|-----|
| Nginx | server_name | ✅ | localhost, curtly-aphorismatic-ginger.ngrok-free.dev |
| Nginx | 监听端口 | ✅ | 80 |
| Nginx | API 代理 | ✅ | /api/ → backend:8080 |
| 前端 | API baseURL | ✅ | 自动检测（/api 或 http://localhost:8080/api） |
| 后端 | CORS origins | ✅ | *.ngrok-free.app |
| 支付宝 | notify-url | ✅ | https://curtly-aphorismatic-ginger.ngrok-free.dev/api/payments/alipay/notify |
| 支付宝 | return-url | ✅ | https://curtly-aphorismatic-ginger.ngrok-free.dev/api/payments/alipay/return |
| Ngrok | 穿透端口 | ✅ | 80 (Nginx) |

---

## 🎯 下一步操作

1. ✅ **构建前端**: `cd frontend && npm run build`
2. ✅ **启动服务**: `docker-compose up -d --build`
3. ✅ **启动 Ngrok**: `ngrok http 80`
4. ✅ **测试访问**: 浏览器打开 `https://curtly-aphorismatic-ginger.ngrok-free.dev`

---

**配置已完成！所有服务已准备好通过 ngrok 访问！** 🎉