1. 为什么这个组合值得单独拿出来聊

前阵子接了个后台系统的活，需求看着平平无奇：用户上传图片、Excel 报表、PDF 合同，运营后台能预览能下载，最好还能给个链接直接分享出去。项目是老系统翻新，之前所有附件全堆在应用服务器的一个本地目录里，/data/upload/，文件夹按日期分，文件名用 UUID。刚上线那会儿一切正常，跑了一年多，问题开始冒头：换机器要拷几百 G 的文件，扩容时三台实例各存各的，用户昨天传的图今天就 404；备份靠人肉rsync，谁敢动；更离谱的是有人传了个 2G 的视频，直接把磁盘写满，整个服务跟着挂。

这次重构我直接上了SpringBoot3 整合 MinIO的方案：应用只负责业务逻辑和元数据，文件本体全部交给对象存储。MinIO 是一个兼容 S3 协议的开源对象存储，单机二进制部署、容器部署都行，也能组集群，接口标准、生态成熟。SpringBoot3 这边则是 Java 17 起步、Jakarta EE 命名空间、自动配置机制也做了一轮调整，两者结合的写法跟 SpringBoot2 时代确实有差别，网上不少老教程直接抄过来会翻车。

这篇东西写给谁看？一是正在把文件存储从本地盘迁到对象存储的开发者，二是刚接触 SpringBoot3、想找个完整链路练手的同学，三是已经在用 MinIO 但总觉得哪里不对劲、想看看别人怎么收拾的同行。我会从选型理由讲到依赖版本、配置细节、完整的上传下载代码、分片与预签名、再到排查问题的实录，中间穿插我自己踩过的坑。代码都是能直接跑起来的，参数怎么算、为什么这么设，我也会把账算清楚。

2. 方案选型的账要怎么算

2.1 本地磁盘、数据库 Blob、对象存储三者的取舍

先把选型捋清楚，不然代码写得再漂亮也是白搭。文件存储这件事，常见就三条路：

数据库存 Blob 这条路我早年试过，一个 20M 的附件塞进去，mysqldump的时候能让人等到怀疑人生，恢复更别提。而且大字段会撑爆 buffer pool，查询性能跟着掉。除非文件真的小到几十 KB，否则别碰。

本地磁盘的问题不在技术，在运维。单机能跑，一旦上了负载均衡就是灾难——用户在 A 机器传的图，请求打到 B 机器就找不到。你可以挂 NFS 共享，但 NFS 的锁和延迟在高并发下又是一堆新问题。对象存储把这件事彻底解耦了：文件有唯一的 URL，任何一台应用实例都能访问，扩容就是加应用实例，存储层不用动。

MinIO 在对象存储这个品类里的优势是三件事：S3 协议兼容（意味着以后想换云厂商的对象存储，代码基本不用改）、部署极轻（一个二进制文件，或者一个容器，几分钟起来）、客户端生态好（Java、Go、Python 都有官方 SDK）。代价是它默认不是强一致分布式系统那一套复杂玩意儿，运维成本比自建 Ceph 低太多，中小团队完全够用。

2.2 SpringBoot3 到底变了什么，为什么老代码抄不过来

这是很多人卡住的地方。SpringBoot3 相对 2.x 有几个硬性变化，直接影响整合写法：

第一，Java 基线抬到 17。这不只是语法糖的事，javax.*全线换成jakarta.*。你从网上抄一段 SpringBoot2 时代的代码，如果里面涉及javax.servlet.http.HttpServletRequest、javax.annotation.Resource这类包名，编译直接报错。MinIO 客户端本身不依赖 Servlet API，所以 SDK 层面不受影响，但你的 Controller、配置类要注意。

第二，自动配置注册文件路径变了。META-INF/spring.factories里的自动配置条目迁移到了META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports。如果你打算自己封一个 starter，这个必须改。只是用 MinIO 官方 SDK 的话不涉及，但很多人会顺手封装一层，就容易在这里翻车。

