1. 从本地磁盘到对象存储一次被迫的存储改造项目做到第三个月文件上传这块先出事了。最初版本很朴素MultipartFile拿过来直接transferTo到服务器本地的一个upload目录数据库里存个相对路径前端拼接域名访问。单机跑得好好的直到运维把服务扩到三个实例用户反馈刚传的头像刷新一下就 404 了——负载均衡把下载请求打到了另一台机器上那台机器上根本没有这个文件。这件事之后我才认真去做了 SpringBoot 3 整合 MinIO 这件事而不是继续在本地磁盘上打补丁。MinIO 是什么一句话讲清楚它是一个可以自己部署的对象存储服务对外提供的接口和 S3 协议高度兼容你把文件扔进去它给你一个 key取的时候拿 key 换内容。它解决的核心问题是文件不再和某一台应用服务器绑定同时把文件读写这件事从操作系统的文件系统抽象成了一套带鉴权的 HTTP 接口。适合谁来参考这篇内容我的判断是三类人一类是项目里正在用本地磁盘存文件、已经被多实例部署坑过的后端一类是要做私有化交付、不能用公有云对象存储的团队还有一类是刚开始接触 SpringBoot 3、想找一个真实可跑的中间件集成案例练手的开发者。MinIO 本身不复杂装起来一个二进制文件加两条命令就能跑。真正花时间的部分在于把它和 SpringBoot 3 缝在一起的过程——依赖版本的互相牵扯、Bean 的装配时机、对象名的设计、预签名 URL 的地址问题、大文件的分片策略、删库和删文件之间的一致性。这些问题在官方文档里大多只有一行说明踩上去才知道疼。下面我把这条链路从头到尾拆一遍代码可以直接抄坑我也标出来了。2. 依赖版本这一步就把人拦下了okhttp 冲突与 Bean 装配2.1 SpringBoot 3 带来的不只是 Jakarta 命名空间很多人以为 SpringBoot 3 的迁移成本就是把javax.*全局替换成jakarta.*改完编译通过就完事了。文件上传这块确实受这个影响——javax.servlet.http.HttpServletRequest变成了jakarta.servlet.http.HttpServletRequest如果你项目里有自定义的 Filter 或者用了某些老版本的 Web 工具库编译期就会报错。但这只是明面上的。真正隐蔽的是第三方 SDK 的传递依赖。MinIO 的 Java SDK 底层用的是 OkHttp 发 HTTP 请求而 OkHttp 4.x 相对 3.x 改了一批静态工厂方法的签名。如果你的项目里还有别的组件比如某些推送 SDK、某些 HTTP 客户端封装把 OkHttp 锁在了 3.xMaven 的最近优先原则可能给你解析出一个混合版本编译期一切正常运行到第一次调用 MinIO 就抛NoSuchMethodError堆栈里指向的是okhttp3.RequestBody.create之类的方法。这个报错第一次见会非常懵因为你的代码里压根没出现过 OkHttp。我当时的做法是先看清依赖树的真实面貌mvn dependency:tree -Dincludescom.squareup.okhttp3输出里如果出现两个不同版本的 okhttp基本就确诊了。解决方式有两种我倾向前一种dependency groupIdio.minio/groupId artifactIdminio/artifactId version8.5.7/version exclusions exclusion groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId /exclusion /exclusions /dependency dependency groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId version4.12.0/version /dependency显式排除再加显式声明等于告诉 Maven这块版本我接管了。另一种是在dependencyManagement里统一锁定 OkHttp 版本效果类似但如果项目是多模块的容易在某个子模块里漏掉反而不如排除来得干脆。实测下来OkHttp 4.12.0 配 minio-java 8.5.x 是稳的组合我用了大半年没再出现过类似的NoSuchMethodError。注意不要图省事把 minio 的版本降到 8.4.x 去迁就旧 OkHttp8.4 系列在部分分片上传场景下有已知的流关闭问题而且新版本对 S3 的兼容性更好往回退是给自己找麻烦。2.2 配置项与 MinioClient 的装配时机MinIO 的连接信息就四个endpoint、accessKey、secretKey、默认桶名。我习惯用ConfigurationProperties接而不是每个字段写一个Value原因是后面如果要加区域、加超时、加多个桶字段会越来越多散落各处的Value维护起来很痛苦。minio: endpoint: http://127.0.0.1:9000 access-key: minioadmin secret-key: minioadmin bucket: app-file presign-endpoint: https://file.example.internal注意endpoint和presign-endpoint是两个值这个后面第 4 节会详细说先记住有这么个东西。Data ConfigurationProperties(prefix minio) public class MinioProperties { private String endpoint; private String accessKey; private String secretKey; private String bucket; private String presignEndpoint; }Configuration EnableConfigurationProperties(MinioProperties.class) public class MinioConfig { Bean public MinioClient minioClient(MinioProperties props) { return MinioClient.builder() .endpoint(props.getEndpoint()) .credentials(props.getAccessKey(), props.getSecretKey()) .build(); } }这里有个容易被忽略的点MinioClient本身是线程安全的官方明确说过一个实例可以全局复用它的 Builder 内部维护了连接池。这意味着你不要在每次上传的时候new一个 client也不要用Scope(prototype)。我曾经在一个项目里见过同事在 Service 方法里现场构建 client压测的时候连接数飙到几千服务端直接开始拒连。另一个点是装配顺序。如果你在PostConstruct里做建桶检查要注意此时网络可能还没就绪尤其是容器化部署MinIO 和应用同时启动的场景。我一般把建桶逻辑放到一个ApplicationRunner里并且加上重试Component RequiredArgsConstructor public class MinioBucketInitializer implements ApplicationRunner { private final MinioClient minioClient; private final MinioProperties props; Override public void run(ApplicationArguments args) { String bucket props.getBucket(); for (int i 0; i 5; i) { try { boolean exists minioClient.bucketExists( BucketExistsArgs.builder().bucket(bucket).build()); if (!exists) { minioClient.makeBucket(MakeBucketArgs.builder().bucket(bucket).build()); } return; } catch (Exception e) { if (i 4) { throw new IllegalStateException(MinIO 桶初始化失败: bucket, e); } try { Thread.sleep(2000L); } catch (InterruptedException ignored) { } } } } }用ApplicationRunner而不是PostConstruct是因为前者在容器完全启动之后才执行此时配置、线程池都就绪了失败重试也不会阻塞 Bean 的创建过程。这算是我踩过的一次坑换来的习惯——之前把建桶写在PostConstruct里MinIO 启动慢了两秒整个应用启动直接失败排查了半天才发现是初始化时序的问题。3. 桶、对象名与上传链路的三处设计取舍3.1 对象名怎么设计决定了后面运维有多痛对象名objectName是 MinIO 里唯一的标识相当于文件系统里的完整路径。我见过三种写法优劣差别很大。第一种是直接把用户上传的原始文件名当对象名报表.xlsx就叫报表.xlsx。这种写法的问题三天内就会暴露两个用户传同名文件后者覆盖前者文件名里的空格、中文、#、?在拼接 URL 的时候需要转义一不小心就 400所有文件平铺在同一层桶里几万个对象之后控制台翻页都卡。第二种是 UUID 加扩展名a3f9c1e2-....xlsx。解决了重名和特殊字符但完全丧失了可读性运维想找某个文件只能靠数据库反查。我现在统一用的是第三种日期分层加业务前缀加 UUID 加扩展名private String buildObjectName(String bizType, String originalFilename) { String ext ; int dot originalFilename.lastIndexOf(.); if (dot -1) { ext originalFilename.substring(dot).toLowerCase(); } String date LocalDate.now().format(DateTimeFormatter.ofPattern(yyyy/MM/dd)); String uuid UUID.randomUUID().toString().replace(-, ); return bizType / date / uuid ext; }这样生成出来的对象名长这样avatar/2024/06/18/9f2c8a1b....jpg。好处有三层日期分层让单个目录下的对象数量可控批量清理历史文件时按前缀删就行业务前缀让你在控制台一眼能看出这个桶里都装了什么类型的文件UUID 保证唯一性不用处理并发重名。原始文件名不丢存在数据库的一个字段里下载的时候再还原成用户看得懂的名字。这里有个细节值得单独说不要用File.separator或者反斜杠。对象名必须是正斜杠而且不能以斜杠开头。有次在 Windows 上开发代码里用了Paths.get(...).toString()拼路径本地跑没问题MinIO 会做兼容处理部署到 Linux 之后所有的对象名都正常但下载时的路径匹配逻辑炸了因为数据库里存的对象名带了反斜杠。3.2 三种上传形态的选择逻辑SpringBoot 里往 MinIO 传文件落到代码上无非是三个入口选哪个取决于文件大小和调用方。小文件走MultipartFile最直观。但要注意MultipartFile.getInputStream()的流只能读一次且getSize()返回的是字节数可以直接传给 SDKpublic String upload(MultipartFile file, String bizType) { String objectName buildObjectName(bizType, file.getOriginalFilename()); try (InputStream in file.getInputStream()) { minioClient.putObject(PutObjectArgs.builder() .bucket(props.getBucket()) .object(objectName) .stream(in, file.getSize(), -1) .contentType(file.getContentType()) .build()); return objectName; } catch (Exception e) { throw new RuntimeException(上传失败, e); } }stream(in, size, partSize)这三个参数值得解释一下。第二个参数是对象总大小第三个参数是分片大小。当size已知且小于 5MiB 时partSize传-1SDK 走单次 PUT当size大于 5MiB 时SDK 会自动切成 5MiB 一片做分片上传partSize传-1让它自己算当size未知比如从网络流直接转发时第二个参数传-1此时必须显式指定partSize且不能小于 5MiB5 * 1024 * 1024否则 SDK 会直接抛参数异常。中等文件走字节数组适合文件已经在内存里的场景比如服务端生成的 Excel、PDF。直接new ByteArrayInputStream(bytes)配上bytes.length就行简单直接。但要注意内存占用一次性把 50MB 读进byte[]并发几十个就是几个 G 的堆压力所以这条路我只在文件确定小于 10MB 的时候用。大文件走前端直传这是最省服务器资源的方案。后端只负责签发一个预签名 URL第 4 节讲前端拿到 URL 之后自己 PUT 到 MinIO文件流量完全不经过应用服务器。代价是前端要处理分片和断点复杂度上去了。三种形态的取舍我整理成了这张表实际选型的时候对着看就行形态适用文件大小服务器压力前端复杂度典型场景MultipartFile 转发 50MB中流量过应用低头像、附件、导入模板字节数组 10MB高占堆内存低动态生成的报表、导出文件预签名直传无上限低流量不过应用高视频、大压缩包、批量素材3.3 Content-Type 与编码这两件小事contentType不传会怎样MinIO 会给你默认成application/octet-stream。后果是浏览器访问这个文件 URL 的时候不会内联预览一律弹下载框。图片、PDF 这类需要在线看的文件必须在putObject的时候显式带上contentType。MultipartFile.getContentType()拿到的值来自浏览器大多数时候是对的但不能全信。用户可以用工具改掉请求头传一个.jpg却声明成text/html。如果你的桶开了公共读这玩意儿就变成了一个可以在你的域名下执行脚本的 HTML 页面风险不小。我现在的做法是服务端根据扩展名做一次收敛白名单之外的统一按application/octet-stream处理private static final MapString, String TYPE_MAP Map.of( jpg, image/jpeg, jpeg, image/jpeg, png, image/png, gif, image/gif, pdf, application/pdf, xlsx, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, docx, application/vnd.openxmlformats-officedocument.wordprocessingml.document ); private String resolveContentType(String filename) { int dot filename.lastIndexOf(.); if (dot -1) return application/octet-stream; String ext filename.substring(dot 1).toLowerCase(); return TYPE_MAP.getOrDefault(ext, application/octet-stream); }多这一步看着啰嗦但它同时解决了两个问题一是健康的内联预览二是把不可信的类型声明挡在门外。上线之后再回来看这十几行代码是整个上传链路里性价比最高的部分。4. 预签名 URL方便背后的地址与签权陷阱4.1 预签名到底在签什么预签名 URLpresigned URL的本质是服务端用 accessKey 和 secretKey 对一个即将发生的请求做 HMAC 签名把签名、过期时间、访问凭证一起拼进 URL 的 query 参数里然后把这个带签名的 URL 交给前端。前端拿着 URL 直接访问 MinIOMinIO 自己校验签名校验通过就返回文件全程不需要应用服务器参与。这个机制最直接的好处是下载流量不过应用服务器而且天然支持时效控制——链接发出去 7 天就失效不需要额外的权限系统。生成代码很短public String presignedGetUrl(String objectName, Duration expiry) { try { return minioClient.getPresignedObjectUrl(GetPresignedObjectUrlArgs.builder() .method(Method.GET) .bucket(props.getBucket()) .object(objectName) .expiry((int) expiry.toSeconds()) .build()); } catch (Exception e) { throw new RuntimeException(生成预签名地址失败, e); } }expiry有硬上限最长 7 天传更大的值 SDK 会直接抛异常。这个限制来自 SigV4 签名规范不是 MinIO 自己加的。所以如果你的业务是生成一个永久下载链接只能靠业务侧发一个短链重定向每次访问时重新签一个。4.2 最容易翻车的地方URL 里的 host 是谁预签名 URL 生成出来之后形如http://127.0.0.1:9000/app-file/avatar/2024/...?X-Amz-Algorithm...X-Amz-Signature...。注意那个 host它是你在MinioClient.builder().endpoint()里配置的值。如果应用服务器和 MinIO 在同一内网你配置的是http://10.0.1.5:9000那签出来的 URL 里就是内网 IP。这个 URL 直接丢给浏览器用户的电脑根本访问不到10.0.1.5结果就是一个超时。这是我在第一个项目里遇到的第一个线上问题测试环境全内网所以一直没发现上线后前端同学说图片全是裂的。解决办法有两个我推荐第二个。办法一配置两套 endpoint。一套给服务端自己调用 SDK 用内网快一套只用来生成对外 URL公网域名。但getPresignedObjectUrl是用 client 的 endpoint 签的你没法在调用时临时换 endpoint。变通做法是再建一个专门用于签名的 clientBean(presignMinioClient) public MinioClient presignMinioClient(MinioProperties props) { return MinioClient.builder() .endpoint(props.getPresignEndpoint()) .credentials(props.getAccessKey(), props.getSecretKey()) .build(); }需要注意签名是按 host 算进去的所以你用公网地址签、前端用公网地址访问签名才对得上。用内网 client 签出来再把 URL 里的 host 字符串替换成公网域名一定会得到SignatureDoesNotMatch因为 Host 是 SigV4 计算签名时参与运算的 header 之一。办法二用反向代理统一域名。Nginx 上挂一个file.example.com同时反代到 MinIO 和应用MinIO 那边通过环境变量MINIO_SERVER_URL声明自己的外部访问地址。这样内网外网看到的是同一个域名签出来的 URL 天然可用。location /app-file/ { proxy_pass http://10.0.1.5:9000/app-file/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; client_max_body_size 0; proxy_buffering off; }proxy_set_header Host $host这行是命门。如果不加Nginx 会把 Host 改成上游地址10.0.1.5:9000而预签名里签的是file.example.com两边一比对签名校验失败。proxy_buffering off是为大文件下载准备的避免 Nginx 先把整个文件缓存到本地临时目录再吐给客户端白白多占一份磁盘 IO。还有一个我踩过的坑URL 里的对象名必须 URL 编码。如果你的对象名里有中文或者空格虽然我在 3.1 里建议不要但历史数据总归有拼 URL 的时候没编码MinIO 那边解析出来的对象名和你签的对象名对不上一样是签名失败。SDK 内部对 objectName 做了编码但如果你是自己手动拼字符串比如在 URL 后面追加?response-content-disposition...之类的参数就要自己处理。4.3 下载时的中文文件名预签名 URL 默认打开是浏览器的行为能识别的类型内联显示不能识别的弹下载。文件名会是对象名里那串 UUID用户看到一个9f2c8a1b.jpg会一脸问号。要指定下载文件名可以在签名的时候加response-content-disposition参数MapString, String queryParams new HashMap(); queryParams.put(response-content-disposition, attachment; filename*UTF-8 URLEncoder.encode(originalName, StandardCharsets.UTF_8));注意必须用filename*UTF-8这个带星号的写法这是 RFC 5987 规定的中文文件名编码方式。老的filenamexxx直接放 UTF-8 字节在某些浏览器上会变成乱码。我一开始用的是老写法测试同学发来截图说下载下来叫 鎶ュ憡.xlsx改成filename*之后正常。如果走的是后端流式下载流量过应用思路一样只是换成设置 Response HeaderGetMapping(/file/{objectName}) public void download(PathVariable String objectName, HttpServletResponse response) throws Exception { StatObjectResponse stat minioClient.statObject( StatObjectArgs.builder().bucket(props.getBucket()).object(objectName).build()); response.setContentType(stat.contentType()); response.setContentLengthLong(stat.size()); response.setHeader(Content-Disposition, attachment; filename*UTF-8 URLEncoder.encode(displayName, StandardCharsets.UTF_8)); try (InputStream in minioClient.getObject(GetObjectArgs.builder() .bucket(props.getBucket()).object(objectName).build())) { StreamUtils.copy(in, response.getOutputStream()); } }StreamUtils.copy内部是 4KB 的缓冲区对大文件来说偏小我一般自己写一个 64KB 的循环拷贝实测在千兆内网下吞吐能高一截。另外别忘了response.flushBuffer()不然在某些容器下最后一点数据会卡在缓冲区里。注意流式下载会占用应用服务器的连接和内存如果同一个接口被批量调用比如一次性下载一个相册的 30 张图连接池很快会被打满。这种场景应该返回预签名 URL 列表让浏览器自己并发去拿。5. 大文件、分片与孤儿对象的善后处理5.1 分片大小不是随便定的MinIO 的 putObject 在对象超过阈值时会自动分片规则很简单除最后一片外每片不得小于 5MiB最多 10000 片。这两条约束反过来限定了你的单对象最大体积——如果每片固定 5MiB理论上限是 48.8GiB想传更大的文件就得调大 partSize。我之前有个项目要传 200MB 左右的视频直接用stream(in, size, -1)让 SDK 自己算它默认用 5MiB 分片也就是切成 40 片。这个粒度其实偏细每片都是一次 HTTP 往返40 次往返加上签名计算总耗时比预期的长不少。后来我把 partSize 显式设成 16MiBminioClient.putObject(PutObjectArgs.builder() .bucket(props.getBucket()) .object(objectName) .stream(in, size, 16 * 1024 * 1024) .contentType(contentType) .build());同样的 200MB 文件切成 13 片上传耗时降了差不多三分之一。经验值是单对象 100MB 以内用 5MiB100MB 到 1GB 用 16MiB再往上用 32MiB 或 64MiB。分片太少也不好一旦某一片失败要整体重传分片太多则是往返开销压过收益。这个平衡点跟你的网络质量强相关内网可以往大调跨地域就得保守一点。还有个细节partSize设成非-1的值之后SDK 会忽略你传的objectSize按分片往下读直到流结束。这意味着如果你传了错误的partSize比如小于 5MiB会在写入第二片的时候报错而此时第一片已经落到 MinIO 上了留下一个不完整的对象。所以这个值一定要通过常量定义别在调用处随手写魔法数字。5.2 合并与前端直传分片前端直传大文件的典型流程是先调后端拿一个初始化分片上传的响应拿到 uploadId然后前端按片 PUT 到预签名 URL全部完成后调后端完成上传后端调 MinIO 的composeObject或者completeMultipartUpload把片合并。Java SDK 里对应的是createMultipartUpload、uploadPart、completeMultipartUpload这一组 API但这些 API 都需要 secretKey 才能调不能直接暴露给前端。前端直传的正确姿势是后端为每一片单独签发一个预签名 PUT URL前端只拿到 URL不碰任何凭证。这里有个坑我踩得很实在预签名 URL 的expiry是每一片各自计算的如果文件很大、上传时间长前面签的 URL 可能已经过期了。我的做法是按预计总时长 30 分钟余量来设而不是每片都签 7 天——长期有效的预签名 URL 相当于一个没有回收机制的通行证泄露风险太大。合并的时候还有一个约束容易被忽略除最后一片外参与合并的每一片都必须不小于 5MiB而且必须按顺序。前端如果并发上传导致 partNumber 乱了合并出来的文件内容是错乱的——不会报错就是文件打不开。这个 bug 极其难查因为服务端一切正常只有用户下载后才发现图片是花的。所以我在完成上传的接口里加了一道校验检查提交上来的 part 列表的 number 是否连续、size 是否符合要求不满足直接拒绝。5.3 删库和删文件之间的一致性业务上的删除操作一定是删数据库记录和删 MinIO 对象两件事。这两件事没有事务能包住必然存在中间态。先说顺序。先删库后删对象还是反过来我选先删库。原因很直接如果先删对象再删库中间失败的话数据库里留着一条指向不存在文件的记录用户点下载会 500反过来先删库再删对象失败最多是留下一个没人引用的孤儿对象占点空间业务上无感知。让不一致的后果落在多占空间而不是功能报错上这是这类跨系统操作的基本原则。但孤儿对象积累起来也是问题。我的处理是加一个兜底的对账任务每天凌晨跑一次扫出超过 N 天且数据库里没有引用的对象删掉。实现上不用扫全量按对象名的日期前缀限定范围就行Scheduled(cron 0 30 3 * * ?) public void cleanOrphanObjects() { LocalDate target LocalDate.now().minusDays(7); String prefix avatar/ target.format(DateTimeFormatter.ofPattern(yyyy/MM/dd)) /; IterableResultItem results minioClient.listObjects( ListObjectsArgs.builder().bucket(props.getBucket()).prefix(prefix).build()); for (ResultItem result : results) { Item item result.get(); if (!fileRecordMapper.existsByObjectName(item.objectName())) { minioClient.removeObject(RemoveObjectArgs.builder() .bucket(props.getBucket()).object(item.objectName()).build()); } } }几点说明。第一只扫 7 天前的那一天范围可控不会因为桶里对象太多跑不完。第二listObjects返回的是懒加载的Iterable遍历过程中每一条都会发一次请求对象多的时候很慢数据量大就换成listObjects的递归版本加批量删除。第三删除之前一定先查库别图快直接删——曾经有一次我把条件写反了删掉了当天正在使用的头像用户反馈头像全没了靠备份才恢复回来。另外MinIO 支持桶级别的生命周期规则可以让它自动清理某个前缀下超过 N 天的对象。这个能力适合临时文件这种场景比如上传中断留下的碎片不适合业务文件因为生命周期规则不认识你的数据库。6. 上线前值得再过一遍的检查项下面这些是我在不同项目里反复确认的东西整理成清单每次上线前对着过一遍能省掉大部分低级事故。检查项具体确认内容出问题的表现依赖版本okhttp 是否被锁到 4.12.x有无多个版本共存运行期 NoSuchMethodError连接复用MinioClient 是否为单例 Bean压测时连接数暴涨、拒绝连接endpoint 配置服务端调用与对外的 presign 地址是否分离前端拿到的链接超时不可达反向代理Host 头是否透传、buffering 是否关闭SignatureDoesNotMatch、大文件下载卡顿分片参数partSize 是否 ≥ 5MiB 且按文件大小分级大文件上传中途失败Content-Type是否按扩展名白名单收敛图片变下载、HTML 注入风险对象名是否含中文、空格、反斜杠、以斜杠开头签名失败、下载 404预签名有效期是否 ≤ 7 天是否按场景缩短凭证泄露面扩大删除顺序是否先删库后删对象是否有孤儿对账任务下载 500或存储无限膨胀桶权限是否误开了公共读文件可被任意人枚举下载关于桶权限这一项展开说两句。MinIO 的桶默认是私有的只有带正确签名的请求才能访问。有些人为了图方便把桶设成公共读mc anonymous set download觉得这样前端拿到的 URL 就是干净的、不带一长串签名参数。这个做法在小项目里确实省事但代价是任何人拿到对象名就能下载而对象名又是可以枚举的尤其是按日期分层之后前缀规律非常明显。我的底线是除了纯公开的静态资源比如站点 logo业务文件一律私有加预签名。还有一个不那么技术但同样重要的点上传接口的限流。文件上传是天然的放大攻击面——一个 50MB 的请求服务端要落盘、要传 MinIO、要写库成本远高于一个普通查询。我在网关层给上传接口单独配了阈值比普通接口严格得多同时在业务层限制了单用户的并发上传数。这件事在业务量小的时候完全感知不到等到有人拿脚本批量传文件的时候才想起来加往往已经晚了。最后分享一个小技巧跟排查效率有关。MinIO 的控制台有一个对象浏览器能直接看到桶里的对象、大小、上传时间还能生成临时的下载链接。调试阶段我几乎不离手——后端说我传上去了前端说我拿不到打开控制台看一眼有没有这个对象五秒钟定位到是哪一侧的问题。配合statObject在日志里打一行对象已写入大小 xxx 字节上传链路上的问题基本不需要再靠猜。 
长河君 · 2026/10/27 11:25:18 · 阅读 1.2k SpringBoot 3整合MinIO：对象存储文件上传与预签名分片实践
1. 从本地磁盘到对象存储一次被迫的存储改造项目做到第三个月文件上传这块先出事了。最初版本很朴素MultipartFile拿过来直接transferTo到服务器本地的一个upload目录数据库里存个相对路径前端拼接域名访问。单机跑得好好的直到运维把服务扩到三个实例用户反馈刚传的头像刷新一下就 404 了——负载均衡把下载请求打到了另一台机器上那台机器上根本没有这个文件。这件事之后我才认真去做了 SpringBoot 3 整合 MinIO 这件事而不是继续在本地磁盘上打补丁。MinIO 是什么一句话讲清楚它是一个可以自己部署的对象存储服务对外提供的接口和 S3 协议高度兼容你把文件扔进去它给你一个 key取的时候拿 key 换内容。它解决的核心问题是文件不再和某一台应用服务器绑定同时把文件读写这件事从操作系统的文件系统抽象成了一套带鉴权的 HTTP 接口。适合谁来参考这篇内容我的判断是三类人一类是项目里正在用本地磁盘存文件、已经被多实例部署坑过的后端一类是要做私有化交付、不能用公有云对象存储的团队还有一类是刚开始接触 SpringBoot 3、想找一个真实可跑的中间件集成案例练手的开发者。MinIO 本身不复杂装起来一个二进制文件加两条命令就能跑。真正花时间的部分在于把它和 SpringBoot 3 缝在一起的过程——依赖版本的互相牵扯、Bean 的装配时机、对象名的设计、预签名 URL 的地址问题、大文件的分片策略、删库和删文件之间的一致性。这些问题在官方文档里大多只有一行说明踩上去才知道疼。下面我把这条链路从头到尾拆一遍代码可以直接抄坑我也标出来了。2. 依赖版本这一步就把人拦下了okhttp 冲突与 Bean 装配2.1 SpringBoot 3 带来的不只是 Jakarta 命名空间很多人以为 SpringBoot 3 的迁移成本就是把javax.*全局替换成jakarta.*改完编译通过就完事了。文件上传这块确实受这个影响——javax.servlet.http.HttpServletRequest变成了jakarta.servlet.http.HttpServletRequest如果你项目里有自定义的 Filter 或者用了某些老版本的 Web 工具库编译期就会报错。但这只是明面上的。真正隐蔽的是第三方 SDK 的传递依赖。MinIO 的 Java SDK 底层用的是 OkHttp 发 HTTP 请求而 OkHttp 4.x 相对 3.x 改了一批静态工厂方法的签名。如果你的项目里还有别的组件比如某些推送 SDK、某些 HTTP 客户端封装把 OkHttp 锁在了 3.xMaven 的最近优先原则可能给你解析出一个混合版本编译期一切正常运行到第一次调用 MinIO 就抛NoSuchMethodError堆栈里指向的是okhttp3.RequestBody.create之类的方法。这个报错第一次见会非常懵因为你的代码里压根没出现过 OkHttp。我当时的做法是先看清依赖树的真实面貌mvn dependency:tree -Dincludescom.squareup.okhttp3输出里如果出现两个不同版本的 okhttp基本就确诊了。解决方式有两种我倾向前一种dependency groupIdio.minio/groupId artifactIdminio/artifactId version8.5.7/version exclusions exclusion groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId /exclusion /exclusions /dependency dependency groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId version4.12.0/version /dependency显式排除再加显式声明等于告诉 Maven这块版本我接管了。另一种是在dependencyManagement里统一锁定 OkHttp 版本效果类似但如果项目是多模块的容易在某个子模块里漏掉反而不如排除来得干脆。实测下来OkHttp 4.12.0 配 minio-java 8.5.x 是稳的组合我用了大半年没再出现过类似的NoSuchMethodError。注意不要图省事把 minio 的版本降到 8.4.x 去迁就旧 OkHttp8.4 系列在部分分片上传场景下有已知的流关闭问题而且新版本对 S3 的兼容性更好往回退是给自己找麻烦。2.2 配置项与 MinioClient 的装配时机MinIO 的连接信息就四个endpoint、accessKey、secretKey、默认桶名。我习惯用ConfigurationProperties接而不是每个字段写一个Value原因是后面如果要加区域、加超时、加多个桶字段会越来越多散落各处的Value维护起来很痛苦。minio: endpoint: http://127.0.0.1:9000 access-key: minioadmin secret-key: minioadmin bucket: app-file presign-endpoint: https://file.example.internal注意endpoint和presign-endpoint是两个值这个后面第 4 节会详细说先记住有这么个东西。Data ConfigurationProperties(prefix minio) public class MinioProperties { private String endpoint; private String accessKey; private String secretKey; private String bucket; private String presignEndpoint; }Configuration EnableConfigurationProperties(MinioProperties.class) public class MinioConfig { Bean public MinioClient minioClient(MinioProperties props) { return MinioClient.builder() .endpoint(props.getEndpoint()) .credentials(props.getAccessKey(), props.getSecretKey()) .build(); } }这里有个容易被忽略的点MinioClient本身是线程安全的官方明确说过一个实例可以全局复用它的 Builder 内部维护了连接池。这意味着你不要在每次上传的时候new一个 client也不要用Scope(prototype)。我曾经在一个项目里见过同事在 Service 方法里现场构建 client压测的时候连接数飙到几千服务端直接开始拒连。另一个点是装配顺序。如果你在PostConstruct里做建桶检查要注意此时网络可能还没就绪尤其是容器化部署MinIO 和应用同时启动的场景。我一般把建桶逻辑放到一个ApplicationRunner里并且加上重试Component RequiredArgsConstructor public class MinioBucketInitializer implements ApplicationRunner { private final MinioClient minioClient; private final MinioProperties props; Override public void run(ApplicationArguments args) { String bucket props.getBucket(); for (int i 0; i 5; i) { try { boolean exists minioClient.bucketExists( BucketExistsArgs.builder().bucket(bucket).build()); if (!exists) { minioClient.makeBucket(MakeBucketArgs.builder().bucket(bucket).build()); } return; } catch (Exception e) { if (i 4) { throw new IllegalStateException(MinIO 桶初始化失败: bucket, e); } try { Thread.sleep(2000L); } catch (InterruptedException ignored) { } } } } }用ApplicationRunner而不是PostConstruct是因为前者在容器完全启动之后才执行此时配置、线程池都就绪了失败重试也不会阻塞 Bean 的创建过程。这算是我踩过的一次坑换来的习惯——之前把建桶写在PostConstruct里MinIO 启动慢了两秒整个应用启动直接失败排查了半天才发现是初始化时序的问题。3. 桶、对象名与上传链路的三处设计取舍3.1 对象名怎么设计决定了后面运维有多痛对象名objectName是 MinIO 里唯一的标识相当于文件系统里的完整路径。我见过三种写法优劣差别很大。第一种是直接把用户上传的原始文件名当对象名报表.xlsx就叫报表.xlsx。这种写法的问题三天内就会暴露两个用户传同名文件后者覆盖前者文件名里的空格、中文、#、?在拼接 URL 的时候需要转义一不小心就 400所有文件平铺在同一层桶里几万个对象之后控制台翻页都卡。第二种是 UUID 加扩展名a3f9c1e2-....xlsx。解决了重名和特殊字符但完全丧失了可读性运维想找某个文件只能靠数据库反查。我现在统一用的是第三种日期分层加业务前缀加 UUID 加扩展名private String buildObjectName(String bizType, String originalFilename) { String ext ; int dot originalFilename.lastIndexOf(.); if (dot -1) { ext originalFilename.substring(dot).toLowerCase(); } String date LocalDate.now().format(DateTimeFormatter.ofPattern(yyyy/MM/dd)); String uuid UUID.randomUUID().toString().replace(-, ); return bizType / date / uuid ext; }这样生成出来的对象名长这样avatar/2024/06/18/9f2c8a1b....jpg。好处有三层日期分层让单个目录下的对象数量可控批量清理历史文件时按前缀删就行业务前缀让你在控制台一眼能看出这个桶里都装了什么类型的文件UUID 保证唯一性不用处理并发重名。原始文件名不丢存在数据库的一个字段里下载的时候再还原成用户看得懂的名字。这里有个细节值得单独说不要用File.separator或者反斜杠。对象名必须是正斜杠而且不能以斜杠开头。有次在 Windows 上开发代码里用了Paths.get(...).toString()拼路径本地跑没问题MinIO 会做兼容处理部署到 Linux 之后所有的对象名都正常但下载时的路径匹配逻辑炸了因为数据库里存的对象名带了反斜杠。3.2 三种上传形态的选择逻辑SpringBoot 里往 MinIO 传文件落到代码上无非是三个入口选哪个取决于文件大小和调用方。小文件走MultipartFile最直观。但要注意MultipartFile.getInputStream()的流只能读一次且getSize()返回的是字节数可以直接传给 SDKpublic String upload(MultipartFile file, String bizType) { String objectName buildObjectName(bizType, file.getOriginalFilename()); try (InputStream in file.getInputStream()) { minioClient.putObject(PutObjectArgs.builder() .bucket(props.getBucket()) .object(objectName) .stream(in, file.getSize(), -1) .contentType(file.getContentType()) .build()); return objectName; } catch (Exception e) { throw new RuntimeException(上传失败, e); } }stream(in, size, partSize)这三个参数值得解释一下。第二个参数是对象总大小第三个参数是分片大小。当size已知且小于 5MiB 时partSize传-1SDK 走单次 PUT当size大于 5MiB 时SDK 会自动切成 5MiB 一片做分片上传partSize传-1让它自己算当size未知比如从网络流直接转发时第二个参数传-1此时必须显式指定partSize且不能小于 5MiB5 * 1024 * 1024否则 SDK 会直接抛参数异常。中等文件走字节数组适合文件已经在内存里的场景比如服务端生成的 Excel、PDF。直接new ByteArrayInputStream(bytes)配上bytes.length就行简单直接。但要注意内存占用一次性把 50MB 读进byte[]并发几十个就是几个 G 的堆压力所以这条路我只在文件确定小于 10MB 的时候用。大文件走前端直传这是最省服务器资源的方案。后端只负责签发一个预签名 URL第 4 节讲前端拿到 URL 之后自己 PUT 到 MinIO文件流量完全不经过应用服务器。代价是前端要处理分片和断点复杂度上去了。三种形态的取舍我整理成了这张表实际选型的时候对着看就行形态适用文件大小服务器压力前端复杂度典型场景MultipartFile 转发 50MB中流量过应用低头像、附件、导入模板字节数组 10MB高占堆内存低动态生成的报表、导出文件预签名直传无上限低流量不过应用高视频、大压缩包、批量素材3.3 Content-Type 与编码这两件小事contentType不传会怎样MinIO 会给你默认成application/octet-stream。后果是浏览器访问这个文件 URL 的时候不会内联预览一律弹下载框。图片、PDF 这类需要在线看的文件必须在putObject的时候显式带上contentType。MultipartFile.getContentType()拿到的值来自浏览器大多数时候是对的但不能全信。用户可以用工具改掉请求头传一个.jpg却声明成text/html。如果你的桶开了公共读这玩意儿就变成了一个可以在你的域名下执行脚本的 HTML 页面风险不小。我现在的做法是服务端根据扩展名做一次收敛白名单之外的统一按application/octet-stream处理private static final MapString, String TYPE_MAP Map.of( jpg, image/jpeg, jpeg, image/jpeg, png, image/png, gif, image/gif, pdf, application/pdf, xlsx, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, docx, application/vnd.openxmlformats-officedocument.wordprocessingml.document ); private String resolveContentType(String filename) { int dot filename.lastIndexOf(.); if (dot -1) return application/octet-stream; String ext filename.substring(dot 1).toLowerCase(); return TYPE_MAP.getOrDefault(ext, application/octet-stream); }多这一步看着啰嗦但它同时解决了两个问题一是健康的内联预览二是把不可信的类型声明挡在门外。上线之后再回来看这十几行代码是整个上传链路里性价比最高的部分。4. 预签名 URL方便背后的地址与签权陷阱4.1 预签名到底在签什么预签名 URLpresigned URL的本质是服务端用 accessKey 和 secretKey 对一个即将发生的请求做 HMAC 签名把签名、过期时间、访问凭证一起拼进 URL 的 query 参数里然后把这个带签名的 URL 交给前端。前端拿着 URL 直接访问 MinIOMinIO 自己校验签名校验通过就返回文件全程不需要应用服务器参与。这个机制最直接的好处是下载流量不过应用服务器而且天然支持时效控制——链接发出去 7 天就失效不需要额外的权限系统。生成代码很短public String presignedGetUrl(String objectName, Duration expiry) { try { return minioClient.getPresignedObjectUrl(GetPresignedObjectUrlArgs.builder() .method(Method.GET) .bucket(props.getBucket()) .object(objectName) .expiry((int) expiry.toSeconds()) .build()); } catch (Exception e) { throw new RuntimeException(生成预签名地址失败, e); } }expiry有硬上限最长 7 天传更大的值 SDK 会直接抛异常。这个限制来自 SigV4 签名规范不是 MinIO 自己加的。所以如果你的业务是生成一个永久下载链接只能靠业务侧发一个短链重定向每次访问时重新签一个。4.2 最容易翻车的地方URL 里的 host 是谁预签名 URL 生成出来之后形如http://127.0.0.1:9000/app-file/avatar/2024/...?X-Amz-Algorithm...X-Amz-Signature...。注意那个 host它是你在MinioClient.builder().endpoint()里配置的值。如果应用服务器和 MinIO 在同一内网你配置的是http://10.0.1.5:9000那签出来的 URL 里就是内网 IP。这个 URL 直接丢给浏览器用户的电脑根本访问不到10.0.1.5结果就是一个超时。这是我在第一个项目里遇到的第一个线上问题测试环境全内网所以一直没发现上线后前端同学说图片全是裂的。解决办法有两个我推荐第二个。办法一配置两套 endpoint。一套给服务端自己调用 SDK 用内网快一套只用来生成对外 URL公网域名。但getPresignedObjectUrl是用 client 的 endpoint 签的你没法在调用时临时换 endpoint。变通做法是再建一个专门用于签名的 clientBean(presignMinioClient) public MinioClient presignMinioClient(MinioProperties props) { return MinioClient.builder() .endpoint(props.getPresignEndpoint()) .credentials(props.getAccessKey(), props.getSecretKey()) .build(); }需要注意签名是按 host 算进去的所以你用公网地址签、前端用公网地址访问签名才对得上。用内网 client 签出来再把 URL 里的 host 字符串替换成公网域名一定会得到SignatureDoesNotMatch因为 Host 是 SigV4 计算签名时参与运算的 header 之一。办法二用反向代理统一域名。Nginx 上挂一个file.example.com同时反代到 MinIO 和应用MinIO 那边通过环境变量MINIO_SERVER_URL声明自己的外部访问地址。这样内网外网看到的是同一个域名签出来的 URL 天然可用。location /app-file/ { proxy_pass http://10.0.1.5:9000/app-file/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; client_max_body_size 0; proxy_buffering off; }proxy_set_header Host $host这行是命门。如果不加Nginx 会把 Host 改成上游地址10.0.1.5:9000而预签名里签的是file.example.com两边一比对签名校验失败。proxy_buffering off是为大文件下载准备的避免 Nginx 先把整个文件缓存到本地临时目录再吐给客户端白白多占一份磁盘 IO。还有一个我踩过的坑URL 里的对象名必须 URL 编码。如果你的对象名里有中文或者空格虽然我在 3.1 里建议不要但历史数据总归有拼 URL 的时候没编码MinIO 那边解析出来的对象名和你签的对象名对不上一样是签名失败。SDK 内部对 objectName 做了编码但如果你是自己手动拼字符串比如在 URL 后面追加?response-content-disposition...之类的参数就要自己处理。4.3 下载时的中文文件名预签名 URL 默认打开是浏览器的行为能识别的类型内联显示不能识别的弹下载。文件名会是对象名里那串 UUID用户看到一个9f2c8a1b.jpg会一脸问号。要指定下载文件名可以在签名的时候加response-content-disposition参数MapString, String queryParams new HashMap(); queryParams.put(response-content-disposition, attachment; filename*UTF-8 URLEncoder.encode(originalName, StandardCharsets.UTF_8));注意必须用filename*UTF-8这个带星号的写法这是 RFC 5987 规定的中文文件名编码方式。老的filenamexxx直接放 UTF-8 字节在某些浏览器上会变成乱码。我一开始用的是老写法测试同学发来截图说下载下来叫 鎶ュ憡.xlsx改成filename*之后正常。如果走的是后端流式下载流量过应用思路一样只是换成设置 Response HeaderGetMapping(/file/{objectName}) public void download(PathVariable String objectName, HttpServletResponse response) throws Exception { StatObjectResponse stat minioClient.statObject( StatObjectArgs.builder().bucket(props.getBucket()).object(objectName).build()); response.setContentType(stat.contentType()); response.setContentLengthLong(stat.size()); response.setHeader(Content-Disposition, attachment; filename*UTF-8 URLEncoder.encode(displayName, StandardCharsets.UTF_8)); try (InputStream in minioClient.getObject(GetObjectArgs.builder() .bucket(props.getBucket()).object(objectName).build())) { StreamUtils.copy(in, response.getOutputStream()); } }StreamUtils.copy内部是 4KB 的缓冲区对大文件来说偏小我一般自己写一个 64KB 的循环拷贝实测在千兆内网下吞吐能高一截。另外别忘了response.flushBuffer()不然在某些容器下最后一点数据会卡在缓冲区里。注意流式下载会占用应用服务器的连接和内存如果同一个接口被批量调用比如一次性下载一个相册的 30 张图连接池很快会被打满。这种场景应该返回预签名 URL 列表让浏览器自己并发去拿。5. 大文件、分片与孤儿对象的善后处理5.1 分片大小不是随便定的MinIO 的 putObject 在对象超过阈值时会自动分片规则很简单除最后一片外每片不得小于 5MiB最多 10000 片。这两条约束反过来限定了你的单对象最大体积——如果每片固定 5MiB理论上限是 48.8GiB想传更大的文件就得调大 partSize。我之前有个项目要传 200MB 左右的视频直接用stream(in, size, -1)让 SDK 自己算它默认用 5MiB 分片也就是切成 40 片。这个粒度其实偏细每片都是一次 HTTP 往返40 次往返加上签名计算总耗时比预期的长不少。后来我把 partSize 显式设成 16MiBminioClient.putObject(PutObjectArgs.builder() .bucket(props.getBucket()) .object(objectName) .stream(in, size, 16 * 1024 * 1024) .contentType(contentType) .build());同样的 200MB 文件切成 13 片上传耗时降了差不多三分之一。经验值是单对象 100MB 以内用 5MiB100MB 到 1GB 用 16MiB再往上用 32MiB 或 64MiB。分片太少也不好一旦某一片失败要整体重传分片太多则是往返开销压过收益。这个平衡点跟你的网络质量强相关内网可以往大调跨地域就得保守一点。还有个细节partSize设成非-1的值之后SDK 会忽略你传的objectSize按分片往下读直到流结束。这意味着如果你传了错误的partSize比如小于 5MiB会在写入第二片的时候报错而此时第一片已经落到 MinIO 上了留下一个不完整的对象。所以这个值一定要通过常量定义别在调用处随手写魔法数字。5.2 合并与前端直传分片前端直传大文件的典型流程是先调后端拿一个初始化分片上传的响应拿到 uploadId然后前端按片 PUT 到预签名 URL全部完成后调后端完成上传后端调 MinIO 的composeObject或者completeMultipartUpload把片合并。Java SDK 里对应的是createMultipartUpload、uploadPart、completeMultipartUpload这一组 API但这些 API 都需要 secretKey 才能调不能直接暴露给前端。前端直传的正确姿势是后端为每一片单独签发一个预签名 PUT URL前端只拿到 URL不碰任何凭证。这里有个坑我踩得很实在预签名 URL 的expiry是每一片各自计算的如果文件很大、上传时间长前面签的 URL 可能已经过期了。我的做法是按预计总时长 30 分钟余量来设而不是每片都签 7 天——长期有效的预签名 URL 相当于一个没有回收机制的通行证泄露风险太大。合并的时候还有一个约束容易被忽略除最后一片外参与合并的每一片都必须不小于 5MiB而且必须按顺序。前端如果并发上传导致 partNumber 乱了合并出来的文件内容是错乱的——不会报错就是文件打不开。这个 bug 极其难查因为服务端一切正常只有用户下载后才发现图片是花的。所以我在完成上传的接口里加了一道校验检查提交上来的 part 列表的 number 是否连续、size 是否符合要求不满足直接拒绝。5.3 删库和删文件之间的一致性业务上的删除操作一定是删数据库记录和删 MinIO 对象两件事。这两件事没有事务能包住必然存在中间态。先说顺序。先删库后删对象还是反过来我选先删库。原因很直接如果先删对象再删库中间失败的话数据库里留着一条指向不存在文件的记录用户点下载会 500反过来先删库再删对象失败最多是留下一个没人引用的孤儿对象占点空间业务上无感知。让不一致的后果落在多占空间而不是功能报错上这是这类跨系统操作的基本原则。但孤儿对象积累起来也是问题。我的处理是加一个兜底的对账任务每天凌晨跑一次扫出超过 N 天且数据库里没有引用的对象删掉。实现上不用扫全量按对象名的日期前缀限定范围就行Scheduled(cron 0 30 3 * * ?) public void cleanOrphanObjects() { LocalDate target LocalDate.now().minusDays(7); String prefix avatar/ target.format(DateTimeFormatter.ofPattern(yyyy/MM/dd)) /; IterableResultItem results minioClient.listObjects( ListObjectsArgs.builder().bucket(props.getBucket()).prefix(prefix).build()); for (ResultItem result : results) { Item item result.get(); if (!fileRecordMapper.existsByObjectName(item.objectName())) { minioClient.removeObject(RemoveObjectArgs.builder() .bucket(props.getBucket()).object(item.objectName()).build()); } } }几点说明。第一只扫 7 天前的那一天范围可控不会因为桶里对象太多跑不完。第二listObjects返回的是懒加载的Iterable遍历过程中每一条都会发一次请求对象多的时候很慢数据量大就换成listObjects的递归版本加批量删除。第三删除之前一定先查库别图快直接删——曾经有一次我把条件写反了删掉了当天正在使用的头像用户反馈头像全没了靠备份才恢复回来。另外MinIO 支持桶级别的生命周期规则可以让它自动清理某个前缀下超过 N 天的对象。这个能力适合临时文件这种场景比如上传中断留下的碎片不适合业务文件因为生命周期规则不认识你的数据库。6. 上线前值得再过一遍的检查项下面这些是我在不同项目里反复确认的东西整理成清单每次上线前对着过一遍能省掉大部分低级事故。检查项具体确认内容出问题的表现依赖版本okhttp 是否被锁到 4.12.x有无多个版本共存运行期 NoSuchMethodError连接复用MinioClient 是否为单例 Bean压测时连接数暴涨、拒绝连接endpoint 配置服务端调用与对外的 presign 地址是否分离前端拿到的链接超时不可达反向代理Host 头是否透传、buffering 是否关闭SignatureDoesNotMatch、大文件下载卡顿分片参数partSize 是否 ≥ 5MiB 且按文件大小分级大文件上传中途失败Content-Type是否按扩展名白名单收敛图片变下载、HTML 注入风险对象名是否含中文、空格、反斜杠、以斜杠开头签名失败、下载 404预签名有效期是否 ≤ 7 天是否按场景缩短凭证泄露面扩大删除顺序是否先删库后删对象是否有孤儿对账任务下载 500或存储无限膨胀桶权限是否误开了公共读文件可被任意人枚举下载关于桶权限这一项展开说两句。MinIO 的桶默认是私有的只有带正确签名的请求才能访问。有些人为了图方便把桶设成公共读mc anonymous set download觉得这样前端拿到的 URL 就是干净的、不带一长串签名参数。这个做法在小项目里确实省事但代价是任何人拿到对象名就能下载而对象名又是可以枚举的尤其是按日期分层之后前缀规律非常明显。我的底线是除了纯公开的静态资源比如站点 logo业务文件一律私有加预签名。还有一个不那么技术但同样重要的点上传接口的限流。文件上传是天然的放大攻击面——一个 50MB 的请求服务端要落盘、要传 MinIO、要写库成本远高于一个普通查询。我在网关层给上传接口单独配了阈值比普通接口严格得多同时在业务层限制了单用户的并发上传数。这件事在业务量小的时候完全感知不到等到有人拿脚本批量传文件的时候才想起来加往往已经晚了。最后分享一个小技巧跟排查效率有关。MinIO 的控制台有一个对象浏览器能直接看到桶里的对象、大小、上传时间还能生成临时的下载链接。调试阶段我几乎不离手——后端说我传上去了前端说我拿不到打开控制台看一眼有没有这个对象五秒钟定位到是哪一侧的问题。配合statObject在日志里打一行对象已写入大小 xxx 字节上传链路上的问题基本不需要再靠猜。