S3
配置并使用 RustFS S3 兼容 API，以及 AWS CLI、AWS SDK 和其他 S3 客户端。
RustFS 为常见对象存储工作负载提供 S3 兼容 REST API。它支持 AWS Signature Version 4（SigV4）；正确配置 RustFS 端点、区域、凭证和寻址方式后，可配合 AWS CLI、AWS SDK 和其他 S3 客户端使用。
概述
S3 将数据组织为存储桶和对象。使用默认的路径式寻址时，RustFS URL 与存储的映射如下：
http://localhost:9000/my-bucket/path/to/hello.txt
| bucket | |---- object key ----|RustFS 涵盖应用、备份工具和 SDK 常用的 S3 数据平面：
| 领域 | 支持的工作流 |
|---|---|
| 存储桶 | 创建、删除、列出、检查和获取位置 |
| 对象 | 放置、获取、查看元数据、复制、删除、批量删除、范围读取、条件请求和用户元数据 |
| 列出 | ListObjects、ListObjectsV2、前缀、分隔符、标记和分页 |
| 大型对象 | 创建、上传、复制、列出、完成和中止分段上传 |
| 数据管理 | 版本控制、生命周期规则、存储桶和对象标签、校验和及对象锁定 |
| 访问控制 | IAM 凭证和策略、存储桶策略、公共访问阻止及预签名 GET/PUT URL |
| 集成 | CORS、存储桶通知、复制配置和服务器端加密工作流 |
已验证身份的客户端使用访问密钥和秘密密钥为请求签名。匿名请求根据适用的存储桶策略进行评估。
兼容性范围
RustFS 为受支持的功能提供广泛的 S3 API 兼容性，但与每个 AWS S3 或 MinIO API 并不完全相同。依赖高级或供应商特定行为前，请查看已知兼容性差异，并针对目标 RustFS 版本进行验证。
配置
S3 API 在 RustFS 主监听器上启用，不需要单独的协议开关。
| 变量 | 用途 | 默认值 |
|---|---|---|
RUSTFS_ADDRESS | S3 API 绑定地址 | :9000 |
RUSTFS_REGION | 用于请求签名和区域感知客户端的区域 | us-east-1 |
RUSTFS_ACCESS_KEY | 根访问密钥 | 因安装而异 |
RUSTFS_SECRET_KEY | 根秘密密钥 | 因安装而异 |
RUSTFS_SERVER_DOMAINS | 用于虚拟主机式请求的逗号分隔域名 | 未设置 |
RUSTFS_TLS_PATH | 包含 rustfs_cert.pem 和 rustfs_key.pem 的目录 | 未设置 |
应用应使用 IAM 用户或服务账户，而不是根凭证，并且只授予所需的 S3 操作权限。
路径式寻址
路径式寻址是默认方式，不需要 DNS 配置。存储桶名称是请求路径的第一个组成部分：
http://localhost:9000/my-bucket/hello.txt客户端配置如下：
- 端点：
http://localhost:9000 - 区域：
us-east-1 - 访问密钥：
<your-access-key> - 秘密密钥：
<your-secret-key> - 寻址方式：路径式
有些客户端默认使用虚拟主机式请求。请启用其路径式选项，例如 AWS SDK 配置中的 force_path_style=true 或 Terraform 中的 s3_use_path_style = true。
虚拟主机式寻址
虚拟主机式寻址将存储桶名称放在主机名中。将 RUSTFS_SERVER_DOMAINS 设置为 RustFS 应识别的每个基础域名：
export RUSTFS_SERVER_DOMAINS="s3.example.com"之后，同一对象的地址为：
https://my-bucket.s3.example.com/hello.txt配置通配符 DNS（如 *.s3.example.com），使其解析到 RustFS 端点。使用 HTTPS 时，证书也必须覆盖存储桶主机名。名称中带点的存储桶可能需要显式证书名称，因为单标签通配符无法跨越多个标签。
配置服务器域名
除非已配置 RUSTFS_SERVER_DOMAINS，否则不要发送虚拟主机式请求。否则 RustFS 会将请求视为路径式，无法从主机名中提取存储桶。
TLS 和网络访问
生产环境请将 RUSTFS_TLS_PATH 设置为包含 rustfs_cert.pem 和 rustfs_key.pem 的目录，然后使用 https:// 端点。确保客户端信任签发证书的证书颁发机构。
在主机防火墙和负载均衡器上允许已配置的 S3 API 端口。默认端口为 TCP 9000；此监听器也承载 RustFS 管理和节点间流量，因此不要在缺少适当网络和 IAM 控制的情况下允许匿名访问。
使用
以下示例使用 AWS CLI 和规范的本地端点。继续前请安装并配置 AWS CLI。
配置 AWS CLI
aws configure根据提示输入以下值：
AWS Access Key ID [None]: <your-access-key>
AWS Secret Access Key [None]: <your-secret-key>
Default region name [None]: us-east-1
Default output format [None]: json每条命令都要传入 RustFS 端点。自定义端点可确保这些示例访问 RustFS 而不是 AWS S3。
export RUSTFS_ENDPOINT="http://localhost:9000"创建和列出存储桶
aws --endpoint-url "$RUSTFS_ENDPOINT" s3api create-bucket \
--bucket my-bucket
aws --endpoint-url "$RUSTFS_ENDPOINT" s3api list-buckets上传和列出对象
printf 'Hello from RustFS\n' > hello.txt
aws --endpoint-url "$RUSTFS_ENDPOINT" s3 cp \
hello.txt s3://my-bucket/path/to/hello.txt
aws --endpoint-url "$RUSTFS_ENDPOINT" s3 ls \
s3://my-bucket/path/to/AWS CLI 的传输配置为大型对象选择分段上传时，会自动使用该方式。RustFS 支持标准的创建、上传分段、完成、列出和中止分段上传工作流。
下载和检查对象
aws --endpoint-url "$RUSTFS_ENDPOINT" s3 cp \
s3://my-bucket/path/to/hello.txt ./downloaded-hello.txt
aws --endpoint-url "$RUSTFS_ENDPOINT" s3api head-object \
--bucket my-bucket \
--key path/to/hello.txt创建预签名 URL
生成有时间限制的 URL，无需暴露凭证即可下载对象：
aws --endpoint-url "$RUSTFS_ENDPOINT" s3 presign \
s3://my-bucket/path/to/hello.txt \
--expires-in 3600接收者使用的主机名、方案、端口、区域和对象路径必须与签名 URL 时使用的值匹配。为其他计算机生成 URL 时，请使用可从外部访问的端点。
删除对象和存储桶
aws --endpoint-url "$RUSTFS_ENDPOINT" s3 rm \
s3://my-bucket/path/to/hello.txt
aws --endpoint-url "$RUSTFS_ENDPOINT" s3api delete-bucket \
--bucket my-bucket删除 S3 存储桶前必须将其清空。
已知兼容性差异
当前 RustFS 兼容性测试涵盖上述常见工作流。以下领域与 AWS S3 或 MinIO 不等同：
- 存储桶访问日志和存储桶所有权控制尚在规划中，未完整实现。
- ACL 授权有意不受支持。预设 ACL 请求头具有部分兼容性，而 XML 授权策略会返回
NotImplemented。请优先使用 IAM 和存储桶策略。 - 已实现 POST Object 表单上传，但该工作流的校验和处理尚不完整。
- 某些分段上传列表和分段查找边缘情况不在默认兼容性门禁范围内。
- S3 Select 目前只接受未压缩输入。
- 未实现 Access Point 和 Outposts 复制源形式。
- MinIO 管理 API 是单独的兼容性接口，不能根据 S3 数据平面支持情况推断其兼容性。
当工具假设存在 AWS 特定服务、存储类、账户所有权控制或端点发现时，客户端行为也可能不同。请始终显式设置 RustFS 端点，并测试应用使用的确切操作。
后续步骤
- 按照完整的 AWS CLI 示例操作。
- 选择用于应用集成的 S3 SDK。
- 配置凭证和访问策略。
- 在可信网络之外开放端点前启用 TLS。