医疗系统大文件上传：WebUploader分片断点续传与SpringBoot+MinIO实战

医疗行业的系统我做过不少，尤其PACS影像、病理切片、电子病历这类场景，几乎每个项目都会遇到大文件上传的坎。早期做的一个影像归档系统，医生反馈说传一个几百MB的DICOM文件，传到一半网络抖动就断了，又得从头再来；碰上老旧的ie浏览器环境，连控件都加载不出来。后来我用WebUploader做了一套局域网环境下的分片断点续传方案，才把这个问题彻底压下去。今天就把这套思路和踩坑记录完整分享出来，希望对正在做医疗系统或者类似B端系统的朋友有帮助。

1. 医疗局域网下大文件上传的核心矛盾

1.1 医疗场景对文件传输的特殊要求

先别急着聊WebUploader的配置，我们先搞清楚医疗系统文件上传到底特殊在哪。普通的OA系统传个几十MB的附件，断了大不了重传一次，体验差一点但能忍。但医疗系统完全不同，一张CT检查的原始数据往往包含几百张DICOM图像，单次检查的数据量动辄几百MB到几个GB；病理切片扫描出来的WSI文件更是夸张，单个文件就能到几个GB甚至十几GB。

这类文件在医疗局域网里是刚需，不是传着玩儿的。医生在阅片工作站上等着调阅影像，如果上传老是失败，直接影响诊断流程。而且医疗系统对数据完整性要求极高，一张切片少传一个层级，后续AI辅助分析结果就完全不可用。所以这里要解决的不是“能不能传”的问题，而是“传得稳、传得完整、传得快”的问题。

1.2 为什么局域网环境反而更需要断点续传

很多人有个误区，觉得局域网带宽大、网络稳定，就不用考虑断点续传了。实际做过医疗项目就会知道，局域网恰恰是断点续传需求最强烈的场景之一。

医疗系统的网络环境并不像想象中那么理想。老院区的综合布线杂乱，楼层交换机性能参差，无线AP覆盖存在盲区，再加上医护人员使用的终端设备配置老旧，网络波动几乎是无处不在的。更麻烦的是，很多医疗业务系统为了避免非工作时间无人值守，会设置夜间自动归档任务，这些任务跑着跑着就可能因为网络瞬时拥塞中断。

退一步说，就算网络真的稳定，几GB的文件一次性上传，中间医生要开会、要处理急诊，电脑休眠或系统重启是再正常不过的事。没有断点续传，这些场景全部意味着重新上传。所以断点续传不是锦上添花，是这个场景下的必备能力。

1.3 方案选型：为什么最终锁定WebUploader

当时可选的方向其实不少，市面上有plupload、fine-uploader，也有商业的uploadify。我最终选择WebUploader，核心是这么几个考量：

一是兼容性。医疗系统最大的兼容性包袱就是ie浏览器，很多医院信息科至今还在用ie11甚至更低版本访问业务系统，尤其涉及CA数字证书、UKey登录这类场景，Chrome反而用不了。WebUploader基于HTML5 + Flash的降级方案，在ie8+环境都能跑，这点直接卡死了很多纯HTML5方案。

二是分片上传能力内建。WebUploader的chunked分片、并发上传、进度回调都是内置的，不需要自己从头造轮子。在医疗这种人力紧张的项目里，能少维护一套自研逻辑就少一份风险。

三是社区成熟度。WebUploader虽然停止更新好几年了，但毕竟经过海量项目验证，网上的踩坑资料非常丰富。真遇到问题搜一下基本都有答案，这对项目交付周期紧张的医疗项目来说太重要了。

当然，WebUploader也有它的问题，后面我会专门讲适配过程中遇到的坑和解决方案。

2. 分片与断点续传机制的内在逻辑

2.1 分片上传的工作流程拆解

要把断点续传讲清楚，必须先理解分片上传是怎么运作的。整个过程可以拆成四个阶段：

