SpringCloud微服务大文件断点续传：分片上传与完整性校验

军工系统里最容易被低估、却又在关键时刻卡住整个业务链条的需求，往往是“把一个文件老老实实传完”。这类系统里，设计图纸、试验记录、质量影像、工装工艺文档，单个文件动辄几百MB甚至几个GB，而且普遍跑在内网专线上，链路抖动、网络割接、临时维护随时可能掐断上传。用SpringCloud搭起来的微服务架构，在大文件上传面前尤其容易露怯：网关超时、内存飙升、分片合并错乱、断点之后找不到进度。这篇文章把我在这类高可靠系统中落地大文件续传方案的完整思路写出来，重点讲清楚分片接口怎么设计、Redis怎么记录上传进度、合并时怎么校验文件完整性，以及高安全环境里绕不开的传输加密、审计留痕和离线部署适配。无论你是在改造企业内部传输平台，还是接手一套严苛可用性要求的文件交换系统，这套方案都可以直接参考。

1. 军工场景的“文件续传”为什么难——相比普通断点续传，差在哪

1.1 真实业务里的文件到底有多大

我接触过的内部数据交换系统，文件来源非常杂：有现场终端定时回传的数据包、有质检环节录制的检测影像、有设计部门导出的三维模型、还有批量生成的测试日志。单文件体积集中在500MB到10GB这个区间，偶尔还有几十GB的大包。网络环境并非大家想象的“内网一定又快又稳”，实际的跨路由专网带宽通常在80~150Mbps之间波动，更麻烦的是连接极不稳定——设备重启、网关切换、安全策略更新，都可能让一个传了半天的任务瞬间归零。

在我们替换掉U盘和共享文件夹之前，日常操作基本靠人肉拷贝，然后手工导入系统。这种模式有两个硬伤：第一，文件不经过系统，后续的版本管理、审批流程、行为审计全部断链；第二，拷贝过程本身没有校验，拷一半拔了U盘，数据损坏了还得依赖人工发现。所以后续上线一套统一上传通道是必然选择，而大文件传输能力就是这里面最基础也最关键的一环。

1.2 普通表单上传为什么会在微服务里崩

很多开发团队第一版都会直接用multipart/form-data方式做文件上传，单机架构下传几十MB的小文件问题不大，但放到SpringCloud体系里传几GB文件就会暴露出一串连锁问题。

首先是网关超时。SpringCloud Gateway默认的响应超时时间并不适合大文件场景，流量经过网关再转发到上传服务，网络稍有波动就触发超时，前端收到的就是一个天折的请求。其次，JVM内存扛不住。如果上传接口把整个文件读入内存再处理，并发三四个GB级上传，堆内存直接被打满，频繁Full GC会让整个微服务集群的响应都变得极慢。第三是失败成本高。专线网络中断一次，前端只能从零开始重传，十万兆的流量有九万兆是白传的，运维侧很难接受。

1.3 续传方案的本质：把大文件拆成可独立校验的小块

所以要解决的不是“把断点续传做成PDF阅读器那种记忆位置”，而是要让每一次网络恢复后，服务端都能精确告诉客户端“你现在缺哪几块，补这几块就行”。这个诉求落到技术上就是分片上传：客户端把文件平分成固定大小的分片，逐片请求上传；服务端收到分片后立即持久化，并记录哪些分片已经完成；全部完成后触发合并，合并时做整体校验。

这里有一个容易被忽略的前提：分片必须独立可校验。每个分片上传成功后，服务端要能单独确认这个分片完整、位置正确、内容没被篡改。如果分片本身不带校验信息，合并时才发现数据坏了，那所有分片都得重传，续传就没有意义了。所以我在设计时给每个分片都加了独立的MD5校验，服务端保存分片时先验一遍，不合格直接拒绝并返回错误码。

2. 基于SpringCloud的大文件续传架构与存储选型

2.1 整体链路与组件分工

