KnowForge/Apache Ozone 简体中文
S3 API

概述

师成师成· 更新于 2026-09-28· 阅读 21 分钟· 0 次阅读
登录后可跨设备保存划线和私人笔记登录

Ozone 提供了 S3 兼容的 REST 接口，可使用任何 S3 兼容工具访问对象存储中的数据。S3 存储桶存储在 /s3v 卷下。

快速开始

S3 网关是一个独立的组件，提供 S3 兼容的 API。除了常规的 Ozone 组件之外，还需要额外启动它。你可以从发布包中启动一个包含 S3 网关的基于 Docker 的集群。

进入 compose/ozone 目录，启动服务：

docker-compose up -d --scale datanode=3

你可以通过 http://localhost:9878 访问 S3 网关。

URL 样式

Ozone S3 网关同时支持虚拟主机式 URL 的 S3 存储桶地址（例如 http://bucketname.host:9878）以及路径式地址（例如 http://host:9878/bucketname）。默认使用路径式寻址。若要使用虚拟主机样式的 URL，请在 ozone-site.xml 中设置你的主域名：

<property>
   <name>ozone.s3g.domain.name</name>
   <value>s3g.internal</value>
</property>

已实现的 REST 端点

Ozone S3 网关实现了 Amazon S3 REST API 的大部分子集。下表汇总了每个 API 的支持状态、功能及相关说明，其中包括与 AWS S3 行为已知的差异。

存储桶操作

API 名称功能说明
✅ ListBuckets列出已认证用户拥有的所有存储桶。返回完整的存储桶列表。
✅ CreateBucket创建新的存储桶。不符合规范的行为： 默认的存储桶 ACL 可能包含额外的组权限，而非严格的私有权限。存储桶名称必须遵循 S3 命名约定。
✅ HeadBucket检查存储桶是否存在。如果存储桶存在，则返回 200 状态码。
✅ DeleteBucket删除存储桶。删除前存储桶必须为空。

对象操作

API 名称功能说明
✅ GetObject获取对象的内容。不符合规范的行为： 对于不存在的对象，Ozone 可能返回通用的 404，而不包含 AWS S3 所定义的结构化 XML 错误正文。
✅ HeadObject获取对象的元数据。与 GET Object 类似，对象缺失时的错误响应可能缺少详细的 AWS 风格错误 XML。
✅ PutObject上传新对象。同时支持单次 PUT 和分片上传。不符合规范的行为： 请求中提供的任何 ACL 头部都会被忽略。
✅ DeleteObject删除单个对象。对缺失的对象返回标准错误码。
✅ DeleteObjects在一次请求中删除多个对象。批量删除操作，提供汇总的错误报告。
✅ CopyObject复制对象（同一存储桶内或跨存储桶）。支持元数据指令（COPY/REPLACE）。不符合规范的行为： 用于更新元数据的自我复制可能与 AWS S3 略有不同。
✅ ListObjectsV2列出存储桶中的对象，支持过滤和分页。支持前缀、分隔符和续传令牌。

对象标签操作

API 名称功能说明
✅ PutObjectTagging为对象添加或更新标签。完全支持；更新操作会替换已有的标签集合。
✅ GetObjectTagging获取对象的标签集合。返回由 S3 API 定义的标签集合。
✅ DeleteObjectTagging删除对象的标签集合。清除与该对象关联的所有标签。

分段上传操作

API 名称功能说明
✅ CreateMultipartUpload启动一个分段上传会话。返回一个 UploadId，供后续上传分段使用。
✅ UploadPart为分段上传上传单个分段。分段编号与 ETag 计算遵循 AWS 语义。
✅ ListMultipartUploads列出存储桶中进行中的分段上传。默认每批最多返回 1000 个分段上传。
✅ ListParts列出进行中的分段上传已上传的分段。当分段数量较多时支持分页。
✅ CompleteMultipartUpload将所有已上传的分段组装成最终对象。返回一个遵循 AWS 分段上传规则的 ETag。
✅ AbortMultipartUpload中止一个进行中的分段上传。释放已上传分段所占用的存储空间。超过 7 天未完成的分段上传会被 Ozone 自动中止。

其他操作

API 名称功能说明
✅ 生成预签名 URL为访问对象生成临时 URL。使用 AWS Signature V4。**不符合规范的行为：**生成的 URL 可能包含固定的默认区域，而不是动态反映存储桶所在的位置。Ozone 现已支持为所有主要的 S3 操作生成预签名 URL，包括 GetObject、PutObject、DeleteObject、HeadObject、HeadBucket、MultipartUpload。

