S3 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

数据集管理服务架构设计

Sun, 08 Jun 2025 10:30:00 +0800

为什么不做成单体

某科技公司的 AI 数据平台需要一个统一的数据集管理服务：往上支撑学术文档上传、解析、向量化、知识图谱构建，往下给知识库问答服务供检索能力。数据形态从 PDF、Word 到图片、结构化表格都有，存储量大，处理链路又长又耗资源。

之所以不做成单体，是因为上传、解析、检索混在一个进程里会互相影响，任何一边都没法独立扩缩容。数据集管理服务就是照着这个约束设计的，后端架构由我主导。

整体怎么拆

服务基于 Hertz（字节开源的 HTTP 框架）搭，按职责拆成几块。API 层管数据集 CRUD、文档上传、检索接口，用 Hertz 的路由分组和中间件做鉴权、日志、限流。存储层分三份：原始文件放 S3 兼容对象存储（MinIO），元数据存 GaussDB，向量和图谱实体存 MongoDB，向量一个集合，图遍历也靠它。处理层用 eino 编排解析流水线，并发交给 pond，前两篇已经讲过。检索层做向量加关键词的混合召回，支持按数据集、文档、元数据过滤。

模块间的依赖注入用 Wire，Service/DAO/Client 各归各层：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// wire.go
func NewDatasetService(
 cfg *Config,
 db *gorm.DB,
 mongo *mongo.Client,
 s3 *s3.Client,
 temporalClient client.Client,
 chain *eino.Chain,
) *DatasetService {
 // ...
}

上传直传，解析异步

上传走 S3 预签名，前端直传对象存储，不占用服务带宽：

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


func (h *DatasetHandler) PresignUpload(c context.Context, ctx *app.RequestContext) {
 var req UploadReq
 if err := ctx.BindAndValidate(&req); err != nil {
 ctx.JSON(400, errResp(err))
 return
 }
 key := fmt.Sprintf("datasets/%s/%s%s", req.DatasetID, snowflake.NextID(), extOf(req.Filename))
 url, err := h.s3.PresignPutObject(c, key, 15*time.Minute)
 if err != nil {
 ctx.JSON(500, errResp(err))
 return
 }
 ctx.JSON(200, map[string]any{"url": url, "object_key": key})
}

前端拿到预签名 URL 直传 S3，传完回调服务，服务创建文档记录、投递解析任务。

处理链路交给 Temporal 编排（和数据治理服务共用一个 Temporal 集群），每个文档一个 workflow，内部调 eino Chain 走完解析、分块、embedding、写图谱。重试、超时、状态持久化都是 Temporal 的活，服务重启任务也不丢。

检索是多路召回

检索接口对知识库问答服务只暴露一个统一的 Search：

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


type SearchService struct {
 vecStore VectorStore
 kwStore KeywordStore
 graph GraphStore
}

func (s *SearchService) Search(ctx context.Context, req *SearchReq) (*SearchResp, error) {
 // 1. 向量召回
 vecHits, err := s.vecStore.Search(ctx, req.DatasetID, req.QueryEmbedding, req.TopK)
 if err != nil {
 return nil, err
 }
 // 2. 关键词召回（BM25）
 kwHits, _ := s.kwStore.Search(ctx, req.DatasetID, req.Query, req.TopK)
 // 3. 融合排序（RRF）
 fused := rrfFuse(vecHits, kwHits)
 // 4. 图谱扩展：对 top 结果关联实体补充邻接信息
 enriched := s.graph.Expand(ctx, fused, req.DatasetID)
 return &SearchResp{Hits: enriched}, nil
}

五个关键取舍

上传和处理必须拆开。最初想在上传接口里同步解析，大文件一进来接口就超时。改成预签名直传加 Temporal 异步任务之后，接口只管元数据和任务投递，处理能力想扩就单独扩。文档状态用状态机管理（uploaded → parsing → parsed / failed），前端轮询或订阅进度。

存储选型上，GaussDB 存结构化元数据（数据集、文档、权限），MongoDB 存向量和非结构化 chunk，主要看中它的向量索引和文档模型，跟 chunk 加 metadata 的形态正合适。图谱没有引入独立图数据库，实体和关系就用 MongoDB 集合存，当前规模够用，还省掉一个中间件的运维成本；等图遍历深度真上去了，再换专门的图库不迟。

大文件和小文件分开对待。几百页的 PDF 解析起来很吃内存，我们在 Temporal workflow 里按页拆 activity，每页独立处理、独立落盘，避免整个文档一口气读进内存。小文件反过来，批量合并处理，省 workflow 调度开销。

幂等和重试要提前想好。解析任务可能因为 OOM 或节点重启被 Temporal 重试，所有写入都以文档 ID 加 chunk 序号做幂等键，重试不会产生重复向量。S3 上的中间结果（解析出的文本、表格）也缓存着，重试时已完成的阶段直接跳过。

多租户隔离贯穿全链路。数据集属于某个 AppRole 团队，所有查询强制带租户过滤条件，S3 的 key 前缀也按租户隔离，预签名 URL 带时效，防越权下载。

三条链路各走各的

整个服务拆开看就三件事：上传走对象存储直传，处理走异步工作流，检索做多路召回。Hertz 顶在 API 层，S3 承载原始文件，eino 加 pond 解决解析并发，Temporal 保证任务可靠，GaussDB 和 MongoDB 分别承接元数据和向量图谱。这套架构支撑着知识库问答服务，也给后续的知识图谱和多模态检索留了扩展空间。

封面图：motleypixel / 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