Spring Boot 集成 MinIO 实现分布式文件存储与管理

ℳ₯㎕ddzོꦿ࿐2025-07-04 6:00

Spring Boot 集成 MinIO 实现分布式文件存储与管理

一、MinIO 简介

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

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

二、Spring Boot 集成 MinIO

1. 添加依赖

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

xml 复制代码 
<dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <version>8.5.7</version>
</dependency>

2. 配置 MinIO 连接

在 application.yml 中配置：

yaml 复制代码 
minio:
  endpoint: http://localhost:9000
  accessKey: minioadmin
  secretKey: minioadmin
  bucketName: default-bucket
  secure: false

3. 创建配置类

java 复制代码 
@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();
    }
}

三、实现文件服务

java 复制代码 
@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 实现

java 复制代码 
@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. 分片上传

java 复制代码 
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. 文件预览

java 复制代码 
    @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));
    }

六、最佳实践

  1. 安全性考虑：

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

  2. 性能优化：

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

  3. 监控与日志：

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

七、常见问题解决

  1. 连接超时问题：

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

  2. 文件存在性检查优化：

    java 复制代码 
    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);
    }
}

八、总结

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

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

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

相关推荐
天天摸鱼的java工程师几秒前
Java与AI：从业务场景到代码实现，构建人工客服系统实战
java·后端·面试
excel10 分钟前
使用 Prisma 实现数据库字段的动态迁移实践
前端·后端
转转技术团队11 分钟前
边学边做：图片识别技术的学习与应用
后端·算法
程序员爱钓鱼14 分钟前
Go语言项目工程化 —— 日志、配置、错误处理规范
后端·google·go
天天摸鱼的java工程师15 分钟前
假设你在开发订单系统时遇到高并发下库存扣减出错，如何解决？由浅入深分析
java·后端·面试
没逻辑16 分钟前
Go 服务架构性能优化指南(实战精选)
后端·性能优化·go
奕川19 分钟前
Spring AI 实战指南：模型集成与调优
后端·aigc
春野蓝19 分钟前
基于Maven Archetype创建项目脚手架
后端
前端拿破轮22 分钟前
不是吧不是吧，leetcode第一题我就做不出来？😭😭😭
后端·算法·leetcode
一块plus25 分钟前
什么是去中心化 AI？区块链驱动智能的初学者指南
人工智能·后端·算法
热门推荐
01手机电脑之间快速传输图片视频文件，不压缩画质、不限制大小的方法！02如何将markdown生成pdf03Coze扣子平台完整体验和实践（附国内和国际版对比）04Coze实战第13讲：飞书多维表格读取+豆包生图模型，轻松批量生成短剧封面05鸽了六年的某大厂面试题：你会手写一个模板引擎吗？06扣子（coze）实战|我用扣子搭建了一个自动分析小红薯笔记内容的AI应用|详细步骤拆解07Word粘贴时出现“运行时错误53,文件未找到：MathPage.WLL“的解决方案08《C#图解教程 第5版》深度推荐09DeepSeek各版本说明与优缺点分析10C#调用WechatOCR.exe实现本地OCR文字识别