SpringBoot集成MinIO实现分布式文件存储与管理方式

更新时间：2025年09月07日 14:53:46 作者：LOVE_DDZ

这篇文章主要介绍了SpringBoot集成MinIO实现分布式文件存储与管理方式,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教

一、MinIO 简介

MinIO 是一个高性能的分布式对象存储服务器，兼容 Amazon S3 API。它具有以下特点：

轻量级且易于部署
高性能（读写速度可达每秒数GB）
支持数据加密和访问控制
提供多种语言的SDK
开源且社区活跃

二、Spring Boot 集成 MinIO

1. 添加依赖

在 pom.xml 中添加 MinIO Java SDK 依赖：

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

2. 配置 MinIO 连接

在 application.yml 中配置：

minio:
  endpoint: http://localhost:9000
  accessKey: minioadmin
  secretKey: minioadmin
  bucketName: default-bucket
  secure: false

3. 创建配置类

@Configuration
public class MinioConfig {
    
    @Value("${minio.endpoint}")
    private String endpoint;
    
    @Value("${minio.accessKey}")
    private String accessKey;
    
    @Value("${minio.secretKey}")
    private String secretKey;
    
    @Bean
    public MinioClient minioClient() {
        return MinioClient.builder()
                .endpoint(endpoint)
                .credentials(accessKey, secretKey)
                .build();
    }
}

三、实现文件服务

@Service
@RequiredArgsConstructor
public class MinioService {

    private final MinioClient minioClient;

    @Value("${minio.bucketName}")
    private String bucketName;

    /**
     * 检查存储桶是否存在
     *
     * @param bucketName 存储桶名称
     * @return 存储桶是否存在 状态码 true:存在 false:不存在
     */
    public boolean bucketExists(String bucketName) throws Exception {
        return !minioClient.bucketExists(BucketExistsArgs.builder().bucket(bucketName).build());
    }

    /**
     * 创建存储桶
     */
    public void makeBucket(String bucketName) throws Exception {
        if (bucketExists(bucketName)) {
            minioClient.makeBucket(MakeBucketArgs.builder().bucket(bucketName).build());
        }
    }

    /**
     * 列出所有存储桶
     */
    public List<Bucket> listBuckets() throws Exception {
        return minioClient.listBuckets();
    }

    /**
     * 上传文件
     *
     * @param file       文件
     * @param bucketName 存储桶名称
     * @param rename     是否重命名
     */
    public String uploadFile(MultipartFile file, String bucketName, boolean rename) throws Exception {
        // 如果未指定bucketName，使用默认的
        bucketName = getBucketName(bucketName);

        // 检查存储桶是否存在，不存在则创建
        ensureBucketExists(bucketName);

        // 生成唯一文件名
        String objectName = generateObjectName(file, rename);
        // 上传文件
        minioClient.putObject(
                PutObjectArgs.builder()
                        .bucket(bucketName)
                        .object(objectName)
                        .stream(file.getInputStream(), file.getSize(), -1)
                        .contentType(file.getContentType())
                        .build());
        return objectName;
    }


    /**
     * 下载文件
     */
    public InputStream downloadFile(String objectName, String bucketName) throws Exception {
        return minioClient.getObject(
                GetObjectArgs.builder()
                        .bucket(getBucketName(bucketName))
                        .object(objectName)
                        .build());
    }

    /**
     * 删除文件
     */
    public void removeFile(String objectName, String bucketName) throws Exception {
        minioClient.removeObject(
                RemoveObjectArgs.builder()
                        .bucket(getBucketName(bucketName))
                        .object(objectName)
                        .build());
    }

    /**
     * 获取文件URL（先检查文件是否存在）
     */
    public String getFileUrl(String objectName, String bucketName) throws Exception {
        try {
            minioClient.statObject(
                    StatObjectArgs.builder()
                            .bucket(getBucketName(bucketName))
                            .object(objectName)
                            .build());
        } catch (ErrorResponseException e) {
            // 文件不存在时抛出异常
            throw new FileNotFoundException("File not found: " + objectName);
        }

        // 文件存在，生成URL
        return minioClient.getPresignedObjectUrl(
                GetPresignedObjectUrlArgs.builder()
                        .method(Method.GET)
                        .bucket(getBucketName(bucketName))
                        .object(objectName)
                        .build());
    }