我们的系统采用SpringCloud微服务架构，文件上传链路大致是这样：前端客户端把分片请求发给SpringCloud Gateway网关，网关做完鉴权和路由后转发给独立的文件上传服务（upload-service），上传服务负责接收分片、更新Redis进度、把分片落到临时存储，最终由异步合并任务生成正式文件并登记到数据库中。整体链路拆成五个角色：

2.2 分片临时数据到底放哪里——这是最容易拍脑袋的决策

分片数据放哪里，直接决定了系统能不能扛住大文件和并发。我见过两种极端做法：一种是把分片存在Redis里，理由是“Redis快”，结果几十GB文件切成上千片，Redis内存直接被塞爆；另一种是全部放数据库BLOB字段，最后数据库体积膨胀到无法备份。这两种都属于拍脑袋。

更务实的做法是：Redis只存元数据，分片二进制内容落到独立的临时文件目录或者对象存储桶里。元数据里记录的是sessionId、文件总大小、分片总数、已收到分片索引集合、当前状态，这部分数据量极小，一个几GB的文件对应Redis里也不过几百字节到几KB。分片文件则用sessionId/chunkIndex.part这种命名方式平铺在临时目录中。

如果系统有对象存储条件，我更建议把临时分片直接丢到MinIO或者同等产品里。理由很简单：文件服务实例经常要扩容缩容，如果分片只存在某个节点的本地磁盘，负载均衡把请求切到另一台机器，那台机器根本找不到已上传的分片。对象存储天然是共享的，所有实例读写同一份分片数据，服务的无状态性就保住了。没有对象存储的单机部署环境，至少要把临时目录放在共享存储上，或者用NFS挂载，否则后续运维会非常酸爽。

2.3 Redis里的进度模型：一个key把会话状态说清楚

Redis里我设计了两种Key来管理上传会话。第一个是上报会话主记录：upload:session:{sessionId}，用Hash结构保存文件基本信息，包括fileName、fileSize、chunkSize、chunkTotal、md5、status、createTime等字段。第二个是分片完成标记：upload:chunks:{sessionId}，用Set结构保存所有已完成分片的索引，比如{0,1,2,5,7}。客户端查询进度时，只要对比Set里的分片索引和总数，就知道还差哪几片。

这里有个关键点：Redis虽然快，但默认的缓存逐出策略可能把上传进度丢掉。所以在高可靠场景下，我给上传会话Redis开启了AOF持久化，并且把maxmemory-policy设置为不淘汰（noeviction）。另一个更保险的玩法是双写，Redis记录热数据用于快速查询，MySQL表记录上传会话的最终状态，保证重启后依然能恢复。后面第4节我会专门展开讲恢复逻辑。

2.4 负载均衡的亲和性陷阱

前面提到分片最好放共享存储，这里补充一个与之相关的架构细节：即便分片都在对象存储里，上传合并任务也要避免“每个节点各自合并”造成资源竞争。通常我会引入消息队列，upload-service收到最后一篇分片后，不直接在本机做合并，而是向队列发一个合并任务。合并消费者由专门的任务实例处理，这样大文件合并时的IO压力就被隔离了，不会拖垮正在接收分片的上传实例。

如果你们没有消息队列，也至少要在代码里通过分布式锁保证同一个sessionId只允许一个节点执行合并。我见过并发场景下两个节点同时合并同一个session，最终文件被覆盖成损坏状态，这个坑后文详述。

3. 续传接口设计：初始化、上传分片、合并校验

3.1 会话初始化接口：先把“契约”定下来

客户端上传前先调初始化接口，把文件的元信息告诉服务端，服务端返回一个全局唯一的sessionId。这个设计类似签合同：先约定文件多大、分多少片、每片多大、总体MD5是多少，后续所有分片都围绕这份契约执行。

