L05_后端_MinIO 安装使用入门指南（实战版）

MinIO 安装使用入门指南（实战版）

MinIO 是基于 Go 开发的高性能对象存储，兼容 S3 协议，适合存储图片、视频、备份数据等非结构化文件（支持 1KB-5TB 大小），国内阿里、腾讯、华为等企业均有使用。本文以「实战」为核心，带你快速完成 MinIO 安装、配置及 Spring Boot 集成。

1、MinIO Server 安装（4种常用方式）

MinIO 仅需一个运行程序，部署极简单，推荐优先选择 Docker 方式（跨系统且无需配置环境）。

1.1 Docker 安装（推荐）

适用于 Windows/Linux/MacOS，需先安装 Docker。

1. 执行启动命令（直接复制运行）：

   # Windows 系统
   docker run -p 9000:9000 -p 9001:9001 -e "MINIO_ACCESS_KEY=admin" -e "MINIO_SECRET_KEY=password" minio/minio server /data --console-address ":9001"
   
   # Linux/MacOS 系统（指定本地存储目录，示例为 /Users/yourDir/minio，需替换为自己的目录）
   docker run -p 9000:9000 -p 9001:9001 -e "MINIO_ACCESS_KEY=admin" -e "MINIO_SECRET_KEY=password" minio/minio server /Users/yourDir/minio --console-address ":9001"

   • 9000 端口：API 访问端口（程序调用用）
   • 9001 端口：Web UI 管理端口（可视化操作）
   • 账号密码：admin/password（实际生产需修改）

1.2 本地安装（Windows/Linux/MacOS）

Windows（PowerShell 中执行）

# 1. 下载 MinIO 程序（国外资源较慢，可手动从官网下载）
Invoke-WebRequest -Uri "https://dl.min.io/server/minio/release/windows-amd64/minio.exe" -OutFile "C:\minio.exe"

# 2. 设置账号密码环境变量
setx MINIO_ROOT_USER admin
setx MINIO_ROOT_PASSWORD password

# 3. 启动服务（F:\Data 为存储目录，可替换）
C:\minio.exe server F:\Data --console-address ":9001"

Linux

# 1. 下载并授权
wget https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio

# 2. 启动服务（/Users/yourDir/minio 为存储目录，可替换）
MINIO_ROOT_USER=admin MINIO_ROOT_PASSWORD=password ./minio server /Users/yourDir/minio --console-address ":9001"

MacOS

# 1. 下载并授权
wget https://dl.min.io/server/minio/release/darwin-amd64/minio
chmod +x minio

# 2. 启动服务（F:\Data 为存储目录，可替换）
MINIO_ROOT_USER=admin MINIO_ROOT_PASSWORD=password ./minio server F:\Data --console-address ":9001"

2、MinIO Web UI 基础操作

启动服务后，通过浏览器访问 http://127.0.0.1:9001 ，输入账号 admin、密码 password 登录。

2.1 新建存储桶（Bucket）

存储桶是文件的「容器」，需先创建才能上传文件：

1. 点击首页 Create Bucket 按钮；
2. 输入存储桶名称（如 ly_test），点击 Create。

2.2 设置公开访问（readonly 规则）

默认文件需授权才能访问，实际场景常需「直接通过 URL 访问」，需添加规则：

1. 点击存储桶右上角的 Configure Bucket （设置图标）→ 选择 Access Rules；
2. 点击 Add Access Rule ，设置 Prefix 为 /、Access 为 readonly，点击 Save。

2.3 上传/访问文件

1. 上传：点击存储桶内的 Upload → Upload File，选择本地文件上传；
2. 访问：文件访问 URL 格式为 http://127.0.0.1:9000/{存储桶名}/{文件名}（注意用 9000 端口）。
   示例：若存储桶为 ly_test，文件名为 test.jpg，则 URL 为 http://127.0.0.1:9000/ly_test/test.jpg。

3、Spring Boot 集成 MinIO（实战）

3.1 引入依赖（pom.xml）