准备阶段：前端读取文件信息，计算文件的唯一标识，通常用MD5值。这个标识是整个断点续传机制的核心，后续所有分片进度都是围绕它来记录的。

切片阶段：把大文件按固定大小切成若干分片，每片都有一个序号，从0开始递增。比如一个500MB的文件，按10MB一片切，就得到50个分片。

上传阶段：前端逐个（或并发几个）上传分片，每个分片单独发起HTTP请求，请求头里带上文件标识、分片序号、总分片数这些元信息。

合并阶段：所有分片上传完成后，前端通知后端执行合并操作，后端按分片序号把临时文件依次拼接成完整文件，再做完整性校验。

WebUploader在切片后还会维护一个队列，已经上传成功的分片会被标记为“完成”状态，上传失败的分片自动重试。这就是断点续传的物理基础——细粒度的分片让“续传”变成了“从未完成的分片接着传”，而不是从整个文件的头部重新传。

2.2 断点续传如何精准识别已传分片

这里要重点说说断点续传的识别机制，也是很多初级开发者容易搞混的地方。WebUploader的断点续传并不是靠文件名来判断，而是靠文件内容的MD5值。

计算一次MD5并不便宜，一个1GB的文件可能要算十几秒甚至更久。所以WebUploader的处理方式是：先在本地计算一次完整文件的MD5，这个值作为文件的唯一指纹；上传前先向后端发送一个查询请求，携带MD5值，询问这个文件的哪些分片已经存在；后端查完记录后返回一个已上传分片序号列表；前端拿到结果后，把未上传的分片加入上传队列即可。

这个机制和“秒传”是同一套逻辑。如果查询发现所有分片都齐了，后端甚至可以跳过合并阶段直接返回成功，这就是用户感知到的“秒传”。

需要强调一点：MD5碰撞的概率虽然极低，但在医疗场景下我建议还是要配合文件大小做双重校验，避免把两个恰好MD5相同的不同文件混在一起。

2.3 并发度与分片大小的权衡

分片大小和并发数是影响上传体验的关键参数。WebUploader默认配置偏保守，但实际项目中必须根据网络环境调优。

以医疗局域网千兆网络为例，我常用的配置是分片10MB、并发3。算一下：千兆局域网的理论带宽125MB/s，实际打六折也有75MB/s左右，10MB的分片上传单片大概需要0.13秒；并发3个请求，理论上可以做到接近30MB/s的有效吞吐。这个参数组合下，1GB的文件大约30多秒传完，速度和稳定性达到了比较好的平衡。

如果分片太小（比如1MB），分片数量会剧增到上千片，每片都需要独立的HTTP请求和数据库记录，请求开销和调度成本反而拉低整体速度。如果分片太大（比如100MB），一旦某片中途失败重传的成本就很高，弱网环境容易卡在一两个大分片上反复失败。

并发数也不是越大越好。并发太高的直接后果是客户端电脑CPU和内存飙升，尤其医疗终端往往还是老旧PC，本来跑着阅片软件就吃力，再开十几个并发上传线程，直接卡死。我在测试环境试过并发10，文件传得确实快了一些，但操作电脑的医生反馈整个系统非常卡顿，立刻改回3。

2.4 一个容易忽略的细节：分片超时与重试策略

网络请求没有100%成功的，分片重试策略是在项目上线后根据实际运行数据调整出来的。我刚上线时的配置是失败重试3次，每次间隔2秒。结果发现一个问题：某个分片如果因为交换机端口拥塞失败，2秒后大概率还是失败，连续重试3次都失败后这个分片就被丢弃了，整个上传任务报错。但实际网络只是短暂拥塞，过个几秒就能恢复。

后来我把策略改成了渐进式重试，第一次失败后等2秒，第二次失败后等5秒，第三次失败后等10秒，最多重试5次。这样既不会在短时故障时疯狂重试浪费带宽，也给了网络恢复留足时间。实测失败率下降了约60%，运维那边收到的上传失败工单明显减少。

