最近在帮某个内网业务系统做升级时遇到一个很现实的问题系统里需要上传动辄几个GB的业务数据包用最传统的表单POST方式传到一半连接超时浏览器直接报错用户心态直接崩掉。更麻烦的是内网环境里断网重连、服务器重启、文件损坏这些情况都发生过一旦传了一半断了又要从头再来浪费的时间足够跑完一整轮业务演练。当时我第一个想到的优化方向就是给上传组件加分块和断点续传。调研了一圈最终落到了WebUploader上。先说结论WebUploader这套开源组件配合服务端做分块存储和合并校验完全可以在局域网环境下支撑大文件的分块上传和断电续传。但能用和好用之间差了大概一整篇踩坑记录的距离。这篇就把我在内网环境里跑通的完整方案、参数设置和那些坑一次性说清楚。1. 内网大文件上传的真正难点不是带宽而是会话和内存很多人在局域网里传大文件第一反应是内网带宽大肯定快。带宽确实不是瓶颈但真正让传统上传方案报废的是另外三个问题。1.1 传统POST上传的三个致命短板首先说超时。Web服务器、应用容器、反向代理层层都有超时配置。PHP默认的max_execution_time、Nginx的proxy_read_timeout、Tomcat的连接超时任何一个到了阈值长连接就会被掐掉。外网环境大家习惯性配大超时但内网系统往往沿用默认配置一个1GB文件传上几分钟服务端早就把连接断掉了前端还在闷头往上写。其次是内存。非流式接收的框架比如某些基于PHP的老接口会把整个请求体读进内存再写磁盘。文件一上来就是2GB服务器内存直接被打满轻则OOM重则拖垮同一台机器上的其他服务。第三个是会话中断后的代价。没有断点续传一次网络抖动、一次服务端发布重启整个文件作废。在内网这种环境里用户可能同时开着好几个业务窗口切换网络、锁屏待机、无线信号波动都会让会话变脆弱。一旦断了重传时间成本是翻倍的。1.2 为什么偏偏选WebUploader在Web端做分块上传可选方案不少自研的、商业的、开源的都有一堆。我选WebUploader的原因很朴素第一它本身就是为分块场景设计的。chunked模式、并发控制、失败重试、文件MD5秒传这些不是靠后期打补丁加上的而是组件原生核心能力。第二它的分块上传逻辑和File API的Blob.slice()紧密结合文件在浏览器侧就被切成小块逐个发送这样浏览器内存里永远只有当前正在传的几个分块不会一次性把一个GB级文件全部载入天然规避了前端内存溢出问题。第三它会记录每个分块的上传状态配合服务端的分块存储天然就支持续传。前端只需要告诉服务端这个文件我已经有哪些分块了服务端比对之后返回缺失列表前端补传即可。顺带提一嘴WebUploader虽然出自某大厂开源但项目停更多年。这不影响使用——它的核心机制稳定社区踩坑资料丰富。相比某些需要商用授权的上传组件它更轻、可控性也强。但如果你的项目要从零开始且团队前端功底扎实也可以参考它的设计思路自研对于急着要在内网上跑通大文件上传的场景直接上手WebUploader是最短路径。2. 分块上传的核心机制文件是怎么被切开的分块上传听起来高大上本质就是把一个文件按字节切成若干段分段发送服务端临时保存全部传完后再拼接回完整文件。WebUploader帮我们把切分和调度这部分封装好了但你得理解它的工作逻辑才知道哪些参数该改、哪些逻辑需要服务端配合。2.1 关键参数chunkSize、threads 和它们的取舍先看一段WebUploader的核心初始化配置var uploader WebUploader.create({ swf: /static/Uploader.swf, server: /api/upload/chunk, pick: #picker, accept: { title: 业务数据包, extensions: dat,zip,tar,gz, mimeTypes: application/octet-stream }, chunked: true, chunkSize: 5 * 1024 * 1024, // 每个分块5MB threads: 3, // 同时并发上传3个分块 fileVal: file, duplicate: true, formData: { bizType: dataPackage } });这里最核心的两个参数就是chunkSize和threads。chunkSize是分块大小。设太大比如50MB一个分块一旦单个分块传输失败重传成本高而且分块数少断点续传的粒度就粗。设太小比如128KB服务端要处理的临时文件数量暴涨合并时IO压力大还容易被部分网关设备误判为攻击流量。内网环境下我实测下来5MB是一个比较舒适的平衡点分块总数合适单块传输在百兆/千兆内网上都是一两秒内的事。threads是并发上传的分块数量。我最终选3原因后面第4部分细说。这里先记住一点内网带宽虽然大但并发数不是越高越好因为这会给服务端磁盘IO和内存带来额外压力尤其是多个用户同时上传的场景。2.2 每个分块到了服务端带了什么身份证WebUploader在发送每个分块时会通过uploadBeforeSend事件往请求参数里附加分块信息。服务端拿到这些字段才能正确识别和处理uploader.on(uploadBeforeSend, function (file, block, data) { data.chunk block.chunk; // 当前分块索引从0开始 data.chunks block.chunks; // 总分块数 // 每个文件的标识可以用 file.id也可以自定义 data.fileKey file.id; // 文件唯一标识可自定义 data.fileName file.name; data.fileSize file.size; });服务端收到的HTTP请求里就会包含类似这样的参数file: [分块文件二进制流] chunk: 0 chunks: 412 fileKey: WU_FILE_0_5f8a3b9c fileName: 业务数据包_20240821.dat注意WebUploader默认的chunk从0开始计数。我见过不止一个服务端同学按1开始写合并逻辑导致文件头缺了一块这种错误特别隐蔽因为文件能生成但校验MD5时永远对不上。2.3 秒传和断点续传的底层逻辑MD5的妙用WebUploader支持一个叫做秒传的玩法。原理简单到令人发指在文件开始上传前前端先给整个文件计算MD5值然后把这个MD5发给服务端服务端查一下自己库里有没有相同MD5的文件——有直接返回传完了前端连分块都不用发用户看到的就是瞬间完成。对于超大文件来说前端计算全文件MD5也是要花时间的。我实测一个2GB的文件在普通办公电脑上算MD5大概需要十几秒。这个时间不是白等的它换来了两个重要能力一是一旦服务端已有相同内容文件直接跳过所有分块传输节省大量时间。这在业务系统里非常实用因为同一批数据文件可能被反复上传。二是可以作为分块传输完整性的最终校验依据。服务端在合并完全部分块之后重新计算合并文件的MD5与前端上报的原始MD5比对一致才算上传成功。前端计算MD5的代码通常配合spark-md5这类库来做var md5Worker new Worker(/static/js/md5-worker.js); md5Worker.postMessage({ file: file.source }); md5Worker.onmessage function (event) { var fileMd5 event.data.md5; uploader.option(formData, { fileMd5: fileMd5 }); // 提交预检查询服务端是否已存在相同MD5文件存在则触发秒传 checkFileExists(fileMd5); };这里有个体验细节计算MD5期间文件处于校验中的状态用户可能会疑惑为什么点了上传没反应。我一般会在UI上明确提示正在校验文件特征预计XX秒并且把MD5计算放在Web Worker线程里避免阻塞页面操作。3. 服务端才是续传的主战场分块存储与合并校验WebUploader只是完成了客户端的工作——把文件切成块、并发发送、失败重试。真正的断点续传靠的是服务端保存分块 查询已传分块的能力。如果只配置了前端而服务端不做配合那你得到的只是一个分块上传功能根本没有续传能力。3.1 分块临时目录怎么设计服务端收到分块请求后不能简单地把分块文件扔到一个大目录里。我需要设计一套能让迟到的分块准确归位的存储结构。我的做法是以文件MD5为一级目录分块索引为子文件/storage/upload_tmp/ └── 5f8a3b9c...文件MD5前若干位 ├── 0 ├── 1 ├── 2 ├── ... └── 411这里有个工程细节如果直接把MD5全裸拼进路径内网系统上还叠加了安全审计的考量路径过长也是麻烦。我一般只取MD5前16位作为目录名加一个随机短串兜底既减少路径长度也减少撞车概率。每个分块通过chunk索引命名索引即顺序合并时直接按文件名顺序拼接不需要额外记录顺序关系。这一设计让合并逻辑变得极其简单。3.2 合并分块的三种策略和取舍分块全部到达后服务端要做的是把这些临时分块合并为完整文件。我试过三种合并方式各有适用场景第一种Java NIO / 普通文件流逐个写入try (FileChannel out new FileChannel.open(destPath, CREATE, WRITE)) { for (int i 0; i chunks; i) { try (FileChannel in FileChannel.open(tmpPath / i, READ)) { in.transferTo(0, in.size(), out); } } }这种方式实现最直白不容易出错适合绝大多数情况。唯一的问题是分块非常多时打开文件的次数多耗时略长。第二种Linux cat命令合并cat /storage/upload_tmp/5f8a3b9c/{0..411} /storage/merge/final.dat速度快、代码量零但有个致命前提分块索引必须连续且从0开始编号。如果中间缺了一个分块cat命令不会报错只会生成了一个缺斤短两的文件MD5校验时才发现问题。我一般不用这个做生产合并只用于人工排查。第三种流式边收边写每个分块到了就写进最终文件的对应偏移量处。优点是省去了最后的合并步骤缺点是并发到达时对同一个文件句柄的随机写入在实现上比较复杂而且如果中途某个分块丢了最终文件立刻就是损坏状态排查难度增加。我最终用的是第一种业务场景里文件上传不是高频高并发操作简单可靠排在第一位。3.3 查询已上传分块续传的关键接口断点续传的核心在于前端重新启动上传时需要知道哪些分块已经在服务端了。我提供了这样一个接口GET /api/upload/query?fileMd55f8a3b9c...服务端逻辑根据fileMd5找到临时目录列出目录下的所有分块文件索引返回已存在分块索引的列表例如[0, 1, 2, 3, 5, 7]。前端拿到这份清单后把缺失的[4, 6, 8, ...]排队补传已存在的分块直接跳过。这里有一个幂等问题必须处理同一个分块被重复提交时服务端不能报错直接覆盖写入即可。因为断点重传、并发重试时同一个分块完全可能被发送两次。我在文件写入时采用存在即覆盖策略并做好原子性——先写临时后缀文件写完再重命名避免出现写到一半的残缺分块被查询接口读到。3.4 合并完成后的清理与校验合并完成后不能直接往前端返回成功。我始终坚持以下顺序计算合并后文件的MD5与前端上报的文件MD5比对一致返回成功并清理临时分块目录不一致保留临时目录并记录日志返回分块校验失败。这里最大的坑是服务器的字符集和文件处理模式。有些语言在处理文件流时如果不显式指定二进制模式会对特殊字符做转义导致合并后的文件与原文件不一致。检查逻辑必须放到最后一步并且必须和前端用同一个MD5算法同一份文件在不同算法、不同编码下的MD5结果可能不同但同一个标准的MD5是确定的。4. 局域网特有的调优实践参数、并发与网关配置把WebUploader的前后端都跑通了只是第一步。内网环境和外网有一个本质区别网络质量更可控延迟更低、带宽更大但服务器处理能力、网关策略、安全防护是另一种风格。这里要调整的参数思路和公网场景是反着来的。4.1 并发数为什么是3不是10外网环境下受限于带宽和TCP拥塞并发太高反而拖慢整体速度。内网千兆环境下一个分块5MB传输本身就是毫秒级的事瓶颈反而转移到服务端的接收处理能力上。我做过一个简单对比实验同样一个2GB文件在同一台服务器上并发数(threads)总耗时服务端观察1约持续稳定耗时最长磁盘写压力很低3总耗时最均衡磁盘写压力适中5耗时反而轻微上升CPU占用升高临时文件锁竞争10部分分块超时重试内存和IO明显紧张所以并发数3是我在千兆内网上的首选。如果你们内网是百兆1到2个并发就够了。并发数不是越大越快而是要让服务端能够平滑处理所有分块请求。4.2 超时和重试配置内网也可以更激进WebUploader提供了timeout参数默认是30秒。在公网场景30秒对于大分块来说可能不够但内网里一个5MB分块在正常情况下几百毫秒就能传完。我把timeout设为60秒不是为了给它更多时间而是为了配合失败的自动重试。WebUploader有内置的重试机制关键参数是retry默认是0即不重试。我给每个分块设置了3次重试机会var uploader WebUploader.create({ chunked: true, timeout: 60 * 1000, retry: 3, // ... });这里要提醒一句重试逻辑只对网络连接异常有效。如果服务端返回了明确的业务错误码比如分块校验失败、目录写入失败WebUploader是不会自动重试的。所以在服务端接口设计时你要尽量把可重试的异常比如临时文件锁冲突和不可重试的异常比如参数错误区分开前者返回5xx或特定错误码后者返回4xx。4.3 局域网部署下的Nginx和网关配置在内网系统里前端请求一般也会经过Nginx或其他网关转发。如果WebUploader的请求被网关层面的超时或上传大小限制拦下来你在前端调什么都白搭。我见过最典型的配置问题# 错误示范 client_max_body_size 100m; proxy_read_timeout 60s;client_max_body_size限制的是单个请求体大小。在没有分块上传时这个值必须大于文件总大小但分块之后单个请求体大小就是chunkSize。不过如果你把client_max_body_size设成100MB然后分块大小设了200MB请求依然会被拒掉。所以务必要确认这个值大于你配置的chunkSize。proxy_read_timeout是另一个大坑。如果这个值设成60秒而你的分块传输过程中前端一直有数据在写后端的读超时一般不会被触发。但有些网关代理会为每个请求建立独立的会话缓冲如果并发3个分块同时到达网关处理慢就可能出现某个分块长时间等不到响应的情况。稳妥的做法是把这个值拉到300秒以上。还有一点很多人忽略内网系统的Web服务器通常有访问控制/代理透传前端请求分块时请一定用完整的域名或固定IP不要用localhost或127.0.0.1否则Cookie、Session、跨域策略都可能在网关层出幺蛾子。5. 实测数据与踩坑记录从能传到稳定传方案落地后我在内网环境千兆局域网普通办公PC作为客户端一台业务服务器作为上传端用一份2.6GB的业务数据包做了完整的压力测试。记录下几个关键数据给大家做参考项目测试环境参数实测结果文件大小2.6GB全部上传成功分块大小5MB共分533个分块并发数3总耗时约4分钟断点续传测试传至60%时手动断开网络再恢复从缺失分块继续未重传已传部分完整MD5校验合并后对比完全一致这些数据不代表所有内网都这样但至少说明一个问题方案本身是通的参数也是合理的。5.1 踩坑一合并后的文件MD5对不上怀疑是分块顺序错乱第一次联调时前端明明所有分块都上传成功了合并后MD5却和原文件对不上。排查了半天发现不是顺序错乱而是服务端合并时用了默认的字符缓冲流没有按二进制写。当分块里包含某些特殊字节时流被温柔地处理了文件就被篡改了一部分。排查经验分块合并时务必用二进制流/字节流处理不要用字符流。同时合并后先不要急着删临时分块等MD5校验通过再清理。5.2 踩坑二断电续传失效卡在查询已上传分块接口内网环境经常遇到整机断电重启。有一次用户反馈上传到一半断电重启后重新选同一文件WebUploader没有从断点继续反而从头传了。定位后发现不是WebUploader的问题而是我前端在文件选择后没有主动调用查询接口。WebUploader本身并不知道这个文件服务端已有哪些分块它只会在分块发送时发现某个分块上传成功。要做到续传前端必须在文件开始上传前主动请求查询已上传分块列表然后跳过已存在的分块。正确姿势是在uploadBeforeSend回调里做拦截根据当前分块索引判断是否在服务端已有列表中如果在就返回false跳过这个分块。或者更优雅的做法是查完列表后用uploader.skipFile(file)或调整需要上传的分块队列。这个逻辑必须自己写WebUploader不帮你做。5.3 踩坑三服务端临时目录把磁盘塞满了联调阶段多次测试后我发现磁盘空间越来越紧张。原因很清晰很多分块文件虽然是上传成功的但合并完成后异常中断的临时分块没有清理。这不算bug是工程上的疏忽。我加了一个定时清理任务临时目录下的文件超过24小时没有被修改的分块直接删除。同时合并成功后的临时目录立即清理。加了这两个策略之后磁盘占用被控制在了正常范围。5.4 最终稳定配置清单把整个项目收尾时我在代码注释里记录了一份经实测稳定的配置这里也分享出来var uploader WebUploader.create({ swf: /static/Uploader.swf, server: /api/upload/chunk, pick: #picker, chunked: true, chunkSize: 5 * 1024 * 1024, threads: 3, timeout: 60 * 1000, retry: 3, duplicate: true, fileVal: file, formData: { bizType: dataPackage } });服务端的关键点总结成一条自查清单分块接口接收参数file、chunk从0开始、chunks、fileMd5分块临时存放目录/tmp-upload/{fileMd5}/{chunkIndex}查询接口返回已上传分块索引列表合并接口按索引从小到大二进制拼接合并后计算MD5并校验清理策略24小时过期分块定时清理合并成功后立即清临时目录。每次换新环境部署我都是拿着这份清单逐项核对基本没有再因为上传问题被半夜叫起来过。最后分享一个自查习惯整个项目跑完我最深刻的体会是分块上传和断点续传不是前端组件 后端接口的简单堆叠而是一整套会话状态配合方案。前端负责把文件切块、并发调度、失败重试后端必须配合做分块存储、进度查询、合并校验两边缺一不可。至于排查问题时的思路我也摸出了自己的套路凡是文件能传上去但内容不对优先查服务端合并逻辑和字节流处理凡是传着传着中断且重试无效优先查Nginx的client_max_body_size和proxy_read_timeout凡是续传失败从头开始传优先查前端有没有在发起上传前调用查询已上传分块接口。这三个方向覆盖了我在内网环境下见过的绝大多数上传故障。你们要是也遇到类似场景可以先按这三条线索去排查大概率能省下半天时间。