java复制@PostMapping("/upload/init")
public UploadSession initUpload(@RequestBody UploadInitRequest request) {
    String sessionId = UUID.randomUUID().toString().replace("-", "");
    String fileMd5 = request.getFileMd5();
    // 判断是否已存在相同文件的上传记录，用于断点续传
    UploadSession existed = uploadMapper.selectByMd5(fileMd5);
    if (existed != null && "COMPLETED".equals(existed.getStatus())) {
        return existed; // 同一文件已传完，直接返回原记录
    }
    UploadSession session = new UploadSession();
    session.setSessionId(sessionId);
    session.setFileName(request.getFileName());
    session.setFileSize(request.getFileSize());
    session.setChunkSize(request.getChunkSize());
    session.setChunkTotal(request.getChunkTotal());
    session.setFileMd5(fileMd5);
    session.setStatus("INIT");
    // 写MySQL，同时写Redis
    uploadMapper.insert(session);
    redisTemplate.opsForHash().putAll("upload:session:" + sessionId,
            Map.of("fileName", request.getFileName(),
                   "fileSize", String.valueOf(request.getFileSize()),
                   "chunkSize", String.valueOf(request.getChunkSize()),
                   "chunkTotal", String.valueOf(request.getChunkTotal()),
                   "md5", fileMd5,
                   "status", "INIT"));
    return session;
}

这里有一个容易被漏掉的逻辑：初始化时用fileMd5做一次去重。客户端用户在断网重试时，如果什么都不带地重新发起上传，服务端应该识别出这是同一个文件，直接返回已有进度，而不是新建session。判断方式可以选“用户维度+文件MD5”，也可以放宽到“全局MD5”，但要小心不同用户传同一个文件时权限隔离的问题，实际按业务需求取舍。

3.2 分片上传接口：接收、校验、落盘、记进度

分片上传是整个方案的承重墙。每次请求携带sessionId、chunkIndex、分片内容和分片MD5，服务端要做的四件事缺一不可：校验分片大小和索引范围、校验分片MD5、持久化分片到临时存储、更新Redis完成标记。

java复制@PostMapping("/upload/chunk")
public UploadProgress uploadChunk(UploadChunkRequest request) {
    String sessionId = request.getSessionId();
    Integer chunkIndex = request.getChunkIndex();
    MultipartFile file = request.getFile();
    // 1. 校验session状态
    UploadSession session = checkSession(sessionId);
    if (session == null || !"INIT".equals(session.getStatus()) && !"UPLOADING".equals(session.getStatus())) {
        throw new UploadException("会话不存在或状态不允许上传");
    }
    // 2. 校验分片索引是否合法
    if (chunkIndex < 0 || chunkIndex >= session.getChunkTotal()) {
        throw new UploadException("分片索引越界");
    }
    // 3. 校验分片MD5
    String chunkMd5 = DigestUtils.md5DigestAsHex(file.getBytes());
    if (!chunkMd5.equals(request.getChunkMd5())) {
        throw new UploadException("分片数据校验失败");
    }
    // 4. 持久化分片到MinIO或临时目录
    String chunkObjectName = "upload/" + sessionId + "/" + chunkIndex + ".part";
    minioClient.putObject(
        PutObjectArgs.builder()
            .bucket("file-temp")
            .object(chunkObjectName)
            .stream(file.getInputStream(), file.getSize(), -1)
            .build());
    // 5. 标记分片完成
    redisTemplate.opsForSet().add("upload:chunks:" + sessionId, String.valueOf(chunkIndex));
    // 6. 返回当前进度
    return getProgress(sessionId);
}

有几个实操细节值得强调。一是分片大小到底取多少合适，我在实际系统里经过多轮压测，最终选的是8MB到16MB。分片太小时请求数量太多，网关和连接开销反而拖慢整体速度；分片太大时网络中断一次损失过大，也容易触发网关body大小限制。二是接口的返回值一定要包含“已完成分片集合”或者“缺失分片集合”，这样客户端每传一片都能本地更新进度，做到即使前端页面刷新，也能瞬间恢复状态。

3.3 合并与校验：最后一个分片到达后干什么

当客户端发现所有分片都已上传成功，就调用合并接口。合并接口首先从Redis拿到分片总数，逐个读取临时分片，按索引顺序写入最终文件，然后对最终文件计算MD5，与会话初始化时登记的全局MD5比对。

