文档中心

对象存储

回源规则

设置镜像回源

设置镜像回源

设置镜像回源后，当请求的对象在桶中不存在时，TOS 支持从源站拉取对象返回给请求方，也支持从源站拉取对象元数据返回给请求方。本文介绍如何设置镜像回源。

背景信息

镜像回源功能支持以下两个操作：

使用 GetObject 触发镜像回源：当请求的对象在桶中不存在时，TOS 将从指定的源站拉取该对象，返回给请求方的同时将该对象写入到桶中。

使用 HeadObject 触发镜像回源：当请求元数据的对象在桶中不存在时，TOS 将从规则设置的源站拉取该对象元数据，并返回给请求方。

注意事项

场景	类别	注意事项
通用	回源请求失败返回规则	触发镜像回源后，源站也不存在此文件，源站会返回 HTTP 状态码给 TOS。具体说明如下：如果源站返回给 TOS 的状态码是 200、206 或 404，则 TOS 也会返回对应状态码给用户。如果源站返回给 TOS 的是其他状态码，则 TOS 统一返回 424 给用户。
		数据处理	不支持同时使用镜像回源和数据处理功能。
		操作权限	主账号默认拥有全部权限，IAM 子用户默认没有任何权限。如果您需要使用子账号执行该操作，则需要主账号通过 IAM 策略或桶策略为该子账号授予以下权限。设置镜像回源规则：tos:PutBucketMirror 查看镜像回源规则：tos:GetBucketMirror 删除镜像回源规则：tos:DeleteBucketMirror
使用 GetObject 触发镜像回源	回源对象大小	最大支持请求 5GiB 的对象。如果需要请求超过 5GiB 的对象，请使用 Get Range 的功能。使用匿名用户触发镜像回源请求对象时，如果存储桶设置了服务端加密，匿名用户没有 KMS 密钥权限，导致文件无法写入到存储桶，镜像回源失败，同时会产生预期外的流量费用。
使用 GetObject 触发镜像回源		回源条件	默认当 GetObject 且返回的 HTTP 状态码为 404 时，才会触发镜像回源，从源站拉取文件。
使用 HeadObject 触发镜像回源	回源限制	不支持通过 HeadObject 请求镜像回源软链接对象。
使用 HeadObject 触发镜像回源		回源条件	只有在创建回源规则时开启是否支持 HeadObject 功能，且 HeadObject 请求返回的 HTTP 状态码为 404 时，才会触发镜像回源。

操作步骤

登录对象存储控制台。

在左侧导航栏，单击桶列表，在桶列表页面单击目标桶名称。

在左侧导航栏，选择基础设置＞回源设置，在回源设置页面，单击创建规则。

在创建回源规则页面，配置如下参数。

