MinIO分片上传与断点续传：Java实现大文件高性能传输

简介：面向Java工程师的MinIO分片上传与断点续传示例，定位为需要实现大文件高效传输的中高级开发者提供可直接复用的完整参考。后端程序只引用必要依赖，启动前按实际MinIO服务地址、端口、密钥调整配置文件即可运行；前端通过脚本解析文件并计算分片摘要，配合上传页面的样式与交互逻辑，使各分片的上传状态清晰可见。资源共13个文件，其中7个Java源码负责分片接收、暂存与合并，2个前端脚本处理分片计算与上传调度，1个HTML页面和1个CSS样式构成操作界面，另外还包括Maven工程配置文件与运行属性文件，压缩包仅19KB，虽体积小巧但覆盖上传链路各环节。已有20968人学习下载，这个热度反映出示例在MinIO上传场景中具有较强实用性。读者可从中理解前后端协作完成分片上传的完整思路，掌握断点续传时组合分片与完整性校验的方法，便于在自身项目中快速改造接入。

1. MinIO 分片上传：先解决“2GB 文件传一半断网”的焦虑

做过文件上传的工程师都懂：单个大文件走一次putObject，网络一抖就全盘重来，传 2GB 的视频卡在 87% 然后报错，那种感觉比加班还难受。MinIO 的多分片上传（Multipart Upload）恰恰就为这件事设计——把大文件切成若干分片，逐个上传，服务端记住每个分片的完成状态，断在哪就从哪继续。这套机制兼容 S3 协议，Java 端用官方 SDK 就能实现，不引入额外中间件。这篇文章我会把分片上传、断点续传的完整实现、参数选型和踩过的坑一并拆开，适合正在做文件上传模块的 Java 开发，或者想给自建对象存储加上传性能优化的从业者。全程用可复现的代码和真实教训说话，照着操作就能落地。

2. Multipart Upload 的设计原理：为什么要分片，又为什么能续传

2.1 分片上传的四个阶段

MinIO 的分片上传对应 S3 协议里的 Multipart Upload，整个过程分四步：发起（Initiate）、逐片上传（Upload Part）、完成合并（Complete）或中止（Abort）。第一步调用initiateMultipartUpload，服务端返回一个全局唯一的uploadId，这个 ID 是后续所有操作的凭证。第二步按分片编号逐一上传，每片上传成功后返回一个ETag。第三步把全部分片的编号和ETag按序提交，服务端校验后合并成一个完整对象。第四步是异常收尾：abortMultipartUpload清理服务端残留的分片数据。

为什么说这天然支持断点续传？因为每个分片是否上传成功、是否校验通过，状态都记录在服务端。客户端只要记住uploadId，随时可以用listParts把所有已上传分片的编号和ETag拉回来，接着从断点继续传，不需要重新上传已完成的 90% 内容。这就是分片机制的核心价值——把“全有或全无”的单次请求，变成“逐段确认”的可恢复流程。

2.2 分片大小与并发数：性能的起点

“最佳性能”不是靠盲目开大线程数。MinIO 对分片有硬约束：除了最后一片，每片最小 5MiB（minPartSize），全文件最多 10000 片。超过上限就要调大分片大小。计算公式很直接：partSize = ceil(fileSize / 10000)，再向上对齐到 5MiB 的整数倍。

拿一个 10GB 视频举例，按 5MiB 分片就是 2048 片，完全在限制内。但到了 100GB 的文件，按 5MiB 算就是 20000 片，直接超限，必须把每片加大到至少 10MiB，甚至 20MiB。我一般会额外加一个向上取整的对齐逻辑，否则 MinIO 在合并阶段可能因为分片大小不一致报错，这种坑属于代码里查不到、只有跑大文件才会暴露的类型。

并发数方面，经验值是本机 CPU 核心数的 2～4 倍，同时抬升 JVM 连接池上限。并发太高，MinIO 端会出现 503 响应；并发太低，10GB 文件的传输时间直接翻倍。这个参数我后面会专门展开。

2.3 为什么选 MinIO：S3 协议的红利

选 MinIO 不只是因为它开源轻量，更因为它实现的 S3 协议是业内事实标准。AWS S3 SDK、MinIO Java SDK 甚至不少云厂商的对象存储都兼容同一套 Multipart Upload 语义，意味着这套分片上传代码换一个兼容层就能平移到其他服务，不绑定厂商。如果你后续要把文件迁到云上，或者接入多云容灾，代码改动量远小于重写一套上传模块。

MinIO 本身是单二进制部署，跑一个 JAR 或可执行文件就能起服务，开发环境的资源占用比一堆中间件小得多，这对本地调试分片上传是刚需——你可以随时mc命令行查看桶里的分片残留，也可以直接重启服务模拟中断场景。对比传统 NFS 或 FTP 上传，MinIO 在并发吞吐、断点续传和服务端去重上都有明显优势，这也是我把它选为上传模块底层存储的原因。

3. Java 端实现分片上传：从初始化和分片规划到并发上传与合并

3.1 初始化客户端与动态分片规划

