系统讲解SpringBoot项目集成MinIO及核心配置参数清单

<dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <version>8.5.7</version>  <!-- 2024年最新稳定版 -->
</dependency>
<!-- 可选：连接池支持（生产强烈建议） -->
<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
</dependency>

minio:
  # -------- 必填参数 --------
  endpoint: http://minio.example.com:9000   # 访问地址（注意：不带 bucket 名）
  access-key: admin                         # 访问密钥（控制台登录账号）
  secret-key: password123                   # 密钥（控制台登录密码）
  # -------- 连接参数（OkHttp 底层） --------
  connect-timeout: 10s                      # 建立连接超时（默认 10s）
  write-timeout: 60s                        # 写入超时（上传大文件调大）
  read-timeout: 60s                         # 读取超时（下载大文件调大）
  # -------- 连接池参数（核心性能） --------
  max-connections: 300                      # 最大空闲连接数（默认 300）
  max-connections-per-route: 100           # 每个路由的最大并发连接数（默认 100）
  connection-ttl: 300s                     # 连接存活时间（默认 300s）
  connection-idle-timeout: 60s             # 空闲连接超时关闭时间（默认 60s）
  # -------- 高级特性 --------
  bucket: my-photos                        # 默认桶（可选，便于业务调用）
  use-ssl: false                           # 是否启用 HTTPS（对应 endpoint 协议）
  user-agent: "MyApp/1.0"                  # 自定义 User-Agent（可选）
  region: cn-south-1                       # 地域（默认 us-east-1）

import io.minio.MinioClient;
import okhttp3.OkHttpClient;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.concurrent.TimeUnit;

@Configuration
public class MinioConfig {

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

    @Value("${minio.access-key}")
    private String accessKey;

    @Value("${minio.secret-key}")
    private String secretKey;

    @Value("${minio.connect-timeout:10s}")
    private String connectTimeout;

    @Value("${minio.write-timeout:60s}")
    private String writeTimeout;

    @Value("${minio.read-timeout:60s}")
    private String readTimeout;

    @Value("${minio.max-connections:300}")
    private int maxConnections;

    @Value("${minio.max-connections-per-route:100}")
    private int maxConnectionsPerRoute;

    @Value("${minio.connection-ttl:300s}")
    private String connectionTtl;

    @Value("${minio.connection-idle-timeout:60s}")
    private String connectionIdleTimeout;

    @Bean
    public OkHttpClient okHttpClient() {
        return new OkHttpClient.Builder()
                .connectTimeout(parseDuration(connectTimeout), TimeUnit.SECONDS)
                .writeTimeout(parseDuration(writeTimeout), TimeUnit.SECONDS)
                .readTimeout(parseDuration(readTimeout), TimeUnit.SECONDS)
                .connectionPool(new okhttp3.ConnectionPool(
                        maxConnections,                     // 最大空闲连接数
                        parseDuration(connectionIdleTimeout), // 空闲连接存活秒数
                        TimeUnit.SECONDS
                ))
                .build();
    }

    @Bean
    public MinioClient minioClient(OkHttpClient okHttpClient) {
        return MinioClient.builder()
                .endpoint(endpoint)
                .credentials(accessKey, secretKey)
                .httpClient(okHttpClient)   // 注入自定义连接池
                .build();
    }

    // 工具：将 "60s" 转为 long
    private long parseDuration(String duration) {
        if (duration.endsWith("s")) {
            return Long.parseLong(duration.substring(0, duration.length() - 1));
        }
        return Long.parseLong(duration);
    }
}

import io.minio.*;
import io.minio.http.Method;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import org.springframework.web.multipart.MultipartFile;

import java.io.InputStream;
import java.util.UUID;
import java.util.concurrent.TimeUnit;

@Slf4j
@Service
@RequiredArgsConstructor
public class MinioService {

    private final MinioClient minioClient;

    @Value("${minio.bucket:my-bucket}")
    private String defaultBucket;

