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: 构建前端

cd frontend
npm install
npm run build
cd ..

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

步骤 2: 启动 Docker 服务

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

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

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

# 确保指向 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

---

🔍 验证清单

✅ 服务状态检查

# 检查容器状态
docker-compose ps

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

✅ Nginx 配置验证

# 测试 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

✅ 端口检查

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

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

✅ Ngrok 隧道检查

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

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

---

🧪 功能测试

1. 测试前端访问

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

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

2. 测试 API 代理

# 测试 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. 测试健康检查

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

---

⚠️ 常见问题

1. Ngrok 显示 "Tunnel not found"

原因: Ngrok 没有运行或端口错误
解决:

# 检查 ngrok 是否运行
Get-Process -Name ngrok

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

2. 502 Bad Gateway

原因: 后端服务未启动或无法连接
解决:

# 检查后端服务状态
docker-compose logs backend

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

3. 前端页面显示但 API 请求失败

原因: API 代理配置问题
解决:

# 检查 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 配置

# 编辑 nginx/nginx.conf
# 修改 server_name 行：
server_name localhost new-address.ngrok-free.dev;

2. 更新支付宝回调地址

# 编辑 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. 重新加载配置

# 重新加载 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 访问！ 🎉