    /**
     * 生成唯一文件名
     */
    private static @Nullable String generateObjectName(MultipartFile file, boolean rename) {
        String fileName = file.getOriginalFilename();
        String objectName = fileName;
        if (rename && fileName != null) {
            objectName = UUID.randomUUID().toString().replaceAll("-", "")
                    + fileName.substring(fileName.lastIndexOf("."));
        }
        return objectName;
    }

    /**
     * 检查存储桶是否存在，不存在则创建
     */
    private void ensureBucketExists(String bucketName) throws Exception {
        if (bucketExists(bucketName)) {
            makeBucket(bucketName);
        }
    }

    /**
     * 获取存储桶名称
     */
    private String getBucketName(String bucketName) {
        if (bucketName == null || bucketName.isEmpty()) {
            bucketName = this.bucketName;
        }
        return bucketName;
    }
}

四、REST API 实现

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/file")
public class MinioController {

    private final MinioService minioService;

    @PostMapping("/upload")
    public ResponseEntity<String> uploadFile(@RequestParam("file") MultipartFile file,
                                             @RequestParam(value = "bucketName", required = false) String bucketName) {
        try {
            String objectName = minioService.uploadFile(file, bucketName, false);
            return ResponseEntity.ok(objectName);
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(e.getMessage());
        }
    }

    @GetMapping("/download")
    public ResponseEntity<byte[]> downloadFile(@RequestParam String objectName,
                                               @RequestParam(value = "bucketName", required = false) String bucketName) {
        try {
            InputStream stream = minioService.downloadFile(objectName, bucketName);
            byte[] bytes = stream.readAllBytes();

            HttpHeaders headers = new HttpHeaders();
            headers.setContentType(MediaType.APPLICATION_OCTET_STREAM);
            headers.setContentDispositionFormData("attachment", objectName);

            return new ResponseEntity<>(bytes, headers, HttpStatus.OK);
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
        }
    }

    @DeleteMapping("/delete")
    public ResponseEntity<String> deleteFile(@RequestParam String objectName,
                                             @RequestParam(value = "bucketName", required = false) String bucketName) {
        try {
            minioService.removeFile(objectName, bucketName);
            return ResponseEntity.ok("File deleted successfully");
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(e.getMessage());
        }
    }

    @GetMapping("/url")
    public ResponseEntity<String> getFileUrl(@RequestParam String objectName,
                                             @RequestParam(value = "bucketName", required = false) String bucketName) {
        try {
            String url = minioService.getFileUrl(objectName, bucketName);
            return ResponseEntity.ok(url);
        } catch (FileNotFoundException e) {
            return ResponseEntity.status(HttpStatus.NOT_FOUND).body(e.getMessage());
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(e.getMessage());
        }
    }
}

五、高级功能实现

1. 分片上传

public String multipartUpload(MultipartFile file, String bucketName) {
    // 1. 初始化分片上传
    String uploadId = minioClient.initiateMultipartUpload(...);
    
    // 2. 分片上传
    Map<Integer, String> etags = new HashMap<>();
    for (int partNumber = 1; partNumber <= totalParts; partNumber++) {
        PartSource partSource = getPartSource(file, partNumber);
        String etag = minioClient.uploadPart(...);
        etags.put(partNumber, etag);
    }
    
    // 3. 完成分片上传
    minioClient.completeMultipartUpload(...);
    
    return objectName;
}

2. 文件预览

    @GetMapping("/preview/{objectName}")
    public ResponseEntity<Resource> previewFile(
            @PathVariable String objectName,
            @RequestParam(value = "bucketName", required = false) String bucketName) throws Exception {

        String contentType = minioService.getFileContentType(objectName, bucketName);
        InputStream inputStream = minioService.downloadFile(objectName, bucketName);

        return ResponseEntity.ok()
                .contentType(MediaType.parseMediaType(contentType))
                .body(new InputStreamResource(inputStream));
    }

六、最佳实践

安全性考虑：

为预签名URL设置合理的过期时间
实现细粒度的访问控制
对上传文件进行病毒扫描

性能优化：

使用CDN加速文件访问
对大文件使用分片上传
实现客户端直传（Presigned URL）

