AI（Gemini版）教你写代码——Springboot中使用Minio-CSDN博客

本文链接：https://blog.csdn.net/LuckyLay/article/details/147596483

“优雅” 的方式在Spring Boot中集成 MinIO

在Spring Boot中，"优雅"通常意味着：

使用标准的配置机制： 将MinIO的连接信息（endpoint, access key, secret key）放在 application.properties 或 application.yml 中。
利用依赖注入： 将 MinioClient 注册为一个 Spring Bean，然后在需要的地方通过 @Autowired 或构造函数注入。
封装业务逻辑： 将 MinIO 的具体操作（上传、下载、删除等）封装到一个 Service 类中，而不是直接在 Controller 或其他地方调用 MinioClient。
使用配置类： 创建一个 @Configuration 类来集中管理 MinioClient 的创建逻辑。

安全与权限管理

MinIO 的权限管理主要基于 IAM (Identity and Access Management) 模型，与 AWS S3 类似。核心概念包括：

用户 (Users)： 访问 MinIO 的身份，由 Access Key 和 Secret Key 组成。你的 Spring Boot 应用将使用一组 Access Key/Secret Key 作为它的身份。
策略 (Policies)： 定义了一组权限规则，指定了允许或拒绝哪些用户对哪些资源（桶、对象）执行哪些操作（读、写、列出、删除等）。
策略绑定： 将一个或多个策略绑定到一个用户或组。

Spring Boot 应用在连接 MinIO 时，它所使用的 Access Key 和 Secret Key 本身就代表了一个用户，这个用户在 MinIO 中被赋予了特定的策略，从而拥有了对应的权限。你的 Spring Boot 应用能执行什么操作，完全取决于你为这个 Access Key/Secret Key 在 MinIO 服务端配置了什么策略。

在 Spring Boot 中考虑安全：

安全地存储凭证： 绝对不要将 Access Key 和 Secret Key 硬编码到代码中。使用 application.properties/application.yml 是基本要求，但更推荐在生产环境中使用环境变量、Spring Cloud Config 或专门的密钥管理系统（如 HashiCorp Vault, Kubernetes Secrets, AWS Secrets Manager等）。
最小权限原则： 为你的 Spring Boot 应用创建专门的 MinIO 用户，并只赋予它执行其所需操作的最小权限策略。例如，如果应用只负责上传和下载，就只给它 putObject 和 getObject 的权限，而不是管理员权限。
使用 HTTPS： 确保你的 Spring Boot 应用通过 HTTPS 连接到 MinIO 服务端，以加密传输中的数据和凭证。在配置 MinioClient 时设置 secure(true).
预签名 URL (Presigned URLs)： 如果你需要允许第三方或客户端（例如浏览器直接上传或下载）在不暴露你的应用凭证的情况下访问 MinIO 对象，应该使用预签名 URL。你的 Spring Boot 后端生成一个有时效性的 URL，客户端使用这个 URL 进行操作。这是一种非常常见的安全访问方式。

代码示例

我们将通过以下步骤实现：

添加 MinIO 依赖。
配置 MinIO 连接属性。
创建 MinioProperties 配置类。
创建 MinioConfig 配置类注册 MinioClient Bean。
创建 MinioService 封装操作。
（可选）创建 Controller 演示用法。
讲解 MinIO 服务端的权限配置（非代码，但非常重要）。
讲解预签名 URL 的生成和使用。
讲解更安全的凭证管理。

1. 添加 MinIO 依赖 (pom.xml)

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

2. 配置 MinIO 连接属性 (application.yml)

使用 application.yml 格式，它通常比 .properties 更清晰。

minio:
  endpoint: http://127.0.0.1:9000 # MinIO 服务器地址，如果是 HTTPS，改为 https://...
  accessKey: minioadmin # 你的 Access Key
  secretKey: minioadmin # 你的 Secret Key
  secure: false # 如果使用 HTTPS，改为 true
  bucketName: my-default-bucket # 可以配置一个默认桶

3. 创建 MinioProperties 配置类

package com.yourcompany.yourapp.config;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "minio")
public class MinioProperties {