第三，Spring Native / AOT 的支持。如果后面想编译成 native image，反射相关的配置要提前想好，MinIO 客户端内部有反射吗？基本没有，它就是个 OkHttp 的封装，这点是加分项。

第四，配置绑定的严格性。SpringBoot3 对@ConfigurationProperties的绑定更严格，宽松绑定规则收紧了，配置文件里写minio.endpoint而字段叫endPoint，在 2.x 时代能绑定上，3.x 某些情况下会失败。我的建议是老老实实字段名和配置 key 完全对齐，别赌。

2.3 为什么不直接用官方 starter

MinIO 官方提供过minio-spring-boot-starter，但那个项目维护节奏跟不上 SpringBoot3 的迭代，很多人反馈版本冲突。而且它封装得很薄，本质上还是帮你 new 一个MinioClient，价值有限。自己写一个配置类，二十行代码，可控性高得多，出问题也知道去哪看。这是我在多个项目里的选择，不是因为它不好，是因为自己掌控更踏实。

3. 环境准备与依赖配置的实操细节

3.1 依赖版本怎么挑，冲突怎么解

核心依赖就两个，一个是 SpringBoot3 的 parent，一个是 MinIO 客户端：

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.5</version> </parent> <properties> <java.version>17</java.version> <minio.version>8.5.10</minio.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>io.minio</groupId> <artifactId>minio</artifactId> <version>${minio.version}</version> </dependency> </dependencies>

这里有个坑得说清楚：MinIO 的 Java SDK 内部依赖 OkHttp。8.5.x 系列依赖 OkHttp 4.x，而 SpringBoot3 的某些组件（比如某些版本的spring-cloud-starter）可能间接引入 OkHttp 3.x。版本不一致的时候，运行期会抛NoSuchMethodError或者NoClassDefFoundError，报错位置还特别诡异，指向okhttp3.internal.Util。

排查方法很土但有效：mvn dependency:tree -Dincludes=com.squareup.okhttp3，把整棵树打出来，看有没有多条路径。有的话在dependencyManagement里锁死一个版本：

<dependencyManagement> <dependencies> <dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>okhttp</artifactId> <version>4.12.0</version> </dependency> </dependencies> </dependencyManagement>

另一个常见冲突是Guava。某些老版本的 MinIO SDK 依赖 Guava，而 SpringBoot3 生态里也有人用 Guava。如果你发现启动时报NoSuchMethodError: com.google.common.*，八成就是版本对不上。8.5.10 这个版本我去掉了 Guava 依赖，相对干净，但升级前还是建议跑一遍dependency:tree确认。

注意：不要在项目里同时引入minio和 AWS 的aws-java-sdk-s3，两套 SDK 的 HTTP 客户端、签名逻辑会互相打架，尤其是都配置了全局的 OkHttp 拦截器时。真需要 S3 兼容层，二选一。

3.2 MinIO 服务端怎么起，桶和权限怎么规划

服务端部署我给两个方案，看你的环境。

开发环境用 Docker，一条命令：

services: minio: image: minio/minio:RELEASE.2024-04-18T19-09-19Z container_name: minio ports: - "9000:9000" # S3 API 端口 - "9001:9001" # 控制台端口 environment: MINIO_ROOT_USER: admin MINIO_ROOT_PASSWORD: Admin@123456 command: server /data --console-address ":9001" volumes: - ./minio-data:/data

9000是给 Java 客户端用的 S3 接口，9001是 Web 控制台，别搞混。很多人第一次配反了，客户端一直连 9001，报的错还特别含糊。

生产环境建议用二进制 + systemd，或者用官方的分布式部署模式。单机单盘只能作为开发用，生产至少要用纠删码模式，否则盘挂了数据就没了。这个不是本文重点，但必须提一句。

桶的规划是有讲究的。不要所有文件塞一个桶。我的做法是按业务域拆分：

原因是权限粒度。公开读的桶配一条 policy 就行，私有桶全部走预签名 URL，两套逻辑不能混在一个桶里。我见过有人图省事全部设公共读，结果用户上传的身份证照片能被全网爬，这个责任担不起。

