MinIO 从下载到集成 Spring Boot 完整教程

第一章：下载 MinIO

1.1 下载地址

┌─────────┬────────────────────────────────────────────────────────────────┐
│ 系统     │ 下载链接                                                       │
├─────────┼────────────────────────────────────────────────────────────────┤
│ Windows │ https://dl.min.io/server/minio/release/windows-amd64/minio.exe │
├─────────┼────────────────────────────────────────────────────────────────┤
│ Linux   │ wget https://dl.min.io/server/minio/release/linux-amd64/minio  │
├─────────┼────────────────────────────────────────────────────────────────┤
│ Mac     │ brew install minio/stable/minio                                │
└─────────┴────────────────────────────────────────────────────────────────┘

1.2 操作步骤

1. 打开浏览器，输入 https://dl.min.io/server/minio/release/windows-amd64/minio.exe
2. 会自动下载一个 minio.exe 文件（大约 30MB）
3. 在 D 盘创建目录：D:\Download Software\MinIO\
4. 把下载的 minio.exe 放到这个目录里

1.3 创建数据存储目录

在 D:\Download Software\MinIO\ 下创建 data 文件夹：

D:\Download Software\MinIO\
├── minio.exe
└── data\    ← 手动新建的文件夹

第二章：启动 MinIO

2.1 打开命令行

进入 MinIO 目录：

cd /d "D:\Download Software\MinIO"

2.2 启动命令

方式一：前台启动（命令行窗口不能关）

minio.exe server D:\Download Software\MinIO\data

方式二：后台启动（推荐，命令行窗口可继续用）

start /B minio.exe server D:\Download Software\MinIO\data

2.3 启动成功后的输出

API: http://192.168.x.x:9000
Console: http://192.168.x.x:9000
RootUser: minioadmin
RootPass: minioadmin

2.4 验证

浏览器访问 http://localhost:9000，看到 MinIO 登录页面 → 启动成功

第三章：登录 MinIO 控制台

3.1 登录

┌────────┬────────────┐
│ 字段   │ 值         │
├────────┼────────────┤
│ 用户名 │ minioadmin │
├────────┼────────────┤
│ 密码   │ minioadmin │
└────────┴────────────┘

3.2 创建 bucket（存储桶）

1. 登录成功后，点左侧菜单 Buckets
2. 点右上角 Create Bucket
3. Bucket Name 输入：test-bucket
4. 点 Create Bucket
5. 创建完成后，点击 test-bucket 进入
6. 找到 Access Policy ，改成 Public（可选，为了方便直接访问文件）

**提示：**如果不改 Public，访问文件需要签名 URL，比较麻烦。

第四章：创建 Spring Boot 项目

4.1 项目结构

Test/
├── pom.xml
└── src/main/
    ├── java/com/test/
    │   ├── Application.java
    │   ├── config/
    │   │   ├── MinioProperties.java
    │   │   └── MinioConfig.java
    │   ├── service/
    │   │   └── MinioService.java
    │   └── controller/
    │       └── FileController.java
    └── resources/
        └── application.yml

第五章：pom.xml

文件路径： pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
&lt;parent&gt;
    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
    &lt;artifactId&gt;spring-boot-starter-parent&lt;/artifactId&gt;
    &lt;version&gt;3.2.4&lt;/version&gt;
    &lt;relativePath/&gt;
&lt;/parent&gt;

&lt;groupId&gt;com.test&lt;/groupId&gt;
&lt;artifactId&gt;Test&lt;/artifactId&gt;
&lt;version&gt;1.0-SNAPSHOT&lt;/version&gt;

&lt;properties&gt;
    &lt;maven.compiler.source&gt;17&lt;/maven.compiler.source&gt;
    &lt;maven.compiler.target&gt;17&lt;/maven.compiler.target&gt;
    &lt;project.build.sourceEncoding&gt;UTF-8&lt;/project.build.sourceEncoding&gt;
&lt;/properties&gt;

