# 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、端点兼容性、认证、对象语义或预签名期限变化时更新本文。