MinIO

一、MinIO 核心概念（先理解）

二、Windows 环境安装 & 启动

步骤 1：下载 MinIO 安装包

1. 官网下载：https://min.io/download#/windows选择「Windows 64-bit」版本，下载后是minio.exe可执行文件（建议放到单独目录，如D:\minio）。
2. 备用下载（国内）：https://dl.min.io/server/minio/release/windows-amd64/minio.exe

步骤 2：启动 MinIO 服务（单机版）

1. 打开 CMD 命令行（管理员身份），进入minio.exe所在目录：

   cmd

   cd D:\minio

2. 启动命令（指定数据存储目录，如D:\minio\data）：

   cmd

   minio server D:\minio\data --console-address ":9001"

   • D:\minio\data：MinIO 存储文件的目录（自动创建）；
   • --console-address ":9001"：Web 控制台端口（默认 9000 是 API 端口，避免冲突）。

步骤 3：访问 MinIO 控制台

1. 启动成功后，控制台输出如下（默认密钥：minioadmin/minioadmin）：

   plaintext

   WARNING: Detected default credentials 'minioadmin:minioadmin', please change the credentials immediately. API: http://192.168.1.100:9000 http://127.0.0.1:9000 Console: http://192.168.1.100:9001 http://127.0.0.1:9001

2. 浏览器访问http://127.0.0.1:9001，输入默认账号密码minioadmin/minioadmin，进入控制台。

步骤 4：修改默认密钥（必做，企业级）

1. 启动前设置环境变量（替代默认密钥）：

   cmd

   # 设置 Access Key set MINIO_ROOT_USER=myadmin # 设置 Secret Key set MINIO_ROOT_PASSWORD=myadmin123456 # 再启动服务 minio server D:\minio\data --console-address ":9001"

2. 或创建start.bat批处理文件（一键启动）：

   bat

   @echo off set MINIO_ROOT_USER=myadmin set MINIO_ROOT_PASSWORD=myadmin123456 minio server D:\minio\data --console-address ":9001" pause

三、Linux 环境安装 & 启动（CentOS/Ubuntu 通用）

步骤 1：下载 MinIO 安装包

1. 执行下载命令（64 位系统）：

   bash

   运行

   # 下载 minio 二进制文件到 /usr/local/bin wget https://dl.min.io/server/minio/release/linux-amd64/minio -O /usr/local/bin/minio # 赋予执行权限 chmod +x /usr/local/bin/minio

步骤 2：创建数据目录 & 配置环境变量

bash

运行

# 创建数据存储目录 mkdir -p /data/minio # 设置永久环境变量（修改密钥） echo "export MINIO_ROOT_USER=myadmin" >> /etc/profile echo "export MINIO_ROOT_PASSWORD=myadmin123456" >> /etc/profile # 生效环境变量 source /etc/profile

步骤 3：启动 MinIO 服务

方式 1：前台启动（测试用）

bash

运行

minio server /data/minio --console-address ":9001"

方式 2：后台启动（企业生产用，推荐）

bash

运行

# 创建日志目录 mkdir -p /var/log/minio # 后台启动（nohup 避免终端关闭停止） nohup minio server /data/minio --console-address ":9001" > /var/log/minio/minio.log 2>&1 &

步骤 4：访问控制台 & 防火墙配置

1. 浏览器访问http://Linux服务器IP:9001，输入密钥myadmin/myadmin123456；
2. 开放端口（防火墙）：

   bash

   运行

   # 开放 9000（API）和 9001（控制台）端口 firewall-cmd --add-port=9000/tcp --permanent firewall-cmd --add-port=9001/tcp --permanent # 重启防火墙 firewall-cmd --reload

四、MinIO 核心用法（控制台 + Java API）

场景 1：Web 控制台基础操作（可视化）

1. 创建 Bucket：
   • 控制台左侧「Buckets」→「Create Bucket」；
   • 输入 Bucket 名称（如test-bucket），关闭「Versioning」（测试用），点击创建。
2. 上传文件：
   • 进入 Bucket →「Upload」→ 选择本地文件（如test.txt）上传。
3. 下载 / 删除文件：
   • 选中文件，点击「Download」下载，「Delete」删除。
4. 设置 Bucket 权限：
   • 「Access Policy」→ 选择「Public」（公开访问，测试用；生产环境需严格控制）。

场景 2：Java 客户端 API 实战（企业核心）

步骤 1：引入 Maven 依赖

xml

<!-- MinIO Java 客户端 --> <dependency> <groupId>io.minio</groupId> <artifactId>minio</artifactId> <version>8.5.7</version> </dependency> <!-- 简化文件操作 --> <dependency> <groupId>commons-io</groupId> <artifactId>commons-io</artifactId> <version>2.15.1</version> </dependency>

