336 lines
6.7 KiB
Markdown
336 lines
6.7 KiB
Markdown
# 上传问题排查指南
|
||
|
||
## 🔍 问题诊断
|
||
|
||
### 错误：`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
|
||
|