S3 完整配置
自建 S3 完整配置（中国大陆）
自建 S3 用于广域网文件传输。Web 端会通过浏览器向后端签发的预签名地址直传文件，因此除了 Endpoint、密钥和桶权限外，必须正确配置桶 CORS。
什么时候需要 S3
- 两台设备不在同一局域网。
- 文件较大，需要稳定的广域网中转。
- 希望文件内容存放在自己的对象存储服务中。
- 局域网直连、WebRTC 或 HTTP 直连不可用。
设置页字段
| 字段 | 说明 |
|---|---|
| Endpoint | S3 API 根地址，必须包含协议，例如 https://cos.ap-guangzhou.myqcloud.com。 |
| Region | 桶所在地域。不同厂商命名不同，请与控制台保持一致。 |
| Bucket | 用于中转和暂存文件的桶名。 |
| Access Key ID | 建议使用只授权该桶的子账号密钥。 |
| Secret Access Key | 仅在保存或测试时提交；重新编辑时可留空以保留原密钥。 |
桶权限建议
建议为虾传单独创建子账号或访问密钥，并只授予目标 Bucket 所需权限：
- 上传对象。
- 下载对象。
- 删除临时对象。
- 分片上传相关权限，包括初始化分片、上传分片、列出分片、完成分片和取消分片。
不要使用主账号密钥，也不要授予无关桶的管理权限。
CORS 必配
浏览器会向对象存储域名发起跨域请求。桶 CORS 必须允许用户打开虾传 Web 时的 Origin。
示例：
https://xiachuan.net
不要填写路径，也不要在末尾加 /。如果用户会通过多个域名访问 Web，每个 Origin 都需要添加。
CORS 规则参考
| 项目 | 建议值 |
|---|---|
| AllowedOrigins | 虾传 Web 的实际 Origin。 |
| AllowedMethods | 至少包含 GET、PUT、POST、DELETE、HEAD。 |
| AllowedHeaders | 建议 *，或至少包含 content-type、content-md5、x-amz-*、x-amz-date、authorization。 |
| ExposeHeaders | 至少包含 ETag。 |
| MaxAgeSeconds | 可设置为 86400，减少预检请求。 |
常见服务商
腾讯云 COS
在桶的「安全管理」或「跨域访问 CORS」中添加规则。Endpoint 通常形如：
https://cos.{region}.myqcloud.com
阿里云 OSS
在桶的「权限管理」或「跨域设置」中添加规则。Endpoint 以控制台展示的外网或内网访问域名为准。
AWS S3
在 Bucket 的 Permissions 中配置 Cross-origin resource sharing。Endpoint 通常使用区域虚拟托管式地址。
Cloudflare R2
在 R2 Bucket Settings 中配置 CORS policy。S3 API Endpoint 以控制台展示为准。
MinIO
在 MinIO Console 为桶配置 CORS。内网部署时，AllowedOrigins 必须包含浏览器实际访问前端的地址和端口。
测试连接
保存配置后，建议立即点击「测试连接」。如果测试失败，请按顺序检查：
- Endpoint 是否包含协议。
- Region 和 Bucket 是否与对象存储控制台一致。
- 密钥是否有目标桶权限。
- CORS 是否包含当前 Web Origin。
- 对象存储服务是否允许公网或当前网络访问。
数据边界
使用自建 S3 时，文件内容会上传到你配置的对象存储。虾传服务端主要负责签发上传/下载地址、记录必要的任务元数据和同步状态。