S3 兼容对象存储客户端（MinIO/阿里云等），按 configKey 缓存客户端实例，配置变化时自动重建。工厂负责生命周期，业务侧永远不要自行构造 Client。

关键导出

• Client 单个配置对应的 S3 客户端
• Instance(ctx, configKey) (*Client, error) / InstanceDefault(ctx) (*Client, error) 取缓存客户端（配置变了自动重建）
• Remove(configKey) 丢弃缓存
• (c *Client) Upload(ctx, key, body, size, contentType) (*PutObjectResult, error)
• (c *Client) Download(ctx, key) (*GetObjectResult, io.ReadCloser, error)
• (c *Client) Delete(ctx, key) / PresignGetURL(ctx, key, ttl)
• BuildPathKey(fileName) string = [prefix/]yyyy/MM/dd/<uuid>.<ext>
• 错误 ErrConfigNotFound / ErrDefaultConfigNotSet

典型用法

// internal/resource/service/oss_service.go:152
client, err := oss.InstanceDefault(ctx)
result, err := client.Upload(ctx, key, src, header.Size, contentType)

坑/约定

WARNING

• 不要自行构造 Client，工厂负责按配置变化重建。
• 两个 checksum 开关必须显式 WhenRequired（MinIO/阿里云不认 x-amz-checksum-*）。
• 预签名客户端 endpoint 用 domainUrl（配了 CDN 指向 CDN，指回源站等于绕 CDN）。
• Download 返回流（io.Copy 直通响应，大文件不打爆内存）， 调用方须关闭 io.ReadCloser。 :::

相关页：/modules/resource、/pkg-reference/config-database-redis。