补充说明

  • 不支持的高级功能：

    • **ACL、存储桶策略、CORS 配置和网站托管：**这些功能尚未完全实现；Ozone 使用的内部权限模型与 AWS S3 不同。
    • **存储桶版本控制、对象锁定、服务端加密和 S3 Select：**这些功能目前尚不支持。
    • **条件请求：**对条件请求（例如 If-Match、If-None-Match）的支持正在规划中，相关进展记录在 HDDS-13117。
    • 生命周期配置、跨区域复制、S3 事件通知正在实现中，并已列入路线图。

  • 虽然 Ozone S3 网关对常见的 S3 操作提供了广泛的支持，但在与需要完整 AWS S3 功能的应用集成时，用户应当注意上述不符合规范的行为和限制。

  • 虽然 Ozone S3 网关不支持 S3 服务端加密，但它支持使用 Apache Ranger KMS 实现加密存储桶。有关更多信息，请参阅透明数据加密文档。

安全性

如果未启用安全性，你可以使用任意 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY。

如果启用了安全性，你可以通过 ozone s3 getsecret 命令获取密钥和密钥秘密（*需要基于 Kerberos 的身份验证）。

kinit -kt /etc/security/keytabs/testuser.keytab testuser/scm@EXAMPLE.COM
ozone s3 getsecret
awsAccessKey=testuser/scm@EXAMPLE.COM
awsSecret=c261b6ecabf7d37d5f9ded654b1c724adac9bd9f13e247a235e567e8296d2999

note

从 Ozone 1.4.0 开始，使用 getsecret 生成的密钥（secret）只会显示一次。如果丢失了该密钥，用户必须先执行 revokesecret，然后才能使用 getsecret 重新生成新的密钥。

现在，你可以使用该 key 和 secret 来访问 S3 端点：

export AWS_ACCESS_KEY_ID=testuser/scm@EXAMPLE.COM
export AWS_SECRET_ACCESS_KEY=c261b6ecabf7d37d5f9ded654b1c724adac9bd9f13e247a235e567e8296d2999
aws s3api --endpoint http://localhost:9878 create-bucket --bucket bucket1

要使密钥失效/撤销密钥，请使用 ozone s3 revokesecret 命令。可在其后附加 -y 参数以跳过交互式确认。

ozone s3 revokesecret
Enter 'y' to confirm S3 secret revocation for 'testuser/scm@EXAMPLE.COM': y
S3 secret revoked.

Ozone Manager 管理员可以运行 ozone s3 getsecret 和 ozone s3 revokesecret 命令并配合 -u 参数来指定其他用户。

# Obtained Kerberos TGT for testuser/scm@EXAMPLE.COM with kinit,
# testuser/scm@EXAMPLE.COM is an OM admin.
ozone s3 getsecret -u om/om@EXAMPLE.COM
awsAccessKey=om/om@EXAMPLE.COM
awsSecret=1e9379d0424cce6669b1a501ff14834e46dee004ee868b41a313b49eabcfb68f

ozone s3 revokesecret -u om/om@EXAMPLE.COM -y
S3 secret revoked.

暴露任意卷

与 S3 相比，Ozone 的命名空间层级中多了一个元素：卷（volume）。默认情况下，/s3v 卷的所有存储桶都可以通过 S3 接口访问，但只有 /s3v 卷中的（Ozone）存储桶会被暴露。

若要通过 S3 接口访问其他任意存储桶，可以创建一个"符号链接"存储桶：

ozone sh volume create /s3v
ozone sh volume create /vol1

ozone sh bucket create /vol1/bucket1
ozone sh bucket link /vol1/bucket1 /s3v/common-bucket

此示例通过 S3 接口，将 /vol1/bucket1 Ozone 存储桶以 S3 兼容的 common-bucket 形式暴露出来。

note

存储桶链接功能的实现细节可参见设计文档。

客户端

AWS CLI

通过指定自定义 REST 端点，即可使用 aws CLI。

aws s3api --endpoint http://localhost:9878 create-bucket --bucket buckettest

或

aws s3 ls --endpoint http://localhost:9878 s3://buckettest

支持的 AWS CLI 版本

兼容的第三方应用

Ozone 的 S3 网关可与各类云原生应用和分析应用集成。以下是已知可与 Ozone 配合使用的工具和平台示例（按字母顺序排列）：

此列表并不详尽——任何支持 S3 协议的应用理论上都可以连接到 Ozone，这使得在现代数据管道和云原生工作流中采用 Ozone 变得轻而易举。

评论

登录后参与评论

正在加载评论…