minio使用简介

前言
安装与初始化
- 1. 安装 SDK
- 2. 导入并创建客户端
核心操作示例
错误处理与高级配置
最佳实践与性能调优

在云原生和微服务时代，对象存储已成为存储非结构化数据（如图片、日志、备份等）的首选方案。MinIO 是一款高性能、兼容 S3 API 的开源对象存储服务，而它的官方 Go SDK —— minio-go，则可以让你在 Go 语言项目中轻松集成对象存储功能。

前言

minio-go 是 MinIO 官方维护的 Go 语言 SDK，兼容 Amazon S3 API。它不仅支持基础的上传、下载、列举、删除等操作，还支持分片上传（Multipart Upload）、桶策略管理、服务端加密、事件通知等高级功能。无论你使用的是公有云（AWS S3、阿里云 OSS 等）还是自建 MinIO 集群，都可以用同一套 SDK 接入，极大简化了开发难度。

安装与初始化

1. 安装 SDK

在你的 Go 项目中，通过模块方式引入：

go get github.com/minio/minio-go/v7

2. 导入并创建客户端

package main

import (
    "context"
    "log"

    "github.com/minio/minio-go/v7"
    "github.com/minio/minio-go/v7/pkg/credentials"
)

func main() {
    // MinIO 服务地址，末尾不要带斜杠
    endpoint := "play.min.io:9000"
    accessKeyID := "YOUR-ACCESSKEYID"
    secretAccessKey := "YOUR-SECRETACCESSKEY"
    useSSL := true

    // 初始化 MinIO 客户端
    minioClient, err := minio.New(endpoint, &minio.Options{
        Creds:  credentials.NewStaticV4(accessKeyID, secretAccessKey, ""),
        Secure: useSSL,
    })
    if err != nil {
        log.Fatalf("初始化 MinIO Client 失败: %v", err)
    }

    // 打印客户端信息
    log.Printf("成功初始化 MinIO 客户端: %#v\n", minioClient)
}

说明：

endpoint 可写成 域名:端口 或 IP:端口。

生产环境中，accessKeyID 与 secretAccessKey 建议通过环境变量或 Secret 管理，而非硬编码。

核心操作示例

以下示例均假设已有上述初始化好的 minioClient，并使用 context.Background() 作为上下文。

创建存储桶（Bucket）

bucketName := "my-bucket"
location := "us-east-1" // 区域，可任意字符串，AWS S3 对其有特殊要求

err = minioClient.MakeBucket(context.Background(), bucketName, minio.MakeBucketOptions{
    Region:        location,
    ObjectLocking: false,
})
if err != nil {
    // 如果桶已存在，会返回 BucketAlreadyOwnedByYou 错误
    exists, errBucketExists := minioClient.BucketExists(context.Background(), bucketName)
    if errBucketExists == nil && exists {
        log.Printf("桶 %s 已存在\n", bucketName)
    } else {
        log.Fatalln(err)
    }
} else {
    log.Printf("成功创建桶 %s\n", bucketName)
}

上传文件（PutObject）

objectName := "photos/sample.jpg"
filePath := "/path/to/local/sample.jpg"
contentType := "image/jpeg"

// 调用 PutObject 上传文件
info, err := minioClient.FPutObject(
    context.Background(),
    bucketName,
    objectName,
    filePath,
    minio.PutObjectOptions{ContentType: contentType},
)
if err != nil {
    log.Fatalln(err)
}
log.Printf("成功上传 %s，大小 %d 字节\n", objectName, info.Size)

如果你想直接上传 []byte 或 io.Reader，可以使用 PutObject 方法：

reader := bytes.NewReader(data)
info, err := minioClient.PutObject(
    context.Background(),
    bucketName,
    objectName,
    reader,
    reader.Size(),
    minio.PutObjectOptions{ContentType: contentType},
)

下载文件（GetObject）

objectName := "photos/sample.jpg"
object, err := minioClient.GetObject(context.Background(), bucketName, objectName, minio.GetObjectOptions{})
if err != nil {
    log.Fatalln(err)
}
defer object.Close()

// 将数据保存到本地文件
localFile, err := os.Create("/path/to/download/sample.jpg")
if err != nil {
    log.Fatalln(err)
}
defer localFile.Close()

if _, err = io.Copy(localFile, object); err != nil {
    log.Fatalln(err)
}
log.Println("下载完成")

列举对象（ListObjects）

// 非递归列举
objectCh := minioClient.ListObjects(context.Background(), bucketName, minio.ListObjectsOptions{
    Prefix:    "photos/",
    Recursive: false,
})

for obj := range objectCh {
    if obj.Err != nil {
        log.Fatalln(obj.Err)
    }
    log.Printf("对象: %s，大小: %d\n", obj.Key, obj.Size)
}

生成预签名 URL（PresignedURL）

// URL 有效期 7 天
reqParams := make(url.Values)
presignedURL, err := minioClient.PresignedGetObject(context.Background(), bucketName, objectName, time.Hour*24*7, reqParams)
if err != nil {
    log.Fatalln(err)
}
log.Printf("预签名下载链接：%s\n", presignedURL)

错误处理与高级配置

重试策略：minio-go/v7 内置了自动重试机制，可通过传入自定义的 HTTPClient 来调整重试逻辑。
分片上传：对于大文件（>5MB），SDK 会自动走分片上传；也可手动控制 PutObjectOptions.PartSize 来优化并发和内存占用。
服务端加密：支持 SSE-S3、SSE-C、SSE-KMS，可以通过在 PutObjectOptions 中设置 ServerSideEncryption。
桶策略与 ACL：可使用 SetBucketPolicy 和 GetBucketPolicy 管理访问策略，实现公开读、只读、只写等权限控制。

最佳实践与性能调优

连接复用：尽量长时间重用同一个 minio.Client 实例，避免重复握手消耗。
并发上传：通过 PartSize 与并发协程数结合，充分利用带宽，提升大文件上传速度。
对象分层：根据业务场景，将不同类型或不同访问频率的对象分桶或分 Prefix，便于管理与清理。
监控与告警：结合 Prometheus、Grafana 等，监控对象存储请求次数、时延、错误率，从而及时定位瓶颈。