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

大文件上传优化指南

问题分析

用户反馈大文件上传时容易出现以下问题：

1. 上传中途卡住
2. 网络中断后重新上传
3. 上传速度不稳定
4. 偶尔出现连接错误

优化措施

1. 降低并发上传数

原因： 并发过多会导致：

• 服务器压力过大
• 网络连接数过多
• 容易触发限流

优化：

// 从 3 个并发降低到 2 个
CONCURRENT_UPLOADS = 2

2. 增加超时时间

原因：

• 大文件分片上传时间较长
• 网络波动可能导致临时变慢

优化：

// 从 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. 提高分片上传阈值

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

优化：

// 从 5MB 提高到 10MB
shouldUseChunkUpload: fileSize > 10MB

6. 增强日志输出

新增日志：

• 批次进度提示
• 详细的重试信息
• 上传速度统计
• 错误详情

使用建议

网络较差环境

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

1. 调整并发数为 1

   // client/src/utils/chunkUpload.ts
   private static readonly CONCURRENT_UPLOADS = 1
   

2. 增加分片大小

   private static readonly DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024 // 5MB
   

3. 增加超时时间

   private static readonly CHUNK_UPLOAD_TIMEOUT = 300000 // 5分钟
   

网络良好环境

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

1. 增加并发数

   private static readonly CONCURRENT_UPLOADS = 4
   

2. 减小分片大小

   private static readonly DEFAULT_CHUNK_SIZE = 1 * 1024 * 1024 // 1MB
   

3. 降低重试次数

   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. 服务器重启后需要重新上传

监控和调试

查看上传日志

浏览器控制台：

// 查看详细的上传进度
// 打开开发者工具 -> Console
// 会显示：
// - 分片计算信息
// - 批次上传进度
// - 重试详情
// - 上传速度

服务端日志：

# 查看上传相关日志
tail -f server/logs/app.log | grep -i upload

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

性能指标

建议的性能指标：

• 上传速度： > 1 MB/s
• 成功率： > 95%
• 重试率： < 10%
• 平均耗时： < 文件大小(MB) 秒

高级配置

自适应并发控制

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

// 检测网络质量
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 // 网络较差
}

智能重试

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

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