    private String endpoint;
    private String accessKey;
    private String secretKey;
    private boolean secure;
    private String bucketName;

    // Getters and Setters
    public String getEndpoint() {
        return endpoint;
    }

    public void setEndpoint(String endpoint) {
        this.endpoint = endpoint;
    }

    public String getAccessKey() {
        return accessKey;
    }

    public void setAccessKey(String accessKey) {
        this.accessKey = accessKey;
    }

    public String getSecretKey() {
        return secretKey;
    }

    public void setSecretKey(String secretKey) {
        this.secretKey = secretKey;
    }

    public boolean isSecure() {
        return secure;
    }

    public void setSecure(boolean secure) {
        this.secure = secure;
    }

    public String getBucketName() {
        return bucketName;
    }

    public void setBucketName(String bucketName) {
        this.bucketName = bucketName;
    }
}

4. 创建 MinioConfig 配置类注册 MinioClient Bean

package com.yourcompany.yourapp.config;

import io.minio.MinioClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableConfigurationProperties(MinioProperties.class) // 启用 MinioProperties
public class MinioConfig {

    @Autowired
    private MinioProperties minioProperties;

    @Bean
    public MinioClient minioClient() {
        try {
            MinioClient client = MinioClient.builder()
                    .endpoint(minioProperties.getEndpoint())
                    .credentials(minioProperties.getAccessKey(), minioProperties.getSecretKey())
                    .secure(minioProperties.isSecure()) // 根据配置设置是否使用 HTTPS
                    .build();

            // Optional: Check if the default bucket exists on startup
            boolean found = client.bucketExists(io.minio.BucketExistsArgs.builder().bucket(minioProperties.getBucketName()).build());
            if (!found) {
                // Create the bucket if it doesn't exist (requires permissions)
                client.makeBucket(io.minio.MakeBucketArgs.builder().bucket(minioProperties.getBucketName()).build());
                System.out.println("Bucket '" + minioProperties.getBucketName() + "' created.");
            } else {
                System.out.println("Bucket '" + minioProperties.getBucketName() + "' already exists.");
            }

            return client;
        } catch (Exception e) {
            // Log the error and handle appropriately in a real application
            e.printStackTrace();
            throw new RuntimeException("Failed to initialize Minio client", e);
        }
    }
}

5. 创建 MinioService 封装操作

package com.yourcompany.yourapp.service;

import com.yourcompany.yourapp.config.MinioProperties;
import io.minio.*;
import io.minio.errors.*;
import io.minio.http.Method;
import io.minio.messages.DeleteError;
import io.minio.messages.DeleteObject;
import io.minio.messages.Item;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.TimeUnit;

@Service
public class MinioService {

    @Autowired
    private MinioClient minioClient;

    @Autowired
    private MinioProperties minioProperties; // 注入属性以获取默认桶名等

    /**
     * 检查桶是否存在
     * @param bucketName 桶名
     * @return 是否存在
     */
    public boolean bucketExists(String bucketName) throws Exception {
        return minioClient.bucketExists(BucketExistsArgs.builder().bucket(bucketName).build());
    }

    /**
     * 创建桶
     * @param bucketName 桶名
     */
    public void createBucket(String bucketName) throws Exception {
        boolean found = minioClient.bucketExists(BucketExistsArgs.builder().bucket(bucketName).build());
        if (!found) {
            minioClient.makeBucket(MakeBucketArgs.builder().bucket(bucketName).build());
        }
    }

    /**
     * 上传文件
     * @param bucketName 桶名
     * @param objectName 对象名 (文件路径+文件名，例如 "docs/document.pdf")
     * @param stream 文件输入流
     * @param contentType 文件类型 (例如 "image/jpeg", "application/pdf")
     */
    public ObjectWriteResponse uploadFile(String bucketName, String objectName, InputStream stream, String contentType) throws Exception {
         // 确保桶存在
        boolean found = minioClient.bucketExists(BucketExistsArgs.builder().bucket(bucketName).build());
        if (!found) {
           createBucket(bucketName); // 或者选择抛出异常，取决于你的业务逻辑
        }

        return minioClient.putObject(
                PutObjectArgs.builder()
                        .bucket(bucketName)
                        .object(objectName)
                        .stream(stream, stream.available(), -1) // stream.available() 获取流的总大小，-1 表示未知大小
                        .contentType(contentType)
                        .build());
    }