&lt;dependencies&gt;
    &lt;!-- Spring Boot Web --&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
        &lt;artifactId&gt;spring-boot-starter-web&lt;/artifactId&gt;
    &lt;/dependency&gt;

    &lt;!-- MinIO Java SDK --&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;io.minio&lt;/groupId&gt;
        &lt;artifactId&gt;minio&lt;/artifactId&gt;
        &lt;version&gt;8.5.12&lt;/version&gt;
    &lt;/dependency&gt;

    &lt;!-- 配置提示（可选） --&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
        &lt;artifactId&gt;spring-boot-configuration-processor&lt;/artifactId&gt;
        &lt;optional&gt;true&lt;/optional&gt;
    &lt;/dependency&gt;

    &lt;!-- Lombok（可选，简化代码） --&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;org.projectlombok&lt;/groupId&gt;
        &lt;artifactId&gt;lombok&lt;/artifactId&gt;
        &lt;optional&gt;true&lt;/optional&gt;
    &lt;/dependency&gt;
&lt;/dependencies&gt;

&lt;build&gt;
    &lt;plugins&gt;
        &lt;plugin&gt;
            &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
            &lt;artifactId&gt;spring-boot-maven-plugin&lt;/artifactId&gt;
        &lt;/plugin&gt;
    &lt;/plugins&gt;
&lt;/build&gt;
</project>

提示： 把这个文件内容直接覆盖你的 pom.xml。

第六章：application.yml

文件路径： src/main/resources/application.yml

server:
  port: 8080
minio:
endpoint: http://localhost:9000
access-key: minioadmin
secret-key: minioadmin
bucket-name: test-bucket

第七章：Application.java

文件路径： src/main/java/com/test/Application.java

package com.test;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}

第八章：MinioProperties.java

文件路径： src/main/java/com/test/config/MinioProperties.java

package com.test.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
@Data
@Component
@ConfigurationProperties(prefix = "minio")
public class MinioProperties {
private String endpoint;
private String accessKey;
private String secretKey;
private String bucketName;
}

第九章：MinioConfig.java

文件路径： src/main/java/com/test/config/MinioConfig.java

package com.test.config;
import io.minio.MinioClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
MinIO 配置类
作用：创建 MinioClient 对象并交给 Spring 管理
*/
@Configuration
public class MinioConfig {
@Bean
public MinioClient minioClient(MinioProperties props) {
// 构建 MinIO 客户端，连接到你启动的 MinIO 服务
return MinioClient.builder()
.endpoint(props.getEndpoint()) // http://localhost:9000
.credentials(props.getAccessKey(), props.getSecretKey())
.build();
}
}

第十章：MinioService.java

文件路径： src/main/java/com/test/service/MinioService.java

