# 上传问题排查指南

## 🔍 问题诊断

### 错误：`net::ERR_CONNECTION_RESET`

这个错误表示连接在上传过程中被重置，常见原因：

#### 1️⃣ **文件大小超限**
- **现象**：上传大文件时连接突然中断
- **原因**：某个中间层限制了请求体大小
- **解决方案**：
  ```bash
  # 检查文件大小
  ls -lh /path/to/your/file
  
  # 建议：
  # - 预览图：< 50MB
  # - 压缩包：< 1GB（理论支持3GB）
  ```

#### 2️⃣ **网络不稳定**
- **现象**：上传进度不稳定，时快时慢，最终失败
- **原因**：网络波动导致连接中断
- **解决方案**：
  - 使用内网地址上传（如果在内网）
  - 检查网络连接质量
  - 尝试有线网络替代 WiFi

#### 3️⃣ **服务器配置问题**
- **现象**：所有用户都无法上传，或特定大小文件失败
- **原因**：服务器端配置限制
- **排查步骤**：见下方"服务器配置检查"

---

## 🛠 配置检查清单

### ✅ Next.js 配置

**文件：** `next.config.js`
```javascript
experimental: {
  serverActions: {
    bodySizeLimit: '3gb', // ✅ 已配置 3GB
  },
}
```

**文件：** `app/api/materials/upload/route.ts`
```typescript
export const maxDuration = 10800 // ✅ 3小时超时
export const maxRequestBodySize = 3 * 1024 * 1024 * 1024 // ✅ 3GB
```

---

### ✅ Nginx 配置（如果使用反向代理）

**位置：** `/etc/nginx/conf.d/3d-yydd-ai.conf` 或 `/etc/nginx/sites-available/3d.yydd.ai`

```nginx
# 必须配置的项目：
client_max_body_size 0;  # ✅ 无限制
client_body_timeout 10800s;  # ✅ 3小时
proxy_read_timeout 10800s;  # ✅ 3小时
proxy_request_buffering off;  # ✅ 关键！禁用缓冲
```

**检查命令：**
```bash
# 测试 Nginx 配置
nginx -t

# 重新加载配置
systemctl reload nginx

# 查看 Nginx 错误日志
tail -f /var/log/nginx/3d-yydd-error.log
```

---

### ✅ Docker 配置

**文件：** `docker-compose.yml`

无需特殊配置，Docker 默认不限制。

---

### ✅ FRP 内网穿透

**文件：** `frpc.toml`

FRP 默认无大小限制，但要确保：
```toml
# 检查是否有 max_pool_count 或其他限制
```

---

## 🔬 实时诊断步骤

### 第一步：检查前端控制台

1. **打开浏览器开发者工具** (F12)
2. **切换到 Console 标签**
3. **尝试上传文件**
4. **查看日志输出**

期望看到的日志：
```
🚀 上传地址: /api/materials/upload
[Upload] Starting upload process...
[Upload] Session checked: true
[Upload] Parsing form data...
```

如果看到错误，记录完整的错误信息。

---

### 第二步：检查服务器日志

**Docker 日志：**
```bash
# 实时查看应用日志
docker logs -f youyidian-3d-material

# 查看最近100行
docker logs --tail 100 youyidian-3d-material
```

**期望看到的日志：**
```
[Upload] Starting upload process...
[Upload] Session checked: true
[Upload] Parsing form data...
[Upload] Form data received: { hasPreviewImage: true, zipFileSize: xxx }
[Upload] Image processed successfully
[Upload] Upload completed successfully!
```

**如果失败，查找错误关键字：**
- `Error:`
- `Failed`
- `timeout`
- `ECONNRESET`

---

### 第三步：网络层诊断

**测试直连（绕过 Nginx）：**
```bash
# 从服务器本地测试上传（小文件）
curl -X POST http://localhost:4320/api/materials/upload \
  -F "previewImage=@test.jpg" \
  -F "zipFile=@test.zip" \
  -F "productModel=TEST-001" \
  -F "categoryName=测试" \
  -F "sceneName=测试场景" \
  -F "renderer=CR" \
  -H "Cookie: your-session-cookie"
```