    /**
     * 使用默认桶上传文件
     */
    public ObjectWriteResponse uploadFile(String objectName, InputStream stream, String contentType) throws Exception {
         return uploadFile(minioProperties.getBucketName(), objectName, stream, contentType);
    }


    /**
     * 下载文件
     * @param bucketName 桶名
     * @param objectName 对象名
     * @return 文件输入流
     */
    public InputStream downloadFile(String bucketName, String objectName) throws Exception {
        return minioClient.getObject(
                GetObjectArgs.builder()
                        .bucket(bucketName)
                        .object(objectName)
                        .build());
    }

      /**
     * 使用默认桶下载文件
     */
    public InputStream downloadFile(String objectName) throws Exception {
         return downloadFile(minioProperties.getBucketName(), objectName);
    }

    /**
     * 删除文件
     * @param bucketName 桶名
     * @param objectName 对象名
     */
    public void deleteFile(String bucketName, String objectName) throws Exception {
        minioClient.removeObject(
                RemoveObjectArgs.builder()
                        .bucket(bucketName)
                        .object(objectName)
                        .build());
    }

     /**
     * 使用默认桶删除文件
     */
    public void deleteFile(String objectName) throws Exception {
         deleteFile(minioProperties.getBucketName(), objectName);
    }

    /**
     * 批量删除文件
     * @param bucketName 桶名
     * @param objectNames 对象名列表
     */
    public void deleteFiles(String bucketName, List<String> objectNames) throws Exception {
        List<DeleteObject> objectsToDelete = new ArrayList<>();
        for (String objectName : objectNames) {
            objectsToDelete.add(new DeleteObject(objectName));
        }

        Iterable<Result<DeleteError>> results = minioClient.removeObjects(
                RemoveObjectsArgs.builder()
                        .bucket(bucketName)
                        .objects(objectsToDelete)
                        .build());

        for (Result<DeleteError> result : results) {
            DeleteError error = result.get();
            System.err.println("Error deleting object " + error.objectName() + ": " + error.message());
             // 根据需要处理删除失败的情况
        }
    }

      /**
     * 使用默认桶批量删除文件
     */
     public void deleteFiles(List<String> objectNames) throws Exception {
         deleteFiles(minioProperties.getBucketName(), objectNames);
     }


    /**
     * 列出桶中的所有对象
     * @param bucketName 桶名
     * @return 对象列表
     */
    public List<Item> listObjects(String bucketName) throws Exception {
        List<Item> objects = new ArrayList<>();
        Iterable<Result<Item>> results = minioClient.listObjects(
                ListObjectsArgs.builder()
                        .bucket(bucketName)
                        .recursive(true) // 是否递归列出所有子目录下的对象
                        .build());

        for (Result<Item> result : results) {
            objects.add(result.get());
        }
        return objects;
    }

      /**
     * 使用默认桶列出所有对象
     */
    public List<Item> listObjects() throws Exception {
         return listObjects(minioProperties.getBucketName());
    }

    /**
     * 生成预签名下载 URL
     * @param bucketName 桶名
     * @param objectName 对象名
     * @param duration 有效期 (秒)
     * @return 预签名 URL
     */
    public String generatePresignedDownloadUrl(String bucketName, String objectName, int duration) throws Exception {
        return minioClient.getPresignedObjectUrl(
                GetPresignedObjectUrlArgs.builder()
                        .method(Method.GET) // 下载使用 GET 方法
                        .bucket(bucketName)
                        .object(objectName)
                        .expiry(duration, TimeUnit.SECONDS)
                        .build());
    }

     /**
     * 使用默认桶生成预签名下载 URL
     */
     public String generatePresignedDownloadUrl(String objectName, int duration) throws Exception {
         return generatePresignedDownloadUrl(minioProperties.getBucketName(), objectName, duration);
     }

