当前位置：首页 > news >正文

SpringBoot整合MinIO快速入门：实现分布式文件存储与管理

news 来源：原创 2025/5/11 1:32:50

文章目录

一、MinIO是什么？为什么选择它？
- 1.1 什么是MinIO？
- 1.2 核心优势
二、本地快速搭建MinIO服务
- 2.1 Docker一键部署
- 2.2 访问管理界面
- 2.3 创建存储桶（Bucket）
三、SpringBoot集成MinIO客户端
- 3.1 添加Maven依赖
- 3.2 配置application.yml
- 3.3 初始化MinioClient
四、核心功能代码实现
- 4.1 封装MinIO工具类
- 4.2 编写测试Controller
五、常见问题排查
- 5.1 连接超时（Connection refused）
- 5.2 存储桶不存在（Bucket not found）
- 5.3 权限不足（Access Denied）
总结

一、MinIO是什么？为什么选择它？

1.1 什么是MinIO？

‌MinIO‌ 是一款高性能的分布式对象存储服务，完全兼容Amazon S3协议。它轻量级、易部署，适合存储非结构化数据（图片、视频、日志等），广泛应用于微服务架构中的文件存储场景。

1.2 核心优势

‌开源免费‌：Apache 2.0协议，企业可免费商用
‌兼容S3‌：无缝对接现有S3生态工具
高性能‌：单机读写速度可达183 GB/s和171 GB/s
‌云原生‌：支持Kubernetes/ Docker部署

二、本地快速搭建MinIO服务

2.1 Docker一键部署

# 创建数据存储目录
mkdir -p ~/minio/data

# 启动MinIO容器（用户名密码自定义）
docker run -d \
  -p 9000:9000 \
  -p 9090:9090 \
  --name minio \
  -v ~/minio/data:/data \
  -e "MINIO_ROOT_USER=admin" \
  -e "MINIO_ROOT_PASSWORD=admin123" \
  minio/minio server /data --console-address ":9090"

2.2 访问管理界面

浏览器打开 http://localhost:9090，输入账号密码登录：
在这里插入图片描述

2.3 创建存储桶（Bucket）

点击左侧‌Buckets‌ → ‌Create Bucket‌
输入Bucket名称（如my-bucket）
修改访问策略为‌public‌（开发环境方便测试）

三、SpringBoot集成MinIO客户端

3.1 添加Maven依赖

<!-- MinIO Java SDK -->
<dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <version>8.5.9</version>
</dependency>

<!-- Lombok简化代码 -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
</dependency>

<!-- Web支持 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

3.2 配置application.yml

minio:
  endpoint: http://localhost:9000
  accessKey: admin    # 对应MINIO_ROOT_USER
  secretKey: admin123 # 对应MINIO_ROOT_PASSWORD
  bucketName: my-bucket

3.3 初始化MinioClient

@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();
    }
}

四、核心功能代码实现

4.1 封装MinIO工具类

@Service
@Slf4j
public class MinioService {

    @Autowired
    private MinioClient minioClient;

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

    /**
     * 上传文件
     * @param file 文件对象
     * @return 文件访问URL
     */
    public String uploadFile(MultipartFile file) throws Exception {
        String fileName = file.getOriginalFilename();
        minioClient.putObject(
                PutObjectArgs.builder()
                        .bucket(bucketName)
                        .object(fileName)
                        .stream(file.getInputStream(), file.getSize(), -1)
                        .contentType(file.getContentType())
                        .build());
        return endpoint + "/" + bucketName + "/" + fileName;
    }

    /**
     * 下载文件
     * @param fileName 文件名
     * @return 文件流
     */
    public InputStream downloadFile(String fileName) throws Exception {
        return minioClient.getObject(
                GetObjectArgs.builder()
                        .bucket(bucketName)
                        .object(fileName)
                        .build());
    }

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

4.2 编写测试Controller

@RestController
@RequestMapping("/file")
public class FileController {

    @Autowired
    private MinioService minioService;

    @PostMapping("/upload")
    public Result<String> upload(@RequestParam MultipartFile file) {
        try {
            String url = minioService.uploadFile(file);
            return Result.success(url);
        } catch (Exception e) {
            return Result.fail("上传失败: " + e.getMessage());
        }
    }

    @GetMapping("/download/{fileName}")
    public void download(@PathVariable String fileName, 
                        HttpServletResponse response) {
        try (InputStream is = minioService.downloadFile(fileName)) {
            response.setContentType("application/octet-stream");
            response.setHeader("Content-Disposition", 
                    "attachment;filename=" + URLEncoder.encode(fileName, "UTF-8"));
            IOUtils.copy(is, response.getOutputStream());
        } catch (Exception e) {
            log.error("下载失败", e);
        }
    }
}