304 lines
6.4 KiB
Markdown
304 lines
6.4 KiB
Markdown
# 上传错误修复总结
|
||
|
||
## 🐛 问题描述
|
||
|
||
**错误信息:** `net::ERR_CONNECTION_RESET`
|
||
|
||
部分用户在上传文件时遇到连接重置错误,导致上传失败。
|
||
|
||
---
|
||
|
||
## ✅ 已实施的修复
|
||
|
||
### 1. **Next.js API Route 配置**
|
||
|
||
**文件:** `app/api/materials/upload/route.ts`
|
||
|
||
添加了请求体大小限制配置:
|
||
```typescript
|
||
// Set maximum request body size for this route (3GB)
|
||
export const maxRequestBodySize = 3 * 1024 * 1024 * 1024 // 3GB in bytes
|
||
```
|
||
|
||
**说明:** Next.js 14+ 的 App Router 需要在路由文件中显式声明最大请求体大小。
|
||
|
||
---
|
||
|
||
### 2. **前端错误处理增强**
|
||
|
||
**文件:** `components/UploadModal.tsx`
|
||
|
||
**改进项:**
|
||
|
||
#### a. 更详细的错误信息
|
||
```typescript
|
||
xhr.addEventListener('error', (e) => {
|
||
console.error('Upload XHR error:', e)
|
||
console.error('XHR status:', xhr.status)
|
||
console.error('XHR readyState:', xhr.readyState)
|
||
|
||
const isConnectionReset = xhr.status === 0
|
||
|
||
if (isConnectionReset) {
|
||
errorMsg = '网络连接中断,可能原因:
|
||
• 文件过大导致服务器重置连接
|
||
• 网络不稳定
|
||
• 服务器配置限制
|
||
|
||
建议:
|
||
1. 检查文件大小(压缩包建议<1GB)
|
||
2. 使用内网地址上传(更快更稳定)
|
||
3. 如果是大文件,尝试压缩后再上传'
|
||
}
|
||
})
|
||
```
|
||
|
||
#### b. HTTP 状态码识别
|
||
```typescript
|
||
xhr.addEventListener('load', () => {
|
||
if (xhr.status === 413) {
|
||
errorMsg = '文件过大,请联系管理员增加上传限制'
|
||
} else if (xhr.status === 408 || xhr.status === 504) {
|
||
errorMsg = '上传超时,建议:...'
|
||
} else if (xhr.status >= 500) {
|
||
errorMsg = `服务器错误 (${xhr.status}):${errorMsg}`
|
||
}
|
||
})
|
||
```
|
||
|
||
#### c. 增强日志输出
|
||
```typescript
|
||
console.log('🚀 上传地址: ${uploadUrl}')
|
||
console.error('Upload XHR error:', e)
|
||
console.error('XHR status:', xhr.status)
|
||
console.error('XHR readyState:', xhr.readyState)
|
||
```
|
||
|
||
---
|
||
|
||
### 3. **Prisma Client 重新生成**
|
||
|
||
运行了 `prisma generate` 和 `prisma db push` 确保:
|
||
- renderer 字段正确添加到 Material 模型
|
||
- zipFileSize 字段正确添加到 Material 模型
|
||
- TypeScript 类型定义更新
|
||
|
||
---
|
||
|
||
## 📋 配置验证清单
|
||
|
||
### ✅ Next.js 配置
|
||
|
||
| 配置项 | 位置 | 值 | 状态 |
|
||
|--------|------|-----|------|
|
||
| Server Actions 限制 | `next.config.js` | 3GB | ✅ |
|
||
| API Route 超时 | `upload/route.ts` | 10800s (3h) | ✅ |
|
||
| API Route 大小限制 | `upload/route.ts` | 3GB | ✅ |
|
||
|
||
### ✅ Nginx 配置
|
||
|
||
| 配置项 | 位置 | 值 | 状态 |
|
||
|--------|------|-----|------|
|
||
| client_max_body_size | nginx config | 0 (无限制) | ✅ |
|
||
| client_body_timeout | nginx config | 10800s | ✅ |
|
||
| proxy_read_timeout | nginx config | 10800s | ✅ |
|
||
| proxy_request_buffering | nginx config | off | ✅ |
|
||
|
||
### ✅ Docker 配置
|
||
|
||
| 配置项 | 值 | 状态 |
|
||
|--------|-----|------|
|
||
| 无特殊限制 | - | ✅ |
|
||
|
||
---
|
||
|
||
## 🔍 诊断工具
|
||
|
||
创建了 `UPLOAD_TROUBLESHOOTING.md` 文档,包含:
|
||
- 详细的问题诊断步骤
|
||
- 配置检查清单
|
||
- 实时诊断命令
|
||
- 常见解决方案
|
||
- 性能基准参考
|
||
|
||
---
|
||
|
||
## 🧪 测试建议
|
||
|
||
### 测试场景 1:小文件上传
|
||
- 预览图:< 1MB
|
||
- 压缩包:< 10MB
|
||
- **预期结果:** 快速成功上传
|
||
|
||
### 测试场景 2:中等文件上传
|
||
- 预览图:5-10MB
|
||
- 压缩包:50-100MB
|
||
- **预期结果:** 成功上传,显示进度条
|
||
|
||
### 测试场景 3:大文件上传
|
||
- 预览图:10-50MB
|
||
- 压缩包:500MB-1GB
|
||
- **预期结果:** 成功上传,可能需要较长时间
|
||
|
||
### 测试场景 4:网络环境
|
||
- **内网测试:** 使用 `http://192.168.58.20:4320`
|
||
- **外网测试:** 使用 `http://180.97.221.140:2320`
|
||
- **预期:** 内网速度明显快于外网
|
||
|
||
---
|
||
|
||
## 📝 用户指导建议
|
||
|
||
### 如果用户遇到上传失败:
|
||
|
||
#### 第一步:检查文件大小
|
||
```
|
||
预览图:建议 < 10MB,最大 50MB
|
||
压缩包:建议 < 500MB,最大 3GB
|
||
```
|
||
|
||
#### 第二步:尝试内网地址
|
||
如果在公司内网,切换到:
|
||
```
|
||
http://192.168.58.20:4320
|
||
```
|
||
|
||
#### 第三步:压缩文件
|
||
使用更高压缩率:
|
||
```bash
|
||
# Windows: 使用 7-Zip
|
||
# 右键 → 7-Zip → 添加到压缩包 → 选择"超级压缩"
|
||
|
||
# Mac/Linux:
|
||
zip -9 -r output.zip folder/
|
||
```
|
||
|
||
#### 第四步:检查网络
|
||
- 使用有线网络替代 WiFi
|
||
- 关闭其他下载任务
|
||
- 检查网络稳定性
|
||
|
||
---
|
||
|
||
## 🚀 后续优化建议
|
||
|
||
### 短期(优先级高)
|
||
1. ✅ 增强错误提示(已完成)
|
||
2. ✅ 添加详细日志(已完成)
|
||
3. ⏳ 监控大文件上传成功率
|
||
4. ⏳ 收集用户反馈
|
||
|
||
### 中期(优先级中)
|
||
1. 实现分块上传(Chunk Upload)
|
||
2. 添加断点续传功能
|
||
3. 实现上传队列管理
|
||
4. 优化图片压缩算法
|
||
|
||
### 长期(优先级低)
|
||
1. 使用 WebSocket 传输大文件
|
||
2. P2P 分布式上传
|
||
3. CDN 加速上传
|
||
4. 智能网络自适应
|
||
|
||
---
|
||
|
||
## 🔄 部署步骤
|
||
|
||
### 开发环境测试
|
||
```bash
|
||
# 1. 安装依赖(如有新增)
|
||
npm install
|
||
|
||
# 2. 重新生成 Prisma Client
|
||
npx prisma generate
|
||
|
||
# 3. 启动开发服务器
|
||
npm run dev
|
||
|
||
# 4. 测试上传功能
|
||
# 访问 http://localhost:3000 并测试上传
|
||
```
|
||
|
||
### 生产环境部署
|
||
```bash
|
||
# 1. 构建新镜像
|
||
docker-compose build
|
||
|
||
# 2. 停止旧容器
|
||
docker-compose down
|
||
|
||
# 3. 启动新容器
|
||
docker-compose up -d
|
||
|
||
# 4. 查看日志
|
||
docker logs -f flnxi-material
|
||
|
||
# 5. 测试上传功能
|
||
# 访问生产地址并测试
|
||
```
|
||
|
||
### Nginx 配置更新(如需要)
|
||
```bash
|
||
# 1. 备份现有配置
|
||
cp /etc/nginx/conf.d/3d-yydd-ai.conf /etc/nginx/conf.d/3d-yydd-ai.conf.backup
|
||
|
||
# 2. 更新配置(已在 setup-nginx-centos.sh 中)
|
||
# 无需手动修改,配置已正确
|
||
|
||
# 3. 测试配置
|
||
nginx -t
|
||
|
||
# 4. 重新加载
|
||
systemctl reload nginx
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 监控指标
|
||
|
||
建议监控以下指标:
|
||
|
||
### 上传成功率
|
||
```
|
||
目标:> 95%
|
||
当前:待监控
|
||
```
|
||
|
||
### 平均上传时间
|
||
```
|
||
小文件 (< 10MB): < 5秒
|
||
中文件 (10-100MB): < 30秒
|
||
大文件 (100MB-1GB): < 300秒
|
||
```
|
||
|
||
### 错误类型分布
|
||
```
|
||
- ERR_CONNECTION_RESET: ?
|
||
- 超时错误: ?
|
||
- 文件过大: ?
|
||
- 其他错误: ?
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 完成检查表
|
||
|
||
- [x] Next.js API Route 大小限制配置
|
||
- [x] 前端错误处理增强
|
||
- [x] Prisma Client 重新生成
|
||
- [x] 创建故障排查文档
|
||
- [x] 创建修复总结文档
|
||
- [ ] 开发环境测试
|
||
- [ ] 生产环境部署
|
||
- [ ] 用户反馈收集
|
||
- [ ] 监控数据分析
|
||
|
||
---
|
||
|
||
**修复日期:** 2025-10-20
|
||
**修复人员:** AI Assistant
|
||
**影响范围:** 文件上传功能
|
||
**风险等级:** 低(只是配置和错误处理改进)
|
||
|
||
|