package com.test.service;
import com.test.config.MinioProperties;
import io.minio.*;
import org.springframework.stereotype.Service;
import org.springframework.web.multipart.MultipartFile;
import java.io.InputStream;
import java.util.UUID;
/**
MinIO 业务服务
提供：上传、下载、删除、获取访问 URL
*/
@Service
public class MinioService {
private final MinioClient minioClient;
private final MinioProperties props;
// 构造方法注入
public MinioService(MinioClient minioClient, MinioProperties props) {
this.minioClient = minioClient;
this.props = props;
// 项目启动时自动检查并创建 bucket
initBucket();
}
/**
初始化 bucket
如果 test-bucket 不存在，自动创建
*/
private void initBucket() {
try {
boolean exists = minioClient.bucketExists(
BucketExistsArgs.builder()
.bucket(props.getBucketName())
.build());
if (!exists) {
minioClient.makeBucket(
MakeBucketArgs.builder()
.bucket(props.getBucketName())
.build());
System.out.println("Bucket '" + props.getBucketName() + "' created.");
}
} catch (Exception e) {
throw new RuntimeException("Failed to init bucket", e);
}
}
/**
上传文件
@param file 前端传来的 MultipartFile
@return 存储在 MinIO 中的文件名（UUID）
*/
public String upload(MultipartFile file) {
// 获取原文件名后缀
String originalName = file.getOriginalFilename();
String suffix = originalName.substring(originalName.lastIndexOf("."));
// 生成唯一文件名：UUID + 后缀
String objectName = UUID.randomUUID().toString().replace("-", "") + suffix;
try (InputStream inputStream = file.getInputStream()) {
minioClient.putObject(
PutObjectArgs.builder()
.bucket(props.getBucketName()) // test-bucket
.object(objectName)
.stream(inputStream, file.getSize(), -1)
.contentType(file.getContentType())
.build());
return objectName;
} catch (Exception e) {
throw new RuntimeException("Upload failed", e);
}
}
/**
下载文件
@param objectName MinIO 中的文件名
@return 文件输入流
*/
public InputStream download(String objectName) {
try {
return minioClient.getObject(
GetObjectArgs.builder()
.bucket(props.getBucketName())
.object(objectName)
.build());
} catch (Exception e) {
throw new RuntimeException("Download failed", e);
}
}
/**
删除文件
@param objectName MinIO 中的文件名
*/
public void delete(String objectName) {
try {
minioClient.removeObject(
RemoveObjectArgs.builder()
.bucket(props.getBucketName())
.object(objectName)
.build());
} catch (Exception e) {
throw new RuntimeException("Delete failed", e);
}
}
/**
获取文件的访问 URL
@param objectName MinIO 中的文件名
@return 完整 URL
*/
public String getFileUrl(String objectName) {
return props.getEndpoint() + "/" + props.getBucketName() + "/" + objectName;
}
}

第十一章：FileController.java

文件路径： src/main/java/com/test/controller/FileController.java

package com.test.controller;
import com.test.service.MinioService;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.HashMap;
import java.util.Map;
/**
文件上传/下载控制器
*/
@RestController
@RequestMapping("/files")
public class FileController {
private final MinioService minioService;
public FileController(MinioService minioService) {
this.minioService = minioService;
}
/**
上传文件
请求方式：POST
接口地址：http://localhost:8080/files/upload
请求参数：file（MultipartFile）
*/
@PostMapping("/upload")
public Map<String, Object> upload(@RequestParam("file") MultipartFile file) {
String objectName = minioService.upload(file);
Map<String, Object> result = new HashMap<>();
result.put("success", true);
result.put("message", "上传成功");
result.put("fileName", objectName);
result.put("url", minioService.getFileUrl(objectName));
return result;
}
/**
下载文件
请求方式：GET
接口地址：http://localhost:8080/files/download/{fileName}
*/
@GetMapping("/download/{fileName}")
public void download(@PathVariable String fileName, HttpServletResponse response) {
response.setContentType(MediaType.APPLICATION_OCTET_STREAM_VALUE);
response.setHeader("Content-Disposition", "attachment; filename="" + fileName + """);
try (InputStream is = minioService.download(fileName);
OutputStream os = response.getOutputStream()) {
is.transferTo(os);
os.flush();
} catch (IOException e) {
response.setStatus(500);
}
}
/**
删除文件
请求方式：DELETE
接口地址：http://localhost:8080/files/delete/{fileName}
*/
@DeleteMapping("/delete/{fileName}")
public Map<String, Object> delete(@PathVariable String fileName) {
minioService.delete(fileName);
Map<String, Object> result = new HashMap<>();
result.put("success", true);
result.put("message", "删除成功");
return result;
}
}

第十二章：验证集成成功

12.1 启动 Spring Boot 项目

在 IDEA 中运行 Application.java

查看启动日志，如果没有报错，说明 MinIO 连接成功。

12.2 用 curl 测试上传

curl -X POST http://localhost:8080/files/upload \
  -F "file=@D:\你的测试图片.jpg"

成功返回示例：

{
  "success": true,
  "message": "上传成功",
  "fileName": "a1b2c3d4e5f6.jpg",
  "url": "http://localhost:9000/test-bucket/a1b2c3d4e5f6.jpg"
}

12.3 验证文件已上传

浏览器打开 http://localhost:9000

登录 → Buckets → test-bucket → 能看到刚才上传的文件

12.4 测试下载

curl -O http://localhost:8080/files/down