背景做外包项目经常遇到文件上传需求——用户头像、合同PDF、Excel导出文件。一开始图省事用阿里云OSS结果有个项目用户上传了几千份合同扫描件一个月OSS费用干到200多。200块不算多但积少成多三个客户的项目加起来一年几千块。而我的服务器本来就剩200G磁盘闲着于是全部切到MinIO自建。MinIO是什么MinIO是开源的对象存储兼容Amazon S3 API。部署在你的服务器上Docker一个容器搞定。代码里原来怎么写S3现在就怎么写MinIO——API一模一样。Docker部署services: minio: image: minio/minio:latest container_name: minio ports: - 9000:9000 # API端口 - 9001:9001 # 控制台端口 volumes: - ./minio/data:/data - ./minio/config:/root/.minio environment: - MINIO_ROOT_USERadmin - MINIO_ROOT_PASSWORDyour_password_here command: server /data --console-address :9001 networks: - aipdt-cloud restart: unless-stopped启动后用http://你的IP:9001登录控制台创建Bucket。建议至少建两个public放公开文件头像之类的private放私密文件合同、证件。SpringBoot接入依赖就一个dependency groupIdio.minio/groupId artifactIdminio/artifactId version8.5.7/version /dependency配置文件minio: endpoint: http://minio:9000 # 容器内直接用服务名 access-key: admin secret-key: your_password_here bucket-public: public bucket-private: private配置类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(); } }工具类把常用操作封装一个工具类业务代码里一行搞定Slf4j Component public class MinioUtil { Autowired private MinioClient minioClient; // 上传文件 public String upload(String bucket, InputStream inputStream, String fileName, long size) { try { minioClient.putObject(PutObjectArgs.builder() .bucket(bucket) .object(fileName) .stream(inputStream, size, -1) .contentType(MediaType.APPLICATION_OCTET_STREAM_VALUE) .build()); return fileName; } catch (Exception e) { log.error(上传失败, e); throw new RuntimeException(文件上传失败); } } // 获取文件流 public InputStream download(String bucket, String fileName) { try { return minioClient.getObject(GetObjectArgs.builder() .bucket(bucket) .object(fileName) .build()); } catch (Exception e) { log.error(下载失败, e); throw new RuntimeException(文件下载失败); } } // 生成临时访问链接7天有效 public String presignedUrl(String bucket, String fileName) { try { return minioClient.getPresignedObjectUrl(GetPresignedObjectUrlArgs.builder() .bucket(bucket) .object(fileName) .expiry(7, TimeUnit.DAYS) .method(Method.GET) .build()); } catch (Exception e) { log.error(生成链接失败, e); return null; } } // 删除文件 public void delete(String bucket, String fileName) { try { minioClient.removeObject(RemoveObjectArgs.builder() .bucket(bucket) .object(fileName) .build()); } catch (Exception e) { log.error(删除失败, e); } } }业务代码示例上传头像PostMapping(/avatar) public ResultString uploadAvatar(RequestParam MultipartFile file) { String fileName avatar/ userId .jpg; minioUtil.upload(bucketPublic, file.getInputStream(), fileName, file.getSize()); String url minioUtil.presignedUrl(bucketPublic, fileName); return Result.ok(url); }导出Excel存MinIO// 生成Excel ByteArrayOutputStream out new ByteArrayOutputStream(); excelWriter.write(out); // 上传到MinIO ByteArrayInputStream in new ByteArrayInputStream(out.toByteArray()); String fileName excel/ UUID.randomUUID() .xlsx; minioUtil.upload(bucketPrivate, in, fileName, out.size()); // 返回下载链接 String downloadUrl minioUtil.presignedUrl(bucketPrivate, fileName);访问策略公开文件头像、封面图等Bucket设置为公开读mc policy set download myminio/public私密文件合同、身份证等Bucket保持私有通过 presigned URL 控制访问链接带过期时间和签名安全可控。踩过的坑1. 容器内用localhost连不上MinIO和SpringBoot都在Docker里时endpoint不能用localhost。配容器名http://minio:9000或用宿主机IP。2. 上传大文件OOMputObject默认把整个文件读进内存。上传几十M的文件时内存会爆。换成分片上传minioClient.putObject(PutObjectArgs.builder() .bucket(bucket) .object(fileName) .stream(inputStream, -1, 5 * 1024 * 1024) // 5M分片 .build());第三个参数-1表示未知总大小第四个参数5M是分片大小。适合前端直传的场景。3. presigned URL 的域名问题MinIO生成的链接默认是http://内网IP:9000/bucket/file。如果前端需要访问链接里得是外网域名。配nginx代理location /minio/ { proxy_pass http://minio:9000/; }或者在MinIO启动时指定环境变量MINIO_SERVER_URLhttps://你的域名。什么时候不适合MinIO需要CDN加速OSS自带CDNMinIO得自己加一层nginx反向代理和CDN配置高可用刚需单机挂了就不可用。MinIO也支持集群模式但你得搞多台服务器合规要求高比如等保三级要求对象存储有审计日志、跨区域备份自建搞起来麻烦以上三条都不满足的话MinIO够用了。总结MinIO替代OSSDocker一键部署S3 API兼容public/private两个Bucket公开读预签名URL两种访问模式大文件用分片上传避免OOM对CDN和高可用没要求的中小型项目MinIO完全够用一年省几千块OSS费用一台服务器资源充分利用本文是独立开发系列实战记录更多经验分享见个人技术博客。
背景做外包项目经常遇到文件上传需求——用户头像、合同PDF、Excel导出文件。一开始图省事用阿里云OSS结果有个项目用户上传了几千份合同扫描件一个月OSS费用干到200多。200块不算多但积少成多三个客户的项目加起来一年几千块。而我的服务器本来就剩200G磁盘闲着于是全部切到MinIO自建。MinIO是什么MinIO是开源的对象存储兼容Amazon S3 API。部署在你的服务器上Docker一个容器搞定。代码里原来怎么写S3现在就怎么写MinIO——API一模一样。Docker部署services: minio: image: minio/minio:latest container_name: minio ports: - 9000:9000 # API端口 - 9001:9001 # 控制台端口 volumes: - ./minio/data:/data - ./minio/config:/root/.minio environment: - MINIO_ROOT_USERadmin - MINIO_ROOT_PASSWORDyour_password_here command: server /data --console-address :9001 networks: - aipdt-cloud restart: unless-stopped启动后用http://你的IP:9001登录控制台创建Bucket。建议至少建两个public放公开文件头像之类的private放私密文件合同、证件。SpringBoot接入依赖就一个dependency groupIdio.minio/groupId artifactIdminio/artifactId version8.5.7/version /dependency配置文件minio: endpoint: http://minio:9000 # 容器内直接用服务名 access-key: admin secret-key: your_password_here bucket-public: public bucket-private: private配置类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(); } }工具类把常用操作封装一个工具类业务代码里一行搞定Slf4j Component public class MinioUtil { Autowired private MinioClient minioClient; // 上传文件 public String upload(String bucket, InputStream inputStream, String fileName, long size) { try { minioClient.putObject(PutObjectArgs.builder() .bucket(bucket) .object(fileName) .stream(inputStream, size, -1) .contentType(MediaType.APPLICATION_OCTET_STREAM_VALUE) .build()); return fileName; } catch (Exception e) { log.error(上传失败, e); throw new RuntimeException(文件上传失败); } } // 获取文件流 public InputStream download(String bucket, String fileName) { try { return minioClient.getObject(GetObjectArgs.builder() .bucket(bucket) .object(fileName) .build()); } catch (Exception e) { log.error(下载失败, e); throw new RuntimeException(文件下载失败); } } // 生成临时访问链接7天有效 public String presignedUrl(String bucket, String fileName) { try { return minioClient.getPresignedObjectUrl(GetPresignedObjectUrlArgs.builder() .bucket(bucket) .object(fileName) .expiry(7, TimeUnit.DAYS) .method(Method.GET) .build()); } catch (Exception e) { log.error(生成链接失败, e); return null; } } // 删除文件 public void delete(String bucket, String fileName) { try { minioClient.removeObject(RemoveObjectArgs.builder() .bucket(bucket) .object(fileName) .build()); } catch (Exception e) { log.error(删除失败, e); } } }业务代码示例上传头像PostMapping(/avatar) public ResultString uploadAvatar(RequestParam MultipartFile file) { String fileName avatar/ userId .jpg; minioUtil.upload(bucketPublic, file.getInputStream(), fileName, file.getSize()); String url minioUtil.presignedUrl(bucketPublic, fileName); return Result.ok(url); }导出Excel存MinIO// 生成Excel ByteArrayOutputStream out new ByteArrayOutputStream(); excelWriter.write(out); // 上传到MinIO ByteArrayInputStream in new ByteArrayInputStream(out.toByteArray()); String fileName excel/ UUID.randomUUID() .xlsx; minioUtil.upload(bucketPrivate, in, fileName, out.size()); // 返回下载链接 String downloadUrl minioUtil.presignedUrl(bucketPrivate, fileName);访问策略公开文件头像、封面图等Bucket设置为公开读mc policy set download myminio/public私密文件合同、身份证等Bucket保持私有通过 presigned URL 控制访问链接带过期时间和签名安全可控。踩过的坑1. 容器内用localhost连不上MinIO和SpringBoot都在Docker里时endpoint不能用localhost。配容器名http://minio:9000或用宿主机IP。2. 上传大文件OOMputObject默认把整个文件读进内存。上传几十M的文件时内存会爆。换成分片上传minioClient.putObject(PutObjectArgs.builder() .bucket(bucket) .object(fileName) .stream(inputStream, -1, 5 * 1024 * 1024) // 5M分片 .build());第三个参数-1表示未知总大小第四个参数5M是分片大小。适合前端直传的场景。3. presigned URL 的域名问题MinIO生成的链接默认是http://内网IP:9000/bucket/file。如果前端需要访问链接里得是外网域名。配nginx代理location /minio/ { proxy_pass http://minio:9000/; }或者在MinIO启动时指定环境变量MINIO_SERVER_URLhttps://你的域名。什么时候不适合MinIO需要CDN加速OSS自带CDNMinIO得自己加一层nginx反向代理和CDN配置高可用刚需单机挂了就不可用。MinIO也支持集群模式但你得搞多台服务器合规要求高比如等保三级要求对象存储有审计日志、跨区域备份自建搞起来麻烦以上三条都不满足的话MinIO够用了。总结MinIO替代OSSDocker一键部署S3 API兼容public/private两个Bucket公开读预签名URL两种访问模式大文件用分片上传避免OOM对CDN和高可用没要求的中小型项目MinIO完全够用一年省几千块OSS费用一台服务器资源充分利用本文是独立开发系列实战记录更多经验分享见个人技术博客。
