企业官网建设流程全解析

简介：这份资源面向具备一定 Java 后端基础的开发者，聚焦 MinIO 对象存储场景下的高性能分片上传与断点续传实现，帮助读者理解大文件上传时如何拆分分片、记录上传进度并在中断后继续传输。压缩包共 13 个文件，约 19KB，以 7 个 Java 源文件为核心，配合 pom.xml 与 properties 配置文件搭建后端示例，前端部分由 2 个 js 脚本、1 个 html 页面和 1 个 css 样式组成，整体结构精简，后端仅引入必要依赖，便于快速对照阅读。资源已有 20971 人学习下载，说明其在同类示例中具有较高的参考价值。读者可从中获得前后端配合的完整演示代码，理解分片上传的接口设计与断点续传逻辑，并借助配置说明将示例接入自己的 MinIO 服务进行验证，适合作为项目集成前的技术预研与排错参考。

1. 分片上传不是把文件切小就完事：MinIO Java 客户端里那套「先初始化、再逐片传、最后合并」的流程

一个 2GB 的视频文件，走单次 PUT 传到一半网络抖了一下，整个请求从头再来——这种场景在 Java 后端对接对象存储时几乎躲不掉。MinIO 的 Java 客户端把大文件上传拆成了分片上传（multipart upload）机制：先发起一次上传任务拿到 uploadId，再把文件按固定大小切成若干片并行或串行上传，每片带独立的分片编号，最后调一次合并接口把分片组装成完整对象。断点续传就建立在这套机制上——只要 uploadId 和已上传分片列表还在，进程重启后可以跳过已完成的分片继续传。这篇笔记拆的是 MinIO Java SDK 里分片上传与断点续传的完整落地路径，适合正在做文件服务、需要处理大文件上传和失败重试的 Java 后端开发者，也适合想搞清楚「分片大小怎么定、并发开多少、断点信息存哪」这类参数边界的人。下面从客户端初始化讲到分片策略、断点状态管理，再到几个我实际踩过的坑。

2. MinIO Java 客户端初始化与分片上传的前置配置

2.1 依赖引入与 MinioClient 构建

MinIO 官方 Java SDK 的坐标是io.minio:minio，分片上传相关 API 在 8.x 版本里已经比较稳定。Maven 项目直接引依赖，注意别和项目里其他 S3 SDK 混用同一个 HTTP 客户端配置，否则连接池参数会互相覆盖。

<dependency> <groupId>io.minio</groupId> <artifactId>minio</artifactId> <version>8.5.7</version> </dependency>

构建客户端时几个参数值得单独说：endpoint指向服务地址，credentials用 accessKey/secretKey，真正影响分片上传体验的是底层 OkHttp 的超时和连接池。分片上传的单个分片请求可能持续几十秒，默认读超时偏短，大分片容易在慢网络下被掐断。

MinioClient client = MinioClient.builder() .endpoint("http://127.0.0.1:9000") .credentials("ACCESS_KEY", "SECRET_KEY") // 自定义 OkHttp，放大连接池与超时，适配大分片 .httpClient(OkHttpClient.builder() .connectTimeout(10, TimeUnit.SECONDS) .writeTimeout(60, TimeUnit.SECONDS) .readTimeout(60, TimeUnit.SECONDS) .connectionPool(new ConnectionPool(64, 5, TimeUnit.MINUTES)) .build()) .build();

writeTimeout和readTimeout要按分片大小反推：一个 16MB 分片在 5Mbps 上行下大约需要 25 秒，留两倍余量设 60 秒比较稳。连接池上限建议不低于并发分片数，否则并发上传时线程会排队等连接，看起来像「卡住」其实是池子满了。这里没有银弹参数，得按实际带宽和分片大小算一遍。

2.2 桶的存在性检查与分片上传的入口 API

分片上传不是独立入口，MinIO Java SDK 把「小文件单次 PUT」和「大文件分片」统一在uploadObject里，通过PutObjectArgs的partSize控制。当文件大小超过partSize时，SDK 内部自动走分片流程；小于则单次上传。这意味着你不需要手动调createMultipartUpload，但也就失去了对 uploadId 的显式控制——断点续传场景下这点很关键，后面会讲。