3. 后端落地方案：SpringBoot与MinIO的整合

3.1 核心接口设计与状态流转

WebUploader只解决前端的问题，真正的分片合并、进度记录和文件存储逻辑还得后端承担。后端我采用的是SpringBoot + MinIO的组合，MinIO负责最终的文件存储，SpringBoot负责分片接收、元数据管理和合并编排。

整个后端接口分成四组：

第一组是文件预检接口。接收前端传来的MD5值、文件大小、文件名，检查数据库里有没有已存在记录。如果文件已完整存在，直接返回“秒传”标识，前端不再执行任何上传。

第二组是分片上传接口。接收单个分片文件，同时接收文件MD5、分片序号、总分片数等元信息，把分片保存到临时目录或MinIO的临时bucket。每个分片上传成功后，数据库记录一条分片完成记录。

第三组是分片校验接口。前端某个分片上传失败后重试前，会调用这个接口询问该分片是否已经存在，避免重复上传。

第四组是合并接口。前端所有分片上传完成后调用，后端启动合并流程。

状态流转我整理成了这样一张表，方便排查问题：

3.2 分片写入与文件合并的实现要点

分片写入我建议直接写MinIO，而不是先落本地磁盘再同步。这样做的原因有两层，一是MinIO天然支持分片对象，具备断点续传和多级容错能力，省去了自己管理临时文件的麻烦；二是MinIO的临时bucket可以设置生命周期策略，比如48小时自动清理，这样即使某个上传任务中途废弃了，残留分片也不会成为磁盘垃圾。

合并阶段要注意，逐个从MinIO拉取分片再拼接到本地文件，最后再把完整文件传回MinIO，这个过程有两次网络IO，效率不高。我采取的是更好的方式：让MinIO服务端基于相同前缀的分片对象执行Combine操作，类似S3的Multipart Upload语义，整个合并过程在存储服务内部完成，应用服务器只发起指令，不承担数据搬运。

每次合并完成后强烈建议做一次文件大小比对。前端在上传前已经把文件大小记录在预检表里，合并端拿到最终文件后比对大小，不一致直接标记FAILED并清理产物，不要想着“差不多就行”。在医疗系统里，数据的准确性和完整性没有任何妥协空间。

3.3 内存溢出的防治：流式处理是关键

热词里有人问“大文件分片上传会OOM吗”，答案非常明确：会，而且如果代码写得不对，基本必然OOM。

最常见的错误写法是把每个分片都读成byte[]，再累积起来合并。一个2GB的文件，就算分100片，每片20MB，如果合并时把所有分片一次性加载进内存，瞬间就是2GB内存被占用，应用服务器必然崩溃。

我的做法是全程流式处理。分片接收时用InputStream直接写入MinIO，不做内存缓存；合并时用流式读取一个分片写一个分片，ProcessBuilder去调MinIO客户端命令或者直接用SDK的流式API。关键点是：任何时刻，只有当前正在处理的这个分片占内存，其他分片都躺在磁盘或对象存储里。

JVM参数也应适当调整。我们的服务是8GB内存的容器，堆设置-Xms4g -Xmx4g，预留了足够的堆外内存和系统内存给网络和IO缓冲。如果你在只有2GB内存的小机器上跑，分片大小建议降到5MB，否则并发3个分片同时写入，每个分片还要走网络缓冲，内存压力会很难看。

3.4 为什么选MinIO做存储底座

细心的读者会问，既然用了SpringBoot，直接存本地文件不就行了，为什么非要引入MinIO？

不是不行，但医疗项目的长期运维会很难受。本地磁盘方案意味着所有文件都在应用服务器的硬盘上，一旦磁盘满了或者服务器坏了，文件全丢，而且多台应用服务器之间文件不共享，负载均衡轮流处理请求时就会出现“这台服务器有文件，另一台没有”的尴尬。

