工程难点与最佳实践
大文件传输系统的工程难点：网关限制、临时文件清理、多实例部署、异步合并
#type / concept
#status / evergreen
#tech / dev / frontend
#tech / dev / backend
[!info] related notes
工程难点与最佳实践
一句话定义
大文件传输系统的成熟度体现在幂等、可恢复、可校验、可观测、可清理、可扩展、安全这七个能力维度。
核心内容
常见工程难点
1. Nginx/网关限制
即使用了 chunk 上传，也可能被限制：
client_max_body_size- 请求超时
- 代理读写超时
解决：后端上传链路必须检查网关层配置。
2. 临时 chunk 清理
用户传到一半不传了，chunk 会堆积。
解决：
- 超过 24 小时未完成的 upload_task 标为过期
- 删除对应 chunk
- 回收存储空间
3. 多实例部署状态一致性
后端有多个实例时：
- chunk 可能落到不同机器
- 合并任务不一定在同一台机器执行
解决：
- 用共享存储或统一写对象存储
- 状态放数据库/Redis
4. 合并耗时长
几十 GB 文件合并可能要很久。
解决：把”合并”做成异步任务：
- 前端调用 complete
- 后端只做参数校验并投递任务
- 异步 worker 执行合并
- 前端轮询状态
设计原则
| 原则 | 说明 |
|---|---|
| 前端一定分块 | 不要硬传整文件 |
| 后端一定有 uploadId 和状态表 | 否则无法做续传、重试、合并管理 |
| chunk 接口一定幂等 | 否则重试会把系统搞乱 |
| 最终结果一定做完整性校验 | 不能只相信”所有 chunk 都上传完了” |
| 大流量场景优先直传对象存储 | 不要让业务服务器做大文件搬运工 |
| 进度条不能只看上传字节 | 还要包含服务端处理状态 |
| 临时数据必须有回收机制 | 否则磁盘迟早爆 |
成熟系统的能力维度
- 幂等：chunk 重传不乱
- 可恢复：断了能续
- 可校验：知道文件没坏
- 可观测：能看到失败在哪一块、哪一步
- 可清理：失败任务不会堆垃圾
- 可扩展：业务服务不会因为上传流量被拖死
- 安全：只有有权限的人能上传、下载、查看
边界与易混淆点
- 前端 vs 后端职责边界：前端负责”拆开、送到、补传”；后端负责”认领、存好、拼回去、确认没坏”
- 分阶段落地：先做基础可用（分块+状态+合并），再提升稳定性（续传+重试+幂等），最后提升体验（秒传+直传+异步合并）