企业官网建设流程全解析

简介：这份资源面向需要实现 MinIO 文件上传能力的 Java 后端开发者，聚焦分片上传与断点续传两个高频难点，提供一套可直接运行的最小化示例。后端仅引入必要依赖，配置好与本地 MinIO 服务一致的连接信息即可启动；前端配合分片计算与上传逻辑，启动后上传任意文件即可验证完整链路，适合作为项目集成前的技术验证或学习参考。压缩包共 13 个文件、约 19KB，以 7 个 Java 源文件为主体，辅以 2 个 JS 脚本、1 个 HTML 页面、1 个 CSS 样式、1 个 pom.xml 与 1 个 properties 配置文件，前后端结构一目了然。该资源已有 20971 人学习下载，说明其在同类示例中具备较好的参考价值。读者可从中获得分片切分、MD5 校验、断点续传状态维护等关键实现思路，并借助清晰的目录结构快速定位后端服务与前端调用代码，减少自行摸索成本。

1. 分片上传不是把文件切开就完事：MinIO Java 客户端到底解决什么问题

一个 2GB 的视频文件，走普通putObject上传，网络抖一下就得从头再来，前端进度条卡在 87% 然后归零，这种体验在后台管理系统里几乎等于事故。MinIO 的 Java 客户端把这件事拆成了两套机制：分片上传（Multipart Upload）负责把大文件切成可控的块并行推上去，断点续传负责在中断后从已完成的块继续，而不是重传整个文件。这两件事听起来简单，真正落地时的难点在于分片大小怎么定、ETag 怎么校验、中断后怎么找回 uploadId、并发数开多大不会把客户端内存打爆。这份示例代码包围绕的就是这几个问题，适合正在做文件服务、对象存储接入、大文件上传功能的后端开发者，尤其是已经用过putObject但被大文件坑过一轮的人。

2. 分片上传的底层机制与 Java 客户端选型：为什么不是自己切文件

2.1 S3 协议的分片模型与 MinIO 的兼容边界

MinIO 对外暴露的是 S3 兼容 API，分片上传在协议层是一组固定的动作序列：CreateMultipartUpload拿到一个 uploadId，然后对每个分片调UploadPart，每片带一个从 1 开始的 partNumber，最后CompleteMultipartUpload把所有 part 的 ETag 按顺序提交，服务端拼成完整对象。中途不想传了就AbortMultipartUpload清理掉。这套模型的关键约束有几条，直接决定代码怎么写：

很多人第一反应是「我自己用RandomAccessFile把文件切成 5MB 的块，逐块putObject传上去，最后再合并」。这条路在单机小文件上能跑，但一旦要断点续传就露馅了：你得自己维护「哪些块传成功了」的元数据，自己处理块与块之间的顺序，自己实现合并逻辑，而且合并本身又是一次全量读写。S3 的分片模型把这些都交给了服务端，客户端只需要记住 uploadId 和已完成的 part 列表，恢复时查一下ListParts就能知道进度。这是选 MinIO Java 客户端而不是手搓切片的第一个理由。

第二个理由是并发。UploadPart之间是相互独立的，天然可以并行。MinIO 客户端内部用线程池调度分片上传，你只需要给一个并发度参数。自己写的话，线程池、失败重试、结果收集都得自己搭，代码量和出错面都上去了。

第三个理由是校验。每个分片上传成功后服务端返回一个 ETag，Complete 时必须按 partNumber 顺序把这些 ETag 原样提交，服务端据此判断分片有没有被篡改或丢失。自己拼文件的话这层校验等于放弃了。

2.2 客户端依赖与初始化：连接池和超时是性能的第一道闸

示例工程用的是 MinIO 官方 Java SDK，Maven 坐标大致如下（版本以你本地仓库实际拉到的为准，不要照抄一个不存在的号）：

<dependency> <groupId>io.minio</groupId> <artifactId>minio</artifactId> <version>8.x.x</version> </dependency>

