做过几年Java后端最怕听到的就是“客户要传个文件”。普通的几MB、几十MB文件还好说但“1T文件上传”这种需求一摆出来如果还想着用传统multipart/form-data一把梭那基本就是给自己挖坑。JAVA WebUploader这套组合拳本质上就是靠“分块策略”把不可能变成可能。这标题我看着就亲切因为我在真实项目里被这种容量级需求蹂躏过今天就把那套踩坑踩出来的思路、方案和代码骨架完整盘一盘。先说清楚这套东西解决的核心痛点单个超大文件1T甚至更大在公网传输时网络抖动、服务器响应超时、中间代理层断开任何一个环节出问题整个上传就前功尽弃。分块策略的核心价值就是“化整为零、断点续传、并行加速”。WebUploader在前端自动把大文件切分成若干分片后端Java负责接收、校验、暂存和最终合并。听起来不复杂但真要稳定跑起来里面的门道不少。1. 为什么1T级文件必须走分块策略1.1 HTTP协议和服务器容器层面的硬限制如果你没处理过超大文件可能对HttpServletRequest获取InputStream这种方式有误解。理论上你可以从请求体里一直读数据直到EOF但现实里根本走不通。首先是服务器容器有默认限制Tomcat对POST大小虽然没有强制上限但一旦涉及maxPostSize、maxSwallowSize这些参数处理不好就会出现连接被重置、请求体被吞掉的情况。Nginx在反向代理场景下更是有client_max_body_size这个默认1M的门槛虽然可以调大但你把它调到1T试试任何一次网络闪断整个请求体就废了客户端只能重新上传。而分块策略就没这个问题。每一块文件大小限制在合理范围内比如10MB到100MB每块都是独立的小请求任何一个代理层、负载均衡器都不会觉得“数据量异常”也就规避了基础设施层对超大请求体的隐式拦截。1.2 网络传输的容错与断点续传1T的文件在1Mbps的上传带宽下理想情况要传差不多100天。这么长的时间跨度里要求一次HTTP连接一直保持几乎不可能。不管是运营商的链路空闲回收还是公司出口防火墙的session超时都会把长连接干掉。更不用说碰上个小区停电、电脑休眠这种不可抗力。分块策略天然具备断点续传的基础前端记录已上传成功的分块索引失败后只重传未完成的分块。实测下来这个特性在真实弱网环境下能把成功率从30%拉到99%以上这不是夸张是亲身对比过的数据。1.3 并发上传带来的效率提升很多人说“带宽是固定的并发有什么意义”这说法确实有道理但不够全面。单TCP连接的吞吐量受限于拥塞窗口和丢包重传机制尤其在高延迟链路比如跨地域传输上单连接根本跑不满带宽。把文件切成上百块每块一个独立连接用4~6个并发通道传输实测能把带宽利用率提升2~3倍。而且分块还能做进度条精确展示1T文件的总块数可能是几万块前端可以根据“已完成块数/总块数”精确算出百分比而不是靠onprogress里不太靠谱的已传输字节数估算。2. 前端分块策略的核心设计与WebUploader落地2.1 分块大小的权衡逻辑分块大小不是拍脑袋定的。块太小比如1MB那么在1T文件面前会产生超过100万个请求光是HTTP请求头的开销、服务端的MD5计算次数就能把CPU拖垮块太大比如500MB又回到“单次请求体积大”的老问题一旦中途失败重传成本过高。我常用的经验值是20MB~50MB之间具体看服务器带宽和磁盘IO。我自己项目里的取值逻辑是这样的如果目标用户是内网环境带宽在千兆以上分块可以放大到100MB减少请求次数如果是公网传输建议20MB起步。WebUploader里对应的是chunkSize参数单位是字节比如chunkSize: 20 * 1024 * 1024。2.2 前端初始化与分块识别WebUploader处理分块的核心在于chunked: true配置以及formData参数里携带的chunk、chunks、name、guid等信息。这里有一个必须注意的点需要为每个文件生成一个全局唯一的guid或者叫fileMd5否则不同文件的分块会混在一起。我在项目中会让前端在上传前先对文件做一次抽样MD5不是全量MD51T文件全量计算太慢加上文件名、文件大小、最后修改时间拼成一个唯一标识。这个标识贯穿所有分块请求后端用它来定位临时目录。var uploader WebUploader.create({ swf: /Public/webuploader/Uploader.swf, server: /api/upload/chunk, pick: #picker, accept: { title: Files, extensions: zip,rar,tar,gz,7z,bak,iso,img }, chunked: true, chunkSize: 20 * 1024 * 1024, threads: 3, formData: { guid: function() { return fileMd5; } } });2.3 并发数与内存耗用的平衡WebUploader的threads参数控制并发上传的分块数量。默认值是3在公网环境这个数值足够内网可以适当调到5~8。但千万别无脑调大每个分块在上传时都会被读取到浏览器内存中部分情况用Blob切片不会全量加载但依然有临时开销并发数太大会导致前端页面假死。还有一个小技巧限制同一时刻的并发数量但允许多个文件同时上传时是独立队列。这样即便批量选择了上百个文件也不会把服务端打成筛子。3. 后端分块接收与存储策略的工程实现3.1 分区目录与临时文件命名规范后端接收分块最忌讳把所有文件都堆到一个目录里。1T文件切分成5万块单目录下的文件数量本身就是性能灾难。我的做法是三级目录策略第一级是upload_tmp根目录第二级是guid的前两位作为散列子目录第三级是完整guid命名的文件专属目录。分块文件的命名规则也要统一{guid}_{chunkIndex}.part。比如a3f9c2d1e4b5_001.part。这样后续合并时只需要按chunkIndex排序即可不需要额外解析元数据。3.2 分块上传接口的设计与参数校验后端接口设计非常关键我采用的是两个接口POST /api/upload/chunk负责接收单个分块POST /api/upload/merge负责合并。分块接收接口的MultipartFile参数是最核心的。这里有个很多新手会踩的坑不要直接transferTo到目标路径应该先用UUID生成一个临时文件名写入临时目录写入成功后再通过File.renameTo或者Files.move原子性地移动到最终分块位置。这样即使写入过程中服务重启也不会在目标位置留下半个分块文件。PostMapping(/api/upload/chunk) public ResponseEntityResult uploadChunk(RequestParam(file) MultipartFile file, RequestParam(guid) String guid, RequestParam(chunk) Integer chunk, RequestParam(chunks) Integer chunks) { if (file.isEmpty()) { return ResponseEntity.badRequest().body(Result.error(分块内容为空)); } String chunkDir buildChunkDir(guid); File dir new File(chunkDir); if (!dir.exists() !dir.mkdirs()) { return ResponseEntity.status(500).body(Result.error(创建临时目录失败)); } String chunkFilename String.format(%s_%04d.part, guid, chunk); File chunkFile new File(chunkDir, chunkFilename); if (chunkFile.exists()) { // 已存在说明之前传过分块直接返回成功支持断点续传 return ResponseEntity.ok(Result.success(分块已存在跳过)); } // 先写临时文件再原子改名避免写一半被别人读到 File tmpFile new File(chunkDir, chunkFilename .tmp); try (InputStream in file.getInputStream(); OutputStream out new FileOutputStream(tmpFile)) { byte[] buffer new byte[4096]; int bytesRead; while ((bytesRead in.read(buffer)) ! -1) { out.write(buffer, 0, bytesRead); } out.flush(); } if (!tmpFile.renameTo(chunkFile)) { Files.move(tmpFile.toPath(), chunkFile.toPath(), StandardCopyOption.REPLACE_EXISTING); } return ResponseEntity.ok(Result.success(分块上传成功)); }注意我用了%04d格式化分块序号这是为了避免1和10这种字符串排序时顺序错乱的问题。如果分块总数超过一万块建议用%05d或者%06d。3.3 合并策略从磁盘顺序读到Streaming输出所有分块都上传完毕后前端调用merge接口。后端合并时不要把5万个分块一股脑读入内存再写出去那样内存直接爆掉。正确姿势是逐块顺序读取然后通过BufferedOutputStream写出去。PostMapping(/api/upload/merge) public ResponseEntityResult mergeChunks(RequestParam(guid) String guid, RequestParam(fileName) String fileName, RequestParam(totalSize) Long totalSize) { String chunkDir buildChunkDir(guid); File dir new File(chunkDir); File[] chunkFiles dir.listFiles((d, name) - name.endsWith(.part)); if (chunkFiles null || chunkFiles.length 0) { return ResponseEntity.status(400).body(Result.error(没有找到任何分块)); } // 按分块序号排序 Arrays.sort(chunkFiles, (a, b) - { int indexA extractChunkIndex(a.getName()); int indexB extractChunkIndex(b.getName()); return Integer.compare(indexA, indexB); }); String storageDir /data/files/; File targetFile new File(storageDir, UUID.randomUUID() _ sanitizeFileName(fileName)); try (BufferedOutputStream bos new BufferedOutputStream(new FileOutputStream(targetFile))) { byte[] buffer new byte[8192]; for (File partFile : chunkFiles) { try (BufferedInputStream bis new BufferedInputStream(new FileInputStream(partFile))) { int bytesRead; while ((bytesRead bis.read(buffer)) ! -1) { bos.write(buffer, 0, bytesRead); } } } } // 合并成功后再删临时目录如果删除失败也不要阻塞主流程 boolean deleted deleteQuietly(dir); if (!deleted) { log.warn(临时目录删除失败: {}, dir.getAbsolutePath()); } return ResponseEntity.ok(Result.success(合并成功, targetFile.getName())); }这段代码里最关键的是extractChunkIndex方法它是从{guid}_{index}.part中解析出索引的。如果你忽略排序合并出来的文件大概率是坏的。3.4 断点续传与秒传的实现前提断点续传不能只在后端做前端也需要配合。WebUploader有个duplicate事件可以用来判断哪些分块已经上传过。但后端也一定要做幂等判断根据guid chunkIndex判断分块文件是否已存在已存在就直接返回成功。秒传的逻辑更简单如果整个文件之前上传过服务端存有文件的MD5值而且能定位到物理文件那么merge接口直接返回历史文件路径即可不用再合并一遍。分块策略对秒传的意义在于它能提前在chunk阶段就知道“这个文件已经传过哪些分块”前端可以跳过已存在的块只传缺失的块配合秒传效率极高。4. 判断分块缺失、并发冲突与安全加固策略4.1 判断哪些分块没传成功前端拿到的chunks数量是确定的但后端拿到的分块不一定是连续的。尤其是弱网环境下用户上传的顺序是乱的、分块有缺口很正常。合并前必须做一次完整性校验遍历临时目录检查从0到chunks-1的所有分块文件是否存在。前端WebUploader的处理方式是在uploadFinished回调里判断是否需要调用merge但有时候它认为全传完了实际上后端还缺块比如前端的成功回执和实际落盘之间有极端情况。所以更稳妥的做法是后端merge接口里再做一次校验发现缺块就返回具体缺失块的索引前端拿到后自动补齐。4.2 多个分块同时到达时的并发冲突分块上传天然是并发的因此后端写入分块文件时要考虑并发问题。如果两个请求同时写同一个chunkIndex后一个覆盖前一个这还算好最怕的是两个请求同时检测到“分块不存在”然后同时创建文件其中一个的FileOutputStream会抛FileNotFoundException或者产生文件锁冲突。解决思路很简单在写分块之前加一个进程内锁。ConcurrentHashMapString, Object按guid_chunkIndex作为key加锁粒度小、开销低。跨多实例部署时需要用分布式锁Redis的SETNX或者Zookeeper但通常来说单实例加锁已经能解决99%的问题。4.3 文件上传漏洞与WebUploader的安全填充做任何文件上传功能安全都是绕不开的话题。特别是超大文件上传这种场景一旦入口没守住攻击面非常大。WebUploader本身在前端校验了扩展名但前端校验是防君子不防小人的别人完全可以绕过你的JS逻辑直接调你的后端接口。后端必须有这几层校验第一层文件扩展名白名单校验。.jsp、.jspx、.php、.exe这些一律拒绝。不要只校验文件的原始扩展名还要校验分块合并后的完整文件名防止攻击者把分块内容伪装成图片合并后变成可执行脚本。第二层MIME类型校验。file.getContentType()是可以伪造的不能作为唯一依据但可以作为辅助条件。更靠谱的做法是用Files.probeContentType()或者Apache Tika来识别真实文件类型识别出来的类型跟白名单对不上就拒绝。第三层内容级检测。对于文本类文件要检测是否包含?php、%、script这些危险标记对于压缩包文件最好解压检查是否有解压炸弹风险。这个在1T级别文件上做全量内容扫描不现实但至少要对文件头前几百字节做检查。第四层文件名清洗。sanitizeFileName这一步不能省防止路径穿越攻击——比如文件名里带../把所有..、/、\、控制字符全部替换成下划线只保留字母、数字、点、下划线、中划线。5. 超大上传场景下的性能调优与常见问题5.1 内存与磁盘IO的平衡术很多人处理文件上传时习惯用file.getBytes()把整个文件读入内存。这在10MB以内的小文件没问题但到了分块上传场景哪怕单个分块只有20MB如果并发5个瞬时内存占用就是100MB。如果Tomcat的maxThreads是200极端情况下光是上传请求就能吃掉几个G内存直接触发OOM。我的实践方式是从MultipartFile拿InputStream用固定大小的byte[]缓冲加上OutputStream写入磁盘流式处理绝不一次性全量读入内存。这个方法在处理每个分块时峰值内存占用基本稳定在几十KB跟文件大小无关。磁盘方面有个需要关注的细节机械硬盘的顺序写性能远好于随机写。分块并发上传时多个连接同时写不同的临时文件会产生随机IO。这块我建议把临时分块目录放在SSD上或者给磁盘阵列做条带化。否则你会发现带宽还很充足但磁盘IO先成了瓶颈上传速度肉眼可见地掉下来。5.2 超时设置的三个关键层第一层Nginx的proxy_read_timeout和proxy_send_timeout必须大于单个分块上传的最大耗时。如果是公网慢速上传20MB的分块可能耗时要几分钟默认60秒超时直接断了连接。建议设成300秒起步。第二层Tomcat的connectionTimeout和keepAliveTimeout同样需要调大否则一个分块传一半连接被容器回收前端只能收到错误码。第三层前端WebUploader的timeout参数默认是0表示不超时。这个参数建议设一个较大的值比如timeout: 30 * 60 * 10000而不是完全不设超时。因为完全不设超时会导致某个分块卡死了也不报错用户看到的进度条一直停在99%。我的习惯性配置是Nginx的client_max_body_size和分块大小保持一致比如分块是20MB就设client_max_body_size 25m。这样即使某个分块因为TCP粘包或者代理层缓冲问题稍微超过预期大小也不会被400拦截。5.3 常见问题速查表我把实际运维中遇到最多的问题整理成一张表基本覆盖了从开发到上线全流程会踩的坑。现象根本原因解决方案上传中途连接被重置Nginxclient_max_body_size过小调大到分块大小的1.2倍上传卡在99%不动最后一个分块丢失或并发数不足导致队头阻塞查看后端日志确认分块数前端增加重试逻辑合并后的文件损坏分块合并顺序错误用%04d格式化命名并严格排序后再合并服务频繁Full GC使用了getBytes()或transferTo不当改为流式读写避免全量读入内存磁盘空间被占满上传中断后临时分块未清理增加定时清理任务删除超过24小时未完成的分块目录跨域上传失败浏览器CORS预检被拦截后端允许对应Origin和自定义Header多次上传同一个文件但结果不一致guid生成规则不稳定用MD5大小最后修改时间做联合指纹上传小文件也报错前端强制分块导致chunks1时逻辑异常对小于分块大小的文件走非分块逻辑5.4 定时清理策略与生产环境注意事项1T文件传不完就搁那儿的情况太多了用户的电脑可能中途就关机了也可能传了一半换了个网络环境拿不到之前的guid。服务端必须有一种机制来兜底启动一个定时任务扫描临时目录凡是lastModified超过24小时没更新的分块目录直接整个删除。清理策略不能只看文件修改时间因为某些分块可能传完后不再有任何IO操作。我的做法是每次分块上传完成时在Redis里记录guid的最后活跃时间清理任务扫描Redis里的过期guid再删除对应的临时目录。这样比单纯扫描文件的时间戳更准确。另外生产环境的Tomcat一定记得调大maxPostSize虽然分块模式下单个POST不大但保险起见设成-1表示不限制避免某些中间代理往请求头里塞东西导致异常。6. 分块上传的扩展场景与后续优化方向6.1 从单个服务到分布式架构的升级单机版的WebUploader分块上传在1T文件面前其实已经很吃力了。如果文件量再上几个数量级就需要把临时目录、分块文件和合并服务拆开。常见的做法是用云存储前端直接分片上传到对象存储后端只负责生成预签名上传URL、记录分块元数据、发起合并指令。这样带宽压力从应用服务器转移到了对象存储应用层只做轻量级调度。6.2 结合消息队列做异步合并如果1T文件的分块数量特别大同步合并可能耗时几分钟导致前端请求一直阻塞。这时候可以改成异步merge接口只把合并任务丢进MQ返回“合并中”状态前端通过轮询或WebSocket查询进度。合并任务消费端逐块读取、写入目标文件、更新进度。6.3 做全量MD5校验的性价比考量1T文件全量计算MD5在普通性能的机器上耗时数分钟但可以在合并过程中“顺带”计算几乎不增加额外IO。合并完成后拿全量MD5跟前端提交的MD5做比对。如果一致说明文件链路完整如果不一致说明某个分块在上传过程中发生了静默损坏要触发重新上传。我在实际项目中第一次用全量MD5校验时还真抓到了一个问题某个网络设备在传输大文件时对特定数据模式做了改写导致合并出来的文件和其他节点对不上。如果没有这层校验这个问题可能永远发现不了。写在最后的一些实在话说句实话1T文件上传这需求真正把WebUploader调通只是第一步。分块策略是骨架断点续传是灵魂安全校验是底线性能调优是血肉。我见过太多人把WebUploader的demo跑通就以为大功告成结果生产环境第一个1G文件就把Tomcat干趴下。这些年我跟文件上传较劲得出的经验就一句话永远默认网络是不可靠的永远默认分块是会丢的永远默认别人传上来的文件是带着恶意的。从我自己接手的项目来看分块逻辑本身难度不大真正花时间的是处理各种边界场景服务器重启、客户端断网、分块重复提交、脏数据清理、跨域拦截、浏览器兼容。把这些边边角角都磨平了这套系统才算真正能扛住1T级文件的考验。如果你正在做类似的方案希望这篇踩坑记录能帮你少走几步弯路。
做过几年Java后端最怕听到的就是“客户要传个文件”。普通的几MB、几十MB文件还好说但“1T文件上传”这种需求一摆出来如果还想着用传统multipart/form-data一把梭那基本就是给自己挖坑。JAVA WebUploader这套组合拳本质上就是靠“分块策略”把不可能变成可能。这标题我看着就亲切因为我在真实项目里被这种容量级需求蹂躏过今天就把那套踩坑踩出来的思路、方案和代码骨架完整盘一盘。先说清楚这套东西解决的核心痛点单个超大文件1T甚至更大在公网传输时网络抖动、服务器响应超时、中间代理层断开任何一个环节出问题整个上传就前功尽弃。分块策略的核心价值就是“化整为零、断点续传、并行加速”。WebUploader在前端自动把大文件切分成若干分片后端Java负责接收、校验、暂存和最终合并。听起来不复杂但真要稳定跑起来里面的门道不少。1. 为什么1T级文件必须走分块策略1.1 HTTP协议和服务器容器层面的硬限制如果你没处理过超大文件可能对HttpServletRequest获取InputStream这种方式有误解。理论上你可以从请求体里一直读数据直到EOF但现实里根本走不通。首先是服务器容器有默认限制Tomcat对POST大小虽然没有强制上限但一旦涉及maxPostSize、maxSwallowSize这些参数处理不好就会出现连接被重置、请求体被吞掉的情况。Nginx在反向代理场景下更是有client_max_body_size这个默认1M的门槛虽然可以调大但你把它调到1T试试任何一次网络闪断整个请求体就废了客户端只能重新上传。而分块策略就没这个问题。每一块文件大小限制在合理范围内比如10MB到100MB每块都是独立的小请求任何一个代理层、负载均衡器都不会觉得“数据量异常”也就规避了基础设施层对超大请求体的隐式拦截。1.2 网络传输的容错与断点续传1T的文件在1Mbps的上传带宽下理想情况要传差不多100天。这么长的时间跨度里要求一次HTTP连接一直保持几乎不可能。不管是运营商的链路空闲回收还是公司出口防火墙的session超时都会把长连接干掉。更不用说碰上个小区停电、电脑休眠这种不可抗力。分块策略天然具备断点续传的基础前端记录已上传成功的分块索引失败后只重传未完成的分块。实测下来这个特性在真实弱网环境下能把成功率从30%拉到99%以上这不是夸张是亲身对比过的数据。1.3 并发上传带来的效率提升很多人说“带宽是固定的并发有什么意义”这说法确实有道理但不够全面。单TCP连接的吞吐量受限于拥塞窗口和丢包重传机制尤其在高延迟链路比如跨地域传输上单连接根本跑不满带宽。把文件切成上百块每块一个独立连接用4~6个并发通道传输实测能把带宽利用率提升2~3倍。而且分块还能做进度条精确展示1T文件的总块数可能是几万块前端可以根据“已完成块数/总块数”精确算出百分比而不是靠onprogress里不太靠谱的已传输字节数估算。2. 前端分块策略的核心设计与WebUploader落地2.1 分块大小的权衡逻辑分块大小不是拍脑袋定的。块太小比如1MB那么在1T文件面前会产生超过100万个请求光是HTTP请求头的开销、服务端的MD5计算次数就能把CPU拖垮块太大比如500MB又回到“单次请求体积大”的老问题一旦中途失败重传成本过高。我常用的经验值是20MB~50MB之间具体看服务器带宽和磁盘IO。我自己项目里的取值逻辑是这样的如果目标用户是内网环境带宽在千兆以上分块可以放大到100MB减少请求次数如果是公网传输建议20MB起步。WebUploader里对应的是chunkSize参数单位是字节比如chunkSize: 20 * 1024 * 1024。2.2 前端初始化与分块识别WebUploader处理分块的核心在于chunked: true配置以及formData参数里携带的chunk、chunks、name、guid等信息。这里有一个必须注意的点需要为每个文件生成一个全局唯一的guid或者叫fileMd5否则不同文件的分块会混在一起。我在项目中会让前端在上传前先对文件做一次抽样MD5不是全量MD51T文件全量计算太慢加上文件名、文件大小、最后修改时间拼成一个唯一标识。这个标识贯穿所有分块请求后端用它来定位临时目录。var uploader WebUploader.create({ swf: /Public/webuploader/Uploader.swf, server: /api/upload/chunk, pick: #picker, accept: { title: Files, extensions: zip,rar,tar,gz,7z,bak,iso,img }, chunked: true, chunkSize: 20 * 1024 * 1024, threads: 3, formData: { guid: function() { return fileMd5; } } });2.3 并发数与内存耗用的平衡WebUploader的threads参数控制并发上传的分块数量。默认值是3在公网环境这个数值足够内网可以适当调到5~8。但千万别无脑调大每个分块在上传时都会被读取到浏览器内存中部分情况用Blob切片不会全量加载但依然有临时开销并发数太大会导致前端页面假死。还有一个小技巧限制同一时刻的并发数量但允许多个文件同时上传时是独立队列。这样即便批量选择了上百个文件也不会把服务端打成筛子。3. 后端分块接收与存储策略的工程实现3.1 分区目录与临时文件命名规范后端接收分块最忌讳把所有文件都堆到一个目录里。1T文件切分成5万块单目录下的文件数量本身就是性能灾难。我的做法是三级目录策略第一级是upload_tmp根目录第二级是guid的前两位作为散列子目录第三级是完整guid命名的文件专属目录。分块文件的命名规则也要统一{guid}_{chunkIndex}.part。比如a3f9c2d1e4b5_001.part。这样后续合并时只需要按chunkIndex排序即可不需要额外解析元数据。3.2 分块上传接口的设计与参数校验后端接口设计非常关键我采用的是两个接口POST /api/upload/chunk负责接收单个分块POST /api/upload/merge负责合并。分块接收接口的MultipartFile参数是最核心的。这里有个很多新手会踩的坑不要直接transferTo到目标路径应该先用UUID生成一个临时文件名写入临时目录写入成功后再通过File.renameTo或者Files.move原子性地移动到最终分块位置。这样即使写入过程中服务重启也不会在目标位置留下半个分块文件。PostMapping(/api/upload/chunk) public ResponseEntityResult uploadChunk(RequestParam(file) MultipartFile file, RequestParam(guid) String guid, RequestParam(chunk) Integer chunk, RequestParam(chunks) Integer chunks) { if (file.isEmpty()) { return ResponseEntity.badRequest().body(Result.error(分块内容为空)); } String chunkDir buildChunkDir(guid); File dir new File(chunkDir); if (!dir.exists() !dir.mkdirs()) { return ResponseEntity.status(500).body(Result.error(创建临时目录失败)); } String chunkFilename String.format(%s_%04d.part, guid, chunk); File chunkFile new File(chunkDir, chunkFilename); if (chunkFile.exists()) { // 已存在说明之前传过分块直接返回成功支持断点续传 return ResponseEntity.ok(Result.success(分块已存在跳过)); } // 先写临时文件再原子改名避免写一半被别人读到 File tmpFile new File(chunkDir, chunkFilename .tmp); try (InputStream in file.getInputStream(); OutputStream out new FileOutputStream(tmpFile)) { byte[] buffer new byte[4096]; int bytesRead; while ((bytesRead in.read(buffer)) ! -1) { out.write(buffer, 0, bytesRead); } out.flush(); } if (!tmpFile.renameTo(chunkFile)) { Files.move(tmpFile.toPath(), chunkFile.toPath(), StandardCopyOption.REPLACE_EXISTING); } return ResponseEntity.ok(Result.success(分块上传成功)); }注意我用了%04d格式化分块序号这是为了避免1和10这种字符串排序时顺序错乱的问题。如果分块总数超过一万块建议用%05d或者%06d。3.3 合并策略从磁盘顺序读到Streaming输出所有分块都上传完毕后前端调用merge接口。后端合并时不要把5万个分块一股脑读入内存再写出去那样内存直接爆掉。正确姿势是逐块顺序读取然后通过BufferedOutputStream写出去。PostMapping(/api/upload/merge) public ResponseEntityResult mergeChunks(RequestParam(guid) String guid, RequestParam(fileName) String fileName, RequestParam(totalSize) Long totalSize) { String chunkDir buildChunkDir(guid); File dir new File(chunkDir); File[] chunkFiles dir.listFiles((d, name) - name.endsWith(.part)); if (chunkFiles null || chunkFiles.length 0) { return ResponseEntity.status(400).body(Result.error(没有找到任何分块)); } // 按分块序号排序 Arrays.sort(chunkFiles, (a, b) - { int indexA extractChunkIndex(a.getName()); int indexB extractChunkIndex(b.getName()); return Integer.compare(indexA, indexB); }); String storageDir /data/files/; File targetFile new File(storageDir, UUID.randomUUID() _ sanitizeFileName(fileName)); try (BufferedOutputStream bos new BufferedOutputStream(new FileOutputStream(targetFile))) { byte[] buffer new byte[8192]; for (File partFile : chunkFiles) { try (BufferedInputStream bis new BufferedInputStream(new FileInputStream(partFile))) { int bytesRead; while ((bytesRead bis.read(buffer)) ! -1) { bos.write(buffer, 0, bytesRead); } } } } // 合并成功后再删临时目录如果删除失败也不要阻塞主流程 boolean deleted deleteQuietly(dir); if (!deleted) { log.warn(临时目录删除失败: {}, dir.getAbsolutePath()); } return ResponseEntity.ok(Result.success(合并成功, targetFile.getName())); }这段代码里最关键的是extractChunkIndex方法它是从{guid}_{index}.part中解析出索引的。如果你忽略排序合并出来的文件大概率是坏的。3.4 断点续传与秒传的实现前提断点续传不能只在后端做前端也需要配合。WebUploader有个duplicate事件可以用来判断哪些分块已经上传过。但后端也一定要做幂等判断根据guid chunkIndex判断分块文件是否已存在已存在就直接返回成功。秒传的逻辑更简单如果整个文件之前上传过服务端存有文件的MD5值而且能定位到物理文件那么merge接口直接返回历史文件路径即可不用再合并一遍。分块策略对秒传的意义在于它能提前在chunk阶段就知道“这个文件已经传过哪些分块”前端可以跳过已存在的块只传缺失的块配合秒传效率极高。4. 判断分块缺失、并发冲突与安全加固策略4.1 判断哪些分块没传成功前端拿到的chunks数量是确定的但后端拿到的分块不一定是连续的。尤其是弱网环境下用户上传的顺序是乱的、分块有缺口很正常。合并前必须做一次完整性校验遍历临时目录检查从0到chunks-1的所有分块文件是否存在。前端WebUploader的处理方式是在uploadFinished回调里判断是否需要调用merge但有时候它认为全传完了实际上后端还缺块比如前端的成功回执和实际落盘之间有极端情况。所以更稳妥的做法是后端merge接口里再做一次校验发现缺块就返回具体缺失块的索引前端拿到后自动补齐。4.2 多个分块同时到达时的并发冲突分块上传天然是并发的因此后端写入分块文件时要考虑并发问题。如果两个请求同时写同一个chunkIndex后一个覆盖前一个这还算好最怕的是两个请求同时检测到“分块不存在”然后同时创建文件其中一个的FileOutputStream会抛FileNotFoundException或者产生文件锁冲突。解决思路很简单在写分块之前加一个进程内锁。ConcurrentHashMapString, Object按guid_chunkIndex作为key加锁粒度小、开销低。跨多实例部署时需要用分布式锁Redis的SETNX或者Zookeeper但通常来说单实例加锁已经能解决99%的问题。4.3 文件上传漏洞与WebUploader的安全填充做任何文件上传功能安全都是绕不开的话题。特别是超大文件上传这种场景一旦入口没守住攻击面非常大。WebUploader本身在前端校验了扩展名但前端校验是防君子不防小人的别人完全可以绕过你的JS逻辑直接调你的后端接口。后端必须有这几层校验第一层文件扩展名白名单校验。.jsp、.jspx、.php、.exe这些一律拒绝。不要只校验文件的原始扩展名还要校验分块合并后的完整文件名防止攻击者把分块内容伪装成图片合并后变成可执行脚本。第二层MIME类型校验。file.getContentType()是可以伪造的不能作为唯一依据但可以作为辅助条件。更靠谱的做法是用Files.probeContentType()或者Apache Tika来识别真实文件类型识别出来的类型跟白名单对不上就拒绝。第三层内容级检测。对于文本类文件要检测是否包含?php、%、script这些危险标记对于压缩包文件最好解压检查是否有解压炸弹风险。这个在1T级别文件上做全量内容扫描不现实但至少要对文件头前几百字节做检查。第四层文件名清洗。sanitizeFileName这一步不能省防止路径穿越攻击——比如文件名里带../把所有..、/、\、控制字符全部替换成下划线只保留字母、数字、点、下划线、中划线。5. 超大上传场景下的性能调优与常见问题5.1 内存与磁盘IO的平衡术很多人处理文件上传时习惯用file.getBytes()把整个文件读入内存。这在10MB以内的小文件没问题但到了分块上传场景哪怕单个分块只有20MB如果并发5个瞬时内存占用就是100MB。如果Tomcat的maxThreads是200极端情况下光是上传请求就能吃掉几个G内存直接触发OOM。我的实践方式是从MultipartFile拿InputStream用固定大小的byte[]缓冲加上OutputStream写入磁盘流式处理绝不一次性全量读入内存。这个方法在处理每个分块时峰值内存占用基本稳定在几十KB跟文件大小无关。磁盘方面有个需要关注的细节机械硬盘的顺序写性能远好于随机写。分块并发上传时多个连接同时写不同的临时文件会产生随机IO。这块我建议把临时分块目录放在SSD上或者给磁盘阵列做条带化。否则你会发现带宽还很充足但磁盘IO先成了瓶颈上传速度肉眼可见地掉下来。5.2 超时设置的三个关键层第一层Nginx的proxy_read_timeout和proxy_send_timeout必须大于单个分块上传的最大耗时。如果是公网慢速上传20MB的分块可能耗时要几分钟默认60秒超时直接断了连接。建议设成300秒起步。第二层Tomcat的connectionTimeout和keepAliveTimeout同样需要调大否则一个分块传一半连接被容器回收前端只能收到错误码。第三层前端WebUploader的timeout参数默认是0表示不超时。这个参数建议设一个较大的值比如timeout: 30 * 60 * 10000而不是完全不设超时。因为完全不设超时会导致某个分块卡死了也不报错用户看到的进度条一直停在99%。我的习惯性配置是Nginx的client_max_body_size和分块大小保持一致比如分块是20MB就设client_max_body_size 25m。这样即使某个分块因为TCP粘包或者代理层缓冲问题稍微超过预期大小也不会被400拦截。5.3 常见问题速查表我把实际运维中遇到最多的问题整理成一张表基本覆盖了从开发到上线全流程会踩的坑。现象根本原因解决方案上传中途连接被重置Nginxclient_max_body_size过小调大到分块大小的1.2倍上传卡在99%不动最后一个分块丢失或并发数不足导致队头阻塞查看后端日志确认分块数前端增加重试逻辑合并后的文件损坏分块合并顺序错误用%04d格式化命名并严格排序后再合并服务频繁Full GC使用了getBytes()或transferTo不当改为流式读写避免全量读入内存磁盘空间被占满上传中断后临时分块未清理增加定时清理任务删除超过24小时未完成的分块目录跨域上传失败浏览器CORS预检被拦截后端允许对应Origin和自定义Header多次上传同一个文件但结果不一致guid生成规则不稳定用MD5大小最后修改时间做联合指纹上传小文件也报错前端强制分块导致chunks1时逻辑异常对小于分块大小的文件走非分块逻辑5.4 定时清理策略与生产环境注意事项1T文件传不完就搁那儿的情况太多了用户的电脑可能中途就关机了也可能传了一半换了个网络环境拿不到之前的guid。服务端必须有一种机制来兜底启动一个定时任务扫描临时目录凡是lastModified超过24小时没更新的分块目录直接整个删除。清理策略不能只看文件修改时间因为某些分块可能传完后不再有任何IO操作。我的做法是每次分块上传完成时在Redis里记录guid的最后活跃时间清理任务扫描Redis里的过期guid再删除对应的临时目录。这样比单纯扫描文件的时间戳更准确。另外生产环境的Tomcat一定记得调大maxPostSize虽然分块模式下单个POST不大但保险起见设成-1表示不限制避免某些中间代理往请求头里塞东西导致异常。6. 分块上传的扩展场景与后续优化方向6.1 从单个服务到分布式架构的升级单机版的WebUploader分块上传在1T文件面前其实已经很吃力了。如果文件量再上几个数量级就需要把临时目录、分块文件和合并服务拆开。常见的做法是用云存储前端直接分片上传到对象存储后端只负责生成预签名上传URL、记录分块元数据、发起合并指令。这样带宽压力从应用服务器转移到了对象存储应用层只做轻量级调度。6.2 结合消息队列做异步合并如果1T文件的分块数量特别大同步合并可能耗时几分钟导致前端请求一直阻塞。这时候可以改成异步merge接口只把合并任务丢进MQ返回“合并中”状态前端通过轮询或WebSocket查询进度。合并任务消费端逐块读取、写入目标文件、更新进度。6.3 做全量MD5校验的性价比考量1T文件全量计算MD5在普通性能的机器上耗时数分钟但可以在合并过程中“顺带”计算几乎不增加额外IO。合并完成后拿全量MD5跟前端提交的MD5做比对。如果一致说明文件链路完整如果不一致说明某个分块在上传过程中发生了静默损坏要触发重新上传。我在实际项目中第一次用全量MD5校验时还真抓到了一个问题某个网络设备在传输大文件时对特定数据模式做了改写导致合并出来的文件和其他节点对不上。如果没有这层校验这个问题可能永远发现不了。写在最后的一些实在话说句实话1T文件上传这需求真正把WebUploader调通只是第一步。分块策略是骨架断点续传是灵魂安全校验是底线性能调优是血肉。我见过太多人把WebUploader的demo跑通就以为大功告成结果生产环境第一个1G文件就把Tomcat干趴下。这些年我跟文件上传较劲得出的经验就一句话永远默认网络是不可靠的永远默认分块是会丢的永远默认别人传上来的文件是带着恶意的。从我自己接手的项目来看分块逻辑本身难度不大真正花时间的是处理各种边界场景服务器重启、客户端断网、分块重复提交、脏数据清理、跨域拦截、浏览器兼容。把这些边边角角都磨平了这套系统才算真正能扛住1T级文件的考验。如果你正在做类似的方案希望这篇踩坑记录能帮你少走几步弯路。
