SpringBoot 集成 MinIO 文件服务器配置与使用

六、Windows 环境下 MinIO 部署与配置

1. 下载 MinIO

硬件要求：Windows 7 及以上 64 位系统，建议 CPU 2 核及以上、内存 4GB 及以上，存储盘预留至少 10GB 可用空间。

软件下载：访问 MinIO 官方下载页或国内镜像地址，下载核心服务端程序 minio.exe；若需命令行管理工具，可同步下载客户端 mc.exe。

2. 启动 MinIO

（1）规划目录

在本地磁盘创建标准化目录结构，用于统一管理程序与数据：

• 主目录：D:\Develop\Env\MinIO
• 程序目录：D:\Develop\Env\MinIO\bin
• 数据目录：D:\Develop\Env\MinIO\data
• 日志目录：D:\Develop\Env\MinIO\logs

（2）创建启动脚本

创建一个 bat 文件，复制以下命令（路径根据实际存放位置修改）：

@echo off
chcp 65001 > nul
echo 正在启动 MinIO 服务...
cd D:\Develop\Env\MinIO\bin
minio.exe server D:\Develop\Env\MinIO\data --console-address ":9001"
pause

（3）双击启动

访问 http://127.0.0.1:9001，用户名和密码默认都为 minioadmin。

3. 汉化操作

目前没有官方汉化配置，最快的方式是使用浏览器翻译功能。

4. MinIO 核心概念解析

1. 桶（Bucket）：MinIO 的基本存储单元，类似文件系统中的'文件夹'，命名规则为 3-63 个字符，仅支持小写字母、数字、横线。
2. 对象（Object）：MinIO 中存储的核心数据单元，对应实际的文件，由'文件内容 + 元数据'组成。
3. API 服务端口：默认 9000 端口，用于客户端通过 SDK 集成 MinIO。
4. Web 控制台端口：默认 9001 端口，提供可视化管理界面。

5. MinIO 基础操作指南（Web 控制台）

（1）创建存储桶 登录 Web 控制台后，点击左侧菜单栏'Create Bucket'，输入桶名称。

（2）对象操作 在桶下面可以创建文件夹或直接上传文件。注意：创建文件夹后需上传资源才算有效。

七、SpringBoot 集成 MinIO

1. 引入 Maven

建议使用 JDK 1.8，SDK 版本 8.5.6。

<!-- MinIO 官方 Java SDK -->
<dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <version>8.5.6</version>
</dependency>
<!-- 用于文件流处理的工具类 -->
<dependency>
    <groupId>commons-io</groupId>
    <artifactId>commons-io</artifactId>
    <version>2.11.0</version>
</dependency>

2. 配置 MinIO 连接信息

在 application.yml 中配置 MinIO 连接参数：

spring:
  minio:
    endpoint: http://localhost:9000
    access-key: minioadmin
    secret-key: minioadmin
    bucket-name: test-bucket
    base-url: http://localhost:9000/test-bucket/

3. 创建 MinIO 客户端配置类

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

@Configuration
public class MinioConfig {
    @Value("${spring.minio.endpoint}")
    private String endpoint;

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

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

    @Bean
    public MinioClient minioClient() {
        return MinioClient.builder()
                .endpoint(endpoint)
                .credentials(accessKey, secretKey)
                .build();
    }
}

4. 封装 MinIO 工具类

import io.minio.*;
import io.minio.http.Method;
import io.minio.messages.Bucket;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
import org.springframework.web.multipart.MultipartFile;
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.List;
import java.util.concurrent.TimeUnit;

@Component
public class MinioUtil {
    @Autowired
    private MinioClient minioClient;

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

    @Value("${spring.minio.base-url}")
    private String baseUrl;

    public void createBucket(String bucketName) throws Exception {
        if (!minioClient.bucketExists(BucketExistsArgs.builder().bucket(bucketName).build())) {
            minioClient.makeBucket(MakeBucketArgs.builder().bucket(bucketName).build());
        }
    }

