# 🔌 端口配置说明

## 📊 当前端口映射

### Docker 生产环境

| 服务 | 容器内部端口 | 宿主机端口 | 访问地址 |
|------|------------|-----------|----------|
| **Backend** (NestJS) | 3000 | 3000 | http://localhost:3000 |
| **Frontend** (Nginx) | 80 | 23337 | http://localhost:23337 |

### 本地开发环境

| 服务 | 端口 | 访问地址 |
|------|------|----------|
| **Backend** (NestJS) | 3000 | http://localhost:3000 |
| **Frontend** (Vite) | 5173 | http://localhost:5173 |

---

## 🔧 如何修改端口

### 修改 Docker 端口

编辑 `docker-compose.yml`：

```yaml
services:
  backend:
    ports:
      - "3001:3000"  # 宿主机:容器
  
  frontend:
    ports:
      - "23338:80"   # 宿主机:容器
```

然后重启：
```bash
docker-compose up -d
```

### 修改本地开发端口

**后端**：编辑 `server/.env` 或启动时指定
```bash
PORT=3001 npm run start:dev
```

**前端**：编辑 `client/vite.config.ts`
```typescript
export default defineConfig({
  server: {
    port: 5174,
  },
})
```

---

## ⚠️ 注意事项

### 1. 端口冲突

如果端口被占用，会看到错误：
```
Error: port is already allocated
```

**解决方案**：
- 查看占用端口的进程
  ```bash
  # Windows
  netstat -ano | findstr :23337
  
  # Linux/Mac
  lsof -i :23337
  ```

- 杀死进程或更换端口

### 2. 防火墙设置

确保防火墙允许访问这些端口：

**Windows**：
1. 控制面板 → Windows Defender 防火墙
2. 高级设置 → 入站规则
3. 新建规则 → 允许端口 23337 和 3000

**Linux**：
```bash
sudo ufw allow 23337/tcp
sudo ufw allow 3000/tcp
```

**Mac**：
系统偏好设置 → 安全性与隐私 → 防火墙 → 选项

### 3. CORS 配置

如果修改了前端端口，需要更新后端的 CORS 配置：

编辑 `.env`：
```env
FRONTEND_URL=http://localhost:23338  # 新的前端地址
```

或者在 `server/src/main.ts` 中修改：
```typescript
app.enableCors({
  origin: process.env.FRONTEND_URL || 'http://localhost:23337',
  credentials: true,
});
```

### 4. 前端 API 地址

如果修改了后端端口，需要更新前端的 API 地址：

**Docker 环境**：编辑 `docker-compose.yml`
```yaml
frontend:
  environment:
    - VITE_API_URL=http://localhost:3001/api  # 新的后端地址
```

**本地开发**：编辑 `client/.env`
```env
VITE_API_URL=http://localhost:3001/api
```

---

## 🎯 推荐的端口方案

### 方案 A：默认配置（推荐）

```yaml
backend:  3000 → 3000
frontend: 80   → 23337
```

**优点**：
- ✅ 避免与常见端口冲突
- ✅ 易于记忆（23337 = "爱生生生气" 😄）
- ✅ 远离常用端口（80, 443, 3000, 5173, 8080）

### 方案 B：标准端口

```yaml
backend:  3000 → 3000
frontend: 80   → 80
```

**优点**：
- ✅ 前端使用标准 HTTP 端口
- ❌ 可能与现有 Web 服务器冲突

### 方案 C：开发友好

```yaml
backend:  3000 → 3000
frontend: 5173 → 5173
```

**优点**：
- ✅ 与本地开发端口一致
- ❌ 可能与 Vite 开发服务器冲突

---

## 📝 端口选择建议

### 避免使用的端口

| 端口 | 用途 |
|------|------|
| 80 | HTTP 默认端口 |
| 443 | HTTPS 默认端口 |
| 3000 | Node.js 常用 |
| 5173 | Vite 默认 |
| 8080 | 代理/备用 HTTP |
| 8443 | 备用 HTTPS |
| 3306 | MySQL |
| 5432 | PostgreSQL |
| 6379 | Redis |
| 27017 | MongoDB |

### 推荐的端口范围

- **20000-29999**：应用服务
- **30000-39999**：临时/测试服务

---

## 🔍 检查端口占用

### Windows

```powershell
# 查看所有监听端口
netstat -ano | findstr LISTENING

# 查看特定端口
netstat -ano | findstr :23337

# 查看进程信息
tasklist | findstr <PID>
```

### Linux/Mac

```bash
# 查看所有监听端口
sudo lsof -i -P -n | grep LISTEN

# 查看特定端口
sudo lsof -i :23337

# 或使用 netstat
sudo netstat -tulpn | grep :23337
```

---

## 🆘 常见问题

### Q1: 为什么前端用 23337 而不是 5173？

**A**: 
- 避免与本地 Vite 开发服务器冲突
- 您可以同时运行 Docker 和本地开发环境
- 23337 是一个不太可能被占用的端口

### Q2: 可以前后端都用同一个端口吗？

**A**: 
不可以。它们是两个独立的服务，需要不同的端口。
但可以通过 Nginx 反向代理实现统一入口（需要额外配置）。

### Q3: 如何在局域网访问？

**A**: 
1. 确保防火墙允许访问
2. 使用宿主机的 IP 地址：
   ```
   http://192.168.1.100:23337  # 前端
   http://192.168.1.100:3000   # 后端
   ```
3. 更新 CORS 配置允许局域网访问

### Q4: 端口修改后无法访问怎么办？

**A**: 
1. 检查 Docker 容器是否正常运行：`docker-compose ps`
2. 查看日志：`docker-compose logs`
3. 确认端口映射正确：`docker port <container-name>`
4. 检查防火墙设置
5. 尝试重启：`docker-compose restart`

---

## 📞 需要帮助？

如果遇到端口相关问题：

1. 查看 [USER-GUIDE.md](USER-GUIDE.md)
2. 查看 [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
3. 提交 Issue

---

**祝您配置顺利！** 🎉