策略配置用mc命令行最方便：

mc alias set local http://127.0.0.1:9000 admin Admin@123456 mc mb local/app-public local/app-private local/app-temp mc anonymous set download local/app-public

app-temp桶记得加生命周期规则，比如 7 天自动清理，不然分片上传失败留下的碎片会一直堆着，时间长了占满磁盘你都不知道。

3.3 配置文件怎么写才不踩坑

application.yml里我一般这么写：

minio: endpoint: http://127.0.0.1:9000 access-key: admin secret-key: Admin@123456 bucket: public: app-public private: app-private temp: app-temp connect-timeout: 10000 write-timeout: 60000 read-timeout: 60000 max-connections: 100

几点说明。endpoint必须带协议头，http://或https://，不带的话 SDK 会抛IllegalArgumentException: endpoint must be a valid URL。这是个新手高频错误。

超时时间要分开设。connect-timeout是建连超时，10 秒够了，网络正常的话建连是毫秒级。write-timeout和read-timeout是传输超时，得按文件大小算。我一般设 60 秒起步，因为大文件上传时，最后一个分片传完到服务端合并，中间可能有较长的等待。设太短会抛java.net.SocketTimeoutException: timeout，而且这个异常是在流读取阶段抛的，业务代码里很难优雅处理。

连接数max-connections别设太大。OkHttp 的默认连接池是 5 个空闲连接，你设 100 只是上限，实际并发上传的线程数才是真正的瓶颈。设太大会在服务端产生大量 TIME_WAIT，反而拖慢。我的经验值是 50~100，够用了。

生产环境千万不要把密钥明文写在配置文件里。用环境变量注入，或者接配置中心。SpringBoot 的@ConfigurationProperties支持从环境变量读，命名规则是MINIO_ACCESS_KEY这种大写下划线格式，直接就能覆盖 yml 里的值，这是最省事的方案。

4. 核心代码：从客户端装配到上传下载全链路

4.1 MinioClient 的 Bean 装配与配置绑定

先写配置属性类：

@Data @ConfigurationProperties(prefix = "minio") public class MinioProperties { private String endpoint; private String accessKey; private String secretKey; private Bucket bucket = new Bucket(); private long connectTimeout = 10000; private long writeTimeout = 60000; private long readTimeout = 60000; private int maxConnections = 100; @Data public static class Bucket { private String publicBucket = "app-public"; private String privateBucket = "app-private"; private String tempBucket = "app-temp"; } }

这里有个细节：@Data是 Lombok 的，字段名的驼峰形式要和 yml 里的 key 对应。publicBucket对应public-bucket，SpringBoot3 的宽松绑定对这个是支持的，但我建议 yml 里也写public-bucket，别写publicBucket，风格统一。

然后是客户端配置类：

@Configuration @EnableConfigurationProperties(MinioProperties.class) public class MinioConfig { @Bean public MinioClient minioClient(MinioProperties props) { OkHttpClient httpClient = new OkHttpClient.Builder() .connectTimeout(props.getConnectTimeout(), TimeUnit.MILLISECONDS) .writeTimeout(props.getWriteTimeout(), TimeUnit.MILLISECONDS) .readTimeout(props.getReadTimeout(), TimeUnit.MILLISECONDS) .connectionPool(new ConnectionPool(props.getMaxConnections(), 5, TimeUnit.MINUTES)) .build(); return MinioClient.builder() .endpoint(props.getEndpoint()) .credentials(props.getAccessKey(), props.getSecretKey()) .httpClient(httpClient) .build(); } }

MinioClient是线程安全的，做成单例 Bean 没有任何问题。它内部持有的就是上面这个OkHttpClient，所以连接池复用是天然生效的。不要每次上传都 new 一个 MinioClient，我见过这种写法，原因是"怕连接被占用"，结果每次 new 都建一个连接池，跑一天下来文件句柄耗尽，服务直接起不来。