    /**
     * 生成预签名上传 URL
     * @param bucketName 桶名
     * @param objectName 对象名
     * @param duration 有效期 (秒)
     * @return 预签名 URL
     */
    public String generatePresignedUploadUrl(String bucketName, String objectName, int duration) throws Exception {
        return minioClient.getPresignedObjectUrl(
                GetPresignedObjectUrlArgs.builder()
                        .method(Method.PUT) // 上传使用 PUT 方法
                        .bucket(bucketName)
                        .object(objectName)
                        .expiry(duration, TimeUnit.SECONDS)
                        .build());
    }

     /**
     * 使用默认桶生成预签名上传 URL
     */
     public String generatePresignedUploadUrl(String objectName, int duration) throws Exception {
         return generatePresignedUploadUrl(minioProperties.getBucketName(), objectName, duration);
     }

    // TODO: Add more methods as needed (copyObject, statObject etc.)
    // TODO: Implement more robust error handling (logging, custom exceptions)
}

6. （可选）创建 Controller 演示用法

package com.yourcompany.yourapp.controller;

import com.yourcompany.yourapp.service.MinioService;
import io.minio.ObjectWriteResponse;
import io.minio.messages.Item;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import java.io.InputStream;
import java.util.List;

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

    @Autowired
    private MinioService minioService;

    // Example Endpoint: Upload a file
    @PostMapping("/upload")
    public ResponseEntity<String> uploadFile(@RequestParam("file") MultipartFile file,
                                           @RequestParam(value = "bucket", required = false) String bucketName,
                                           @RequestParam("objectName") String objectName) {
        try {
            String targetBucket = bucketName != null ? bucketName : "default-bucket-from-config"; // 使用请求参数或默认桶
            InputStream inputStream = file.getInputStream();
            String contentType = file.getContentType();

            ObjectWriteResponse response = minioService.uploadFile(targetBucket, objectName, inputStream, contentType);
            return ResponseEntity.ok("File uploaded successfully: " + response.object());
        } catch (Exception e) {
            e.printStackTrace();
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("Upload failed: " + e.getMessage());
        }
    }

    // Example Endpoint: Download a file
    @GetMapping("/download")
    public ResponseEntity<InputStream> downloadFile(@RequestParam(value = "bucket", required = false) String bucketName,
                                                  @RequestParam("objectName") String objectName) {
        try {
             String targetBucket = bucketName != null ? bucketName : "default-bucket-from-config";
            InputStream stream = minioService.downloadFile(targetBucket, objectName);
            // TODO: Set appropriate headers for file download (Content-Disposition, Content-Type)
            return ResponseEntity.ok(stream); // Note: This is a basic example, proper streaming/handling is needed for large files
        } catch (Exception e) {
            e.printStackTrace();
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
        }
    }

    // Example Endpoint: List objects
    @GetMapping("/list")
    public ResponseEntity<List<Item>> listObjects(@RequestParam(value = "bucket", required = false) String bucketName) {
        try {
            String targetBucket = bucketName != null ? bucketName : "default-bucket-from-config";
            List<Item> objects = minioService.listObjects(targetBucket);
            return ResponseEntity.ok(objects);
        } catch (Exception e) {
            e.printStackTrace();
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
        }
    }

     // Example Endpoint: Generate presigned download URL
     @GetMapping("/presigned/download")
     public ResponseEntity<String> generatePresignedDownloadUrl(@RequestParam(value = "bucket", required = false) String bucketName,
                                                               @RequestParam("objectName") String objectName,
                                                               @RequestParam(value = "duration", defaultValue = "600") int duration) {
         try {
             String targetBucket = bucketName != null ? bucketName : "default-bucket-from-config";
             String url = minioService.generatePresignedDownloadUrl(targetBucket, objectName, duration);
             return ResponseEntity.ok(url);
         } catch (Exception e) {
             e.printStackTrace();
             return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("Failed to generate URL: " + e.getMessage());
         }
     }

      // Example Endpoint: Generate presigned upload URL
      @GetMapping("/presigned/upload") // Note: GET for generating, PUT/POST would be used by client to upload
      public ResponseEntity<String> generatePresignedUploadUrl(@RequestParam(value = "bucket", required = false) String bucketName,
                                                               @RequestParam("objectName") String objectName,
                                                               @RequestParam(value = "duration", defaultValue = "600") int duration) {
          try {
               String targetBucket = bucketName != null ? bucketName : "default-bucket-from-config";
              String url = minioService.generatePresignedUploadUrl(targetBucket, objectName, duration);
              return ResponseEntity.ok(url);
          } catch (Exception e) {
              e.printStackTrace();
              return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("Failed to generate URL: " + e.getMessage());
          }
      }

    // TODO: Add delete endpoint, batch delete etc.
    // TODO: Implement Spring Security to protect these endpoints
}