监控与日志：

记录所有文件操作
监控存储空间使用情况
设置自动清理策略

七、常见问题解决

连接超时问题：

@Bean
public MinioClient minioClient() {
    return MinioClient.builder()
            .endpoint(endpoint)
            .credentials(accessKey, secretKey)
            .httpClient(HttpClient.newBuilder()
                    .connectTimeout(Duration.ofSeconds(30))
                    .build())
            .build();
}

文件存在性检查优化：

public boolean fileExists(String objectName, String bucketName) {
    try {
        minioClient.statObject(
            StatObjectArgs.builder()
                .bucket(getBucketName(bucketName))
                .object(objectName)
                .build());
        return true;
    } catch (ErrorResponseException e) {
        if (e.errorResponse().code().equals("NoSuchKey")) {
            return false;
        }
        throw new FileStorageException("检查文件存在性失败", e);
    } catch (Exception e) {
        throw new FileStorageException("检查文件存在性失败", e);
    }
}

八、总结

通过本文的介绍，我们实现了：

Spring Boot 与 MinIO 的基本集成
文件上传、下载、删除等基础功能
文件预览、分片上传等高级功能
安全性、性能等方面的最佳实践

MinIO 作为轻量级的对象存储解决方案，非常适合中小型项目使用。结合 Spring Boot 可以快速构建强大的文件存储服务。

以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。

您可能感兴趣的文章:

Java实现修改PDF文件MD5值且保持内容不变
在某些场景中,我们可能需要改变PDF文件的MD5值,而又不希望改变文件的可视内容,本文详细介绍了如何实现这一目标,并提供了具体的Java实现示例,需要的可以参考下
2023-10-10
浅析Spring基于注解的AOP
Spring是一个广泛应用的框架，SpringAOP则是Spring提供的一个标准易用的aop框架，依托Spring的IOC容器，提供了极强的AOP扩展增强能力，对项目开发提供了极大地便利
2022-11-11
Java判断字符串是否在List中的方案详解(忽略大小写)
对于需要频繁调用且数据量大的情况,有几种优化方案可以选择,下面给大家分享三种方案给大家详细介绍java字符串判断是否在list中,感兴趣的朋友一起看看吧
2025-05-05
基于java计算买卖股票的最佳时机
这篇文章主要介绍了基于java计算买卖股票的最佳时机,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2019-10-10
java使用JWT的方法
这篇文章主要介绍了java使用JWT的方法，JWT是token的一种，一个JWT字符串包含三个部分分别是Header、Payload和Signature，本文通过实例代码给大家介绍的非常详细,需要的朋友可以参考下
2022-06-06
Java中的NoClassDefFoundError报错含义解析
这篇文章主要为大家介绍了Java中的NoClassDefFoundError含义详解，有需要的朋友可以借鉴参考下，希望能够有所帮助
2023-11-11
java 多线程Thread与runnable的区别
这篇文章主要介绍了java 多线程Thread与runnable的区别的相关资料,java线程有两种方法继承thread类与实现runnable接口，下面就提供实例帮助大家理解，需要的朋友可以参考下
2017-08-08
初步认识JVM的体系结构
大家都知道,Java中JVM的重要性,学习了JVM你对Java的运行机制、编译过程和如何对Java程序进行调优相信都会有一个很好的认知.在面试中JVM也是非常重要的一部分,比如JVM调优,JVM对象分配规则,内存模型、方法区,还有种要GC等,需要的朋友可以参考下
2021-06-06
一步步教你写一个SpringMVC框架
现在主流的Web MVC框架除了Struts这个主力外,其次就是Spring MVC了,因此这也是作为一名程序员需要掌握的主流框架,这篇文章主要给大家介绍了关于如何一步步写一个SpringMVC框架的相关资料,需要的朋友可以参考下
2022-03-03
Spring Boot中使用JSR-303实现请求参数校验
这篇文章主要介绍了Spring Boot中使用JSR-303实现请求参数校验,JSR-303校验我们一般都是对Java的实体类对象进行校验,主要检验JSR-303是Java中的一个规范,用于实现请求参数校验在我们的实体类对象的属性上,感兴趣的朋友跟随小编一起看看吧
2023-10-10