初始化客户端时，最容易忽略的是 HTTP 连接池和超时。默认的 OkHttp 客户端连接数有限，分片并发一高就会出现连接等待，表现是上传速度上不去但 CPU 和带宽都没跑满。常见做法是显式构造一个带连接池的OkHttpClient再传给MinioClient：

// 构造带连接池的 HTTP 客户端，连接数要 >= 分片并发数 OkHttpClient httpClient = new OkHttpClient.Builder() .connectTimeout(30, TimeUnit.SECONDS) // 建连超时，内网可调小 .writeTimeout(60, TimeUnit.SECONDS) // 单分片写入超时，大分片要放宽 .readTimeout(60, TimeUnit.SECONDS) .connectionPool(new ConnectionPool(64, 5, TimeUnit.MINUTES)) // 池大小按并发定 .build(); MinioClient client = MinioClient.builder() .endpoint("http://minio-host:9000") // 服务端地址，不带桶名 .credentials("ACCESS_KEY", "SECRET_KEY") .httpClient(httpClient) .build();

这里几个参数的含义要说清楚。connectionPool的第一个参数是最大空闲连接数，它应该不小于你的分片并发数，否则并发线程会排队等连接，分片上传退化成串行。writeTimeout针对的是单个分片的写入，分片越大这个值越要放宽，否则大分片在慢网络下会被误判超时。connectTimeout在内网环境可以压到 5 到 10 秒，公网环境留 30 秒比较稳。凭证不要硬编码在源码里，示例里用常量只是为了演示，实际项目走配置中心或环境变量。

提示：连接池大小和分片并发数不匹配是「上传慢但查不出原因」的头号嫌疑，先对齐这两个数再谈别的优化。

2.3 分片大小的计算逻辑：一个公式决定成败

分片大小不是拍脑袋定的，它要同时满足两个条件：不小于 5MiB，且分片总数不超过 10000。所以最小分片大小的下界是max(5MiB, ceil(fileSize / 10000))。示例里通常会给一个带阶梯的策略，我一般这么写：

// 根据文件大小计算分片大小，保证分片数不超过 10000 且不小于 5MiB private static final long MIN_PART_SIZE = 5L * 1024 * 1024; // 5MiB 协议下限 private static final long MAX_PART_COUNT = 10000L; // 协议上限 private static final long DEFAULT_PART_SIZE = 16L * 1024 * 1024; // 常规文件默认 16MiB public static long calcPartSize(long fileSize) { // 先按默认分片算需要多少片 long partSize = DEFAULT_PART_SIZE; // 如果默认分片会导致超过 10000 片，就按上限反推每片至少多大 if (fileSize / partSize > MAX_PART_COUNT) { partSize = (long) Math.ceil((double) fileSize / MAX_PART_COUNT); } // 再兜底一次协议下限，防止小文件算出小于 5MiB 的值 return Math.max(partSize, MIN_PART_SIZE); }

逻辑分三步：先用默认的 16MiB 试算，如果文件大到分片数会超过 10000，就按「文件大小除以 10000 向上取整」反推一个更大的分片；最后用 5MiB 兜底，防止极小文件算出不合法的分片。为什么默认选 16MiB 而不是 5MiB？因为分片太小会让请求数暴涨，每个分片都有一次 HTTP 往返和一次 ETag 计算，5MiB 分片传 1GB 文件就是 200 多次请求，开销明显；16MiB 在请求数和单请求耗时之间比较平衡。但也不是越大越好，分片太大意味着单个分片失败重传的代价高，而且并发粒度变粗，带宽利用率反而下降。经验值是 8 到 32MiB 之间，内网高带宽可以往 32MiB 走，公网不稳定就往 8MiB 靠。

3. 断点续传的落地：uploadId、进度持久化与恢复流程

3.1 断点续传的本质是「外部记住进度」

很多人以为断点续传是客户端 SDK 自带的能力，调个参数就行。实际上 MinIO Java 客户端的分片上传 API 是偏底层的，它给你uploadId和partNumber，但「传到第几片了」这件事得你自己记。原因很简单：客户端进程一重启，内存里的状态全没了，只有把 uploadId 和已完成分片列表落到外部存储（数据库、Redis、本地文件都行），下次才能接着传。

