awd-platform @夜莫离 模版网盘上传大文件失败如何解决？

Question

在使用 awd-platform @夜莫离 模版网盘上传大文件（如 >500MB）时，常见失败原因包括：① 前端未启用分片上传逻辑，导致单次请求超时或被 Nginx/CDN 限流（默认 client_max_body_size=1M）；② 后端未正确配置 multipart 文件解析超时与内存缓冲区（如 Spring Boot 的 `spring.servlet.multipart.max-file-size` 未调大）；③ 缺少断点续传支持，网络抖动即全量重传；④ 浏览器端未处理 `AbortError` 或 `NetworkError`，UI 无重试机制。此外，若模版基于旧版 WebUploader 或自研上传组件，可能未适配现代浏览器的 Blob API 与 Fetch + ReadableStream 流式上传。建议统一升级至支持分片、秒传、校验（MD5/SHA256）、后台任务队列（如 Celery/RabbitMQ）的上传模块，并在 Nginx 层显式配置 `client_max_body_size 2G; proxy_read_timeout 3600;`。排查时优先检查浏览器 Network 面板中预检（OPTIONS）是否 403、POST 是否 413/504，再比对前后端日志中的 uploadId 与分片序号一致性。

Answer 1

```html

一、现象层：上传失败的典型表征与可观测信号

用户在 awd-platform @夜莫离 模板网盘中上传 >500MB 文件时，常见终端反馈为「上传中断」「进度卡死」「报错 413 Request Entity Too Large」或「Network Error」。浏览器 DevTools 的 Network 面板 是首要诊断入口：预检请求（OPTIONS）返回 403 Forbidden 暗示 CORS 或 Nginx 限流；主上传 POST 请求出现 413（体过大）、504 Gateway Timeout（反向代理超时）或 0 status（连接重置），均指向基础设施层配置缺陷。

二、链路层：端到端上传流程的四段式阻塞点分析

阶段	关键组件	典型故障表现	根因归类
① 浏览器侧	Blob API / Fetch + ReadableStream	大文件 File.slice() 崩溃、AbortError 未捕获、UI 无重试按钮	前端逻辑缺失
② 网关层	Nginx / CDN	client_max_body_size=1M 默认值触发 413；proxy_read_timeout=60s 导致长连接中断	基础设施硬限制
③ 应用层	Spring Boot + MultipartResolver	MaxUploadSizeExceededException、OOM GC 频繁、分片合并耗时 >10min	后端配置与架构缺陷
④ 存储层	OSS/S3/本地磁盘	秒传校验失败、MD5 不一致、分片文件残留未清理	业务逻辑鲁棒性不足

三、配置层：Nginx 与 Spring Boot 的黄金参数矩阵

以下为生产环境强推荐配置（需同步生效）：

# Nginx.conf 全局段（非 location 内）
client_max_body_size 2G;
client_header_timeout 300;
client_body_timeout 3600;
proxy_connect_timeout 3600;
proxy_send_timeout 3600;
proxy_read_timeout 3600;
send_timeout 3600;

# Spring Boot application.yml
spring:
  servlet:
    multipart:
      max-file-size: 2GB
      max-request-size: 2GB
      file-size-threshold: 16MB  # 触发磁盘缓冲阈值
  web:
    resources:
      cache:
        period: 0

四、架构层：从单体上传到云原生上传服务演进路径

graph LR A[前端分片] --> B{是否已存在同MD5文件？} B -->|是| C[秒传：直接注册元数据] B -->|否| D[并发上传分片
含SHA256校验] D --> E[后端接收分片并落盘/OSS临时区] E --> F[异步任务队列 Celery/RabbitMQ] F --> G[分片合并+完整性校验+持久化] G --> H[通知前端完成+清理临时分片]

五、工程层：可落地的升级实施清单

1. 前端替换 WebUploader → 基于 axios + ReadableStream 的自研分片 SDK（支持 pause/resume/retry）
2. 引入 spark-md5 或 Web Crypto API 实现浏览器端秒传哈希计算（规避 Base64 传输开销）
3. 后端新增 /api/v2/upload/init 接口生成唯一 uploadId，绑定用户会话与分片策略
4. 所有分片请求携带 X-Upload-ID 与 X-Part-Number Header，便于日志追踪与幂等控制
5. Nginx 开启 underscores_in_headers on; 支持下划线命名 Header 透传
6. 增加 Prometheus 指标：upload_duration_seconds_bucket、upload_failure_total{reason}

六、排查层：标准化故障定位 SOP（含日志交叉验证）

执行以下三步交叉比对：

1. 前端日志：提取某次失败上传的 uploadId = "up_abc123" 及其最后成功分片序号 part=17
2. Nginx access.log：过滤 up_abc123，确认是否存在 413 或 504 对应行，并检查 $request_time 是否超 3600s
3. Spring Boot trace.log：搜索 uploadId=up_abc123，验证后端是否收到 part=18 请求、是否有 OutOfMemoryError 或 RejectedExecutionException

```