简介这份资源是面向 Java 后端开发者的 MinIO 分片上传与断点续传实战示例针对大文件直传易超时、网络中断需重传等痛点给出可直接运行的前后端完整方案。压缩包共 13 个文件约 19KB包含 7 个 Java 源码、2 个 JavaScript 脚本、1 个 HTML 页面、1 个 CSS 样式、1 个 Maven 的 pom.xml 与 1 个 properties 配置文件后端仅引入必要依赖保持纯净。前端借助 spark-md5 计算文件指纹、按分片切分并记录上传进度后端负责分片接收、合并与断点续传校验配置项与 MinIO 服务信息对应后即可启动测试。目前已有 20968 人学习下载适合需要落地大文件上传、优化传输稳定性的中高级开发者参考可据此快速理解分片策略、秒传与续传的实现思路并直接迁移到自己的项目中。1. MinIO 分片上传与断点续传为什么直传大文件迟早要翻车一个 2GB 的视频文件用最朴素的putObject直接怼到 MinIO在本地测试环境跑得挺欢一上生产就原形毕露请求超时、内存飙升、网络抖一下就前功尽弃用户还得从头再传一遍。这不是 MinIO 的锅是「单次 PUT 传大文件」这个模式本身就不适合生产环境。MinIO 基于 S3 协议天然支持 Multipart Upload分片上传把大文件切成若干块并行上传最后合并成一个对象配合前端记录已上传分片就能实现断点续传——刷新页面、断网重连后只补传缺失的那几片。这套方案解决的核心问题是大文件上传的稳定性、速度和用户体验。适合谁做企业网盘、视频平台、跨境商城后台、在线教育课件系统的 Java 工程师只要你的业务里有超过 100MB 的文件上传需求分片加断点续传就是绕不过去的一课。下面从 MinIO 的 SDK 选型讲到 Spring Boot 落地再到参数调优和血泪踩坑一步步拆开。2. MinIO Java SDK 选型与分片上传的核心机制2.1 为什么是 MinIO Java SDK 而不是自己拼 HTTPMinIO 官方提供了minio-java这个 SDK封装了 S3 的 Multipart Upload 协议。有人会想不就是几个 HTTP 请求吗自己用HttpClient拼不行吗行但你得自己处理签名AWS Signature V4、分片编号、ETag 校验、合并请求的 XML 组装任何一处算错就是SignatureDoesNotMatch或者InvalidPart。常见做法是直接用官方 SDK它把createMultipartUpload、uploadPart、completeMultipartUpload、abortMultipartUpload四个动作都封装好了你只需要调方法。选型上还有一个坑minio-java有 8.x 和 7.x 两个大版本API 差异不小。8.x 用MinioClient.builder()构建方法名和参数更贴近 S3 语义7.x 的PutObjectOptions在 8.x 里变成了PutObjectArgs。如果你在网上搜到的示例代码编译不过八成是版本对不上。我一般会锁定一个版本在pom.xml里写死避免依赖漂移。dependency groupIdio.minio/groupId artifactIdminio/artifactId version8.5.7/version /dependency版本号只是示例实际用你项目里验证过的那一个。关键是别用LATESTMinIO SDK 的小版本之间偶尔会有行为变化。2.2 分片上传的四个阶段与断点续传的数据结构MinIO 的分片上传分四步初始化上传拿到uploadId按分片编号逐个上传拿到每片的etag最后把所有partNumber etag提交合并或者中途放弃调abort。断点续传的关键在于前端或客户端要持久化uploadId和已上传分片的partNumber etag列表。下次续传时先查这个列表跳过已完成的片只传缺失的。这里有个容易忽略的点MinIO 的uploadId是有生命周期的默认 7 天不活动会被清理。如果你把uploadId存到数据库里用户隔了半个月才回来续传这个uploadId已经失效了得重新初始化。所以续传逻辑里必须处理「uploadId失效」这个分支不能假设它永远有效。数据结构上我一般用一张表记录上传任务字段类型说明upload_idvarcharMinIO 返回的上传 IDobject_namevarchar目标对象名含路径file_md5varchar文件整体 MD5用于秒传判断total_partsint分片总数part_sizebigint每片字节数statustinyint0 进行中 1 已完成 2 已放弃created_atdatetime创建时间分片明细另存一张表记录upload_id part_number etag size。续传时查这张表就知道哪些片已经传完了。2.3 分片大小怎么定5MB 不是随便写的S3 协议规定除了最后一片每片最小 5MB最大 5GB最多 10000 片。这意味着如果你传一个 100GB 的文件每片至少 10MB 才够分。分片太小会导致请求数暴增签名和网络开销占比过高分片太大则单次失败重传成本高并行度也上不去。我的经验值100MB 以下的文件分片 5MB100MB 到 1GB分片 10MB1GB 以上分片 20MB 到 50MB。并行上传的线程数控制在 3 到 5 个太多会打满客户端带宽反而拖慢整体速度。这个参数不是拍脑袋是压测出来的——你可以用minio自带的mc工具或者自己写个压测脚本观察不同分片大小下的吞吐量曲线。提示分片大小一旦确定续传时必须用同样的值否则分片编号和边界对不上合并会失败。3. Spring Boot 集成 MinIO 分片上传的完整落地3.1 初始化客户端与创建上传任务先配置MinioClient把它注册成 Spring 的 Bean。注意endpoint要带协议头accessKey和secretKey从配置中心或环境变量读别硬编码在代码里。Configuration public class MinioConfig { Value(${minio.endpoint}) private String endpoint; Value(${minio.access-key}) private String accessKey; Value(${minio.secret-key}) private String secretKey; Bean public MinioClient minioClient() { return MinioClient.builder() .endpoint(endpoint) .credentials(accessKey, secretKey) .build(); } }endpoint的格式是http://127.0.0.1:9000这种不要只写 IP 和端口。如果 MinIO 部署在 Docker 里注意容器网络和宿主机网络的差异localhost在容器内指向的是容器本身不是宿主机。创建上传任务时先调createMultipartUpload拿到uploadId然后把任务信息落库。public String initUpload(String objectName, String contentType) throws Exception { CreateMultipartUploadArgs args CreateMultipartUploadArgs.builder() .bucket(my-bucket) .object(objectName) .contentType(contentType) .build(); CreateMultipartUploadResponse response minioClient.createMultipartUpload(args); String uploadId response.result().uploadId(); // 落库upload_id, object_name, status0, created_atnow uploadTaskMapper.insert(new UploadTask(uploadId, objectName, 0, new Date())); return uploadId; }contentType要传对否则浏览器下载时可能被当成二进制流直接下载而不是预览。objectName如果包含路径MinIO 会自动创建目录层级不需要提前建目录。3.2 上传单个分片并记录 etag前端把文件切片后每片单独调后端接口。后端收到分片后调uploadPart拿到etag存库。public String uploadPart(String uploadId, String objectName, int partNumber, InputStream stream, long size) throws Exception { UploadPartArgs args UploadPartArgs.builder() .bucket(my-bucket) .object(objectName) .uploadId(uploadId) .partNumber(partNumber) .stream(stream, size, -1) .build(); UploadPartResponse response minioClient.uploadPart(args); String etag response.etag(); // 落库upload_id, part_number, etag, size uploadPartMapper.insert(new UploadPart(uploadId, partNumber, etag, size)); return etag; }stream(stream, size, -1)里的size必须准确是这一片的字节数不是整个文件的。-1表示分片大小未知时由 SDK 自己算但传大文件时建议明确指定避免内存缓冲。partNumber从 1 开始不是 0这个坑我踩过传 0 会直接报错。3.3 合并分片与放弃上传所有分片传完后按partNumber升序组装Part列表调completeMultipartUpload。public void completeUpload(String uploadId, String objectName) throws Exception { ListUploadPart parts uploadPartMapper.selectByUploadId(uploadId); parts.sort(Comparator.comparingInt(UploadPart::getPartNumber)); ListPart partList parts.stream() .map(p - new Part(p.getPartNumber(), p.getEtag())) .collect(Collectors.toList()); CompleteMultipartUploadArgs args CompleteMultipartUploadArgs.builder() .bucket(my-bucket) .object(objectName) .uploadId(uploadId) .parts(partList) .build(); minioClient.completeMultipartUpload(args); // 更新任务状态为已完成 uploadTaskMapper.updateStatus(uploadId, 1); }如果用户主动取消上传或者任务超时要调abortMultipartUpload清理掉 MinIO 上的临时分片否则这些分片会一直占着存储空间时间久了就是一笔糊涂账。public void abortUpload(String uploadId, String objectName) throws Exception { AbortMultipartUploadArgs args AbortMultipartUploadArgs.builder() .bucket(my-bucket) .object(objectName) .uploadId(uploadId) .build(); minioClient.abortMultipartUpload(args); uploadTaskMapper.updateStatus(uploadId, 2); }3.4 断点续传的查询接口前端在续传前先调一个接口查已上传的分片列表。后端返回uploadId和已完成的partNumber集合前端据此跳过已传的片。public ResumeInfo getResumeInfo(String fileMd5) { UploadTask task uploadTaskMapper.selectByMd5AndStatus(fileMd5, 0); if (task null) { return null; // 没有进行中的任务需要重新初始化 } ListInteger uploadedParts uploadPartMapper .selectPartNumbersByUploadId(task.getUploadId()); return new ResumeInfo(task.getUploadId(), uploadedParts, task.getTotalParts()); }这里用文件 MD5 来关联任务是为了支持「秒传」——如果同一个文件之前已经传完过直接返回已有对象的 URL不用再传。MD5 的计算在前端做大文件可以用分片 MD5 再合并的方式避免一次性读入内存。4. 参数调优与性能压测别让默认值拖后腿4.1 连接池与超时参数MinioClient底层用的是 OkHttp默认连接池和超时时间不一定适合你的场景。传大文件时如果超时设得太短分片传到一半就断了。我一般会显式设置OkHttpClient httpClient new OkHttpClient.Builder() .connectTimeout(30, TimeUnit.SECONDS) .writeTimeout(60, TimeUnit.SECONDS) .readTimeout(60, TimeUnit.SECONDS) .connectionPool(new ConnectionPool(50, 5, TimeUnit.MINUTES)) .build(); MinioClient client MinioClient.builder() .endpoint(endpoint) .credentials(accessKey, secretKey) .httpClient(httpClient) .build();connectTimeout30 秒够用writeTimeout和readTimeout根据你的分片大小和网络带宽调。如果分片 50MB上传速度 10MB/s那至少需要 5 秒留 60 秒余量比较稳妥。连接池大小和你的并发上传线程数匹配50 个连接够大多数场景用了。4.2 并行上传的线程模型前端并行上传分片时后端接口本身是无状态的每个分片请求独立处理。但要注意MinIO 服务端对同一个uploadId的并发uploadPart是支持的不会互相干扰。真正的瓶颈在客户端带宽和服务端的磁盘 IO。我一般用CompletableFuture做并行上传控制并发数ExecutorService executor Executors.newFixedThreadPool(4); ListCompletableFutureString futures new ArrayList(); for (int i 0; i parts.size(); i) { final int partNumber i 1; final byte[] data parts.get(i); futures.add(CompletableFuture.supplyAsync(() - { try { return uploadPart(uploadId, objectName, partNumber, new ByteArrayInputStream(data), data.length); } catch (Exception e) { throw new RuntimeException(e); } }, executor)); } CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();线程数设 4 是个平衡点。设 8 或 10 在千兆网下可能更快但会挤占其他请求的资源。如果你的服务是共享的建议做成可配置的参数按环境调整。4.3 压测方法与观察指标压测不是随便传几个文件就完事。我会准备三组文件100MB、500MB、2GB分别用 5MB、10MB、20MB 的分片大小跑一遍记录总耗时、失败率、服务端 CPU 和内存。MinIO 服务端可以用mc admin trace看请求级别的耗时定位是网络慢还是磁盘慢。观察指标里uploadPart的 P99 延迟最能说明问题。如果 P99 突然飙高通常是某一片重传了多次或者服务端在做 compaction。另外注意 MinIO 的纠删码模式EC对写入性能有影响EC 44 和 EC 88 的吞吐量差异明显压测时要和你的生产配置保持一致。5. 避坑指南分片上传断点续传的五个血泪教训5.1 现象合并时报 InvalidPart但分片明明都传了原因etag里带了引号或者partNumber顺序不对。MinIO 返回的etag有时是带双引号的字符串直接存库再取出来拼Part时引号会导致匹配失败。另外Part列表必须按partNumber升序排列乱序提交会报错。解决存etag时去掉首尾引号提交前对partNumber排序。我一般在uploadPart拿到etag后就做replace(\, )。5.2 现象续传时 uploadId 失效报 NoSuchUpload原因MinIO 默认清理超过 7 天未活动的分片上传任务。如果用户隔了很久才回来续传uploadId已经被回收了。解决在续传接口里捕获NoSuchUpload异常返回一个标志让前端重新初始化上传。同时后台可以跑一个定时任务清理超过 3 天还没完成的任务主动调abort释放空间。5.3 现象分片上传到一半内存溢出原因把整个分片读成byte[]再传分片设得太大比如 100MB并发一高就 OOM。解决用流式上传uploadPart的stream参数直接传InputStream不要先读到内存。如果前端传的是MultipartFile用getInputStream()拿流注意流只能读一次别在日志里打印内容。5.4 现象Docker 里跑 MinIOJava 客户端连不上原因endpoint配了localhost:9000但 Java 应用和 MinIO 不在同一个容器网络里。或者 MinIO 容器启动时没映射端口。解决用 Docker 网络别名或者宿主机 IP。如果是docker-compose服务名就是主机名。另外检查 MinIO 的--console-address和--address参数API 端口和控制台端口是分开的别连错。5.5 现象上传速度忽快忽慢像坐过山车原因分片大小和并发数不匹配。分片太小请求数太多签名和网络握手开销占比高并发太高带宽被抢每个请求都慢。解决用固定分片大小加固定并发数压测找到最优组合。另外检查 MinIO 服务端的磁盘是否用了网络存储NFS 之类网络存储的延迟抖动会直接反映到上传速度上。6. 进阶技巧用预签名 URL 把上传压力从后端卸掉前面讲的方案分片数据都要经过 Java 后端中转后端既是计算节点又是带宽瓶颈。文件一大、并发一高后端就成了瓶颈。进阶做法是后端只负责调createMultipartUpload和completeMultipartUpload分片上传用预签名 URL 让前端直连 MinIO。具体流程后端为每个分片生成一个预签名 PUT URL前端拿到 URL 后直接 PUT 到 MinIO不经过 Java 服务。这样后端的带宽压力几乎为零只需要处理元数据。public String getPresignedPartUrl(String uploadId, String objectName, int partNumber) throws Exception { GetPresignedObjectUrlArgs args GetPresignedObjectUrlArgs.builder() .method(Method.PUT) .bucket(my-bucket) .object(objectName) .expiry(1, TimeUnit.HOURS) .extraQueryParams(Map.of( uploadId, uploadId, partNumber, String.valueOf(partNumber) )) .build(); return minioClient.getPresignedObjectUrl(args); }expiry设 1 小时够前端传完一片了。extraQueryParams里带上uploadId和partNumberMinIO 会自动识别这是分片上传请求。前端拿到 URL 后用fetch或XMLHttpRequest直接 PUT注意Content-Type要和初始化时一致。这个方案的好处是后端彻底轻量化坏处是前端要处理预签名 URL 的过期和重试。如果 URL 过期了前端得重新向后端要一个。另外预签名 URL 的权限是临时的泄露了也只影响这一个分片风险可控。验证方法传一个 1GB 的文件观察 Java 后端的网络出入带宽。如果后端带宽几乎为零说明预签名方案生效了。再对比一下直传方案的总耗时通常能快 20% 到 40%取决于后端原来的负载。我自己的习惯是小文件100MB 以下走后端中转简单省事大文件走预签名直传把带宽留给 MinIO。两种方案在同一个项目里共存按文件大小路由。这套组合拳打下来大文件上传的稳定性和速度都能上一个台阶。希望帮到你。本文还有配套的精品资源点击获取