ConnectionPool的第二个参数是 keepAlive 时间，5 分钟是合理值。太短的话连接频繁重建，长连接的优势就没了。

4.2 启动自检：桶不存在就自动创建

生产环境部署时，桶不一定提前建好了，尤其是新环境初始化。我习惯在启动时做一次自检：

@Component @RequiredArgsConstructor @Slf4j public class MinioBucketInitializer implements ApplicationRunner { private final MinioClient minioClient; private final MinioProperties props; @Override public void run(ApplicationArguments args) { List<String> buckets = List.of( props.getBucket().getPublicBucket(), props.getBucket().getPrivateBucket(), props.getBucket().getTempBucket() ); for (String bucket : buckets) { try { boolean exists = minioClient.bucketExists( BucketExistsArgs.builder().bucket(bucket).build()); if (!exists) { minioClient.makeBucket( MakeBucketArgs.builder().bucket(bucket).build()); log.info("桶 {} 创建成功", bucket); } } catch (Exception e) { log.error("初始化桶 {} 失败", bucket, e); throw new IllegalStateException("对象存储初始化失败，服务无法启动", e); } } } }

用ApplicationRunner而不是@PostConstruct，原因是@PostConstruct执行时机太早，某些 Bean 还没就绪，且失败后容器的处理逻辑不太可控。ApplicationRunner在容器启动完成后执行，抛异常能明确阻止服务对外提供能力。

这里必须抛异常让服务起不来。我见过有同事写成log.error就完事了，结果服务正常启动，用户传文件时才报错，排查了半天。启动期失败的成本远低于运行期失败，这个原则值得记住。

4.3 上传：文件名、路径、元数据的处理套路

上传的核心逻辑我封装成一个服务类，关键点全在细节里：

@Service @RequiredArgsConstructor @Slf4j public class FileStorageService { private final MinioClient minioClient; private final MinioProperties props; public String upload(MultipartFile file, String bizType) { String originalName = file.getOriginalFilename(); String ext = getExtension(originalName); String objectName = buildObjectName(bizType, ext); String contentType = resolveContentType(file, ext); try (InputStream in = file.getInputStream()) { minioClient.putObject(PutObjectArgs.builder() .bucket(props.getBucket().getPrivateBucket()) .object(objectName) .stream(in, file.getSize(), -1) .contentType(contentType) .build()); return objectName; } catch (Exception e) { log.error("文件上传失败, name={}", originalName, e); throw new BizException("文件上传失败"); } } private String buildObjectName(String bizType, String ext) { LocalDate now = LocalDate.now(); String datePath = String.format("%d/%02d/%02d", now.getYear(), now.getMonthValue(), now.getDayOfMonth()); String uuid = UUID.randomUUID().toString().replace("-", ""); return String.format("%s/%s/%s.%s", bizType, datePath, uuid, ext); } }

buildObjectName用了业务类型/年/月/日/uuid.扩展名的结构。为什么不直接把原始文件名当 objectName？三个原因：一是用户上传的文件名可能带中文、空格、特殊字符，S3 的 key 虽然支持，但拼接 URL 时各种转义问题会让人崩溃；二是同名文件会互相覆盖；三是按日期分目录方便后续做归档和生命周期管理，比如"去年的临时文件整体清掉"。

putObject的stream(in, size, -1)这几个参数是有讲究的。第二个参数是对象总大小，第三个是分片大小，-1表示由 SDK 自动决定。如果总大小未知（比如从网络流直接透传），要传-1作为 size，SDK 会自动走分片上传模式。但如果 size 是已知的，一定要传准确值，SDK 会据此决定是否分片，传错会导致上传失败或文件损坏。

contentType必须设置。不设的话，MinIO 默认给application/octet-stream，浏览器访问时直接触发下载，图片没法预览。我的处理逻辑是优先用MultipartFile.getContentType()，但它经常返回null或者不准（比如某些客户端把 png 报成application/octet-stream），所以还要根据扩展名兜底：