恢复流程是这样的：先根据文件标识（比如文件内容的 MD5 或者业务侧的文件 ID）查有没有未完成的 uploadId；有的话调listParts向服务端确认哪些分片真的传成功了（不能只信本地记录，本地可能记了但服务端没落盘）；然后跳过这些分片，从下一个未完成的分片继续uploadPart；全部传完后completeMultipartUpload。这里有个细节：listParts返回的 part 列表是服务端视角的权威数据，本地记录只用来快速定位，最终以服务端为准。

// 查询已上传的分片，返回已完成的 partNumber 集合 public Set<Integer> listUploadedParts(String bucket, String object, String uploadId) throws Exception { Set<Integer> done = new HashSet<>(); // listParts 是分页的，必须循环取完，否则大文件会漏掉后面的分片 ListPartsResponse resp = client.listParts( ListPartsArgs.builder() .bucket(bucket) .object(object) .uploadId(uploadId) .maxParts(1000) // 每页最多 1000 片 .build()); while (true) { for (Part part : resp.result().partList()) { done.add(part.partNumber()); // 记录服务端确认已存在的分片号 } if (!resp.result().isTruncated()) break; // 没有更多页就退出 resp = client.listParts( ListPartsArgs.builder() .bucket(bucket).object(object).uploadId(uploadId) .partNumberMarker(resp.result().nextPartNumberMarker()) // 从上一页末尾继续 .maxParts(1000).build()); } return done; }

这段代码的关键在分页。listParts一次最多返回 1000 个分片，文件大到接近 10000 片时如果不循环取，你会以为只传了 1000 片，恢复时把已经传过的分片又传一遍，白白浪费带宽。partNumberMarker是游标，指向下一页的起点，isTruncated告诉你还有没有下一页。这两个字段配合使用是 S3 分页接口的通用套路，换成listObjects也是同样的逻辑。

3.2 进度持久化的表结构与写入时机

进度记录建议单独建一张表，字段大致是：文件标识、桶名、对象名、uploadId、分片大小、文件总大小、已完成分片号列表、更新时间。已完成分片号可以存成逗号分隔的字符串，也可以每个分片一行，前者写入次数少、后者查询灵活，看你的恢复频率。写入时机很关键：每传完一个分片就更新一次，而不是等全部传完再写。因为断点续传要防的就是「传到一半进程挂了」，如果进度只在最后写，挂了就等于没记。

-- 分片上传进度表，按文件标识唯一 CREATE TABLE upload_progress ( file_key VARCHAR(128) PRIMARY KEY, -- 业务侧文件唯一标识，如内容 MD5 bucket VARCHAR(64) NOT NULL, object_name VARCHAR(512) NOT NULL, upload_id VARCHAR(256) NOT NULL, -- MinIO 返回的 uploadId part_size BIGINT NOT NULL, -- 本次上传采用的分片大小 total_size BIGINT NOT NULL, done_parts TEXT, -- 已完成分片号，逗号分隔 updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );

file_key用文件内容的 MD5 是最稳的，因为同一个文件不管从哪台机器传、传几次，MD5 都一样，天然能命中之前的进度。用业务文件 ID 也行，但要保证同一个文件不会因为重新上传而换了 ID。part_size必须存下来，因为恢复时如果重新算出一个不同的分片大小，已传分片的边界就对不上了，服务端会认为你提交的分片和之前的不一致。这是断点续传里最隐蔽的坑之一，后面避坑章节还会展开。

3.3 完整的上传主流程代码

把分片计算、进度查询、并发上传、完成提交串起来，主流程大致长这样：