java复制@PostMapping("/upload/merge")
public FileEntity mergeUpload(@RequestParam String sessionId) {
    UploadSession session = checkSession(sessionId);
    int chunkTotal = session.getChunkTotal();
    // 校验是否所有分片都已到达
    Long doneCount = redisTemplate.opsForSet().size("upload:chunks:" + sessionId);
    if (doneCount == null || doneCount != chunkTotal) {
        throw new UploadException("分片不完整，无法合并");
    }
    // 创建输出流，按索引顺序合并
    String finalDir = "/data/files/" + LocalDate.now().toString();
    Files.createDirectories(Paths.get(finalDir));
    String finalPath = finalDir + "/" + session.getFileName();
    try (OutputStream out = Files.newOutputStream(Paths.get(finalPath))) {
        for (int i = 0; i < chunkTotal; i++) {
            String chunkObjectName = "upload/" + sessionId + "/" + i + ".part";
            try (InputStream in = minioClient.getObject(
                    GetObjectArgs.builder()
                        .bucket("file-temp")
                        .object(chunkObjectName)
                        .build())) {
                IOUtils.copy(in, out, 16 * 1024 * 1024);
            }
        }
    }
    // 合并后整体校验
    String finalMd5 = DigestUtils.md5DigestAsHex(Files.newInputStream(Paths.get(finalPath)));
    if (!finalMd5.equalsIgnoreCase(session.getFileMd5())) {
        throw new UploadException("文件完整性校验失败，合并异常");
    }
    // 更新数据库状态，登记文件元数据
    FileEntity fileEntity = new FileEntity();
    fileEntity.setSessionId(sessionId);
    fileEntity.setFileName(session.getFileName());
    fileEntity.setFilePath(finalPath);
    fileEntity.setFileMd5(finalMd5);
    fileEntity.setFileSize(session.getFileSize());
    fileEntity.setCreateTime(LocalDateTime.now());
    fileMapper.insert(fileEntity);
    // 清理临时分片
    deleteTempChunks(sessionId);
    return fileEntity;
}

合并接口同时要承担“防重复合并”的职责。我用Redis的setnx做了一个简单的合并锁：以upload:merge:lock:{sessionId}为key，能成功设置表示当前节点拿到合并权限，设置失败说明已有其他节点在合并，直接返回“合并任务已提交”。合并完成后删除锁和临时分片，避免垃圾数据堆积。

3.4 客户端如何配合服务端完成断点续传

服务端把接口设计好了，客户端那边的配合也同样关键。前端我用的是基于fetch的分片上传逻辑：加载文件后按chunkSize切片，逐个（或并发少量几个）上传。每次上传分片前先查一次/upload/status?sessionId=xxx，拿到缺失分片列表，只补传缺失的部分。页面刷新后再次进入上传页，也先调这个接口恢复进度。

这里顺便说一个我在对接浏览器客户端时踩的坑：fetch上传分片时直接用FormData没有问题，但如果切到axios并设置了全局的Content-Type: application/json，分片内容会被JSON序列化，二进制数据直接损坏。文件上传请求必须使用浏览器自动生成的multipart/form-data边界，不能手动固定。

4. 一致性、幂等性与进度恢复：续传最要命的三个坑

4.1 分片重复上传会不会导致数据错乱

高并发的分片上传里，网络超时后客户端常常会重试同一个分片。如果没有幂等设计，两次写同一个chunkIndex.part文件就可能产生覆盖写，极端情况下出现半个旧分片+半个新分片拼接的错误文件。我在设计时用“先查重、后写入”的规则规避了这个问题：写入分片前先看Redis的Set里是否已包含该索引，如果包含就直接返回成功，不再写文件；如果不包含，才执行写入，写入完成后再添加Set成员。

这里要特别提醒：先写存储、后写Redis的顺序不能反。如果先标记Redis成功再写存储，中途宕机就会出现“Redis说分片有了、实际文件不存在”的假成功，合并时必然失败。反过来，即使写入后Redis更新失败，客户端重试同一分片，服务端检查Set里没有该索引，会重新写入覆盖原分片，数据依然是完整的，只是多一次IO而已。

