AIGC/demo/NGINX_INTRANET_TUNNEL.md

# 🔗 Nginx 内网穿透配置指南

## 📋 概述

使用 Nginx 反向代理后，**只需要穿透一个端口：80端口**

## 🎯 需要穿透的端口

### ✅ 必须穿透的端口

**端口 80** - Nginx 反向代理服务
- 这是唯一需要穿透的端口
- 用户通过此端口访问整个应用（前端 + API）
- Nginx 会自动将 `/api/` 请求代理到后端服务

### ❌ 不需要穿透的端口

- **8080** - 后端服务端口
  - 原因：通过 Nginx 内部代理访问，不需要对外暴露
  - 即使暴露，也建议关闭以提高安全性
  
- **3306** - MySQL 数据库端口
  - 原因：仅在 Docker 网络内部使用
  - 安全建议：永远不要对外暴露数据库端口

---

## 🔧 内网穿透工具配置

### 方式一：使用 ngrok（推荐）

#### 1. 安装 ngrok
```bash
# 下载 ngrok
# https://ngrok.com/download

# Windows: 下载 exe 文件
# Linux/Mac: 
wget https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.tgz
tar -xzf ngrok-v3-stable-linux-amd64.tgz
```

#### 2. 启动 ngrok 穿透 80 端口
```bash
ngrok http 80
```

#### 3. 获取穿透地址
ngrok 会输出类似：
```
Forwarding   https://xxxxx.ngrok-free.app -> http://localhost:80
```

#### 4. 配置 Nginx（如果需要自定义域名）

修改 `nginx/nginx.conf`：
```nginx
server {
    listen 80;
    server_name xxxxx.ngrok-free.app;  # ngrok 分配的域名
    # ... 其他配置
}
```

---

### 方式二：使用 frp（Fast Reverse Proxy）

#### 1. 服务器端配置（frps.ini）
```ini
[common]
bind_port = 7000

# 如果使用自定义域名
subdomain_host = yourdomain.com
```

#### 2. 客户端配置（frpc.ini）
```ini
[common]
server_addr = your-server-ip
server_port = 7000

[web]
type = http
local_ip = 127.0.0.1
local_port = 80
custom_domains = your-domain.com
# 或者使用子域名
# subdomain = aigc
```

#### 3. 启动 frp 客户端
```bash
frpc -c frpc.ini
```

---

### 方式三：使用 NPS（Nginx Proxy Server）

#### 1. 服务器端配置
```json
{
  "tcp": [
    {
      "port": 80,
      "target": "your-local-ip:80"
    }
  ]
}
```

#### 2. 客户端连接服务器
```bash
npc -server=server-ip:port -vkey=your-key
```

---

## 🔐 安全建议

### 1. 只暴露必要的端口
```yaml
# docker-compose.yml
# ✅ 保留（需要穿透）
nginx:
  ports:
    - "80:80"

# ❌ 建议移除（提高安全性）
backend:
  # ports:
  #   - "8080:8080"  # 注释掉，不对外暴露

mysql:
  # ports:
  #   - "3306:3306"  # 注释掉，不对外暴露
```

### 2. 配置 HTTPS（推荐）

#### 使用 ngrok（自动HTTPS）
```bash
# ngrok 自动提供 HTTPS
ngrok http 80
```

#### 使用 Nginx + Let's Encrypt
```nginx
server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    # ... 其他配置
}
```

---

## 📝 配置示例

### 完整的 docker-compose.yml（优化版 - 只暴露80端口）

```yaml
services:
  mysql:
    image: mysql:8.0
    # 移除 ports，不对外暴露
    # ports:
    #   - "3306:3306"
    networks:
      - app-network

  backend:
    build:
      context: .
      dockerfile: Dockerfile.backend
    # 移除 ports，通过 Nginx 内部访问
    # ports:
    #   - "8080:8080"
    networks:
      - app-network

  nginx:
    build:
      context: ./nginx
      dockerfile: Dockerfile
    ports:
      - "80:80"  # ✅ 唯一需要穿透的端口
    networks:
      - app-network
```

---

## 🧪 测试内网穿透

### 1. 启动服务
```bash
docker-compose up -d
```

### 2. 启动内网穿透工具
```bash
# 使用 ngrok
ngrok http 80

# 或使用 frp
frpc -c frpc.ini
```

### 3. 访问测试
```bash
# 使用穿透地址访问
curl https://xxxxx.ngrok-free.app/health

# 测试 API
curl https://xxxxx.ngrok-free.app/api/health
```

---

## 📊 端口使用总结

| 服务 | 端口 | 是否需要穿透 | 说明 |
|------|------|-------------|------|
| Nginx | 80 | ✅ **是** | 唯一需要穿透的端口 |
| Backend | 8080 | ❌ 否 | 通过 Nginx 内部访问 |
| MySQL | 3306 | ❌ 否 | 仅在 Docker 网络内访问 |

---

## 🚀 快速开始

### 使用 ngrok（最简单）

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

# 2. 启动 ngrok
ngrok http 80

# 3. 复制 ngrok 提供的 HTTPS 地址
# 例如: https://xxxxx.ngrok-free.app

# 4. 在浏览器中访问该地址
```

---

## 💡 常见问题

### Q: 为什么不需要穿透 8080 端口？
A: 因为 Nginx 已经配置了反向代理，所有 `/api/` 请求都会自动转发到后端服务，用户只需要访问 Nginx 的 80 端口即可。

### Q: 如果需要直接访问后端 API 怎么办？
A: 如果确实需要直接访问，可以在 docker-compose.yml 中保留 8080 端口的映射，但不推荐。

### Q: ngrok 的地址会变吗？
A: 免费版 ngrok 每次启动地址都会变化。可以：
- 使用付费版获得固定域名
- 使用其他工具如 frp 配置自定义域名

---

## 📚 相关文档

- [ngrok 官方文档](https://ngrok.com/docs)
- [frp 官方文档](https://gofrp.org/docs/)
- [Nginx 反向代理指南](./NGINX_REVERSE_PROXY_GUIDE.md)

---

**总结：只需要穿透 80 端口即可！** ✅