Go对象存储:MinIO与S3 SDK摘要: 本篇讲解Go语言集成MinIO对象存储用minio-go客户端实现bucket管理、文件上传下载、预签名URL和分片上传分享大文件单次上传超时导致上传失败的踩坑经验对比MinIO、直接文件系统和阿里云OSS三种存储方案。开篇故事我们的文件存储原先是直接写服务器磁盘用Nginx做静态文件服务。业务量小的时候没问题500GB的存储空间够用。后来用户上传的图片和文档越来越多一个月磁盘就涨到2TB单机存不下。文件分散在多台机器上备份和迁移都是手动操作出了两次磁盘故障丢了用户数据。决定上MinIO自建对象存储。MinIO兼容S3协议单机部署起步数据量大了可以组分布式集群。三个节点每节点2TB硬盘纠删码模式下数据安全有保障。Go用minio-go客户端集成API跟AWS S3 SDK几乎一样以后换云上S3迁移成本很低。上线第一周踩了个坑。用户上传2GB的视频文件超时设了60秒上传到一半连接断了。后来改成分片上传每片100MB断点续传问题解决。这篇把MinIO的Go集成写清楚。一、MinIO客户端与bucket管理minio-go是MinIO官方Go客户端兼容S3协议也能连AWS S3、阿里云OSS等兼容S3的服务。先看客户端初始化和bucket管理。packagestorageimport(contextiologtimegithub.com/minio/minio-go/v7github.com/minio/minio-go/v7/pkg/credentials)// MinIOClient MinIO客户端封装typeMinIOClientstruct{client*minio.Client// minio-go原生客户端}// NewMinIOClient 创建MinIO客户端// endpoint: MinIO地址如minio.example.com:9000// accessKey, secretKey: 访问密钥// useSSL: 是否启用HTTPSfuncNewMinIOClient(endpoint,accessKey,secretKeystring,useSSLbool)(*MinIOClient,error){// 创建客户端client,err:minio.New(endpoint,minio.Options{Creds:credentials.NewStaticV4(accessKey,secretKey,),Secure:useSSL,// 区域MinIO默认us-east-1Region:us-east-1,})iferr!nil{returnnil,err}returnMinIOClient{client:client},nil}// MakeBucket 创建bucket// bucketName: bucket名称全局唯一// location: 区域如us-east-1func(c*MinIOClient)MakeBucket(ctx context.Context,bucketName,locationstring)error{// 先检查bucket是否已存在exists,err:c.client.BucketExists(ctx,bucketName)iferr!nil{returnerr}ifexists{// bucket已存在直接返回returnnil}// 创建bucketreturnc.client.MakeBucket(ctx,bucketName,minio.MakeBucketOptions{Region:location,})}// SetBucketPolicy 设置bucket访问策略// 设为public允许匿名读适合图片等公开资源func(c*MinIOClient)SetBucketPolicy(ctx context.Context,bucketNamestring,publicReadbool)error{if!publicRead{// 私有bucket默认行为不设策略returnnil}// 设置公共读策略允许匿名GETpolicy:{ Version: 2012-10-17, Statement: [{ Effect: Allow, Principal: {AWS: [*]}, Action: [s3:GetObject], Resource: [arn:aws:s3:::bucketName/*] }] }returnc.client.SetBucketPolicy(ctx,bucketName,policy)}// ListBuckets 列出所有bucketfunc(c*MinIOClient)ListBuckets(ctx context.Context)([]minio.BucketInfo,error){returnc.client.ListBuckets(ctx)}bucket是MinIO的顶层容器类似文件夹。bucket名称全局唯一创建后不能改名。private bucket所有操作需要认证public bucket允许匿名读取适合图片这类公开资源。二、文件上传与下载文件上传分两种方式。小文件用PutObject一次性上传简单直接。大文件用分片上传支持断点续传。// UploadFile 上传文件// bucketName: 目标bucket// objectName: 对象名即存储路径如images/avatar/123.jpg// filePath: 本地文件路径// contentType: MIME类型如image/jpegfunc(c*MinIOClient)UploadFile(ctx context.Context,bucketName,objectName,filePath,contentTypestring)error{// 单次上传适合小于1GB的文件_,err:c.client.FPutObject(ctx,bucketName,objectName,filePath,minio.PutObjectOptions{ContentType:contentType,},)returnerr}// UploadStream 流式上传// 适合从网络读取数据写入存储无需落盘// reader: 数据读取器// objectName: 对象名// size: 数据大小-1表示未知大小func(c*MinIOClient)UploadStream(ctx context.Context,bucketName,objectNamestring,reader io.Reader,sizeint64,contentTypestring)error{_,err:c.client.PutObject(ctx,bucketName,objectName,reader,size,minio.PutObjectOptions{ContentType:contentType,},)returnerr}// DownloadFile 下载文件到本地// bucketName: 源bucket// objectName: 对象名// filePath: 本地保存路径func(c*MinIOClient)DownloadFile(ctx context.Context,bucketName,objectName,filePathstring)error{returnc.client.FGetObject(ctx,bucketName,objectName,filePath,minio.GetObjectOptions{},)}// DownloadStream 流式下载// 返回reader适合直接传给HTTP响应或处理管道func(c*MinIOClient)DownloadStream(ctx context.Context,bucketName,objectNamestring)(io.ReadCloser,error){// GetObject返回reader调用方负责关闭obj,err:c.client.GetObject(ctx,bucketName,objectName,minio.GetObjectOptions{},)iferr!nil{returnnil,err}returnobj,nil}流式上传和下载的好处是不需要把文件完整加载到内存。比如用户上传100MB的图片服务端用流式处理缩略图后直接流式上传峰值内存占用控制在几十MB。三、预签名URL预签名URL让客户端直接访问MinIO不需要走业务服务器中转。服务端生成带签名的URL客户端用这个URL直接上传或下载。减少服务端带宽压力。// PresignedGetURL 生成下载用预签名URL// 客户端用这个URL直接下载文件无需走服务端// bucketName: bucket名// objectName: 对象名// expiry: URL有效期func(c*MinIOClient)PresignedGetURL(ctx context.Context,bucketName,objectNamestring,expiry time.Duration)(string,error){// 生成预签名URLurl,err:c.client.PresignedGetObject(ctx,bucketName,objectName,expiry,nil,)iferr!nil{return,err}returnurl.String(),nil}// PresignedPutURL 生成上传用预签名URL// 客户端用这个URL直接上传文件到MinIO// 服务端不参与文件传输节省带宽func(c*MinIOClient)PresignedPutURL(ctx context.Context,bucketName,objectNamestring,expiry time.Duration)(string,error){url,err:c.client.PresignedPutObject(ctx,bucketName,objectName,expiry)iferr!nil{return,err}returnurl.String(),nil}典型场景是用户上传大文件。前端先请求后端生成一个上传预签名URL前端拿到URL后直接PUT文件到MinIO上传完通知后端。整个文件传输不过后端后端只做URL签发和上传完成回调。// PresignedUploadFlow 预签名上传完整流程// 1. 生成上传URL// 2. 客户端直传MinIO// 3. 客户端回调通知完成func(c*MinIOClient)PresignedUploadFlow(ctx context.Context,bucketName,objectNamestring)(string,error){// 生成1小时有效的上传URLurl,err:c.PresignedPutURL(ctx,bucketName,objectName,time.Hour)iferr!nil{return,err}log.Printf(上传URL已生成: %s, 有效期1小时,objectName)returnurl,nil}四、分片上传大文件单次上传有两个问题。第一是超时网络波动导致连接中断整个文件从头来。第二是内存占用单次上传要把文件全部读到内存或分块读取。minio-go的PutObject内部自动做分片上传。但手动控制分片大小和断点续传需要用底层API。// UploadLargeFile 大文件分片上传// bucketName: 目标bucket// objectName: 对象名// filePath: 本地文件路径// partSize: 每片大小字节func(c*MinIOClient)UploadLargeFile(ctx context.Context,bucketName,objectName,filePathstring,partSizeint64)error{// minio-go的FPutObject底层自动分片上传// 设置partSize控制每片大小默认5MB_,err:c.client.FPutObject(ctx,bucketName,objectName,filePath,minio.PutObjectOptions{// 每片大小建议10MB到100MBPartSize:partSize,// 并发上传分片数NumThreads:4,},)returnerr}// UploadLargeStream 大文件流式分片上传// 从reader读取按partSize分片上传func(c*MinIOClient)UploadLargeStream(ctx context.Context,bucketName,objectNamestring,reader io.Reader,totalSizeint64,partSizeint64)error{// PutObject对大文件自动分片// totalSize已知时分片上传未知时流式上传_,err:c.client.PutObject(ctx,bucketName,objectName,reader,totalSize,minio.PutObjectOptions{PartSize:partSize,NumThreads:4,},)returnerr}// GetMultipartUpload 查询分片上传状态// 用于断点续传查询已上传的分片func(c*MinIOClient)GetObjectInfo(ctx context.Context,bucketName,objectNamestring)(minio.ObjectInfo,error){obj,err:c.client.GetObject(ctx,bucketName,objectName,minio.GetObjectOptions{})iferr!nil{returnminio.ObjectInfo{},err}deferobj.Close()// Stat获取对象信息包括大小和ETagreturnobj.Stat()}minio-go底层封装了S3的分片上传协议。上传大文件时客户端把文件切成多个part每个part独立上传全部上传完后服务端合并。某个part失败只需重传那个part不用整个文件重来。NumThreads控制并发上传数配合带宽调整吞吐。五、踩坑经验:大文件上传超时未设分片这个坑前面提过详细讲。第一版上传代码用HTTP接口接收文件后端用PutObject写入MinIO。上传接口超时设了60秒。用户上传2GB的视频文件内网带宽100MB/s理论上传20秒。但HTTP接口层有个30秒的读超时大文件传到一半连接被切断PutObject也跟着失败。用户重试几次都失败投诉过来。排查发现两个问题。第一后端做中转上传文件先到后端再到MinIO走了两次网络。第二单次上传没有断点续传断了就从头来。解决方案分两步。第一步改预签名URL直传文件不过后端。第二步大文件强制分片上传。// ResolveLargeUpload 解决大文件上传的完整方案// 1. 文件大于100MB走预签名直传// 2. 小文件走后端分片上传每片10MBfunc(c*MinIOClient)ResolveLargeUpload(ctx context.Context,bucketName,objectName,filePathstring,fileSizeint64)(string,error){// 文件大于100MB走预签名URL直传iffileSize100*1024*1024{// 生成2小时有效的上传URLurl,err:c.PresignedPutURL(ctx,bucketName,objectName,2*time.Hour)iferr!nil{return,err}log.Printf(大文件直传: %s, 大小%dMB, URL有效期2小时,objectName,fileSize/1024/1024)returnurl,nil}// 小文件走后端上传分片10MBerr:c.UploadLargeFile(ctx,bucketName,objectName,filePath,10*1024*1024)return,err}改动上线后2GB文件上传稳定通过前端直传MinIO不过后端带宽。分片大小设50MB某个分片失败只重传那一片。预签名URL有效期设2小时足够大文件上传完成。六、对比分析特性MinIO本地文件系统阿里云OSS部署方式自建/云上服务器磁盘云服务S3兼容是否部分运维成本中高(扩容难)低(按量付费)数据安全纠删码单点风险多副本带宽成本自有带宽自有带宽按流量计费扩展性水平扩展垂直(加盘)自动适合场景中大规模自建小规模云原生本地文件系统适合小规模项目几百GB以内不频繁扩容。MinIO适合中大规模自建数据量大需要分布式和纠删码保护。阿里云OSS适合云原生项目不想运维存储基础设施按量付费。迁移方面MinIO和OSS都兼容S3协议互相切换成本低。总结MinIO用minio-go集成PutObject内部自动分片上传PartSize和NumThreads控制分片大小和并发数。预签名URL让客户端直传MinIO后端不参与文件传输节省带宽。大文件必须走分片上传和预签名直传单次上传容易超时失败。MinIO兼容S3协议以后迁到云上OSS或AWS S3代码改动很小。