4.2 服务重启后进度怎么恢复

高可靠系统不可能不重启。为了更新补丁、调整参数，应用节点经常要滚动重启，如果Redis只是普通缓存，分片进度就会全部丢失，用户就得从头传。我在线上系统里用了一套“Redis+MySQL双保险”的恢复策略。

Redis负责热数据，上传过程中秒级查询进度都走它；MySQL里的upload_session表则是兜底，每次分片状态变更时异步更新数据库的chunk_done计数。应用启动时，写到Redis的键带上过期时间（比如一个会话允许24小时内完成），但MySQL记录不过期。恢复流程是这样的：客户端带着sessionId来查进度，如果Redis键已过期不存在，upload-service就从MySQL查出这个会话的总分片数和已完成分片标记，再把进度重建到Redis。

有些人可能觉得异步更新数据库会增加复杂度，但只要把更新操作做成批量异步提交，对性能影响几乎可以忽略。考虑到军工系统对数据可靠性要求高，这笔复杂度我认为是值的。

4.3 合并时的并发打架和最终校验

最后一个分片传到一半时，用户手滑多点了一次“合并”，或者两个客户端同时操作同一个会话，这种释放会出现在正式环境里。还有更隐蔽的情况：两个不同会话上传同一个文件，服务端判重逻辑没写好，两个会话的临时分片错乱到同一个对象名前缀，最终合并出来的文件就坏了。

我的处理方式是三管齐下。第一，合并锁必须有，且锁的作用域要包含“合并的整个过程”，而不是只在接口入口点一下。拿到锁后，合并操作全程持有，完成后才释放。第二，相同文件的判重不能只看文件名，必须看文件MD5和文件大小，这两个字段同时相等才认为是同一文件。第三，合并完成后做最后一层整体校验，校验不过就抛异常并保留临时分片，让客户端重新触发上传流程。这样即使前面哪一环出了问题，也不会把损坏文件登记到正式库。

5. 高安全环境下的传输加密、审计与内网部署适配

5.1 传输链路与文件本身的加密

军工业务系统对数据安全的要求不是“可有可无”的装饰，而是硬约束。分片上传过程中，如果只是裸HTTP传输，文件内容在链路上等于是明文，这在安全审计中肯定过不了关。第一道防线是TLS加密，所有经过网关的请求必须走HTTPS，证书统一由内部CA签发。第二道防线是文件本身加密，上传接口接收到的分片不直接落盘，而是先经过一个加密层处理，密钥从独立的密钥管理服务获取，存储侧保存的是密文分片。

落地方式不复杂：每个上传会话生成一个临时对称密钥，分片写入前用AES-256-GCM加密，密钥存在会话记录里。合并时读取密文分片，解密后写最终文件。这样即使存储介质被拷走，没有密钥也还原不出原始文件。有一点要提醒读者：不要把密钥硬编码在配置文件里，那样加密形同虚设，务必接入密钥管理服务，或者至少做到环境变量注入并定期轮换。

5.2 鉴权、权限控制与审计留痕

上传链路经过SpringCloud Gateway时，网关会先做统一鉴权，用户在网关拿到经过签名的令牌，后续分片请求都带着令牌走。upload-service侧的过滤器会校验令牌合法性，并判断当前用户是否拥有该sessionId的操作权限——不能让A用户带着B用户的sessionId去上传分片或触发合并。

审计方面，我强烈建议把上传操作的全生命周期记录下来：谁在什么时间初始化了上传、哪个IP传了哪些分片、每个分片的大小和MD5、合并最终结果、文件删除操作，全部追加到独立的审计日志表。这些数据平时不参与业务查询，但一旦出现泄密或数据篡改争议，它就是唯一的追溯依据。审计日志本身不能允许业务开发人员随意修改，写权限只开放给文件服务这一个入口。

5.3 内网离线环境下的部署与升级适配