7. MinIO 服务端的权限配置（非常重要！）

这部分不是 Spring Boot 代码，而是在 MinIO 服务端进行的操作，它决定了你的 Spring Boot 应用（使用特定的 Access Key/Secret Key）在 MinIO 中拥有什么权限。

你可以通过 MinIO 控制台 (UI)、mc 命令行工具或 MinIO API 来管理用户和策略。

基本步骤：

创建用户： 使用 mc admin user add YOUR-ACCESS-KEY YOUR-SECRET-KEY 或在 UI 中创建新用户。确保为你的 Spring Boot 应用创建一个专用的用户，而不是使用默认的 minioadmin。

创建策略： 策略是 JSON 格式的文档，定义了权限。例如，一个只允许读写特定桶的策略：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::my-data-bucket/*",
                "arn:aws:s3:::my-data-bucket"
            ]
        }
    ]
}

Effect: Allow 或 Deny。
Action: 允许或拒绝的操作，例如 s3:GetObject, s3:PutObject, s3:DeleteObject, s3:ListBucket, s3:MakeBucket 等。
Resource: 应用权限的资源。arn:aws:s3:::bucket-name/* 表示桶中的所有对象，arn:aws:s3:::bucket-name 表示桶本身。

绑定策略： 将创建的策略绑定到你的 Spring Boot 应用使用的 MinIO 用户。使用 mc admin policy attach POLICY-NAME --user YOUR-ACCESS-KEY 或在 UI 中操作。

关键点：

你的 Spring Boot 应用的权限是受其连接 MinIO 时使用的 Access Key/Secret Key 所关联的策略控制的。 你在 Spring Boot 代码中调用 minioClient.putObject() 时，如果该用户没有 s3:PutObject 权限，MinIO 会拒绝该请求。
为不同的应用或功能创建不同的 MinIO 用户和策略，实现权限隔离。

8. 预签名 URL 的生成和使用

正如 MinioService 中所示，你可以生成一个带有签名和过期时间的 URL。

下载预签名 URL： 将生成的 URL 提供给客户端（例如前端浏览器）。客户端直接使用 HTTP GET 请求访问这个 URL，就可以下载文件，而不需要你的 Spring Boot 后端作为代理，也不需要客户端知道你的 MinIO 凭证。
上传预签名 URL： 生成一个 PUT 方法的预签名 URL。客户端直接使用 HTTP PUT 请求向这个 URL 上传文件。这允许客户端直接上传到 MinIO，减轻后端压力。

安全性： 预签名 URL 是有时效性的，并且只能执行生成时指定的操作（GET 或 PUT）。过期后 URL 失效，提高了安全性。

9. 更安全的凭证管理

在 application.yml 中存放凭证适用于开发环境。在生产环境，强烈建议使用更安全的方案：

环境变量： 在部署 Spring Boot 应用的环境中设置环境变量，例如 MINIO_ACCESS_KEY, MINIO_SECRET_KEY。Spring Boot 会自动将 application.yml 中的属性映射到同名的环境变量（通常是大写，点换成下划线）。
Spring Cloud Config: 如果你使用 Spring Cloud，可以使用 Config Server 集中管理配置，包括敏感信息。
密钥管理系统： 使用 Kubernetes Secrets, Docker Secrets, HashiCorp Vault, AWS Secrets Manager, Azure Key Vault 等专业密钥管理工具。你的应用在启动时或运行时从这些系统中获取凭证。

总结

以上代码和讲解展示了在 Spring Boot 中优雅且安全地集成 MinIO 的方法。关键在于：