    public String uploadFile(MultipartFile file, String bucketName) throws Exception {
        if (bucketName == null || bucketName.isEmpty()) {
            bucketName = defaultBucket;
        }
        createBucket(bucketName);
        String originalFilename = file.getOriginalFilename();
        String fileName = "upload/" + System.currentTimeMillis() + "_" + originalFilename;
        minioClient.putObject(
                PutObjectArgs.builder()
                        .bucket(bucketName)
                        .object(fileName)
                        .stream(file.getInputStream(), file.getSize(), -1)
                        .contentType(file.getContentType())
                        .build());
        return baseUrl + fileName;
    }

    public InputStream downloadFile(String fileName, String bucketName) throws Exception {
        if (bucketName == null || bucketName.isEmpty()) {
            bucketName = defaultBucket;
        }
        return minioClient.getObject(
                GetObjectArgs.builder()
                        .bucket(bucketName)
                        .object(fileName)
                        .build());
    }

    public void deleteFile(String fileName, String bucketName) throws Exception {
        if (bucketName == null || bucketName.isEmpty()) {
            bucketName = defaultBucket;
        }
        minioClient.removeObject(
                RemoveObjectArgs.builder()
                        .bucket(bucketName)
                        .object(fileName)
                        .build());
    }

    public List<Bucket> getBucketList() throws Exception {
        return minioClient.listBuckets();
    }

    public String getPresignedUrl(String fileName, String bucketName, int expireSeconds) throws Exception {
        if (bucketName == null || bucketName.isEmpty()) {
            bucketName = defaultBucket;
        }
        return minioClient.getPresignedObjectUrl(
                GetPresignedObjectUrlArgs.builder()
                        .method(Method.GET)
                        .bucket(bucketName)
                        .object(fileName)
                        .expiry(expireSeconds, TimeUnit.SECONDS)
                        .build());
    }
}

5. 编写测试接口

import org.apache.commons.io.IOUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import java.io.InputStream;

@RestController
@RequestMapping("/minio")
public class MinioController {
    @Autowired
    private MinioUtil minioUtil;

    @PostMapping("/upload")
    public String uploadFile(@RequestParam("file") MultipartFile file) {
        try {
            return minioUtil.uploadFile(file, null);
        } catch (Exception e) {
            return "上传失败：" + e.getMessage();
        }
    }

    @GetMapping("/download")
    public ResponseEntity<byte[]> downloadFile(@RequestParam("fileName") String fileName) {
        try {
            InputStream in = minioUtil.downloadFile(fileName, null);
            byte[] bytes = IOUtils.toByteArray(in);
            HttpHeaders headers = new HttpHeaders();
            headers.setContentDispositionFormData("attachment", new String(fileName.getBytes("UTF-8"), "ISO-8859-1"));
            headers.setContentType(MediaType.APPLICATION_OCTET_STREAM);
            return new ResponseEntity<>(bytes, headers, HttpStatus.OK);
        } catch (Exception e) {
            return ResponseEntity.status(500).body(("下载失败：" + e.getMessage()).getBytes());
        }
    }

    @DeleteMapping("/delete")
    public String deleteFile(@RequestParam("fileName") String fileName) {
        try {
            minioUtil.deleteFile(fileName, null);
            return "删除成功";
        } catch (Exception e) {
            return "删除失败：" + e.getMessage();
        }
    }

    @GetMapping("/getUrl")
    public String getFileUrl(@RequestParam("fileName") String fileName) {
        try {
            return minioUtil.getPresignedUrl(fileName, null, 3600);
        } catch (Exception e) {
            return "获取链接失败：" + e.getMessage();
        }
    }
}

6. 测试验证

1. 启动 SpringBoot 项目和 MinIO 服务。
2. 使用 Postman 测试接口：
   • 上传文件：发送 POST 请求到 http://localhost:8080/minio/upload，参数类型 form-data，键 file，值选择本地文件。
   • 下载文件：发送 GET 请求到 http://localhost:8080/minio/download?fileName=文件名，浏览器自动下载文件。
   • 删除文件：发送 DELETE 请求到 http://localhost:8080/minio/delete?fileName=文件名。
   • 获取临时链接：发送 GET 请求到 http://localhost:8080/minio/getUrl?fileName=文件名，返回有效期 1 小时的临时访问链接。