MinIO Fan-Out Uploads：基于 S3 POST 扩展的并发扇出上传技术解析

MinIO 在标准 S3 PostObject 接口之上实现了一个扩展能力——Fan-Out Uploads（扇出上传）：客户端在一次 POST 请求中提交一份源数据流和一个扇出列表（fan-out list），MinIO 服务端会并发地从同一份源流中完成多次独立的 PutObject，把同一份内容“复制”到多个目标对象名（Key）之下。本文以 Fan-Out 扩展文档 为主线，结合 cmd/bucket-handlers.go 与 cmd/post-policy-fan-out.go 的服务端源码，完整讲解该特性的适用场景、请求格式、权限模型、加密与版本化行为、并发上限和响应/事件机制。

一、Fan-Out Uploads 解决什么问题

Fan-Out 是 MinIO 对 S3 的一个扩展（extension），用于执行多个并发的扇出上传操作。官方文档给出的典型使用场景是：

• TSB（Time Shift Buffer，时移缓冲）分发：TSB 是广播电视行业中实现电视信号与媒体内容“时移回放”（time-shifted playback）的手段。在直播/录制链路中，同一个 TSB 数据流往往需要同时落到多个存储位置（例如不同频道、不同时移实例、不同保留策略的对象），Fan-Out 让一次网络传输完成多个对象写入，避免客户端对同一数据流重复发送。

与普通 PostObject 的差异在于：

1. 请求中除 file 字段外，额外携带一个名为 x-minio-fanout-list 的 form-field，其内容是 JSON 数组，数组中每一项描述一个扇出目标对象；
2. 每一项可以携带自定义元数据（metadata）、标签（tags）以及文档所述的其他保留（retention）相关设置，即不同目标对象可以拥有各自的属性；
3. 上传完成后，所有生成的对象都可以通过标准 S3 GetObject API 独立读取，它们与普通对象没有任何区别。

从 Fan-Out 文档 的定义看，该特性“只要 PostUpload API 请求中提供了 x-minio-fanout-list form-field 就会自动启用”，服务端没有额外的开关或配置项需要打开。

二、服务端入口：PostPolicyBucketHandler 如何解析扇出列表

Fan-Out 的入口是 MinIO 的 POST 对象处理器 PostPolicyBucketHandler，定义在 cmd/bucket-handlers.go 中，该函数同时承担标准 PostObject 与 Fan-Out 两种模式：

1. SSE-KMS 直接拒绝：函数开头检查 crypto.S3KMS.IsRequested(r.Header)，SSE-KMS 加密的 POST 请求返回 NotImplemented（cmd/bucket-handlers.go）。
2. 逐 part 解析 multipart 表单：处理器以 maxParts = 1000 为上限逐个读取 form part，对非 file 的普通字段做大小管控；当字段名规范化后等于 x-minio-fanout-list 时进入扇出分支（cmd/bucket-handlers.go）：

if http.CanonicalHeaderKey(name) == http.CanonicalHeaderKey("x-minio-fanout-list") {
    dec := json.NewDecoder(part)
    // while the array contains values
    for dec.More() {
        var m minio.PutObjectFanOutEntry
        if err := dec.Decode(&m); err != nil {
            // ... 返回 ErrMalformedPOSTRequest
        }
        fanOutEntries = append(fanOutEntries, m)
    }
    part.Close()
    continue
}

即 x-minio-fanout-list 的取值是一个 JSON 数组，服务端用流式解码器逐项反序列化为 minio.PutObjectFanOutEntry。从服务端代码对该类型的实际消费方式（req.Key、req.UserMetadata、req.UserTags，见下文）可以推断，每个条目至少包含目标对象键名、用户自定义元数据集合和用户标签集合三类字段。

3. 其余字段按标准 PostObject 规则处理：file 字段必须是表单最后一个字段且只能有一个；Key 字段必填（支持 ${filename} 占位符替换）；Policy 字段走与标准 PostObject 相同的签名校验（doesPolicySignatureMatch）。

4. 权限模型差异：签名校验通过后，如果存在扇出条目，鉴权动作从标准的 s3:PutObject 切换为专用的 s3:PutObjectFanOut（源码中为 policy.PutObjectFanOutAction）（cmd/bucket-handlers.go）：