private String resolveContentType(MultipartFile file, String ext) { String ct = file.getContentType(); if (ct != null && !ct.isBlank() && !"application/octet-stream".equals(ct)) { return ct; } return switch (ext.toLowerCase()) { case "png" -> "image/png"; case "jpg", "jpeg" -> "image/jpeg"; case "gif" -> "image/gif"; case "pdf" -> "application/pdf"; case "xlsx" -> "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"; case "docx" -> "application/vnd.openxmlformats-officedocument.wordprocessingml.document"; default -> "application/octet-stream"; }; }

提示：扩展名一定要从原始文件名里取，并且做白名单校验。不校验的话，用户传个.jsp、.html，如果你的桶是公共读的，就变成了一个可执行的静态页面托管，这是典型的安全隐患。白名单之外的类型直接拒绝，别图省事。

4.4 下载与预览：流式响应和预签名两条路

下载分两种场景，实现方式完全不同。

场景一：后端代理下载。文件是私有的，用户请求先到你后端，鉴权通过后由后端从 MinIO 拉流返回。适合小文件、需要精细控制权限的场景。

public void download(String objectName, HttpServletResponse response) { try (InputStream in = minioClient.getObject(GetObjectArgs.builder() .bucket(props.getBucket().getPrivateBucket()) .object(objectName) .build())) { StatObjectResponse stat = minioClient.statObject(StatObjectArgs.builder() .bucket(props.getBucket().getPrivateBucket()) .object(objectName) .build()); response.setContentType(stat.contentType()); response.setContentLengthLong(stat.size()); String encoded = URLEncoder.encode(stat.object(), StandardCharsets.UTF_8) .replace("+", "%20"); response.setHeader("Content-Disposition", "attachment; filename*=UTF-8''" + encoded); StreamUtils.copy(in, response.getOutputStream()); } catch (Exception e) { log.error("下载失败, object={}", objectName, e); throw new BizException("文件下载失败"); } }

Content-Disposition里的中文文件名必须用filename*=UTF-8''的格式，直接写中文会乱码。这是 HTTP 头的老问题，URLEncoder.encode之后还要把+替换成%20，因为+在 RFC 3986 里表示空格，某些浏览器解析不一致。

StreamUtils.copy是 Spring 提供的流拷贝工具，内部用了缓冲区，比手写while循环干净。但要注意，它不负责关闭流，try-with-resources已经处理了。

场景二：预签名直传/直下。这是 MinIO 最有价值的能力之一。后端只负责签发一个带签名的临时 URL，客户端拿着这个 URL 直接跟 MinIO 通信，流量不经过你的应用服务器。

public String presignedGetUrl(String objectName, int expireSeconds) { try { return minioClient.getPresignedObjectUrl(GetPresignedObjectUrlArgs.builder() .method(Method.GET) .bucket(props.getBucket().getPrivateBucket()) .object(objectName) .expiry(expireSeconds, TimeUnit.SECONDS) .build()); } catch (Exception e) { throw new BizException("生成访问链接失败"); } }

这个方法的价值在带宽上。假设你的应用服务器是 5M 带宽，用户下载一个 500M 的文件，走代理要占满带宽好几分钟，期间其他请求全卡住。走预签名，应用服务器只返回一个几百字节的 URL，文件流量走 MinIO 自己的网络，应用层压力直接归零。

expiry的有效期要注意，MinIO 对预签名 URL 的最大有效期有限制，默认上限是 7 天。设太长有安全风险，设太短用户打开链接就过期。我的经验是：一次性下载给 5 分钟，页面内预览给 30 分钟，分享链接给 24 小时（并且要求分享链接本身带业务层的鉴权 token）。

还有一点，预签名 URL 里包含了签名信息，一旦泄露，任何人在有效期内都能访问。所以私有文件的预签名 URL 绝对不能写进日志，也不能放在前端可以被别人抓包的地方。我见过把预签名 URL 直接拼在<img src>里然后被爬虫批量抓取的，等同于把文件裸奔。

5. 大文件、分片与性能的精细控制