MinIO是对象存储，天然就是分布式的，多个节点之间自动同步，文件上传到一个节点后其他节点立即可见；同时它具备纠删码能力，允许一部分磁盘损坏而不丢数据。医疗系统7x24小时运转，数据保存年限要求高，对象存储的可靠性远优于本地磁盘。

当然MinIO也不是银弹，它有自己的学习曲线和运维要求，但对于我们这种动辄TB级影像数据的场景，这个补偿完全值得。

4. 前端适配与WebUploader参数调优

4.1 WebUploader核心配置项与推荐值

WebUploader的配置项非常多，但真正影响大文件上传体验的就那么几个。我把医疗场景下实测过的最佳配置整理成一个参考示例：

javascript复制var uploader = WebUploader.create({
    swf: '/static/Uploader.swf',
    server: '/api/medical/upload/chunk',
    pick: '#picker',
    accept: {
        title: 'MedicalFiles',
        extensions: 'dcm,jpg,png,svs,tif',
        mimeTypes: 'image/*,application/octet-stream'
    },
    chunked: true,
    chunkSize: 10 * 1024 * 1024,
    threads: 3,
    fileVal: 'file',
    formData: {
        storageType: 'pacs'
    },
    fileNumLimit: 10,
    fileSizeLimit: 10 * 1024 * 1024 * 1024,
    duplicate: true
});

几个参数值得重点解释。chunked: true是总开关，关掉分片上传后面的断点续传全免谈；chunkSize是每个分片的大小，单位是字节，医疗局域网我推荐10MB；threads是并发上传数，设置为3是稳定性和速度的平衡点；fileSizeLimit限制单文件最大10GB，可以按需调整，但注意这个参数是给用户提示用的，后端必须做同等的限制，不能只靠前端。

4.2 老IE环境下的兼容处理

前面说过医疗系统绕不开IE兼容，这里详细讲怎么适配。WebUploader在IE下的原理是走Flash通道，所以有两个前置条件必须满足：一是页面上要正确引入swf文件路径，二是浏览器要允许运行Flash插件，且管理后台-Internet选项-安全设置里要允许Script ActiveX，否则控件根本不被加载。

另一个典型问题是IE下Flash上传时中文文件名乱码。这个问题本质是编码格式不统一，WebUploader在Flash模式下使用GBK/GB2312编码请求体，而后端默认按UTF-8解码，导致接收到的文件名全是乱码。解决办法是在后端对Flash通道单独做一次编码转换，或者对文件名的编码格式做统一约定后转换回UTF-8。

我在前端的处理方式是，在uploadBeforeSend钩子里，统一把文件名转码：

javascript复制uploader.on('uploadBeforeSend', function (block, data) {
    data.fileName = encodeURIComponent(file.name);
});

后端在SpringBoot里解码时主动处理：

java复制String fileName = URLDecoder.decode(request.getParameter("fileName"), "UTF-8");

这样在IE和Chrome下都能拿到正确的中文文件名。

4.3 局域网弱网场景的前端降级策略

医疗局域网的网络质量虽然比公网好，但也承担不起全员同时上传大文件时的带宽冲击。高峰期住院部护士站同时上传患者影像，千兆交换机的背板带宽也可能被打满。

我做了一个非常简单的带宽自适应逻辑：上传前先做一次小文件的探速，比如先传一个200KB的测试块，根据耗时估算当前网络的可用带宽。带宽低于某个阈值时，自动把并发数从3降到1，分片大小从10MB降到5MB。带宽恢复后再逐步调回去。

这样做的收益很明显，高峰期整网卡顿的概率大幅降低，而且每个上传任务的完成时间并没有显著变长，因为降低并发本来就是为了避免拥塞导致的重传浪费。在弱网下，慢就是快。

5. 全程踩坑实录与问题排查速查表

5.1 实战中高频出现的六个问题