boolean exists = client.bucketExists( BucketExistsArgs.builder().bucket("demo-bucket").build()); if (!exists) { client.makeBucket(MakeBucketArgs.builder().bucket("demo-bucket").build()); } // 自动分片：partSize 设为 16MB，文件超过即走分片 client.uploadObject( UploadObjectArgs.builder() .bucket("demo-bucket") .object("video/big.mp4") .filename("/data/big.mp4") .contentType("video/mp4") // 分片大小，最小 5MB（S3 协议下限） .build());

partSize有硬下限：S3 兼容协议规定除最后一片外，每片不得小于 5MB，MinIO 同样遵守。设成 1MB 会直接报错。常见做法是按文件大小动态算：小于 100MB 用 5MB 分片，100MB 到 1GB 用 16MB，超过 1GB 用 32MB 或 64MB。分片太小请求数暴涨、元数据开销大；分片太大单请求失败重传成本高，重试一次就是几十 MB 白传。这个权衡是分片上传最核心的调参点。

3. 手动分片与断点续传：uploadId、分片编号与状态持久化

3.1 为什么断点续传必须绕开 uploadObject 自动模式

uploadObject的自动分片在单次调用内完成，进程一挂，uploadId 和已传分片信息全丢，下次只能从头来。真正的断点续传需要拿到 uploadId 并自己维护「哪些分片已完成」。MinIO Java SDK 没有直接暴露createMultipartUpload的公开方法，但底层兼容 S3 协议，可以通过S3Base或者直接用 AWS S3 SDK 的CreateMultipartUploadRequest对接同一个 endpoint。实操里更常见的做法是：用 AWS S3 SDK 的S3Client连 MinIO，因为它把分片上传的每个阶段都暴露成了独立 API，控制粒度更细。

S3Client s3 = S3Client.builder() .endpointOverride(URI.create("http://127.0.0.1:9000")) .credentialsProvider(StaticCredentialsProvider.create( AwsBasicCredentials.create("ACCESS_KEY", "SECRET_KEY"))) .region(Region.US_EAST_1) // MinIO 忽略 region，但 SDK 要求必填 .forcePathStyle(true) // MinIO 必须开路径风格，否则桶名被当子域 .build(); // 第一步：初始化分片上传，拿到 uploadId CreateMultipartUploadResponse init = s3.createMultipartUpload( CreateMultipartUploadRequest.builder() .bucket("demo-bucket") .key("video/big.mp4") .contentType("video/mp4") .build()); String uploadId = init.uploadId();

forcePathStyle(true)是连 MinIO 最容易翻车的一行——不开的话 SDK 会把桶名拼成demo-bucket.127.0.0.1这种子域，DNS 解析直接失败。region随便填一个合法值即可，MinIO 不校验，但 SDK 客户端构建时必填，漏了会抛异常。

3.2 分片上传循环与断点状态的存储设计

拿到 uploadId 后，把文件按分片大小切开，逐片调uploadPart，每片返回一个 ETag，合并时必须按分片编号顺序提交 ETag 列表。断点续传的关键在于：把 uploadId 和「已完成分片编号 → ETag」的映射持久化到数据库或 Redis，进程重启后先查这份状态，跳过已完成的分片。