<project>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.6.4</version>
    </parent>

    <dependencies>
        <!-- MinIO 客户端依赖（8.2.2 版本稳定，高版本可能有依赖冲突） -->
        <dependency>
            <groupId>io.minio</groupId>
            <artifactId>minio</artifactId>
            <version>8.2.2</version>
        </dependency>
    </dependencies>
</project>

3.2 配置 MinIO 客户端（MinIOConfiguration）

创建配置类，初始化 MinioClient 实例（供程序调用）：

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

@Configuration
public class MinIOConfiguration {

    @Bean
    public MinioClient minioClient() {
        // 实际项目中，建议将配置写在 application.yml 中
        String endpoint = "http://127.0.0.1:9000"; // MinIO API 地址
        String accessKey = "admin"; // 账号
        String secretKey = "password"; // 密码

        // 初始化客户端
        return MinioClient.builder()
                .endpoint(endpoint)
                .credentials(accessKey, secretKey)
                .build();
    }
}

3.3 实现文件接口（FileController）

提供「上传（POST）」和「删除（DELETE）」接口：

import io.minio.MinioClient;
import io.minio.RemoveObjectArgs;
import io.minio.PutObjectArgs;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import javax.annotation.Resource;
import java.util.UUID;

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

    @Resource
    private MinioClient minioClient;

    // 配置（实际项目建议放 application.yml）
    private String endpoint = "http://127.0.0.1:9000";
    private String bucket = "ly_test"; // 存储桶名（需与 UI 中创建的一致）

    /**
     * 文件上传接口
     * @param file 上传的文件
     * @return 文件访问 URL
     */
    @PostMapping("/upload")
    public String upload(@RequestParam("file") MultipartFile file) throws Exception {
        // 生成随机文件名（避免重复，用 UUID）
        String fileName = UUID.randomUUID().toString();

        // 上传文件到 MinIO
        minioClient.putObject(PutObjectArgs.builder()
                .bucket(bucket) // 存储桶
                .object(fileName) // 文件名
                .stream(file.getInputStream(), file.getSize(), -1) // 文件流
                .contentType(file.getContentType()) // 文件类型（如 image/jpeg）
                .build());

        // 返回文件访问 URL
        return String.format("%s/%s/%s", endpoint, bucket, fileName);
    }

    /**
     * 文件删除接口
     * @param path 文件名（即 upload 接口返回的 URL 中最后一段）
     */
    @DeleteMapping("/delete")
    public void delete(@RequestParam("path") String path) throws Exception {
        minioClient.removeObject(RemoveObjectArgs.builder()
                .bucket(bucket)
                .object(path) // 要删除的文件名
                .build());
    }
}

3.4 启动类（MinIOApplication）

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MinIOApplication {
    public static void main(String[] args) {
        SpringApplication.run(MinIOApplication.class, args);
    }
}

3.5 测试接口（用 Postman）

1. 启动服务 ：运行 MinIOApplication；
2. 上传测试 ：
   • 方法：POST，URL：http://localhost:8080/file/upload；
   • 参数：file（选择本地图片）；
   • 响应：返回文件访问 URL，可直接在浏览器打开。
3. 删除测试 ：
   • 方法：DELETE，URL：http://localhost:8080/file/delete；
   • 参数：path（上传接口返回的 URL 中最后一段，如 UUID 字符串）；
   • 效果：MinIO 中对应文件被删除。

4、补充：MinIO Client 命令行工具（可选）

MinIO 提供命令行工具 mc，用法类似 Linux 命令（如 ls/cp/rm），适合批量操作：

• 安装：参考 MinIO Client 下载；
• 常用命令：
  • mc ls：列出存储桶；
  • mc cp 本地文件 存储桶名/文件名：上传文件；
  • mc rm 存储桶名/文件名：删除文件。

总结

MinIO 核心优势是「轻量、高性能、兼容 S3」，适合自建文件存储服务。本文通过「安装 → UI 操作 → Spring Boot 集成」的流程，实现了基础的文件管理功能，可直接用于开发测试或小型项目。实际生产中，需注意：

1. 修改默认账号密码；
2. 配置存储目录备份；
3. 高可用场景需部署 MinIO 集群。