第一个是MD5计算阻塞主线程导致页面假死。WebUploader的md5计算是纯前端逻辑，大文件计算时间长，如果同步执行会卡死界面。解决方法是把MD5计算放到Web Worker里，计算完成后回调主线程再启动上传。我在一个4GB的WSI文件上实测，主线程直接算MD5会让浏览器卡顿近30秒，改成Worker后台计算后页面完全没影响。

第二个是后端分片接收时临时目录权限问题。Linux下Tomcat运行用户对临时目录没有写权限，会在上传分片时报IOException。排查方法很简单，看Tomcat的catalina.out日志，找不到就调整上传目录权限。

第三个是分片合并时文件顺序错乱。数据库记录的分片序号是字符串类型，排序时按字典序排，第10片排到了第2片前面。这个坑尤其隐蔽，因为小文件分片少看不出问题，文件一旦超过10片就必然出错。解决方式是对分片序号做Integer转换后再排序。

第四个是前端进度条回跳。WebUploader默认的进度条按已上传分片数计算，分片重传或并发上传时进度条会出现回退、忽快忽慢的现象。解决方法是自定义进度计算逻辑，只统计已成功完成的分片，已上传分片数除以总分片数按百分比展示。

第五个是MinIO端口被防火墙拦截。服务器上MinIO默认监听9000端口，但运维侧防火墙默认只放行80和443，导致前端分片写入MinIO直接超时。这个排查起来最费时间，因为应用日志里看到的可能是上传超时的表象，实际是底层访问不通。

第六个是WebUploader的Flash模式在HTTPS页面下被浏览器拦截。现在越来越多的医院内网改HTTPS，但Flash运行需要安全策略授权。还好医疗系统通常走的是HTTP内网，暂时影响可控，但从长远看各厂商都在去Flash化，建议后续架构里逐步切换为核心浏览器方案。

5.2 问题排查速查表

为了让你在日常维护中能快速定位问题，我把常见现象、可能原因和解决动作整理成了表格：

5.3 基于实际项目的一些经验反思

项目做完之后复盘，有几个经验值得分享给正在做同类项目的人。

第一，合理取舍实时性。上传进度实时推送确实能提升体验，但如果在医疗内网里每个分片都要推一次WebSocket更新，高峰期对服务器的压力不小。我们最终设置成每完成3个分片推送一次进度，体验差别很小，后端压力降了一大截。

第二，安全机制不能因为内网就省略。医疗数据是敏感数据，用户认证、上传权限校验、请求报文加密这些环节，不能因为跑在局域网里就全部省略。宁可在开发时多花点时间，也不要在上线后等审计发现问题再补。

第三，监控和告警必须有。上传成功率、平均上传耗时、失败分片数这些指标，都要埋点统计并可视化。我们当时接入了内网的监控看板，上传成功率低于阈值就自动告警，运维可以在医生察觉之前发现潜在问题。

第四，备份策略要想清楚。MinIO虽然自带数据冗余，但整个bucket被误删或者被勒索病毒加密的情况并不少。在存储层面之外，定期做冷备、异地快照，是医疗系统不能省的功夫。

6. 一点实操心得

回头再看这个项目，WebUploader本身只是一个工具，真正让方案跑稳的是对它运行机制的理解，以及对医疗场景特殊性的尊重。分片、断点续传、MD5指纹、合并策略、存储底座，每一环都要配合得严丝合缝，少了任何一环，表面上传功能正常，一遇到真实网络状况就原形毕露。

最后分享一个我一直在用的小技巧：任何大文件上传方案上线前，一定要准备一组测试用例，覆盖文件大小、分片数量边界、网络抖动、服务端重启、并发上传等场景，并且把测试结果记录成文档。这个文档在后续排障时能省下大量时间，尤其是当你需要向医院信息科解释“为什么上传会失败”的时候，一份清晰的测试记录比任何口头解释都有说服力。