企业官网建设流程全解析

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("context""io""log""time""github.com/minio/minio-go/v7""github.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}return&MinIOClient{client:client},nil}// MakeBucket 创建bucket// bucketName: bucket名称，全局唯一// location: 区域，如"us-east-1"func(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/jpeg"func(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直传iffileSize>100*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小时，足够大文件上传完成。

六、对比分析

本地文件系统适合小规模项目，几百GB以内，不频繁扩容。MinIO适合中大规模自建，数据量大需要分布式和纠删码保护。阿里云OSS适合云原生项目，不想运维存储基础设施，按量付费。迁移方面MinIO和OSS都兼容S3协议，互相切换成本低。

总结

MinIO用minio-go集成，PutObject内部自动分片上传，PartSize和NumThreads控制分片大小和并发数。预签名URL让客户端直传MinIO，后端不参与文件传输，节省带宽。大文件必须走分片上传和预签名直传，单次上传容易超时失败。MinIO兼容S3协议，以后迁到云上OSS或AWS S3代码改动很小。