步骤 2：核心工具类（封装常用操作）

java

运行

import io.minio.*; import io.minio.errors.MinioException; import io.minio.http.Method; import org.apache.commons.io.IOUtils; import java.io.File; import java.io.FileInputStream; import java.io.FileOutputStream; import java.io.InputStream; import java.util.concurrent.TimeUnit; /** * MinIO 企业级工具类（封装上传/下载/删除/预览等核心操作） */ public class MinioUtils { // MinIO 配置（企业建议放配置文件） private static final String ENDPOINT = "http://127.0.0.1:9000"; // Windows/Linux 替换为对应IP private static final String ACCESS_KEY = "myadmin"; private static final String SECRET_KEY = "myadmin123456"; // 创建 MinIO 客户端 private static MinioClient getMinioClient() { return MinioClient.builder() .endpoint(ENDPOINT) .credentials(ACCESS_KEY, SECRET_KEY) .build(); } /** * 1. 创建 Bucket（存储桶） */ public static void createBucket(String bucketName) throws Exception { MinioClient client = getMinioClient(); // 检查 Bucket 是否存在 if (!client.bucketExists(BucketExistsArgs.builder().bucket(bucketName).build())) { client.makeBucket(MakeBucketArgs.builder().bucket(bucketName).build()); System.out.println("Bucket " + bucketName + " 创建成功"); } else { System.out.println("Bucket " + bucketName + " 已存在"); } } /** * 2. 上传文件（本地文件 → MinIO） * @param bucketName 存储桶名 * @param objectName MinIO 中的文件名（如 "test/1.txt"） * @param filePath 本地文件路径 */ public static void uploadFile(String bucketName, String objectName, String filePath) throws Exception { MinioClient client = getMinioClient(); // 上传文件 client.uploadObject( UploadObjectArgs.builder() .bucket(bucketName) .object(objectName) .filename(filePath) .build() ); System.out.println("文件 " + filePath + " 上传成功，对象名：" + objectName); } /** * 3. 下载文件（MinIO → 本地） * @param bucketName 存储桶名 * @param objectName MinIO 中的文件名 * @param savePath 本地保存路径 */ public static void downloadFile(String bucketName, String objectName, String savePath) throws Exception { MinioClient client = getMinioClient(); // 下载文件 client.downloadObject( DownloadObjectArgs.builder() .bucket(bucketName) .object(objectName) .filename(savePath) .build() ); System.out.println("文件 " + objectName + " 下载成功，保存到：" + savePath); } /** * 4. 删除文件 */ public static void deleteFile(String bucketName, String objectName) throws Exception { MinioClient client = getMinioClient(); client.removeObject( RemoveObjectArgs.builder() .bucket(bucketName) .object(objectName) .build() ); System.out.println("文件 " + objectName + " 删除成功"); } /** * 5. 获取文件预览链接（带过期时间，企业常用） * @param expireSeconds 过期时间（秒） */ public static String getPresignedUrl(String bucketName, String objectName, int expireSeconds) throws Exception { MinioClient client = getMinioClient(); // 生成预览链接（GET 方法，可直接在浏览器访问） String url = client.getPresignedObjectUrl( GetPresignedObjectUrlArgs.builder() .method(Method.GET) .bucket(bucketName) .object(objectName) .expiry(expireSeconds, TimeUnit.SECONDS) .build() ); System.out.println("文件预览链接：" + url); return url; } /** * 6. 上传流（如接口接收的文件流） */ public static void uploadStream(String bucketName, String objectName, InputStream inputStream, long fileSize) throws Exception { MinioClient client = getMinioClient(); client.putObject( PutObjectArgs.builder() .bucket(bucketName) .object(objectName) .stream(inputStream, fileSize, -1) // -1 表示自动检测大小 .build() ); System.out.println("流文件 " + objectName + " 上传成功"); } // 测试主方法 public static void main(String[] args) throws Exception { String bucketName = "test-bucket"; // 1. 创建 Bucket createBucket(bucketName); // 2. 上传本地文件 String localFilePath = "D:\\test.txt"; // Windows 路径 // String localFilePath = "/root/test.txt"; // Linux 路径 uploadFile(bucketName, "test/1.txt", localFilePath); // 3. 生成预览链接（1小时过期） getPresignedUrl(bucketName, "test/1.txt", 3600); // 4. 下载文件 String savePath = "D:\\test_download.txt"; downloadFile(bucketName, "test/1.txt", savePath); // 5. 删除文件 // deleteFile(bucketName, "test/1.txt"); } }

场景 3：Spring Boot 集成（企业实战）

步骤 1：配置文件（application.yml）

yaml

spring: # MinIO 配置 minio: endpoint: http://127.0.0.1:9000 access-key: myadmin secret-key: myadmin123456 default-bucket: test-bucket # 默认存储桶

步骤 2：配置类（注入 MinioClient）

java

运行

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

步骤 3：Controller 实现文件上传接口

java

运行

import io.minio.MinioClient; import org.apache.commons.io.IOUtils; import org.springframework.beans.factory.annotation.Value; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import org.springframework.web.multipart.MultipartFile; import javax.annotation.Resource; import java.util.UUID; /** * 企业级文件上传接口 */ @RestController public class MinioController { @Resource private MinioClient minioClient; @Value("${spring.minio.default-bucket}") private String defaultBucket; @PostMapping("/upload") public String uploadFile(@RequestParam("file") MultipartFile file) throws Exception { // 1. 校验文件 if (file.isEmpty()) { return "文件不能为空"; } // 2. 生成唯一文件名（避免重复） String originalFilename = file.getOriginalFilename(); String suffix = originalFilename.substring(originalFilename.lastIndexOf(".")); String objectName = "upload/" + UUID.randomUUID() + suffix; // 3. 上传文件流 minioClient.putObject( PutObjectArgs.builder() .bucket(defaultBucket) .object(objectName) .stream(file.getInputStream(), file.getSize(), -1) .contentType(file.getContentType()) .build() ); // 4. 生成预览链接 String previewUrl = minioClient.getPresignedObjectUrl( GetPresignedObjectUrlArgs.builder() .method(Method.GET) .bucket(defaultBucket) .object(objectName) .expiry(3600, TimeUnit.SECONDS) .build() ); return "上传成功，预览链接：" + previewUrl; } }

五、企业级进阶用法

1. 分布式部署（Linux 集群）

生产环境需部署分布式 MinIO（多节点高可用），核心命令：

bash

运行

# 4节点分布式部署（每节点1个数据目录） minio server http://node1/data/minio http://node2/data/minio http://node3/data/minio http://node4/data/minio --console-address ":9001"

2. 文件权限控制

• 私有 Bucket：默认权限，仅授权用户可访问；
• 公共 Bucket：设置策略允许匿名访问：

  java

  运行

  // 设置 Bucket 公共读权限 client.setBucketPolicy( SetBucketPolicyArgs.builder() .bucket(bucketName) .config("{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":\"*\",\"Action\":\"s3:GetObject\",\"Resource\":\"arn:aws:s3:::" + bucketName + "/*\"}]}") .build() );

3. 大文件分片上传

MinIO 支持分片上传（适合 GB 级文件），核心 API：

java

运行

// 初始化分片上传 String uploadId = client.initiateMultipartUpload( InitiateMultipartUploadArgs.builder() .bucket(bucketName) .object(objectName) .build() ).uploadId(); // 上传分片（第1片，索引从1开始） client.uploadPart( UploadPartArgs.builder() .bucket(bucketName) .object(objectName) .uploadId(uploadId) .partNumber(1) .stream(inputStream, partSize, -1) .build() ); // 完成分片上传 client.completeMultipartUpload( CompleteMultipartUploadArgs.builder() .bucket(bucketName) .object(objectName) .uploadId(uploadId) .parts(parts) // 分片列表 .build() );

六、常见问题 & 避坑要点

1. 连接超时：
   • 检查 MinIO 服务是否启动；
   • 防火墙 / 安全组开放 9000/9001 端口；
   • 确保 Endpoint 是「http://IP:9000」（不是控制台端口 9001）。
2. 权限不足：
   • Linux 下 MinIO 进程需有数据目录的读写权限（chmod 777 /data/minio）；
   • 密钥错误会报「Access Denied」，核对MINIO_ROOT_USER/MINIO_ROOT_PASSWORD。
3. 文件上传后无法预览：
   • 未设置 ContentType（如图片需设置image/jpeg）；
   • Bucket 权限为私有，需生成预签名链接访问。
4. Windows 启动闪退：
   • 检查数据目录是否存在（MinIO 不会自动创建多级目录）；
   • 用 CMD 启动，不要双击minio.exe（闪退无法看错误日志）。

总结

1. 安装：Windows 直接下载 exe 启动，Linux 下载二进制文件 + 后台启动；
2. 核心操作：创建 Bucket、上传 / 下载 / 删除文件、生成预签名链接（企业最常用）；
3. 企业实战：Spring Boot 集成 MinioClient，封装工具类，实现接口上传；
4. 进阶：分布式部署、分片上传、权限控制，满足高可用 / 大文件场景。