**测试 Nginx 代理：**
```bash
# 通过 Nginx 测试
curl -X POST http://localhost/api/materials/upload \
  -F "previewImage=@test.jpg" \
  -F "zipFile=@test.zip" \
  -F "productModel=TEST-001" \
  -F "categoryName=测试" \
  -F "sceneName=测试场景" \
  -F "renderer=CR" \
  -H "Cookie: your-session-cookie"
```

---

## 💡 常见解决方案

### 方案 1️⃣：增大 Nginx 缓冲区（如果使用 Nginx）

编辑 Nginx 配置：
```nginx
# /etc/nginx/conf.d/3d-yydd-ai.conf

http {
    # 增加缓冲区
    client_body_buffer_size 256k;
    client_header_buffer_size 8k;
    large_client_header_buffers 8 32k;
}

server {
    location /api/materials/upload {
        # 完全关闭缓冲
        proxy_request_buffering off;
        proxy_buffering off;
        
        # 无限制
        client_max_body_size 0;
        
        # 超长超时
        client_body_timeout 10800s;
        proxy_read_timeout 10800s;
        proxy_send_timeout 10800s;
    }
}
```

重启 Nginx：
```bash
nginx -t && systemctl reload nginx
```

---

### 方案 2️⃣：使用内网地址上传

如果你在公司内网：
1. 打开网站后，顶部会显示内网地址提示
2. 点击提示切换到 `http://192.168.58.20:4320`
3. 内网上传速度更快、更稳定

**优点：**
- 绕过 FRP 穿透
- 绕过外网 Nginx
- 直连 Docker 容器
- 速度提升 10-100 倍

---

### 方案 3️⃣：分块上传（未来优化）

对于超大文件（>2GB），考虑实现：
- 分块上传
- 断点续传
- WebSocket 传输

---

### 方案 4️⃣：压缩文件

上传前先压缩：
```bash
# 使用 7z 最大压缩
7z a -t7z -mx=9 output.7z input_folder/

# 使用 zip 压缩
zip -r -9 output.zip input_folder/
```

---

## 📊 性能基准

### 预期上传速度

| 网络环境 | 速度 | 1GB 文件耗时 |
|---------|------|-------------|
| 内网直连 | 100-300 MB/s | 3-10秒 |
| 内网穿透 | 10-50 MB/s | 20-100秒 |
| 公网上传 | 1-10 MB/s | 100-1000秒 |

### 文件大小建议

| 文件类型 | 推荐大小 | 最大支持 |
|---------|---------|---------|
| 预览图 | < 10MB | 50MB |
| 压缩包 | < 500MB | 3GB |

---

## 🚨 紧急恢复步骤

### 如果完全无法上传：

1. **重启 Docker 容器：**
   ```bash
   docker restart youyidian-3d-material
   ```

2. **重启 Nginx：**
   ```bash
   systemctl restart nginx
   ```

3. **检查磁盘空间：**
   ```bash
   df -h
   # 确保 /app/uploads 有足够空间
   ```

4. **清理临时文件：**
   ```bash
   # 清理旧的上传文件
   find /path/to/uploads -type f -mtime +30 -delete
   ```

---

## 📞 获取帮助

如果以上方案都无法解决问题，请收集以下信息：

1. **文件信息：**
   - 预览图大小：______
   - 压缩包大小：______
   - 文件格式：______

2. **错误信息：**
   - 浏览器控制台错误：
   - 服务器日志错误：

3. **环境信息：**
   - 访问地址：内网/外网
   - 浏览器：______
   - 网络类型：WiFi/有线

4. **日志文件：**
   ```bash
   # 导出最近的错误日志
   docker logs --tail 500 youyidian-3d-material > upload-error.log
   tail -n 500 /var/log/nginx/3d-yydd-error.log > nginx-error.log
   ```

---

**最后更新：** 2025-10-20  
**版本：** v1.0