文档中心

对象存储

请输入

最佳实践

AWS S3 协议兼容性说明

本文描述了数据从任何兼容 S3 协议存储迁移到 TOS 后的应用无缝切换方案、相关的注意事项，并提供了 TOS 兼容的 S3 协议接口详细说明。

背景信息

火山引擎对象存储 TOS（以下简称 TOS）提供了对 AWS S3 协议（以下简称 S3 协议）的兼容性支持，因此将数据从任何兼容 S3 协议存储迁移到 TOS 后，可以将之前访问该兼容 S3 协议存储的应用几乎无缝地切换到 TOS。

约束限制

TOS 兼容 S3 协议，因此可以通过 AWS S3 SDK 或者其他支持 S3 协议的工具进行创建桶、上传对象等相关操作。

使用过程中带宽、QPS 等限制需要遵循 TOS 的约束限制，详情请参见 TOS 约束限制。

应用切换方案

对于在兼容 S3 协议存储上已有数据的场景，应用切换前需要先将数据迁移到 TOS，然后再将应用的访问切换到 TOS。

步骤一：将数据迁移到 TOS

您可以使用火山引擎存储迁移服务将兼容 S3 协议存储的数据迁移到 TOS，详细方案请参见存储迁移服务用户指南。

步骤二：通过 S3 协议访问 TOS

将数据从兼容 S3 协议存储迁移到 TOS 后，应用可以继续使用 AWS S3 SDK 或者其他支持 S3 协议的工具（例如 AWSCli、S3Browser、Postman等）访问 TOS，但需要注意以下事项：

访问域名选择

TOS 为 S3 协议提供了专属的访问域名（即 Endpoint），使用 S3 协议访问 TOS 时必须使用 S3 协议的专属域名。

注意

不同于 AWS S3 等云厂商内外网域名一致的方案，TOS 为内外网提供了不同的访问域名。例如，通过内外网访问 TOS 华北2（北京）地域的 S3 协议域名分别为 tos-s3-cn-beijing.ivolces.com 和 tos-s3-cn-beijing.volces.com。

TOS 支持的域名详情，请参见访问域名。

TOS 仅支持 S3 协议的 V4 签名算法，不支持 V2 签名算法。

域名区域差异

不同于 AWS S3 等云厂商支持全局域名（即 s3.amazonaws.com，任何区域的桶都可以通过该全局域名访问），TOS 仅支持区域域名（即 Region 域名），对于桶的访问必须使用对应的 Region 域名。示例如下：

桶
地域
访问域名
bucket-test1
华北2（北京）
tos-s3-cn-beijing.volces.com
bucket-test2
华南1（广州）
tos-s3-cn-guangzhou.volces.com

访问密钥获取

TOS 通过火山引擎 IAM 提供的访问密钥（即 AccessKey ID 和 AccessKey Secret）进行签名认证，使用各种支持 S3 协议的 SDK 和工具访问 TOS 时，需要配置从火山引擎 IAM 获取到的 AccessKey ID 和 AccessKey Secret，获取方法，请参见访问密钥。

请求方式设置

TOS 仅支持使用虚拟主机（即 VirtualHostStyle）的请求方式，不支持路径样式（即 PathStyle）的请求方式。因此使用各种支持 S3 协议的 SDK 和工具访问 TOS 时，请务必确保配置了 VirtualHostStyle 的请求方式。

例如，使用 AWS S3 Java SDK 时，需要在客户端初始化时确保设置了禁用 PathStyle 的配置参数：AmazonS3Builder.withPathStyleAccessEnabled(false)。

ACL 权限支持

TOS 与 S3 协议对 ACL 权限的定义完全一致，但是在对 ACL 的特性支持上 TOS 是 S3 协议的子集，详细区别可参见下表。