if len(fanOutEntries) > 0 {
    if !globalIAMSys.IsAllowed(policy.Args{
        AccountName: cred.AccessKey,
        Groups:      cred.Groups,
        Action:      policy.PutObjectFanOutAction,
        ...
    }) {
        writeErrorResponse(ctx, w, errorCodes.ToAPIErr(ErrAccessDenied), r.URL)
        return
    }
}

这意味着：为 Fan-Out 用户配置 IAM Policy 时，需要显式授予 s3:PutObjectFanOut 权限，普通 s3:PutObject 不覆盖该路径。

三、源流缓冲与限制：16 MiB 上限、MD5 复用

进入扇出路径前，有一个关键设计约束：所有扇出对象共享同一份源数据，而 POST 请求体是单向流，无法重读。源码中的注释解释了处理方式（cmd/bucket-handlers.go）：

// Fan-out requires no copying, and must be carried from original source
// ... instead of "copying" from a "copy", we need the stream to be seekable
// to ensure that we can make fan-out calls concurrently.
buf := bytebufferpool.Get()
...
// Maximum allowed fan-out object size.
const maxFanOutSize = 16 << 20

n, err := io.Copy(io.MultiWriter(buf, md5w), ioutil.HardLimitReader(pReader, maxFanOutSize))
...
// Set the correct hex md5sum for the fan-out stream.
fanOutOpts.MD5Hex = hex.EncodeToString(md5w.Sum(nil))

由此得到两个明确的实现事实：

• 扇出源流必须整体驻留内存：处理器把源流一次性读入内存缓冲（bytebufferpool 复用）并用 HardLimitReader 做硬限制，超过 16 MiB（16 << 20 字节）直接报错。因此 Fan-Out 适用于小对象（如 TSB 片段、信令文件），不适合大文件；
• MD5 只计算一次：源流的 MD5 在缓冲阶段计算一次（fanOutOpts.MD5Hex），后续每个扇出目标复用该摘要，避免 N 个对象做 N 次重复哈希（这一点也与 internal/hash/reader.go 中“主要用于 FanOut API 调用、以禁用昂贵 md5sum 计算”的注释相互印证）。

四、并发扇出核心：fanOutPutObject

真正执行“一次源、多次写入”的函数是 cmd/post-policy-fan-out.go 中的 fanOutPutObject，其函数注释写明：a context cancellation by the caller would ensure all fan-out operations are canceled——调用方取消 context 会取消全部扇出操作。其实现要点：

1. 每个条目一个 goroutine，通过 sync.WaitGroup 等待全部完成：

var wg sync.WaitGroup
for i, req := range fanOutEntries {
    wg.Add(1)
    go func(idx int, req minio.PutObjectFanOutEntry) {
        defer wg.Done()
        objInfos[idx] = ObjectInfo{Name: req.Key}
        ...
    }(i, req)
}
wg.Wait()

2. 每条目独立的属性：从源缓冲构造 bytes.NewReader(fanOutBuf) + hash.NewReaderWithOpts（DisableMD5: true，复用预算 MD5），随后按条目设置 UserMetadata、用 tags.NewTags(req.UserTags, true) 校验并写入标签（对应文档中“optionally supports custom metadata, tags”），再调用标准的 objectAPI.PutObject。

3. 版本化感知：每个 PutObject 都依据桶的版本化配置传入 Versioned / VersionSuspended（globalBucketVersioningSys.PrefixEnabled/PrefixSuspended 按目标前缀判断），即同一扇出批次中不同前缀的对象可以分别遵循启用/暂停版本化的策略。

4. 可选的逐对象加密：当请求声明了 SSE 时，每个条目走 newEncryptReader 生成各自的对象加密键（cmd/post-policy-fan-out.go）。注意结合入口处的校验，POST 路径不支持 SSE-KMS，SSE-C 与 SSE-S3（含桶默认加密）可用；且 SSE-C 与 SSE-S3 同时出现、SSE-Copy 与其他 SSE 混用等组合会被拒绝（cmd/bucket-handlers.go）。

5. 错误隔离：errs 与 objInfos 均为与条目等长的切片，某个目标失败只记录在该下标上，不影响其他目标继续执行。