    /**
     * 上传图片（自动分片）
     */
    public String uploadImage(MultipartFile file, String userId) throws Exception {
        // 1. 生成对象名（Key）
        String objectName = String.format("%s/%s/%s.jpg",
                LocalDate.now().format(DateTimeFormatter.ISO_DATE),
                userId,
                UUID.randomUUID().toString()
        );

        // 2. 检查桶是否存在，不存在则创建
        boolean bucketExists = minioClient.bucketExists(BucketExistsArgs.builder()
                .bucket(defaultBucket)
                .build());
        if (!bucketExists) {
            minioClient.makeBucket(MakeBucketArgs.builder()
                    .bucket(defaultBucket)
                    .build());
            // 可选：设置桶策略为公开读（谨慎）
            // setBucketPolicy(defaultBucket, PolicyType.READ_ONLY);
        }

        // 3. 上传（携带自定义元数据）
        minioClient.putObject(PutObjectArgs.builder()
                .bucket(defaultBucket)
                .object(objectName)
                .stream(file.getInputStream(), file.getSize(), -1) // -1 表示自动分片（>64M 自动分片）
                .contentType(file.getContentType())
                .userMetadata(Map.of(
                        "user-id", userId,
                        "upload-time", String.valueOf(System.currentTimeMillis())
                ))
                .build());

        log.info("文件上传成功: {}", objectName);
        return objectName;
    }

    /**
     * 下载（返回流）
     */
    public InputStream download(String objectName) throws Exception {
        return minioClient.getObject(GetObjectArgs.builder()
                .bucket(defaultBucket)
                .object(objectName)
                .build());
    }

    /**
     * 生成临时访问链接（核心：保护私有桶）
     * @param objectName 对象名
     * @param expiry 过期时间（单位：秒）
     */
    public String getPresignedUrl(String objectName, int expiry) throws Exception {
        return minioClient.getPresignedObjectUrl(GetPresignedObjectUrlArgs.builder()
                .bucket(defaultBucket)
                .object(objectName)
                .method(Method.GET)
                .expiry(expiry, TimeUnit.SECONDS)  // 默认 7 天
                .build());
    }

    /**
     * 列举指定前缀下的所有图片（慎用大数据量）
     */
    public List<String> listImages(String prefix) throws Exception {
        List<String> result = new ArrayList<>();
        Iterable<Result<Item>> results = minioClient.listObjects(
                ListObjectsArgs.builder()
                        .bucket(defaultBucket)
                        .prefix(prefix)
                        .recursive(true)
                        .maxKeys(1000)  // 每次最多返回 1000 个
                        .build()
        );

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

    /**
     * 删除文件（支持批量删除）
     */
    public void delete(String objectName) throws Exception {
        minioClient.removeObject(RemoveObjectArgs.builder()
                .bucket(defaultBucket)
                .object(objectName)
                .build());
    }
}

@RestController
@RequestMapping("/api/images")
@RequiredArgsConstructor
public class ImageController {

    private final MinioService minioService;

    @PostMapping("/upload")
    public ResponseEntity<String> upload(@RequestParam("file") MultipartFile file,
                                         @RequestParam("userId") String userId) {
        try {
            String objectName = minioService.uploadImage(file, userId);
            return ResponseEntity.ok(objectName);
        } catch (Exception e) {
            return ResponseEntity.status(500).body("上传失败: " + e.getMessage());
        }
    }

    @GetMapping("/url")
    public ResponseEntity<String> getUrl(@RequestParam("objectName") String objectName,
                                         @RequestParam(value = "expiry", defaultValue = "3600") int expiry) {
        try {
            String url = minioService.getPresignedUrl(objectName, expiry);
            return ResponseEntity.ok(url);
        } catch (Exception e) {
            return ResponseEntity.status(500).body("生成链接失败");
        }
    }

    @GetMapping("/list")
    public ResponseEntity<List<String>> list(@RequestParam("prefix") String prefix) {
        try {
            List<String> objects = minioService.listImages(prefix);
            return ResponseEntity.ok(objects);
        } catch (Exception e) {
            return ResponseEntity.status(500).build();
        }
    }
}