5.1 分片上传的两种实现路线

小文件（比如 10M 以内）直接putObject就够了，MinIO SDK 内部会处理。但超过一定大小，问题就来了：一是 HTTP 请求体太大，中间任何一层代理（Nginx 的client_max_body_size、网关的请求体限制）都可能直接掐断；二是失败重传成本太高，传了 900M 断了，要从头再来。

分片上传有两条路线。

路线一：后端中转分片。前端把文件切片，逐片传给后端，后端传给 MinIO 的临时对象，最后合并。这条路线对前端要求低，但流量还是过应用服务器，优势不明显，只适合"前端没法直连 MinIO"的内网环境。

路线二：前端直传 + 预签名。前端自己切片，每片向后端要一个预签名 PUT URL，直传 MinIO，最后通知后端合并。这是主流做法，带宽完全走存储层。

预签名上传的生成：

public String presignedPutUrl(String objectName, int expireSeconds) { try { return minioClient.getPresignedObjectUrl(GetPresignedObjectUrlArgs.builder() .method(Method.PUT) .bucket(props.getBucket().getTempBucket()) .object(objectName) .expiry(expireSeconds, TimeUnit.SECONDS) .build()); } catch (Exception e) { throw new BizException("生成上传链接失败"); } }

前端拿到 URL 后，用fetch或者axios直接 PUT 二进制数据，注意Content-Type要跟签名时一致，否则会SignatureDoesNotMatch。

合并用composeObject：

public void composeChunks(String targetObject, List<String> chunkObjects) { try { List<ComposeSource> sources = chunkObjects.stream() .map(name -> ComposeSource.builder() .bucket(props.getBucket().getTempBucket()) .object(name) .build()) .toList(); minioClient.composeObject(ComposeObjectArgs.builder() .bucket(props.getBucket().getPrivateBucket()) .object(targetObject) .sources(sources) .build()); } catch (Exception e) { throw new BizException("文件合并失败"); } }

composeObject有个限制：除最后一个分片外，每个分片不能小于 5MB。这是 S3 协议的硬性规定，不是 MinIO 自己加的。所以前端切片时，chunkSize必须大于 5MB，我一般设 5MB 或 10MB。设成 1MB 的话，合并时直接报EntityTooSmall，而且报错信息不会告诉你是哪个分片的问题，排查起来很费劲。

分片数量也有上限，S3 协议规定最多 10000 片。按 5MB 一片算，单个文件最大 50G 左右。超过这个大小就得用更大的分片。这个账要提前算：如果你的业务可能传 100G 的文件，chunkSize 至少设 10MB。

5.2 秒传与去重：用摘要做前置判断

用户重复上传同一个文件的场景比你想象的多。前端加个秒传逻辑，体验提升明显：