军工系统的部署环境往往是隔离的，内网无法访问外网公共仓库，所有依赖包都需要提前准备好，支持离线安装。SpringCloud组件的版本选型不能随手用最新版，要在一开始就选定一个相对稳定且依赖互相兼容的版本组合，把制品库整体同步到内网。我在项目里还专门做了“离线依赖清单”，包括Spring Boot、Spring Cloud Alibaba、MinIO客户端、Redis客户端这些核心库的版本号和依赖树，方便后续在新环境重建。

另一个离线环境适配点是文件存储路径的规划。不同服务器的磁盘挂载点不一定相同，不能把分片路径写死成/tmp或/data，而应该通过配置中心下发，让每台实例各自适配。我在配置中心维护了一个file.storage.local-path的配置项，按环境分组管理，新节点接入时只需改配置，不用动代码。

6. 实测调优与踩坑记录：一些必须写进文档的血泪经验

6.1 JVM内存被分片上传击穿

第一次压测时，我们模拟10个客户端并发上传3GB文件，结果upload-service在merge阶段直接OOM。事后分析发现，合并代码里用了一个List<InputStream>把所有分片的流一次性打开，再循环写入，文件分片多的时候句柄和缓冲全堆在内存里，不炸才怪。

修正方案是流式串行合并：打开一个分片流，写入目标文件，关闭该流，再打开下一个。虽然IO次数变多，但内存峰值从“所有分片总和”降到“单个分片大小+缓冲大小”，对JVM友好得多。另外给合并任务单独设置了线程池，最大并发数限制在2~3个，避免合并任务把接收分片的主线程池挤爆。

6.2 网关默认配置把分片请求拦在半路

SpringCloud Gateway默认的请求体大小限制很保守，我们第一个版本传8MB分片直接被拒，返回413错误。排查时费了一点时间，因为网关日志没有明显异常，只有前端看到上传失败。解决办法是在网关的全局配置里调大spring.codec.max-in-memory-size，同时显式设置路由级别的请求体限制。如果是Nginx前置代理，还要同步调大client_max_body_size。

这里我建议把分片大小和网关限制设计成联动配置：分片8MB时，网关限制至少要留到16MB以上；如果以后改分片大小，一定要记得同步改网关，否则上线当天就会收到一堆上传失败告警。

6.3 MD5校验失败率为什么突然升高

联调阶段出现过一批分片MD5校验失败，抓包对比后发现前端计算的MD5和服务端拿到的不一致。根因是中间链路上的某个安全设备开启了透明代理并对传输内容做了重组，导致分片到达服务端时字节顺序发生了变化。这个问题在普通互联网环境几乎不会出现，但在强管控的内网里却很常见。

解决方案有两层：第一，传输层全部走TLS，让安全设备无法对加密流量做内容重组；第二，应用层保留分片MD5校验，一旦发现校验失败立即返回错误码并让客户端重传，不静默接受。很多团队觉得MD5校验是多此一举，但在强管控网络里它就是最后一道数据完整性防线。

6.4 临时分片目录被写爆，以及遗漏的清理机制

另一个运维事故是某个节点的临时目录磁盘使用率达到100%，导致所有上传请求失败。原因是上传任务中断后，会话一直停在UPLOADING状态，临时分片没有自动清理机制，日积月累把磁盘塞满了。后来我加了一个定时清理任务：每小时扫描一次临时分片目录，凡是关联会话处于INIT或UPLOADING状态且超过24小时没有新分片写入的，先删除分片记录再清理文件，同时更新会话状态为EXPIRED。

清理任务要特别注意不能误删正在上传的活跃会话。判断依据最后写入时间而不是创建时间，因为一个断断续续传了20小时的会话，只要最近1小时内有新分片写入，就应该保留。这个阈值可以根据业务容忍度调节，但定时清理的机制必须有，否则存储迟早会爆。

最后再分享一个我自己体会很深的点：大文件续传方案从来不是一个纯后端工程，它从接口设计到存储选型再到运维策略，是一条完整的链路。如果你刚接手这类系统，不要急着写代码，先把分片存储位置、进度恢复机制、合并并发控制三件事想清楚，这三件事定了，剩下就是常规开发。信我，这个顺序能帮你少走很多弯路。