对象存储 on 姚玉亮的网络日志

S3 对象存储体系：文档与数据的高性能上传

Mon, 23 Jun 2025 10:30:00 +0800

文件一大，后端先扛不住

数据治理服务和数据集管理服务这两个项目，每天要接收大量文档：论文 PDF、Word 报告、扫描件，还有向量化后生成的二进制向量文件。早期图省事，直接让客户端把文件 POST 到后端，后端再 io.Copy 进 MinIO。文件一大就露馅：后端内存和带宽立刻吃紧，Gin 的 c.Request.Body 碰上百兆文件还会触发 OOM。

权限是另一摊麻烦。数据集属于不同 AppRole 团队，不能谁拿到 URL 就能下载。我当时的思路是把"上传通道"和"业务权限"解耦：后端只签发临时凭证，客户端直传 S3，文件落桶之后再由后端登记元数据。

让字节流绕开业务后端

核心是 S3 Presigned URL。客户端先调后端的"申请上传"接口，后端校验团队配额、文件大小、MIME 类型，然后签发一个带时效的 PUT URL。客户端拿着 URL 直传对象存储，业务后端全程不碰字节流。

超过一定阈值的文件（我们设的 32MB）走分片上传（Multipart Upload）：客户端先申请 UploadID，并发上传各个 Part，最后发一个 Complete 请求。断点续传和失败重试都在客户端做掉，后端压力一下子小了很多。

预签名和分片的代码

后端用的是 AWS SDK for Go v2，MinIO 和各家云厂商的 S3 都兼容这套 API：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


// PresignClient 封装预签名逻辑
type PresignClient struct {
 s3 *s3.Client
 presign *s3.PresignClient
 bucket string
}

func (p *PresignClient) PresignPut(ctx context.Context, key, contentType string, size int64) (string, error) {
 input := &s3.PutObjectInput{
 Bucket: aws.String(p.bucket),
 Key: aws.String(key),
 ContentType: aws.String(contentType),
 // 服务端加密，防止桶策略误配导致明文泄露
 ServerSideEncryption: types.ServerSideEncryptionAes256,
 }
 // 15 分钟有效期，够大文件传完
 resp, err := p.presign.PresignPutObject(ctx, input,
 s3.WithPresignExpires(15*time.Minute))
 if err != nil {
 return "", err
 }
 return resp.URL, nil
}

分片上传的初始化，和为每个 Part 签发预签名 URL：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// 申请分片上传
func (p *PresignClient) InitMultipart(ctx context.Context, key string) (string, error) {
 out, err := p.s3.CreateMultipartUpload(ctx, &s3.CreateMultipartUploadInput{
 Bucket: aws.String(p.bucket),
 Key: aws.String(key),
 })
 if err != nil { return "", err }
 return *out.UploadId, nil
}

// 为每个 Part 生成预签名 URL
func (p *PresignClient) PresignPart(ctx context.Context, key, uploadID string, partNum int32) (string, error) {
 out, err := p.presign.PresignUploadPart(ctx, &s3.UploadPartInput{
 Bucket: aws.String(p.bucket),
 Key: aws.String(key),
 UploadId: aws.String(uploadID),
 PartNumber: partNum,
 }, s3.WithPresignExpires(30*time.Minute))
 if err != nil { return "", err }
 return out.URL, nil
}

Hertz 路由层只做参数校验和登记：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


func (h *UploadHandler) ApplyUpload(ctx context.Context, c *app.RequestContext) {
 var req ApplyUploadReq
 if err := c.BindAndValidate(&req); err != nil { c.JSON(400, err); return }

 // 校验 AppRole 团队配额
 if err := h.quota.Check(ctx, req.TeamID, req.Size); err != nil {
 c.JSON(403, map[string]string{"msg": err.Error()}); return
 }

 key := buildKey(req.TeamID, req.FileName)
 url, err := h.presign.PresignPut(ctx, key, req.ContentType, req.Size)
 if err != nil { c.JSON(500, err); return }

 // 落一条"待确认"记录，回调后变正式
 h.meta.CreatePending(ctx, key, req.Size, req.TeamID)
 c.JSON(200, map[string]string{"url": url, "key": key})
}

CORS、分片大小和孤儿分片

第一个坑是 CORS。浏览器直传 S3 必须配 CORSRule，AllowedHeader 要放行 Content-Type 和 x-amz-*，否则预检直接挂。我们一开始只在云控制台配了个 *，结果带签名头的 PUT 照样被拦；排查了半天才发现是 ExposeHeader 没配 ETag，前端拿不到分片 ETag，Complete 发不出去。

第二个坑是分片大小。S3 要求除最后一个 Part 外每个 Part 不小于 5MB，太小直接被拒；太大则单个 Part 失败重试的成本高。我们最后固定 8MB，配 pond worker pool 把并发控制在 5，既跑满带宽，又不至于把客户端网卡打满。

第三个是孤儿分片。客户端传一半放弃了，UploadID 不会自动消失，这些 Part 会一直计费。我们用定时任务扫 ListMultipartUploads，超过 24 小时未完成的一律 AbortMultipartUpload 掉。

下载侧同理走预签名 GET URL，不过我们多加了一层：敏感数据集的 URL 只给 5 分钟有效期，URL 里还绑上下载者的用户 ID 当查询参数，签发之前后端会再校验一遍 RBAC 权限。

数据面和控制面

S3 预签名上传说白了就是把"数据面"和"控制面"分开：业务后端只管鉴权和元数据，字节流直接走对象存储。配上分片上传和定时清理，数据集管理服务里大量文档并发入库是稳的，后端的内存和带宽基本不再跟着文件大小涨。