long fileSize = Files.size(Path.of("/data/big.mp4")); long partSize = 16L * 1024 * 1024; // 16MB int partCount = (int) ((fileSize + partSize - 1) / partSize); // 从 Redis/DB 读已上传分片：partNumber -> etag Map<Integer, String> uploaded = loadUploadedParts(uploadId); List<CompletedPart> completed = new ArrayList<>(); try (RandomAccessFile raf = new RandomAccessFile("/data/big.mp4", "r")) { for (int i = 1; i <= partCount; i++) { if (uploaded.containsKey(i)) { // 断点：跳过已完成分片 completed.add(CompletedPart.builder() .partNumber(i).eTag(uploaded.get(i)).build()); continue; } long offset = (long) (i - 1) * partSize; int len = (int) Math.min(partSize, fileSize - offset); byte[] buf = new byte[len]; raf.seek(offset); raf.readFully(buf); UploadPartResponse resp = s3.uploadPart(UploadPartRequest.builder() .bucket("demo-bucket").key("video/big.mp4") .uploadId(uploadId).partNumber(i) .build(), RequestBody.fromBytes(buf)); String etag = resp.eTag(); saveUploadedPart(uploadId, i, etag); // 每片成功即落库，别攒到最后 completed.add(CompletedPart.builder() .partNumber(i).eTag(etag).build()); } }

分片编号从 1 开始，不是 0，这是 S3 协议的规定，写错会导致合并时报InvalidPart。saveUploadedPart必须每片成功就写，不能等整个循环结束再批量落库——中途崩溃时最后几片的 ETag 就丢了，续传时这些片会被重传，虽然不致命但浪费带宽。存储结构用 Redis Hash 最顺手：key 是upload:{uploadId}，field 是分片号，value 是 ETag，再配一个过期时间兜底清理僵尸任务。

3.3 合并分片与失败清理

所有分片传完后调completeMultipartUpload，把CompletedPart列表按分片号升序提交。合并本身是元数据操作，很快，但如果 ETag 对不上或者分片缺失，会直接失败。

completed.sort(Comparator.comparingInt(CompletedPart::partNumber)); s3.completeMultipartUpload(CompleteMultipartUploadRequest.builder() .bucket("demo-bucket").key("video/big.mp4") .uploadId(uploadId) .multipartUpload(CompletedMultipartUpload.builder() .parts(completed).build()) .build()); // 成功后清理断点状态 clearUploadState(uploadId);

合并失败时不要急着删 uploadId，先看错误码：InvalidPart通常是 ETag 不匹配或分片号错位，NoSuchUpload说明 uploadId 已过期（MinIO 默认对未完成的分片上传有生命周期清理，常见配置是 7 天）。如果确认要放弃这次上传，调abortMultipartUpload主动清理，否则残留分片会一直占存储空间，时间久了桶的用量会莫名其妙涨上去。

4. 并发分片、重试与几个容易翻车的参数

4.1 并发上传的线程模型与分片顺序

串行传 2GB 文件在百兆上行下要几分钟，并发能压到几十秒，但并发不是越大越好。每个并发分片占一个 HTTP 连接和一块内存缓冲（16MB 分片就是 16MB 堆内存），并发 8 就是 128MB 常驻。常见做法是用固定大小线程池，并发数控制在 4 到 8，配合有界队列。

ExecutorService pool = Executors.newFixedThreadPool(8); List<Future<CompletedPart>> futures = new ArrayList<>(); for (int i = 1; i <= partCount; i++) { final int partNumber = i; futures.add(pool.submit(() -> uploadOnePart(s3, uploadId, partNumber))); } // 收集结果时按分片号排序，合并接口要求有序 List<CompletedPart> parts = futures.stream() .map(f -> { try { return f.get(); } catch (Exception e) { throw new RuntimeException(e); } }) .sorted(Comparator.comparingInt(CompletedPart::partNumber)) .collect(Collectors.toList());

并发上传时 ETag 落库要注意线程安全，Redis 单条 HSET 是原子的没问题，但如果用本地 Map 缓存再批量刷，得加锁或用 ConcurrentHashMap。另外分片读取用RandomAccessFile的seek是线程安全的读操作，但多个线程共用一个RandomAccessFile实例时seek和read不是原子组合，稳妥做法是每个线程自己开一个文件句柄，或者用FileChannel.read(buffer, position)的定位读，避免共享游标。

4.2 重试策略：哪些错误该重试，哪些不该

分片上传的重试要区分错误类型。网络超时、连接重置、5xx 这类瞬时错误值得重试；4xx 里的NoSuchUpload、InvalidPart重试多少次都没用，只会拖长失败时间。SDK 自带的RetryPolicy可以配，但分片场景我一般自己包一层，因为要配合断点状态——重试成功后同样要落 ETag。