先建立 MinIO 客户端，注意配置连接超时和读取超时。大文件上传场景下，默认超时往往不够用，建议建连接 30 秒、读超时 5 分钟，避免某个分片在慢速网络下被误杀。

import io.minio.MinioClient; import io.minio.PutObjectArgs; import io.minio.CreateMultipartUploadResponse; import io.minio.messages.Part; MinioClient client = MinioClient.builder() .endpoint("http://127.0.0.1:9000") .credentials("minioadmin", "minioadmin") .build();

endpoint 指向 MinIO 服务地址，credentials 对应用户名和密钥。真实环境里密钥不要写死在代码里，用环境变量或配置中心注入。拿到客户端后，第二步是规划分片。计算逻辑如下：

private long calcPartSize(long fileSize) { long minPartSize = 5L * 1024 * 1024; // 5MiB long maxPartCount = 10000; long partSize = (long) Math.ceil((double) fileSize / maxPartCount); if (partSize < minPartSize) { partSize = minPartSize; } // 向上对齐到 5MiB 的整数倍 long align = (partSize + minPartSize - 1) / minPartSize * minPartSize; return Math.max(align, minPartSize); }

这里fileSize / maxPartCount算出的是“在不超过 10000 片前提下”的最小分片值，再与 5MiB 取较大者，最后向上对齐到 5MiB 整数倍。如果你直接把一个 200GB 的文件按 5MiB 切，分片数会超限，MinIO 在合并阶段直接拒绝。这段代码就是专门挡这种边界条件的。

3.2 发起上传并并发提交分片

分片规划完成之后，调用createMultipartUpload拿到uploadId，这个 ID 必须保存，它是后续续传、合并、中止的唯一凭证。

CreateMultipartUploadResponse response = client.createMultipartUpload(bucket, object, null, null); String uploadId = response.result().uploadId();

bucket 是桶名，object 是对象名，uploadId 是本次上传任务的标识。接下来用线程池并发上传各分片：

int partSize = 5 * 1024 * 1024; // 实际开发时用上一步计算的结果 int concurrency = Runtime.getRuntime().availableProcessors() * 2; ExecutorService executor = Executors.newFixedThreadPool(concurrency); List<CompletableFuture<Part>> futures = new ArrayList<>(); int partNumber = 1; try (InputStream in = new BufferedInputStream(new FileInputStream(file), 1024 * 1024)) { byte[] buffer = new byte[partSize]; int len; while ((len = in.read(buffer)) != -1) { byte[] partData = Arrays.copyOf(buffer, len); final int idx = partNumber; futures.add(CompletableFuture.supplyAsync(() -> uploadPart(uploadId, idx, partData), executor)); partNumber++; } CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join(); }

核心点是“每个分片的读取与上传解耦”——主线程只负责读文件切片，上传交给线程池，避免 IO 阻塞拖慢整个流程。uploadPart内部就是调用uploadPart接口把分片字节流提交给服务端，返回Part对象，里面封装了分片编号和ETag。

3.3 完成合并：排序、ETag 与校验

所有分片上传成功后，最后一步是合并。这里有一个不显眼但必须做的步骤：对 Part 列表按partNumber升序排序，再把Part对象提交给completeMultipartUpload。并发上传完成顺序是乱的，不排序直接合并，MinIO 大概率返回 400，因为服务端要求分片严格按序号排列。

Part[] parts = futures.stream() .map(CompletableFuture::join) .sorted(Comparator.comparingInt(Part::partNumber)) .toArray(Part[]::new); client.completeMultipartUpload(bucket, object, uploadId, parts, null, null);

这里的Part对象包含partNumber和etag。排序逻辑用了 Java 8 的Comparator.comparingInt，对整型字段排序没有类型转换风险。合并成功后，服务端返回的对象就是完整的文件。习惯上我会再调一次statObject校验对象大小是否与本地文件一致，如果差一字节，说明某个分片在传输或合并环节出了问题，直接走异常流程重新发起上传。

4. 断点续传恢复机制：用 uploadId 与 listParts 实现精准续传

4.1 持久化上传状态：uploadId 必须落盘

分片上传进行到一半，程序崩溃或者网络断开，恢复的关键第一步是找回uploadId。仅把 uploadId 放在内存里是不够的——进程一重启就丢了，服务端的分片数据变成孤儿。我会在上传发起时，把uploadId、分片大小、文件路径、桶名、对象名一起写进本地状态文件，格式不用复杂，JSON 或 properties 都行：

private void saveUploadState(String filePath, String uploadId, long partSize) { Map<String, String> state = new HashMap<>(); state.put("filePath", filePath); state.put("uploadId", uploadId); state.put("partSize", String.valueOf(partSize)); // 写入本地文件，比如 ~/.upload_state/{objectName}.json }

状态文件的作用是给“续传”提供起始点。上传成功后我习惯立即删除状态文件，避免脏数据遗留。这个文件就是断点续传的“后悔药”。

4.2 查询已上传分片：listParts 的正确用法

恢复上传时，不能盲目从第 1 片开始重传。调用listParts查询服务端已存在的分片列表：

ListPartsResponse partsResponse = client.listParts(bucket, object, uploadId); List<Part> uploadedParts = partsResponse.result().parts(); Set<Integer> uploadedPartNumbers = uploadedParts.stream() .map(Part::partNumber) .collect(Collectors.toSet());

listParts默认一页返回 1000 条，一个 10GB 文件按 5MiB 分片就是 2048 片，需要处理分页。partsResponse.result().partNumberMarker()可以拿到下一页游标，循环拉全。还有一个特殊情况：如果服务端已清理该uploadId对应的分片数据（MinIO 一般会定期回收未完成的上传任务），listParts返回空列表，这时候必须重新走initiateMultipartUpload整套流程，不能傻等。

4.3 跳过已传分片并收尾

有了已上传分片集合，续传逻辑就很直接了：遍历本地分片编号，如果服务端已存在，直接跳过上传；否则重新上传。上传完成后同样走合并流程。

for (int partNumber = 1; partNumber <= totalPartCount; partNumber++) { if (uploadedPartNumbers.contains(partNumber)) { continue; // 已上传，跳过 } // 读取对应分片数据并上传 futures.add(CompletableFuture.supplyAsync(() -> uploadPart(uploadId, partNumber, partData), executor)); }

两处细节要留意。第一，本地文件的偏移量计算必须一致，读取第 N 片时的偏移量是(N-1) * partSize，不能复用内存里的上次位置。第二，已传分片里可能有上传了一半就断掉的残留，但 Multipart Upload 协议里一个分片要么完整存在、要么不存在，不存在“半片”状态，listParts查到的就是完整可用的分片。这也是服务端协议带来的好处，客户端不用处理脏半片。

5. 避坑指南：分片上传的五个高频翻车现场

5.1 uploadId 丢了，服务端残留一堆分片

现象：上传中断后重启进程，代码不知道之前的uploadId，只能重新发起整个上传，旧的分片在桶里堆积，占用存储空间。

原因：初始化返回的uploadId只存在内存中，进程一结束就没了，服务端却没有自动清理。

解决：发起点就持久化状态文件，见 4.1 节。上传完成后删除状态文件，避免堆积。

5.2 分片小于 5MiB，合并阶段直接报错

现象：代码正常运行，分片也都显示上传成功，但completeMultipartUpload抛EntityTooSmall类似的异常。

原因：MinIO 要求除最后一片外，每个分片不得小于 5MiB。代码里如果用了固定 1MiB 缓冲区，就会被拒。

解决：分片大小按 2.2 节公式动态计算，并做 5MiB 对齐。同时上传前校验partData.length < minPartSize且不是最后一片时补足或合并。

5.3 自己拼 XML 时 ETag 不带引号，签名校验失败

现象：用旧版 SDK 或手写 REST 请求时，complete请求里携带的ETag不带引号，服务端报签名错误。

原因：S3 协议中ETag在分片合并 XML 里必须带双引号，很多 SDK 内部不处理这个格式，需要手动包一层。

解决：优先用官方 SDK 的Part对象，不手拼 XML。确需手拼时，<ETag>"xxx"</ETag>里必须包含引号。这个坑排查时极难发现，属于典型的协议边界问题。

5.4 并发分片过多，MinIO 返回 503

现象：并发数从 8 提到 32，吞吐没有翻倍，反而大量分片超时报 503，整体耗时更长。

原因：MinIO 端不是无限连接池，并发超过服务端承受上限时开始拒绝请求。线程数和连接数是两套独立参数，只调一个没用。

解决：并发数维持在CPU 核心数 * 2到CPU 核心数 * 4之间，并同步调大 MinIO 服务端线程池和 JVM 侧 HTTP 连接池。出现 503 后做指数退避重试，退避间隔从 500ms 起递增。

5.5 listParts 返回空，续传直接失败

现象：中断后调用listParts查询，返回的分片列表为空，但本地明明已经传了一部分。

原因：MinIO 对未完成的 Multipart Upload 有时限回收策略，长时间未合并的上传任务会被清理，uploadId随之失效。

解决：查询到空列表时，不要用旧uploadId续传，而是重新发起上传并更新状态文件。这也是为什么状态文件里uploadId的参数可以替换。

6. 压测验证与调参路径：用数据确认“最佳性能”而不是凭感觉

分片参数不能拍脑袋，我会跑一个组合测试来验证：同一台机器、同一个 2GB 测试文件，分别用并发数=4/8/16、分片大小=5MiB/10MiB/20MiB组合上传，记录总耗时、吞吐量和失败分片数。结果矩阵大致长这样：

从这个表能明显看出，并发从 4 提到 8 收益最大，到 16 之后性能提升有限且开始触发服务端限流，这时候就该收手。分片大小的影响在并发较低时体现为请求次数减少、磁盘缓冲压力下降，但也不会无限优化。每换一台部署机器，这个矩阵就要重跑一遍，因为 CPU 核数、内存带宽、磁盘 IO 都会改变最优值。从那以后我每次调上传性能，都强制先跑一轮这种小规模对照测试，用数据说话；希望这套思路也能帮你在自己的环境里少走几步弯路。

本文还有配套的精品资源，点击获取