封面图：jdnx / Flickr · CC BY 2.0

S3 预签名上传在大文件治理场景的实践

Tue, 01 Oct 2024 10:30:00 +0800

后端中转扛不住

数据治理服务接收的论文 PDF、数据集文件普遍在几十到几百 MB。早期上传走的是「客户端 → 后端 → MinIO」的中转，后端的带宽和内存压力很大：Go 的 c.FormFile 会把 multipart 内容写临时文件，并发一上来磁盘 IO 和 GC 都吃紧。更难受的是，大文件传到一半断了，只能从头再来。

结论很自然：客户端直接把文件 PUT 到对象存储，后端只负责签发上传 URL 和记录元信息。S3 兼容协议（我们用 MinIO）的预签名 URL 正好干这件事。

客户端直传，后端只签名

后端提供一个 POST /files/presign 接口，入参是文件名、大小、MIME、内容 SHA256。后端做四件事：

生成全局 file_id 和 object key（raw/{tenant}/{yyyy}/{mm}/{file_id}.ext）；
调 S3 SDK 生成一个 15 分钟有效的 PUT 预签名 URL，绑定 Content-Type；
在 file_objects 表插一条 status=uploading 的记录；
把 URL 和 file_id 返回给客户端。

客户端拿着这个 URL 直接 PUT 文件到 MinIO，传完回调 POST /files/{id}/complete。后端校验对象是否真实存在、大小是否匹配，状态置为 uploaded，然后投递解析任务。

超过 100MB 的文件走分片上传（CreateMultipartUpload → 各分片预签名 → CompleteMultipartUpload），支持断点续传。

Presign 与 Complete

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


import (
 "context"
 "time"
 "github.com/aws/aws-sdk-go-v2/aws"
 "github.com/aws/aws-sdk-go-v2/service/s3"
)

type PresignReq struct {
 FileName string `json:"file_name"`
 Size int64 `json:"size"`
 MIMEType string `json:"mime_type"`
 Sha256 string `json:"sha256"`
}

func (h *FileHandler) Presign(c *gin.Context) {
 var req PresignReq
 c.ShouldBindJSON(&req)

 fileID, _ := h.sf.NextID()
 key := buildKey(c.GetInt64("tenant_id"), fileID, req.FileName)

 input := &s3.PutObjectInput{
 Bucket: aws.String(h.bucket),
 Key: aws.String(key),
 ContentType: aws.String(req.MIMEType),
 Metadata: map[string]string{
 "sha256": req.Sha256,
 "file-id": strconv.FormatInt(fileID, 10),
 },
 }

 presignClient := s3.NewPresignClient(h.s3Client,
 func(o *s3.PresignOptions) { o.Expires = 15 * time.Minute })

 resp, err := presignClient.PresignPutObject(c.Request.Context(), input)
 if err != nil {
 c.JSON(500, gin.H{"msg": "presign failed"})
 return
 }

 h.db.Create(&FileObject{
 ID: fileID, TenantID: c.GetInt64("tenant_id"),
 FileKey: key, FileName: req.FileName,
 Size: req.Size, MIMEType: req.MIMEType,
 Hash: req.Sha256, Status: "uploading",
 })

 c.JSON(200, gin.H{
 "file_id": fileID,
 "upload_url": resp.URL,
 "method": resp.Method,
 "headers": resp.SignedHeader,
 })
}

Complete 时用 HeadObject 校验：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


func (h *FileHandler) Complete(c *gin.Context) {
 id, _ := strconv.ParseInt(c.Param("id"), 10, 64)
 var obj FileObject
 h.db.First(&obj, id)

 out, err := h.s3Client.HeadObject(c.Request.Context(), &s3.HeadObjectInput{
 Bucket: aws.String(h.bucket),
 Key: aws.String(obj.FileKey),
 })
 if err != nil || *out.ContentLength != obj.Size {
 h.db.Model(&obj).Update("status", "failed")
 c.JSON(400, gin.H{"msg": "upload verify failed"})
 return
 }
 h.db.Model(&obj).Update("status", "uploaded")
 h.publishParseTask(obj.ID)
 c.JSON(200, gin.H{"msg": "ok"})
}

五个坑

第一个最常见：预签名 URL 绑定了 HTTP 方法和 headers，客户端必须原样使用。前端爱犯的错是 PUT 时手动加了个 Content-Type，值却和签名时不一致，S3 直接甩回来一个 SignatureDoesNotMatch。要么严格对齐，要么签名时不指定 ContentType 让客户端自定，但后者有类型被篡改的风险。

第二个是权限。预签名 URL 本身不鉴权，拿到的人都能传。我们把有效期压到 15 分钟，object key 用不可猜的 Snowflake ID，防枚举。

第三个是大文件。单片 PUT 虽然简单，500MB 的文件断一次就得重传，体验很差。分片上传每片 16MB，并发传，单片失败只需重传那一片。

第四个：HeadObject 校验不能省。客户端可能拿到 URL 后根本不传，或者传一半就调 complete，必须从 S3 侧确认对象真实存在且大小匹配。

第五个是 MinIO 版本。它的预签名 v4 和 AWS S3 行为基本一致，但部分老版本对带 Metadata 的签名有兼容问题，升级到最新稳定版就好。

后来

预签名上传把后端从数据通路里摘了出去，只做签名和校验，带宽压力降得非常明显，客户端还能直接用上对象存储的分片和断点续传。配上 file_objects 表的状态机，上传、校验、解析三步衔接得很清楚。大文件场景，我觉得这个模式值得用。

封面图：Aaron Volkening / Flickr · CC BY 2.0