public UploadResult fastUpload(String fileMd5, String originalName, long size) { String objectName = md5Index.get(fileMd5); if (objectName == null) { return UploadResult.needUpload(); } try { minioClient.statObject(StatObjectArgs.builder() .bucket(props.getBucket().getPrivateBucket()) .object(objectName) .build()); return UploadResult.hit(objectName); } catch (Exception e) { // 对象已不存在，索引失效，走正常上传 md5Index.remove(fileMd5); return UploadResult.needUpload(); } }

statObject这一步不能省。索引里记录了 md5 到 objectName 的映射，但对象可能已经被清理了（比如生命周期规则删掉了，或者有人手动删了），不校验直接返回秒传结果，用户拿到的就是 404。

md5 索引我一般放 Redis，key 是md5的十六进制，value 是 objectName，设置一个合理的过期时间（比如 30 天）。放数据库也行，但查询频率高，Redis 更合适。

注意：秒传有一个隐私问题。如果 A 用户上传了一个文件，B 用户用同样的 md5 请求秒传，B 就"拥有"了这个文件的访问权，而他实际上没上传过。对于敏感业务（比如合同、病历），这个逻辑是绝对不能用的。只对公开资源或者内部资料库开放秒传，这点必须按业务性质判断。

5.3 参数调优的几个关键账

举个实际算例：假设业务允许最大 20G 的文件，分片上限 10000，那 chunkSize 至少是20 * 1024 / 10000 ≈ 2.05MB，但受限于 5MB 下限，取 10MB 更稳妥，这样最大支持10000 * 10MB ≈ 97G，留足余量。

再算连接池。假设峰值 50 个用户同时上传，每个上传占 1 个连接，加上后台的下载、预览请求，峰值可能到 80 个连接。设 100 是合理的，设 500 就浪费了，还容易把服务端的ulimit打满。

6. 常见问题与排查实录

6.1 异常速查表

6.2 几个真实踩过的坑

坑一：本地调试正常，上生产就 403。排查了半天，发现是生产环境前面挂了反向代理，代理转发时把Host头改成了内网地址，MinIO 校验签名时用的 host 对不上。解决办法是给 MinIO 配MINIO_SERVER_URL环境变量，或者在代理层保留原始 Host。这个问题的迷惑性在于，MinIO 服务端的日志里只有一条SignatureDoesNotMatch，什么细节都不给。

坑二：上传大文件时 JVM 堆爆了。代码里写的是byte[] bytes = file.getBytes(); 然后 new ByteArrayInputStream(bytes)。一个 500M 的文件，光这一个请求就吃掉 500M 堆内存，几个并发直接 OOM。改成file.getInputStream()直接透传就好了。这是我见过的最高频的低级错误，没有之一。

坑三：图片上传后前端预览不了，浏览器直接下载。原因是contentType设成了application/octet-stream。追下去发现，前端上传时用的FormData，MultipartFile.getContentType()拿到的就是octet-stream，后端又原样存了。解决办法就是上面那段根据扩展名兜底的逻辑，别偷懒。

坑四：分片上传偶尔出现文件损坏。查了很久，最后发现是前端并发传分片时，同一个 objectName 用了相同的分片 key，后传的覆盖了先传的。分片对象的 key 必须包含分片序号，比如temp/{uploadId}/{index}，而且上传前要生成一个全局唯一的uploadId，不能只靠文件名。

坑五：Windows 下开发，文件名带中文，下载乱码。本质是Content-Disposition的编码问题，前面已经说过用filename*=UTF-8''。但还有一个细节：某些老版本浏览器对filename*支持不好，可以同时给一个 ASCII 的filename作为兜底，两个头都带上。

6.3 生产环境的加固清单

上线前我一般会过一遍这几项，少一项都不放心：

• 密钥管理：走环境变量或配置中心，配置文件中不出现明文。定期轮换密钥，轮换时用双密钥过渡，避免服务中断。
• 桶权限最小化：只有确实需要公开的桶设公共读，其余全部私有。每个桶单独评估，别偷懒批量设。
• 生命周期规则：临时桶必须配自动清理，保留 7 天。正式桶的归档策略按业务定，别让存储无限膨胀。
• 上传大小限制：Spring 层配spring.servlet.multipart.max-file-size，Nginx 层配client_max_body_size，MinIO 层可以通过策略限制。三层都要配，任何一层漏了都可能被绕过。
• 文件类型白名单：扩展名 + MIME 双重校验，且以扩展名为准（MIME 可以被伪造）。
• 访问日志：MinIO 的审计日志要开，记录谁在什么时候访问了哪个对象。出了数据泄露事件，这是唯一的追溯依据。
• 备份策略：用mc mirror定期同步到另一个存储实例，注意是增量同步，别每次都全量。

最后分享一个我自己的小习惯：给每个上传的文件在数据库里单独记一条元数据，包括 objectName、原始文件名、大小、contentType、md5、上传人、上传时间、业务归属。看起来是多此一举，但等到需要做"找出某个用户上传的所有文件""统计某类文件的总存储量""清理三个月前的废弃附件"这类需求时，你会发现这张表比在 MinIO 里翻对象高效一百倍。对象存储负责存，数据库负责管，职责分清楚，后面才不难受。