CompletedPart uploadWithRetry(S3Client s3, String uploadId, int partNumber, byte[] data) { int maxAttempts = 3; for (int attempt = 1; attempt <= maxAttempts; attempt++) { try { UploadPartResponse resp = s3.uploadPart(UploadPartRequest.builder() .bucket("demo-bucket").key("video/big.mp4") .uploadId(uploadId).partNumber(partNumber) .build(), RequestBody.fromBytes(data)); return CompletedPart.builder() .partNumber(partNumber).eTag(resp.eTag()).build(); } catch (S3Exception e) { // 4xx 客户端错误不重试，直接抛 if (e.statusCode() >= 400 && e.statusCode() < 500) throw e; if (attempt == maxAttempts) throw e; sleepBackoff(attempt); // 指数退避：1s、2s、4s } } throw new IllegalStateException("unreachable"); }

退避时间用指数增长，别用固定间隔——固定 1 秒重试在服务端短暂过载时等于持续加压。maxAttempts设 3 足够，再多说明不是瞬时问题，该去查网络或服务端日志了。

4.3 分片大小与内存占用的联动关系

分片大小不只影响请求数，还直接决定堆内存峰值。并发 8、分片 64MB 时，光分片缓冲就 512MB，加上 JVM 其他开销，小内存机器直接 OOM。我一般按「并发数 × 分片大小 ≤ 堆的 25%」倒推：4GB 堆的机器，并发 8 时分片最大 128MB，但实际会取 32MB 留余量。另一个容易忽略的点是RequestBody.fromBytes会把整个分片读进内存，如果分片很大，可以改用RequestBody.fromInputStream配合Content-Length，让 SDK 流式读取，内存占用降到缓冲区大小。不过流式读取要求能准确给出长度，且重试时流要能重置，实现上比字节数组麻烦，分片在 32MB 以内时用字节数组更省心。

5. 避坑排查：分片上传里那些让人怀疑人生的报错

5.1 合并时报 InvalidPart，ETag 明明存了

现象：所有分片都返回 200，ETag 也落了库，合并时却抛InvalidPart。原因多半是 ETag 存的时候带了引号或者被截断。S3 返回的 ETag 形如"abc123"，带双引号，有些序列化框架会把引号当字符串内容存进去，合并时 SDK 再拼一次引号就变成""abc123""，服务端比对失败。解决：落库前统一etag.replace("\"", "")，合并时 SDK 会自己加引号。另一个可能是分片号从 0 开始，检查循环起始值。

5.2 断点续传后合并失败，提示分片缺失

现象：进程重启后按 Redis 里的记录跳过已完成分片，合并却报某个分片不存在。原因通常是 Redis 里的 ETag 是旧的，而那次上传其实已经被abort过（比如超时清理任务跑过），uploadId 失效但状态没清。解决：续传前先调listParts核对服务端实际存在的分片列表，以服务端为准，本地状态只作加速提示。listParts返回的Part列表就是权威数据，对不上就以它重建本地状态。

5.3 并发上传时偶发连接池耗尽

现象：并发 16 上传，日志里大量线程卡在获取连接，吞吐反而比并发 4 还低。原因是 OkHttp 连接池上限设得比并发数小，或者maxIdleConnections太小导致连接频繁重建。解决：连接池maxIdleConnections不低于并发数，keepAliveDuration设 5 分钟以上；同时确认没有在每次请求里 new 一个OkHttpClient，客户端要复用单例。

5.4 小文件也走了分片，请求数暴涨

现象：几百 KB 的图片上传也触发分片，日志里一堆uploadPart。原因是partSize设得太小，或者判断逻辑写成了「文件大小 > 0 就分片」。解决：分片阈值单独判断，小于partSize的直接走putObject单次上传；partSize不低于 5MB 的协议下限，实际按文件大小分档。

5.5 上传成功但对象大小不对

现象：合并返回 200，下载下来文件比原文件小一截。原因多半是最后一片的长度算错，Math.min(partSize, fileSize - offset)里fileSize用了int导致大文件溢出，或者RandomAccessFile.readFully读到的字节数少于预期却没校验。解决：文件大小一律用long，每片读完校验实际读取长度等于预期长度，不等就抛异常而不是继续传。

6. 一个可复用的分片上传封装：把 uploadId 生命周期管起来

把上面这些拼成一个可复用的服务类，核心是把 uploadId 的生命周期和断点状态绑在一起管理。我一般会封装一个MultipartUploader，对外只暴露upload(file, objectKey)和resume(uploadId)两个方法，内部维护「初始化 → 分片循环 → 合并 → 清理」四段状态机。关键设计是状态机每一步都落库：INIT时写 uploadId，每片成功写 ETag，COMPLETE后删记录，ABORT时也删记录。这样任何时刻进程挂掉，重启后扫一遍未完成记录就能续。

public class MultipartUploader { private final S3Client s3; private final UploadStateStore store; // Redis 实现 public String upload(Path file, String bucket, String key) throws Exception { long size = Files.size(file); long partSize = choosePartSize(size); // 按大小分档 int partCount = (int) ((size + partSize - 1) / partSize); String uploadId = s3.createMultipartUpload( CreateMultipartUploadRequest.builder() .bucket(bucket).key(key).build()).uploadId(); store.init(uploadId, bucket, key, partCount); // 记录任务 List<CompletedPart> parts = new ArrayList<>(); try (FileChannel ch = FileChannel.open(file, StandardOpenOption.READ)) { for (int i = 1; i <= partCount; i++) { long offset = (long) (i - 1) * partSize; int len = (int) Math.min(partSize, size - offset); ByteBuffer buf = ByteBuffer.allocate(len); ch.read(buf, offset); // 定位读，线程安全 buf.flip(); UploadPartResponse resp = s3.uploadPart( UploadPartRequest.builder() .bucket(bucket).key(key) .uploadId(uploadId).partNumber(i).build(), RequestBody.fromByteBuffer(buf)); String etag = resp.eTag().replace("\"", ""); store.savePart(uploadId, i, etag); // 每片落库 parts.add(CompletedPart.builder() .partNumber(i).eTag(etag).build()); } } catch (Exception e) { // 不 abort，保留现场供续传；由定时任务清理超时任务 throw e; } parts.sort(Comparator.comparingInt(CompletedPart::partNumber)); s3.completeMultipartUpload(CompleteMultipartUploadRequest.builder() .bucket(bucket).key(key).uploadId(uploadId) .multipartUpload(CompletedMultipartUpload.builder().parts(parts).build()) .build()); store.clear(uploadId); return uploadId; } private long choosePartSize(long size) { if (size < 100L * 1024 * 1024) return 5L * 1024 * 1024; if (size < 1024L * 1024 * 1024) return 16L * 1024 * 1024; return 32L * 1024 * 1024; } }

choosePartSize的三档是我按常见带宽试出来的经验值，不是标准答案：5MB 档适合内网快传，16MB 档是通用平衡点，32MB 档给超大文件减少请求数。FileChannel.read(buf, offset)的定位读天然线程安全，比共享RandomAccessFile省心，并发改造时直接把循环体丢进线程池即可，注意ByteBuffer每个线程独立分配。异常分支故意不abort，是为了保留 uploadId 让续传能接上，清理交给独立的定时任务扫store里超过 24 小时未完成的任务，逐个abortMultipartUpload并删记录——这一步不做，桶里会攒下一堆看不见的分片垃圾，账单和用量对不上时排查起来很痛苦。

验证这套封装是否靠谱，我会跑三个用例：正常大文件上传后比对 MD5；上传到一半 kill 进程再重启续传，确认最终文件完整；故意把某片 ETag 改错，确认合并失败后状态没被误清。从那以后我每次接对象存储的分片上传，都强制先把「断点状态存哪、谁来清理僵尸任务」这两件事定下来再写业务代码，否则后面补起来就是血泪经验。希望帮到你。

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