public void uploadWithResume(String bucket, String object, File file, String fileKey) throws Exception { long fileSize = file.length(); long partSize = calcPartSize(fileSize); int partCount = (int) ((fileSize + partSize - 1) / partSize); // 向上取整 // 1. 查本地进度，看有没有可复用的 uploadId UploadProgress progress = progressRepo.find(fileKey); String uploadId; Set<Integer> doneParts = new HashSet<>(); if (progress != null && progress.getPartSize() == partSize) { uploadId = progress.getUploadId(); doneParts = listUploadedParts(bucket, object, uploadId); // 以服务端为准 } else { // 2. 没有进度或分片大小变了，重新发起分片上传 uploadId = client.createMultipartUpload( CreateMultipartUploadArgs.builder().bucket(bucket).object(object).build()) .result().uploadId(); progressRepo.save(new UploadProgress(fileKey, bucket, object, uploadId, partSize, fileSize)); } // 3. 并发上传未完成的分片 List<Part> uploaded = new ArrayList<>(); ExecutorService pool = Executors.newFixedThreadPool(8); // 并发度按带宽和内存调 List<Future<Part>> futures = new ArrayList<>(); try (RandomAccessFile raf = new RandomAccessFile(file, "r")) { for (int i = 1; i <= partCount; i++) { if (doneParts.contains(i)) continue; // 跳过已传分片 final int partNumber = i; futures.add(pool.submit(() -> { long offset = (long) (partNumber - 1) * partSize; long len = Math.min(partSize, fileSize - offset); byte[] buf = new byte[(int) len]; synchronized (raf) { raf.seek(offset); raf.readFully(buf); } // 文件指针非线程安全 UploadPartResponse r = client.uploadPart( UploadPartArgs.builder() .bucket(bucket).object(object).uploadId(uploadId) .partNumber(partNumber) .data(new ByteArrayInputStream(buf), len) .build()); progressRepo.markDone(fileKey, partNumber); // 每片完成即落库 return new Part(partNumber, r.etag()); })); } for (Future<Part> f : futures) uploaded.add(f.get()); // 收集结果，异常会在这里抛出 } finally { pool.shutdown(); } // 4. 合并已传分片（包括之前恢复的），按 partNumber 排序后提交 uploaded.sort(Comparator.comparingInt(Part::partNumber)); client.completeMultipartUpload( CompleteMultipartUploadArgs.builder() .bucket(bucket).object(object).uploadId(uploadId) .parts(uploaded).build()); progressRepo.delete(fileKey); // 完成后清理进度 }

几个地方值得单独说。RandomAccessFile的seek加read不是线程安全的，多个线程同时读同一个文件句柄会串位，所以要么加锁（示例里的synchronized），要么每个线程自己开一个FileChannel按位置读。加锁会让读文件变成串行，如果磁盘读是瓶颈，用FileChannel.read(buffer, position)更合适，它是按位置读、不移动共享指针。并发度 8 是个保守值，实际要看客户端内存：每个分片在内存里占partSize大小的字节数组，8 并发乘 16MiB 就是 128MiB 堆内存，分片再大或并发再高就要相应调 JVM 参数。completeMultipartUpload提交的 part 列表必须按 partNumber 升序，乱序提交服务端会报错，所以收集完结果要排一次序。

4. 避坑与排查：分片上传翻车的五个真实场景

4.1 现象：Complete 报「分片太小」，但代码里明明设了 5MiB

原因通常出在最后一片之外的分片小于 5MiB。比如文件 12MiB，你按 5MiB 切，得到 5、5、2 三片，第三片是最后一片所以合法；但如果因为恢复逻辑错乱，把中间某片算成了 2MiB，Complete 就会拒绝。还有一种情况是分片大小用了int计算，大文件乘法溢出变成负数，切出来的片大小完全不对。解决方式是分片大小和偏移量一律用long，并且在切分前断言除最后一片外每片都>= 5MiB。

4.2 现象：断点续传恢复后，Complete 报 ETag 不匹配

这是最典型的一类。原因有两个：一是恢复时重新算了分片大小，和第一次上传时不一致，导致分片边界错位；二是本地记录的已完成分片和服务端实际状态不一致，比如本地记了第 5 片完成，但那次请求其实超时了、服务端没落盘。解决办法是恢复时永远以listParts的服务端结果为准，本地记录只做快速筛选；同时把partSize持久化下来，恢复时直接读，不要重算。

4.3 现象：上传速度上不去，带宽只跑了一半

先查连接池。默认 OkHttp 连接池的空闲连接数很小，分片并发开到 8 但池子只有 5 个连接，剩下 3 个线程就在排队。把ConnectionPool的最大空闲连接数调到不小于并发数。再查是不是所有分片串行在读文件，synchronized包住整个读操作会让磁盘读变成单线程，改成按位置读的FileChannel能缓解。最后看服务端，MinIO 单节点的写入吞吐有上限，客户端并发再高也压不上去，这种情况要横向扩节点而不是继续调客户端参数。

4.4 现象：进程重启后 uploadId 找不到了

uploadId只存在内存里，进程一挂就丢，这是设计问题不是 bug。必须把 uploadId 和文件标识一起落库，而且要在createMultipartUpload成功后立刻写，不能等第一个分片传完再写。另一个容易忽略的点是 uploadId 有生命周期，服务端会定期清理长时间不活动的分片上传任务，如果你的恢复间隔太长（比如隔了几天），uploadId 可能已经失效，这时listParts会报NoSuchUpload，正确做法是捕获这个异常、清掉本地记录、重新发起一次全新的分片上传。

4.5 现象：小文件也走分片，反而比直接 put 慢

分片上传有额外的create和complete两次往返，对小文件来说是纯开销。常见做法是设一个阈值，比如 16MiB 以下直接putObject，超过才走分片。这个阈值不是固定的，取决于你的网络 RTT：RTT 高的环境阈值可以调大，因为两次额外往返的代价更高；内网低 RTT 环境阈值可以调小，让更多文件享受并发上传。示例代码里如果没做这个分流，接入时自己补一个判断。

5. 进阶：把分片上传压到接近带宽上限的几个调参习惯

真正把分片上传调到「跑满带宽」的状态，靠的不是某一个神奇参数，而是几个参数之间的匹配关系。我一般按这个顺序调：先定并发度，再定分片大小，最后回头校连接池和内存。

并发度先看客户端能承受多少内存。每个在途分片占partSize大小的堆内存，并发数 × 分片大小就是峰值内存占用，要留出至少一倍余量给 GC 和其他对象。比如堆 1GB、分片 16MiB，并发开到 16 就是 256MiB 峰值，还算安全；开到 32 就 512MiB，GC 压力明显上来。所以并发度不是越高越好，它受内存硬约束。

分片大小和并发度是联动的。同样的内存预算下，分片调大、并发就得调小，反之亦然。总吞吐大致正比于「并发数 × 单分片大小 / 单分片往返时间」，但单分片往返时间会随分片变大而变长，所以存在一个甜点。我的经验是内网千兆环境用 16MiB 分片配 8 到 12 并发，万兆环境用 32MiB 配 16 并发，公网不稳定环境用 8MiB 配 4 到 6 并发，牺牲一点峰值换稳定性。

连接池和超时是配套的。连接池空闲连接数要>=并发数，writeTimeout要大于「最大分片在最低预期带宽下的传输时间」。比如 32MiB 分片、预期最低 10Mbps，传输时间约 27 秒，那writeTimeout至少给 60 秒，否则慢网络下会误杀。

验证调参有没有效果，别只看「传完了」，要看三个数：总耗时、峰值堆内存、失败重试次数。总耗时除以文件大小得到实际吞吐，和带宽上限比一下就知道还有多少空间；峰值堆内存用 JVM 监控看，接近预算上限就说明并发开大了；失败重试次数如果非零，说明超时或连接池设置有问题，先解决稳定性再谈速度。我习惯在压测时把这三个数打到日志里，每次调参前后对比，比凭感觉调靠谱得多。

还有一个容易被忽略的点：completeMultipartUpload本身在大分片数下也会变慢，因为它要校验所有 ETag 并做元数据合并。分片数接近 10000 时，这一步可能占掉总耗时的可观比例。如果业务允许，尽量让分片数控制在几千以内，别贴着上限跑。

从那以后我每次接对象存储的大文件上传，都强制先跑一遍「小文件直传 + 大文件分片 + 中断恢复」三条路径的回归，尤其是中断恢复那条，手动 kill 进程再重启验证一遍，比任何参数调优都让人安心。希望帮到你。

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