GameServerManager/docs/大文件上传优化指南.md

# 大文件上传优化指南

## 问题分析

用户反馈大文件上传时容易出现以下问题：
1. 上传中途卡住
2. 网络中断后重新上传
3. 上传速度不稳定
4. 偶尔出现连接错误

## 优化措施

### 1. 降低并发上传数

**原因：** 并发过多会导致：
- 服务器压力过大
- 网络连接数过多
- 容易触发限流

**优化：**
```typescript
// 从 3 个并发降低到 2 个
CONCURRENT_UPLOADS = 2
```

### 2. 增加超时时间

**原因：** 
- 大文件分片上传时间较长
- 网络波动可能导致临时变慢

**优化：**
```typescript
// 从 60秒 增加到 120秒（2分钟）
CHUNK_UPLOAD_TIMEOUT = 120000
```

### 3. 优化重试策略

**改进点：**
- 增加重试次数：3次 → 5次
- 增加重试延迟：使用指数退避 + 随机抖动
- 添加详细的重试日志

**重试时间表：**
| 重试次数 | 延迟时间 | 说明 |
|---------|---------|------|
| 第1次 | 2-3秒 | 基础延迟 + 随机抖动 |
| 第2次 | 4-5秒 | 延迟翻倍 |
| 第3次 | 8-9秒 | 继续翻倍 |
| 第4次 | 16-17秒 | 继续增长 |
| 第5次 | 30秒 | 最大延迟 |

### 4. 添加批次间延迟

**目的：** 避免请求过快导致服务器压力

**实现：**
- 每个批次之间延迟 200ms
- 每上传10个分片休息 100ms

### 5. 提高分片上传阈值

**原因：** 小文件使用普通上传更快

**优化：**
```typescript
// 从 5MB 提高到 10MB
shouldUseChunkUpload: fileSize > 10MB
```

### 6. 增强日志输出

**新增日志：**
- 批次进度提示
- 详细的重试信息
- 上传速度统计
- 错误详情

## 使用建议

### 网络较差环境

如果您的网络环境较差，建议：

1. **调整并发数为 1**
   ```typescript
   // client/src/utils/chunkUpload.ts
   private static readonly CONCURRENT_UPLOADS = 1
   ```

2. **增加分片大小**
   ```typescript
   private static readonly DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024 // 5MB
   ```

3. **增加超时时间**
   ```typescript
   private static readonly CHUNK_UPLOAD_TIMEOUT = 300000 // 5分钟
   ```

### 网络良好环境

如果您的网络环境很好，可以：

1. **增加并发数**
   ```typescript
   private static readonly CONCURRENT_UPLOADS = 4
   ```

2. **减小分片大小**
   ```typescript
   private static readonly DEFAULT_CHUNK_SIZE = 1 * 1024 * 1024 // 1MB
   ```

3. **降低重试次数**
   ```typescript
   private static readonly MAX_RETRIES = 3
   ```

## 故障排查

### 问题1: 频繁出现 "ECONNREFUSED" 错误

**原因：** 
- 服务器负载过高
- 并发数过多
- 防火墙限制

**解决方法：**
1. 降低并发数到 1
2. 检查服务器资源使用情况
3. 检查防火墙/安全组设置

### 问题2: 上传速度很慢

**原因：**
- 网络带宽限制
- 服务器上行带宽不足
- 分片过小导致请求频繁

**解决方法：**
1. 增加分片大小到 5MB 或更大
2. 检查网络带宽
3. 优化服务器配置

### 问题3: 上传中途卡住

**原因：**
- 超时时间不够
- 网络不稳定
- 浏览器内存不足

**解决方法：**
1. 增加超时时间到 5分钟
2. 使用稳定的网络环境
3. 关闭不必要的浏览器标签

### 问题4: 断点续传不工作

**原因：**
- 上传会话过期（超过24小时）
- 服务器重启

**解决方法：**
1. 在24小时内完成上传
2. 服务器重启后需要重新上传

## 监控和调试

### 查看上传日志

**浏览器控制台：**
```javascript
// 查看详细的上传进度
// 打开开发者工具 -> Console
// 会显示：
// - 分片计算信息
// - 批次上传进度
// - 重试详情
// - 上传速度
```

**服务端日志：**
```bash
# 查看上传相关日志
tail -f server/logs/app.log | grep -i upload

# 查看错误日志
tail -f server/logs/error.log
```

### 性能指标

建议的性能指标：
- **上传速度：** > 1 MB/s
- **成功率：** > 95%
- **重试率：** < 10%
- **平均耗时：** < 文件大小(MB) 秒

## 高级配置

### 自适应并发控制

可以根据网络质量动态调整并发数：

```typescript
// 检测网络质量
async function detectNetworkQuality() {
  // 测试上传小文件
  const start = Date.now()
  await uploadTestChunk()
  const duration = Date.now() - start
  
  // 根据速度调整并发
  if (duration < 1000) return 4 // 网络很好
  if (duration < 3000) return 2 // 网络一般
  return 1 // 网络较差
}
```

### 智能重试

根据错误类型调整重试策略：

```typescript
function getRetryDelay(error: Error, attempt: number) {
  // 网络错误：快速重试
  if (error.message.includes('network')) {
    return 1000 * attempt
  }
  
  // 服务器错误：慢速重试
  if (error.message.includes('500')) {
    return 5000 * attempt
  }
  
  // 默认：指数退避
  return 2000 * Math.pow(2, attempt)
}
```

## 最佳实践

1. **文件大小限制**
   - 建议单个文件不超过 5GB
   - 超大文件建议使用专业上传工具

2. **网络要求**
   - 稳定的网络连接
   - 建议使用有线网络
   - 避免在弱网环境上传大文件

3. **浏览器要求**
   - 使用最新版本的现代浏览器
   - 保持浏览器标签页不被关闭
   - 避免浏览器休眠

4. **服务器配置**
   - 确保足够的磁盘空间
   - 配置合理的并发限制
   - 定期清理临时文件

## 更新日志

### v1.1.0 (2025-01-04)

**优化：**
- 🔧 降低并发数：3 → 2
- ⏱️ 增加超时：60秒 → 120秒
- 🔄 优化重试：3次 → 5次
- 📊 增强日志输出
- 🎯 提高分片阈值：5MB → 10MB
- ⚡ 添加批次间延迟
- 🎲 添加重试随机抖动

**修复：**
- 🐛 修复频繁连接错误
- 🐛 修复上传卡顿问题
- 🐛 优化网络中断恢复

---

**文档更新时间：** 2025-01-04