参数	说明
回源方式	选择镜像回源。
回源条件	按需求选择触发的回源条件，触发回源需同时满足配置的所有回源条件。回源条件说明如下: HTTP状态码：默认选中且仅支持 HTTP状态码为 404。文件名前缀：选中后设置需要触发的文件名前缀。文件名后缀：选中后设置需要触发的文件名后缀。例如您选中了文件名前后缀并分别设置为 test 和 object.png，当您访问存储桶下的 test***object.png 对象不存在且返回的 HTTP 状态码为 404 时，TOS 会提供规则中设置的回源地址供您访问。说明选中文件名前后缀后，您需要设置相应的信息，该条件才会生效；不填则表示不会匹配。如果您想匹配前缀下的所有后缀名，只需要选中文件名前缀；或者选中文件名后缀后不设置任何信息。
指定来源域名回源	指定访问源站的域名，指定后，仅该域名可以访问源站触发镜像回源。注意最多指定 20 个来源域名。域名需要能访问到存储桶，建议填写存储桶绑定的自定义域名。
回源类型	设置回源的源站类型，说明如下：选中回源私有桶：表示源站为 TOS 私有桶或其他云厂商的私有桶。不选中回源私有桶：表示源站为 TOS 公共桶或其他云厂商的公共桶。
回源地址	设置回源条件触发后需要跳转的回源地址，支持三种方式：添加前后缀、回源地址、替换文件名前缀。公共配置项（三种方式通用）源站类型：必填，可选主站、备站，均支持配置多个。TOS 优先请求主站，仅当所有主站连接失败时才请求备站；当主站（或备站）有多个时，随机选择其一发起回源请求。协议：必填，可选 http 或 https，默认 https。域名：必填，须为域名格式，不支持 IP 地址。添加前后缀文件名前缀/文件名后缀：选填，设置后，请求源站时，分别在请求的对象名前、后面添加。最后返回给客户端的对象名称与此前缀无关，仍然是客户端请求的对象名称。例如：在客户端请求 aaa.txt 对象，设置文件名前缀为 bbb，则在源站请求的对象是 bbbaaa.txt，最后返回给客户端的对象仍然为 aaa.txt。回源地址触发回源规则时，跳转的回源地址。例如：在客户端请求 aaa.txt 对象，设置回源地址为 http://example.com，则在源站请求 aaa.txt 对象时，如果源站没有该对象，则会跳转至 http://example.com，在该地址下拉取 aaa.txt 对象。替换文件名前缀触发回源规则时，跳转至替换文件名前缀的文件。替换前缀：选填。替换前缀需要与回源条件中的文件名前缀搭配使用，此处文件名前缀用于指定需要被替换的对象名前缀，替换前缀用于指定对象名前缀替换后的值。填写替换后的前缀字段时，相当于截断；不填写替换前的文件名前缀时，相当于添加文件名前缀。最后返回给客户端的对象名称与此前缀无关，仍然是客户端请求的对象名称。例如：在客户端请求 aaa.txt 对象，设置回源条件的文件名前缀为 aa，替换前缀为 bb，则在源站请求的对象为 bba.txt 对象，最后返回给客户端的对象是 aaa.txt。说明当回源类型为私有桶时，您还需要在回源地址处配置源桶服务商等信息，用于确认回源地址，说明如下：当源桶服务商为火山引擎时，您需要单击点击授权，授予 TOS 访问您私有桶的权限。选择回源的存储桶，回源桶必须是当前账号下的存储桶。当源桶服务商为百度云、其他S3存储协议时，您需要填写访问源站服务商的 AccessKey、SecretKey，源站 Region，回源的存储桶和回源地址。
是否支持 HeadObject	是否支持 HeadObject 请求触发镜像回源，默认关闭。关闭（默认）：仅 GetObject 请求可触发镜像回源。开启：GetObject 和 HeadObject 请求均可触发镜像回源。
是否携带请求参数	是否将请求携带的 queryString 透传至源站。默认打开。注意如果您的源站是私有桶，开启携带请求参数功能后，仅支持透传 S3 v4 签名约定的请求参数至源站，不支持透传 queryString 包含的所有请求参数。
禁止 Range 下载请求拉取文件	当通过范围下载请求触发镜像回源时，会从源站拉取文件返回给请求方，支持设置是否同时将该文件写入到存储桶中，默认关闭。关闭（默认）：仅将拉取到的文件返回给请求方，不写入存储桶。开启：将文件返回给请求方的同时，写入存储桶，保证数据完整性。范围下载的详细介绍，请参见范围下载（Java SDK）。
是否跟随源站重定向	是否跟随源站的 3XX 重定向请求回源，最多可重定向 1 次。默认关闭。
HTTP Header 传递规则（客户端到源站）	TOS 在访问指定的源站时，允许传递的响应头。支持以下规则：透传所有 HTTP Header（默认）：选择后透传所有参数，但以下请求头不会透传：Host、Content-length、Date、Authorization。透传指定 HTTP Header：指定允许传递的 Header，最多可添加 10 个。禁止透传所有 HTTP Header：选择后禁止透传所有参数。禁止透传指定 HTTP Header：指定禁止传递的 Header，最多可添加 10 个。
新增指定 HTTP Header（客户端到源站）	指定 HTTP Header 的 Key 和 Value，指定后，会在 Header 中添加该 Key 和 Value，并透传到源站。注意最多指定 10 个 HTTP Header。不支持指定 Content-Length、Date、Range、Authorization 类型的 Header。
支持自定义元数据	从指定源站拉取文件时，可将源站指定的响应头（SourceHeader）保存为对象的自定义元数据。TOS 会自动为元数据键名添加 x-tos-meta- 前缀，再拼接您设置的后缀（MetaDataSuffix），形成最终存储的元数据键。单击添加元数据，配置如下信息：左输入框填写源站响应头名称（SourceHeader）。右输入框填写元数据键后缀（MetaDataSuffix）。可增删多组映射，单条规则最多添加 10 个。示例：SourceHeader：content-language；MetaDataSuffix：language；最终存储的元数据键：x-tos-meta-language

单击提交。

镜像回源规则创建完成后，您可以在策略列表中查看已创建的规则。

相关操作

编辑回源规则：单击目标规则操作列的编辑，即可修改回源规则。

删除回源规则：单击目标规则操作列的删除，在弹出的对话框中单击确定，即可删除回源规则。

上移/下移回源规则：选择目标规则操作列的 ... ＞上移或者 ... ＞下移，即可调整回源规则顺序。

最近更新时间：2026.08.04 15:30:18

这个页面对您有帮助吗？

有用

有用

无用

无用