S3 协议使用说明
本文介绍如何使用 S3 兼容接口访问 Cloud Blox 存储桶：如何获取端点与密钥、认证方式、支持的操作、常用客户端配置与注意事项。适用于使用 AWS CLI、s3cmd、MinIO Client（mc）、各语言 AWS SDK 等标准工具进行上传、下载、列举、删除等操作。
适用场景
- 需要通过 S3 兼容接口 对接脚本、备份工具、第三方系统或对象存储客户端时，可使用 S3 协议。
- 支持 AWS Signature Version 4 与 预签名 URL 鉴权，与常见 S3 客户端、SDK 兼容。
- 存储桶可配置 ACL（私有 / 公有读 / 公有读写），便于控制匿名访问范围。
端点与密钥
获取 S3 端点
- S3 使用独立端口或独立域名，与管理后台、访问域名分离。
- 配置项通常为
s3_port（如 28080）或 S3 专用域名，实际地址以部署环境或运维提供的说明为准。 - 示例：
http://服务器IP:28080、https://s3.你的域名。
获取 Access Key 与 Secret Key
- 登录管理后台，进入 对象存储 → 密钥管理（S3）。
- 新建密钥，填写名称并选择可访问的存储桶及权限（读 / 写 / 列表）。
- 创建成功后保存 Access Key ID 与 Secret Access Key（Secret 仅展示一次，请妥善保存）。
- 将 Endpoint、Access Key、Secret Key 配置到 S3 客户端；Region 可填
us-east-1或与桶所在区域一致（用于签名与跨区域转发）。
路径风格
- 路径风格：
http://endpoint/桶名/对象键。 - 列举桶：
GET /；桶操作：GET|PUT|DELETE|HEAD /桶名；对象操作：GET|PUT|HEAD|DELETE /桶名/对象键。 - 对象键即桶内路径，如
folder/sub/file.txt表示桶内folder/sub/下的文件。
认证方式
Authorization 头（推荐）
- 使用 AWS Signature Version 4：在请求头中携带 Authorization、X-Amz-Date 等，由客户端或 SDK 自动计算。
- 客户端与服务器时间偏差需在 ±15 分钟 内，否则会返回签名错误。
- AWS CLI、s3cmd、mc、各语言 AWS SDK 均支持，配置 Endpoint 与密钥即可。
预签名 URL
- 服务端或持有 Secret Key 的一方可生成带签名的临时 URL（Query 参数鉴权）。
- 持有该 URL 的用户在有效期内无需密钥即可访问（GET 下载或 PUT 上传），适用于临时授权、前端直传、分享下载。
桶 ACL 与匿名访问
- 桶可配置：私有（默认，均需认证）、公有读（读与列举可匿名）、公有读写（读写真名均可，慎用）。
- 匿名请求无需 Authorization 头；需认证的请求若未带有效签名会返回 403。
支持的操作
存储桶
| 操作 | 说明 |
|---|---|
| 列举桶 | 列出当前密钥有权限的存储桶。 |
| 创建桶 | 创建新存储桶（需写权限、符合命名与区域约束）。 |
| 删除桶 | 仅当桶内无对象时可删除。 |
| 检查桶存在 | 用于探测桶是否存在。 |
| 获取桶区域 | 用于跨区域或客户端区域配置。 |
对象
| 操作 | 说明 |
|---|---|
| 上传（简单） | 单次 PUT 上传整个对象；请求先落盘并返回成功，后台再同步到存储通道。 |
| 下载 | GET 获取对象内容；支持 Range 分段下载；若 URL 带媒体处理参数则返回处理结果。 |
| 获取元数据 | HEAD 获取大小、Content-Type、ETag 等，不返回正文。 |
| 删除 | DELETE 为硬删除，立即从列表移除，不进入回收站，不可恢复。 |
| 复制 | PUT 且带 x-amz-copy-source 头，在服务端复制对象（同桶或跨桶）。 |
列举对象
- 支持 ListObjects v1 与 v2：按前缀（prefix）、分隔符（delimiter）筛选，分页（max-keys、continuation-token 等）。
分片上传
- 大文件建议使用分片上传：初始化 获得 uploadId → 上传各分片（partNumber + uploadId）→ 完成合并 或 中止。
- 分片上传完成后同样经后台同步到存储通道；未完成或已中止的上传会占用存储，建议定期清理。
使用说明
列举存储桶
- 在客户端执行「列出桶」或 ListBuckets，可看到当前密钥有权限的桶列表。
- 主密钥 或 全部存储桶 权限：返回该用户下全部桶；指定桶授权：仅返回已授权且属于该用户的桶。
- 若列表为空，请确认密钥已绑定可访问的存储桶。
创建与删除桶
- 创建：需具备该用户下的创建权限，桶名需符合命名规范且全局唯一；请求体可带区域等配置。
- 删除：仅当桶内无对象（含未完成的分片上传）时可删除。
上传与下载对象
- 简单上传：PUT 到
/:bucket/key，请求体为对象内容；可设置 Content-Type、Content-MD5 等头。 - 下载：GET
/:bucket/key获取内容；带媒体处理参数时返回处理后的结果。 - 上传采用异步同步：接口返回成功时对象处于「处理中」，同步完成后才可从存储读取。
删除对象
- DELETE
/:bucket/key为硬删除：立即从对象列表移除，物理文件由后台按引用计数异步清理；不进入回收站，不可恢复。 - 删除不存在的 key 仍返回 204（与 S3 语义一致）。
跨区域与权限
- 桶可配置所在区域；当请求 Host 与桶所在区域不一致时，服务端可转发到该区域端点，对客户端透明。
- 密钥权限：读（GetObject、HeadObject）、写（PutObject、CopyObject、DeleteObject、分片上传）、列表（ListObjects、ListBuckets 可见桶范围）。
- 账号欠费时，写操作与部分敏感操作可能被拒绝；读/下载是否受限以产品策略为准。
错误与注意事项
- 错误响应为 S3 风格 XML，包含 Code 与 Message，如
NoSuchBucket、NoSuchKey、AccessDenied、InvalidArgument等。 - 404：桶或对象不存在；403：认证失败、无权限或欠费。
- 签名错误：请检查 Access Key/Secret Key、Region、时间偏差（±15 分钟）及请求体/头是否与签名一致。
- 健康检查：
GET /health为无需认证的探测端点，可用于负载均衡或运维探测。
常用客户端配置
AWS CLI
- 配置 endpoint、region、access key 与 secret key（
aws configure或环境变量、配置文件）。 - 使用
--endpoint-url=http://你的S3地址:端口指定 Cloud Blox S3 端点。
s3cmd
- 在
.s3cfg或命令行中指定host_base、host_bucket、access_key、secret_key。
MinIO Client (mc)
mc alias set mypool http://你的S3地址:端口 ACCESS_KEY SECRET_KEY，之后使用mypool执行 ls、cp、mb、rm 等命令。
具体参数名与格式以各客户端文档为准；只要支持自定义 endpoint 与 Access Key/Secret Key，即可对接 Cloud Blox 的 S3 接口。