功能	AWS S3	TOS
请求头中携带 ACL 枚举（使用 x-amz-acl 头域）	支持 7 种枚举值： private public-read public-read-write authenticated-read aws-exec-read bucket-owner-read bucket-owner-full-control	支持 6 种枚举值，与 S3 协议对应的枚举值语义一致： private public-read public-read-write authenticated-read bucket-owner-read bucket-owner-full-control
消息体中携带 ACL 配置	Type 支持 3 种枚举值： CanonicalUser AmazonCustomerByEmail Group 当 Type 为 Group 时，URI 支持 3 种枚举值： AllUsers：http://acs.amazonaws.com/groups/global/AllUsers AuthenticatedUsers：http://acs.amazonaws.com/groups/global/AuthenticatedUsers LogDelivery：http://acs.amazonaws.com/groups/s3/LogDelivery	Type 支持 2 种枚举值，与 S3 协议对应的枚举值语义一致： CanonicalUser Group 当 Type 为 Group 时，URI 支持 2 种枚举值，与 S3 协议对应的枚举值语义一致： AllUsers：http://acs.amazonaws.com/groups/global/AllUsers AuthenticatedUsers：http://acs.amazonaws.com/groups/global/AuthenticatedUsers

存储类型对照

TOS 当前支持标准存储、低频访问存储、智能分层存储、归档闪回存储、归档存储、冷归档存储和深度冷归档存储，除深度冷归档存储外，其他存储类型属于 S3 协议的子集，对应关系如下：

AWS S3	TOS
支持 9 种枚举值： STANDARD REDUCED_REDUNDANCY STANDARD_IA ONEZONE_IA INTELLIGENT_TIERING GLACIER_IR GLACIER DEEP_ARCHIVE OUTPOSTS	支持 6 种枚举值： STANDARD：标准存储 IA：低频访问存储 INTELLIGENT_TIERING：智能分层存储 ARCHIVE_FR：归档闪回存储 ARCHIVE：归档存储 COLD_ARCHIVE：冷归档存储

注意

使用 AWS-SDK 时，仍然按照 AWS-S3 定义的枚举值设置对象存储类型。

使用 TOS-SDK 时，需要按照 TOS 定义的枚举值设置对象存储类型。

接口定义对照

TOS 确保了对 S3 协议常用接口（如 CreateBucket、ListBuckets、PutObject、GetObject、ListObjects）的完全兼容。详情请参见附表：TOS 兼容 S3 协议的接口。

注意

虽然 TOS 确保完全兼容 S3 协议的接口，但在特性实现上，TOS 接口通常是 S3 协议对应接口的子集，部分 S3 协议支持的参数，在请求 TOS 时可能会被忽略，实际使用时请您特别注意此类差异。

附表：TOS 兼容 S3 协议的接口

接口类型	S3 协议接口名	TOS 兼容性说明
桶相关接口	CreateBucket	完全兼容。
		HeadBucket	完全兼容。
		DeleteBucket	完全兼容。
		ListBuckets	完全兼容。
对象相关接口	CopyObject	该接口的请求参数和响应结果兼容 S3 协议，但只支持同区域的对象复制，不支持跨区域的对象复制。
		DeleteObject	完全兼容。
		DeleteObjects	完全兼容，TOS 在说明文档上的接口名称为 DeleteMultiObjects。
		GetObject	完全兼容。
		GetObjectAcl	完全兼容，TOS 在说明文档上的接口名称为 GetObjectACL。
		HeadObject	完全兼容。
		ListObjects	完全兼容。
		ListObjectVersions	完全兼容。
		PutObject	完全兼容。
		PostObject	完全兼容。
		PutObjectAcl	完全兼容，TOS 在说明文档上的接口名称为 PutObjectACL。
分片相关接口	CreateMultipartUpload	完全兼容。
		UploadPart	完全兼容。
		CompleteMultipartUpload	该接口的请求参数和响应结果兼容 S3 协议，但只支持合并指定 UploadId 的所有已上传的分片，不支持仅合并部分已上传的分片。
		AbortMultipartUpload	完全兼容。
		UploadPartCopy	完全兼容。
		ListMultipartUploads	完全兼容。
		ListParts	完全兼容。

最近更新时间：2026.08.21 16:59:30

这个页面对您有帮助吗？

有用

无用

桶	地域	访问域名
bucket-test1	华北2（北京）	tos-s3-cn-beijing.volces.com
bucket-test2	华南1（广州）	tos-s3-cn-guangzhou.volces.com