MinIO

1. MinIO 是什么？适合解决什么问题？

MinIO 是一个兼容 Amazon S3 协议 的对象存储服务（Object Storage）。

它解决的问题：

存文件：图片、视频、PDF、Word、日志文件、模型文件等
存大文件：不适合放到数据库 BLOB 的文件
支持海量对象：以对象（Object）的形式存储，而不是传统文件系统的目录树

典型业务模式：

文件上传到 MinIO → 数据库只存元数据（文件名、大小、objectKey、业务关联 ID 等）
下载/预览时：
- 要么后端代理下载（安全但更耗带宽）
- 要么生成 预签名 URL（Presigned URL）让前端直连（高性能，需控制有效期）

2. 核心概念

2.1 Bucket（桶）

类似"顶层容器"，可以理解成一个"大文件夹/命名空间"。
bucket 通常按业务/权限划分：
- 私有桶：需要鉴权
- 公共桶：允许匿名读（通常只放公开资源）

2.2 Object（对象）与 objectKey

Object 是存储的"文件实体"，由：
- bucket
- objectKey（对象 key / 对象名）
  共同唯一定位。

建议：生产环境避免直接使用原始文件名作为 objectKey 的核心部分，可用 UUID、防止重名与路径穿越。

2.3 元数据（Metadata）

MinIO（S3）对象可以带 metadata（键值对），但多数项目会把业务元数据放在数据库。

3. 项目中的 MinIO 集成方式（Spring Boot）

3.1 MinIO 客户端 Bean

java 复制代码

@Bean
public MinioClient minioClient() {
    return MinioClient.builder()
            .endpoint(minioProperties.getEndpoint())
            .credentials(minioProperties.getAccessKey(), minioProperties.getSecretKey())
            .build();
}

3.2 配置属性映射

MinioProperties 使用：

java 复制代码

@ConfigurationProperties(prefix = "shouyida.minio")
public class MinioProperties {
    private String endpoint;
    private String accessKey;
    private String secretKey;
    private String bucket;
    private String publicBucket;
}

你可以在 application.yml 里类似这样配置（示例）：

yaml 复制代码

demo:
  minio:
    endpoint: http://127.0.0.1:9000
    accessKey: minioadmin
    secretKey: minioadmin
    bucket: demo-private
    publicBucket: demo-public

4. 常用操作清单（上传/下载/删除/预签名）

4.1 创建 Bucket（如果不存在）

java 复制代码

boolean exists = minioClient.bucketExists(
    BucketExistsArgs.builder().bucket(bucket).build()
);
if (!exists) {
    minioClient.makeBucket(MakeBucketArgs.builder().bucket(bucket).build());
}

4.2 上传对象（PutObject）

两种常见方式：

直接传 InputStream（更通用）
或基于 MultipartFile 的 stream

java 复制代码

minioClient.putObject(
    PutObjectArgs.builder()
        .bucket(bucket)
        .object(objectKey)
        .stream(file.getInputStream(), file.getSize(), -1)
        .contentType(file.getContentType())
        .build()
);

注意：流式上传要关注 size 与 partSize（大文件分片）。

5.3 下载对象（GetObject）

java 复制代码

try (InputStream in = minioClient.getObject(
        GetObjectArgs.builder().bucket(bucket).object(objectKey).build())) {
    // 读取 inputStream
}

5.4 删除对象（RemoveObject）

java 复制代码

minioClient.removeObject(
    RemoveObjectArgs.builder().bucket(bucket).object(objectKey).build()
);

5.5 生成预签名 URL（让前端直连）

java 复制代码

String url = minioClient.getPresignedObjectUrl(
    GetPresignedObjectUrlArgs.builder()
        .method(Method.GET)
        .bucket(bucket)
        .object(objectKey)
        .expiry(60 * 10) // 10 分钟
        .build()
);

用途：

前端直接 GET 该 URL 下载/预览
URL 过期自动失效

6. 常见坑与最佳实践（非常推荐看）

6.1 objectKey 命名与安全

不要相信 originalFilename（可能包含 ../ 等）
建议：
- 服务端生成文件名（UUID/雪花 ID）
- 保留后缀用于识别类型（或存到 DB）

6.2 bucket 权限与公开访问

公共桶（publicBucket）适合放公开图片/静态资源
私有桶下载建议：
- 后端鉴权后返回预签名 URL
- 或后端代理流式下载

6.3 大文件与内存

避免把文件一次性读到内存（比如 getBytes()）
使用 InputStream/transferTo 等流式处理

6.4 "MinIO + 数据库"一致性问题

常见场景：

MinIO 上传成功，但数据库插入失败 → MinIO 残留"孤儿文件"
数据库插入成功，但 MinIO 上传失败 → DB 有记录但文件不存在

常用解决思路：

顺序策略：先上传 MinIO，再写 DB
失败补偿：DB 写入失败时删除刚上传的对象
异步清理：定时任务清理孤儿对象（或孤儿记录）
事件驱动：上传成功发消息，后续处理失败可重试

注意：@Transactional 只能保证数据库事务，不能自动回滚 MinIO。

6.5 反向代理与 endpoint

如果你用 Nginx 代理 MinIO，确保：
- endpoint 是对外可访问地址
- 上传大文件时代理层允许较大 body（如 client_max_body_size）

7. 一句话总结

MinIO 是 S3 兼容的对象存储：用 bucket + objectKey 管理文件。
在 Spring Boot 中通常用 MinioClient + 配置属性注入。
项目最佳实践是：MinIO 存文件本体、数据库存元数据，并考虑失败补偿与权限控制。