gongxiangp2/UPLOAD_TROUBLESHOOTING.md

上传问题排查指南

🔍 问题诊断

错误：net::ERR_CONNECTION_RESET

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

1️⃣ 文件大小超限

• 现象：上传大文件时连接突然中断
• 原因：某个中间层限制了请求体大小
• 解决方案：

  # 检查文件大小
  ls -lh /path/to/your/file
  
  # 建议：
  # - 预览图：< 50MB
  # - 压缩包：< 1GB（理论支持3GB）
  

2️⃣ 网络不稳定

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

3️⃣ 服务器配置问题

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

---

🛠 配置检查清单

✅ Next.js 配置

文件： next.config.js

experimental: {
  serverActions: {
    bodySizeLimit: '3gb', // ✅ 已配置 3GB
  },
}

文件： app/api/materials/upload/route.ts

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

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

检查命令：

# 测试 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 默认无大小限制，但要确保：

# 检查是否有 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 日志：

# 实时查看应用日志
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）：

# 从服务器本地测试上传（小文件）
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 代理：

# 通过 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 配置：

# /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：

nginx -t && systemctl reload nginx

---

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

如果你在公司内网：

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

优点：

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

---

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

对于超大文件（>2GB），考虑实现：

• 分块上传
• 断点续传
• WebSocket 传输

---

方案 4️⃣：压缩文件

上传前先压缩：

# 使用 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 容器：

   docker restart youyidian-3d-material
   

2. 重启 Nginx：

   systemctl restart nginx
   

3. 检查磁盘空间：

   df -h
   # 确保 /app/uploads 有足够空间
   

4. 清理临时文件：

   # 清理旧的上传文件
   find /path/to/uploads -type f -mtime +30 -delete
   

---

📞 获取帮助

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

1. 文件信息：

   • 预览图大小：______
   • 压缩包大小：______
   • 文件格式：______

2. 错误信息：

   • 浏览器控制台错误：
   • 服务器日志错误：

3. 环境信息：

   • 访问地址：内网/外网
   • 浏览器：______
   • 网络类型：WiFi/有线

4. 日志文件：

   # 导出最近的错误日志
   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