五、并发度控制与响应格式

回到 PostPolicyBucketHandler 的扇出执行段（cmd/bucket-handlers.go）：

concurrentSize := min(runtime.GOMAXPROCS(0), 100)
...
if len(fanOutEntries) < concurrentSize {
    objInfos, errs = fanOutPutObject(ctx, bucket, objectAPI, fanOutEntries, buf.Bytes()[:n], fanOutOpts)
    done = true
} else {
    objInfos, errs = fanOutPutObject(ctx, bucket, objectAPI, fanOutEntries[:concurrentSize], buf.Bytes()[:n], fanOutOpts)
    fanOutEntries = fanOutEntries[concurrentSize:]
}

• 并发度上限为 min(GOMAXPROCS, 100)：条目数超过该值时分批循环提交，直到全部处理完；
• 响应为 JSON Lines：用 json.NewEncoder(w) 逐条 Encode 每个 PutObjectFanOutResponse，即 HTTP 响应体是“每行一个 JSON 对象”的流式格式。成功条目返回 Key、ETag、VersionID、LastModified；失败条目返回 Key 与 Error 字符串——部分成功是合法的，客户端需要逐行解析判断；
• 事件通知：每个成功（或失败）条目都会触发 s3:ObjectCreated:Post（event.ObjectCreatedPost）通知事件，UserAgent 中附加 MinIO-Fan-Out 标识，便于事件下游（如 docs/bucket/notifications 所述的通知配置）区分来源；失败条目的 UserAgent 还会追加 (failed: <原因>)。

六、客户端使用方式

按 Fan-Out 文档 的指引，MinIO 的 SDK 提供了高层 API 封装该扩展，无需手工拼 multipart 表单与签名 Policy。minio-go SDK 中的对应方法签名为：

PutObjectFanOut(ctx context.Context, bucket string, fanOutContent io.Reader, fanOutReq minio.PutObjectFanOutRequest) ([]minio.PutObjectFanOutResponse, error)

其语义与服务端行为对应：传入源内容读取器 fanOutContent 与扇出请求 PutObjectFanOutRequest（内部即生成 x-minio-fanout-list 表单字段），返回每个目标对象的处理结果切片。若不使用 SDK，也可以直接向 POST /{bucket} 发送 multipart/form-data 请求，表单包含 Policy、X-Amz-Credential、X-Amz-Algorithm、X-Amz-Date、Signature 等标准 PostObject 签名字段、x-minio-fanout-list JSON 数组以及最后的 file 字段。

七、能力边界与使用前提小结

项目	说明	依据
启用方式	请求携带 x-minio-fanout-list form-field 即自动启用，无独立开关	Fan-Out 文档、cmd/bucket-handlers.go
单份源流大小上限	16 MiB（源流必须可整体驻留内存）	cmd/bucket-handlers.go
并发度	单批 min(GOMAXPROCS, 100) 个条目，超出分批	cmd/bucket-handlers.go
加密支持	POST 路径不支持 SSE-KMS；支持 SSE-C / SSE-S3（逐对象加密键）	cmd/bucket-handlers.go、cmd/post-policy-fan-out.go
权限	需要 s3:PutObjectFanOut，区别于普通 s3:PutObject	cmd/bucket-handlers.go
版本化	每个目标按其前缀的桶版本化配置生效	cmd/post-policy-fan-out.go
响应格式	JSON Lines，支持部分成功，逐条含 ETag/VersionID 或 Error	cmd/bucket-handlers.go
事件通知	每条目发送 s3:ObjectCreated:Post，UserAgent 带 MinIO-Fan-Out 标记	cmd/bucket-handlers.go
后续读取	所有对象与普通对象一致，走标准 GetObject	Fan-Out 文档

Fan-Out Uploads 本质上把“客户端 N 次上传同一内容”压缩为“一次网络传输 + 服务端 N 次并发落盘”，特别适合 TSB 时移回放这类一份源流要分发到多个对象命名的场景。理解其 16 MiB 内存上限、s3:PutObjectFanOut 权限要求、JSON Lines 部分成功语义，以及逐对象元数据/标签/加密/版本化的行为，是正确使用该扩展的关键。