1.9 KiB
S3 兼容对象存储接入契约
元数据
- Owner：基础设施维护人
- 实现：
pkg/storage/ - SDK：
github.com/aws/aws-sdk-go v1.55.5 - 核验日期：2026-08-07
当前实际使用范围
系统支持对象上传、下载、Head 元数据、删除、存在性判断，以及上传/下载预签名 URL；Provider 当前只接受 s3。未发现版本管理、生命周期或跨区域复制调用。
配置、认证与字段
配置键为 storage.provider、storage.s3.endpoint、region、bucket、access_key_id、secret_access_key、use_ssl、path_style，以及 storage.presign.upload_expires、download_expires、storage.temp_dir。默认上传 URL 有效期 15 分钟，下载 URL 有效期 24 小时，运行配置可覆盖。
关键输入为对象 Key、Content-Type、Metadata 和可重复读取的数据流。预签名结果返回 URL、文件 Key 与过期时间；调用方必须保存 Key，不应把临时 URL 当作永久标识。
幂等、失败与重试
相同 Key 的上传按 S3 覆盖语义执行，唯一性由业务层保证；删除遵循服务端删除语义，存在性通过 Head 判断。适配器未额外实现重试策略，实际网络重试遵循 AWS SDK 默认行为；写操作重试前必须确保输入可重复读取。
安全与验证
AccessKey、SecretKey、私有对象 URL 和敏感 Metadata 不进入文档或普通日志。预签名 URL 仅在所需最短期限内分发，Bucket 权限、CORS 与生命周期由部署侧人工验收。
可复现静态证据：pkg/storage/s3.go、pkg/storage/service.go、pkg/storage/types.go、pkg/config/config.go。真实验收需使用隔离 Bucket 完成上传、Head、下载、删除及过期 URL 验证；本次不访问生产 Bucket。
官方参考：https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html
SDK、端点兼容性、认证、对象语义或预签名期限变化时更新本文。