[!info] related notes

• 所属 MOC: 前端工程化 MOC
• 相关概念: 大文件传输概述, 前端切片与并发控制, 后端状态管理与分块合并, Uppy, tus 协议
• 易混淆概念: 断点续传机制, 秒传机制

大文件传输系统设计

范围

本文串联大文件传输的各个原子概念，解释它们之间的关系、依赖路径和整体架构设计。

为什么要放在一起理解

大文件传输不是单一技术点，而是一个分布式任务协作系统：

• 前端在拆任务和调度任务
• 后端在记录任务和收集任务结果
• 存储在承载任务产物
• 最后再把这些结果组装成一个完整文件

只有理解整体架构，才能做出正确的技术选型和接口设计。

关系与依赖

核心概念依赖路径

[[large-file-upload-overview|大文件传输概述]]
    ├─ 前端侧：[[frontend-file-chunk-upload|前端切片与并发控制]]
    │   ├─ [[frontend-hash-calculation-strategy|前端哈希计算策略]]
    │   └─ [[resumable-upload-mechanism|断点续传机制]]（前端部分）
    │
    ├─ 后端侧：[[backend-upload-state-management|后端状态管理与分块合并]]
    │   ├─ [[instant-upload-mechanism|秒传机制]]
    │   └─ [[file-integrity-verification|完整性校验]]
    │
    ├─ 下载侧：[[large-file-download-range-request|大文件下载与 Range 请求]]
    │
    └─ 工程实践：[[large-file-upload-engineering-challenges|工程难点与最佳实践]]

前后端协作协议

关键约定：

• chunk 编号规则必须统一（从 0 还是 1 开始）
• 重复 chunk 如何处理（幂等性）
• 失败码要有区分（便于前端做不同恢复策略）
• 上传完成的语义要明确（收到 vs 合并校验通过）

典型接口设计

接口	作用
POST /upload/init	创建任务，判断秒传，返回配置
POST /upload/chunk	上传单个 chunk（幂等）
GET /upload/status	查询已上传 chunk 列表
POST /upload/complete	触发合并与校验
POST /upload/cancel	取消任务，清理临时数据

对比与易混淆点

分块上传 vs 断点续传

	分块上传	断点续传
关系	基础能力	在分块基础上的状态恢复
依赖	无	依赖分块上传
目的	解决大文件传输稳定性	解决中断后继续上传

秒传 vs 断点续传

	秒传	断点续传
触发条件	文件 hash 已存在	上传中断后恢复
传输量	0	剩余未上传部分
依赖	hash 去重	状态记录

前端直传 vs 后端中转

	前端直传对象存储	后端中转
带宽压力	分散到存储服务	集中在业务服务
复杂度	需要签名/凭证管理	简单但扩展性差
适用场景	大流量、高并发	小规模、快速实现

落地路径

第一阶段：基础可用

• 分块上传
• 并发控制
• 合并接口
• 上传状态记录

第二阶段：提升稳定性

• 断点续传
• 单 chunk 重试
• 幂等处理
• 临时文件清理

第三阶段：提升体验和性能

• 秒传
• Web Worker 哈希
• 直传对象存储
• 异步合并
• 更精细的进度条

工具选型参考

前端上传框架

• Uppy：模块化、可扩展的 JavaScript 文件上传器，提供现成 UI 和插件系统
  • 适合：需要快速搭建前端上传页面，需要现成 UI 组件
  • 可接：tus、XHR、S3 Multipart 等多种后端

断点续传协议

• tus 协议：基于 HTTP 的可恢复上传开放协议
  • 适合：需要严格的断点续传能力，需要前后端统一协议标准
  • 实现：tus-js-client（JS 客户端）、tusd（Go 服务端）

常见组合

1. Uppy + tus：前端用 Uppy，底层用 tus 协议实现断点续传
2. 单独使用 Uppy：用 XHR 或 S3 Multipart，不需要严格断点续传
3. 单独使用 tus：自己写前端，但用 tus-js-client 实现断点续传

Related notes

• 前端工程化MOC
• 前端基础MOC
• CSS MOC
• ECMAScript MOC