最近更新时间:2026-11-16 10:51:00
该接口支持将 Bucket 设置为静态网站托管模式,并设置跳转规则。该模式支持以下功能:
设置默认首页、默认404页。
设置重定向规则。
有关静态网站托管的更多详细信息请参见文档:静态网站托管。
使用该接口的用户必须是主账号或具有ks3:PutBucketWebsite权限的用户。
仅2026年8月3日及之后创建的桶,支持使用静态网站功能,2026年8月3日前创建的桶,不支持使用静态网站功能。
静态网站功能必须使用自定义域名访问才会生效,使用非自定义域名访问会当做普通请求处理,静态网站规则不生效。绑定自定义域名详情请请参见文档:域名绑定。
静态网站功能仅支持匿名用户访问,带签名访问时静态网站功能不生效,当做普通请求处理。因此使用静态网站功能,必须将相关文件的 ACL 权限设置为公开读(或 Bucket Policy 设置支持匿名用户访问)。
将一个Bucket设置为静态网站托管模式后,对静态网站根域名的匿名GET访问,KS3将返回默认首页页面。对静态网站根域名的签名GET访问,KS3将返回GET Bucket (LIST Objects)的结果。
如果设置了多个重定向规则(RoutingRule),KS3会从前往后依次匹配,如果匹配成功,则执行此规则,后续的规则不再执行。
访问返回 404 错误时,优先匹配对应错误码的重定向规则(RoutingRule),命中则执行重定向;未命中返回默认404页(ErrorDocument) 的内容,即重定向规则的优先级高于默认404页。
PUT /?website HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}
Content-length: {length}
Website configuration in the request body该接口不使用请求参数。
该接口仅使用公共请求头。
一段描述 WebsiteConfiguration 的 XML:
<WebsiteConfiguration>
<IndexDocument>
<Suffix>index.html</Suffix>
<SupportSubDir>true</SupportSubDir>
</IndexDocument>
<ErrorDocument>
<Key>error.html</Key>
</ErrorDocument>
<RoutingRules>
<RoutingRule>
<Condition>
<KeyPrefixEquals>abc/</KeyPrefixEquals>
<HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
</Condition>
<Redirect>
<Protocol>https</Protocol>
<HostName>www.example.com</HostName>
<HttpRedirectCode>302</HttpRedirectCode>
<ReplaceKeyPrefixWith>report-404/</ReplaceKeyPrefixWith>
</Redirect>
</RoutingRule>
<RoutingRule>
<Condition>
<KeyPrefixEquals>abc/</KeyPrefixEquals>
<HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
</Condition>
<Redirect>
<Protocol>https</Protocol>
<HostName>www.example.com</HostName>
<HttpRedirectCode>302</HttpRedirectCode>
<ReplaceKeyWith>errorpage.html</ReplaceKeyWith>
<PassQueryString>true</PassQueryString>
</Redirect>
</RoutingRule>
</RoutingRules>
</WebsiteConfiguration>XML中的节点具体描述如下:
WebsiteConfiguration 的内容
参数名称 | 描述 | 是否必选 |
|---|---|---|
WebsiteConfiguration | 包含静态网站托管规则的容器。
| 是 |
默认首页 IndexDocument 的内容
参数名称 | 描述 | 是否必选 |
|---|---|---|
IndexDocument | 默认首页的容器。
| 条件必选,IndexDocument、ErrorDocument、RoutingRules三个容器至少需指定一个。 |
Suffix | 默认首页。访问所有
Suffix仅支持填写文件名称,不支持携带斜杠。 | 条件必选,如果指定了父节点IndexDocument,则必须指定此项。 |
SupportSubDir | 访问子目录时,是否跳转到该子目录下的默认首页文件。取值范围如下:
假设默认首页 Suffix 设置为 index.html,访问
| 否 |
默认404页 ErrorDocument 的内容
参数名称 | 描述 | 是否必选 |
|---|---|---|
ErrorDocument | 404页面的容器。
| 条件必选,IndexDocument、ErrorDocument、RoutingRules三个容器至少需指定一个。 |
Key | 错误页面。指定错误页面后,如果访问(GET/HEAD)的文件不存在,则返回此错误页面。
如果是Range GET请求,文件本身不存在时,会返回错误页面的完整文件。 | 条件必选,如果指定了父节点ErrorDocument,则必须指定此项。 |
HttpStatus | 返回错误页面时返回的HTTP状态码。
| 否 |
重定向规则 RoutingRules 的内容
参数名称 | 描述 | 是否必选 |
|---|---|---|
RoutingRules | RoutingRule 的容器。
| 条件必选,IndexDocument、ErrorDocument、RoutingRules三个容器至少需指定一个。 |
RoutingRule | 指定跳转规则,最多指定50个RoutingRule。
| 条件必选,如果指定了父节点RoutingRules,则必须指定此项。 |
Condition | 设置重定向规则的匹配条件。只有当设置的条件全部匹配后,才会执行具体的重定向规则(Redirect)。
如果Condition内的子节点均不填写或填写值均为空,表示针对所有请求(GET/HEAD)均进行重定向规则。 | 条件必选,如果指定了父节点RoutingRule,则必须指定此项。 |
KeyPrefixEquals | 只有匹配此前缀的Object才会执行重定向规则。
如果设置KeyPrefixEquals的同时也设置了HttpErrorCodeReturnedEquals,则两个条件同时匹配时,才会执行重定向规则。 | 否 |
HttpErrorCodeReturnedEquals | 只有匹配此 HTTP 状态码的请求才会执行重定向规则。例如设置HttpErrorCodeReturnedEquals 为 404,表示当访问指定对象不存在时,执行重定向规则(Redirect)。
如果设置HttpErrorCodeReturnedEquals的同时也设置了KeyPrefixEquals,则两个条件同时匹配时,才会执行重定向规则。 | 否 |
Redirect | 设置重定向规则。
| 条件必选,如果指定了父节点RoutingRule,则必须指定此项。 |
Protocol | 重定向请求时使用的协议,支持 http 和 https 协议。默认使用 http 协议。
| 否 |
HostName | 跳转时的域名。
1. 未配置HostName时,默认继承原请求的域名。 2. HostName不能包含斜杠。 3. 假设要访问的文件为test,设置Hostname为 | 否 |
HttpRedirectCode | 跳转时返回的状态码。
| 否 |
ReplaceKeyPrefixWith | 重定向时 Object 的前缀将替换成该值。替换方式为替换原始请求中所匹配到的前缀部分( KeyPrefixEquals)。注意ReplaceKeyPrefixWith 不能与 ReplaceKeyWith 同时设置。
1. 假如要访问的 Object 为 abc/test.txt,如果设置 KeyPrefixEquals为abc/,ReplaceKeyPrefixWith 为 def/,则 Location 头为 2. 当 ReplaceKeyPrefixWith 和 ReplaceKeyWith 均不填写时,重定向会保留原始请求的路径(默认不带查询参数),仅更换指定域名(HostName)。 3. 如果 KeyPrefixEquals 值为空或不使用 KeyPrefixEquals 参数,则会将 ReplaceKeyPrefixWith 设置的值插入 Key 的前面,等同于添加前缀。 4. ReplaceKeyPrefixWith 支持设置值为空,为空表示删除指定前缀(keyPrefixEquals)。 | 否 |
ReplaceKeyWith | 所有命中请求的 Object,完整的 Key 将替换成 ReplaceKeyWith 指定的值。替换方式为替换整个原始请求 Object 的 Key。注意 ReplaceKeyWith 不能与 ReplaceKeyPrefixWith 同时设置。
1. ReplaceKeyWith 支持设置变量,目前支持的变量为 ${key},表示该请求 Object 的 Key。比如要访问的 Object 为 test,如果设置 ReplaceKeyWith 设置为 2. 如果想把 docs 目录下所有对象的请求重定向到 documents/error.html,可以将 Condition 中的 KeyPrefixEquals 设置为 docs,Redirect 中的 ReplaceKeyWith 设置为 documents/error.html。则对于比如对象 Key 为 docs/a.html 和 docs/b.html 的文件,重定向的结果均为 documents/error.html。 3. 当 ReplaceKeyWith 和 ReplaceKeyPrefixWith 均不填写时,重定向会保留原始请求的路径(默认不带查询参数),仅更换指定域名(HostName)。 4. ReplaceKeyWith 支持设置为空,为空表示重定向的请求路径均为空(参数是否为空由 PassQueryString 控制)。 | 否 |
PassQueryString | 执行跳转规则时,是否携带请求参数,默认不携带。
比如用户请求 KS3 时携带了请求参数 | 否 |
该接口仅返回常用响应头部。
该接口不返回响应体。
示例1:将桶的所有 GET/HEAD 请求重定向至其他域名:
PUT /?website HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}
Content-length: {length}
<WebsiteConfiguration>
<RoutingRules>
<RoutingRule>
<Condition>
</Condition>
<Redirect>
<HostName>www.example.com</HostName>
<Protocol>https</Protocol>
</Redirect>
</RoutingRule>
</RoutingRules>
</WebsiteConfiguration>示例2:仅设置默认首页和默认 404 页,不设置重定向规则:
PUT /?website HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}
Content-length: {length}
<WebsiteConfiguration>
<IndexDocument>
<Suffix>index.html</Suffix>
<SupportSubDir>true</SupportSubDir>
</IndexDocument>
<ErrorDocument>
<Key>error.html</Key>
</ErrorDocument>
</WebsiteConfiguration>示例3:设置默认首页和默认 404 页,并设置针对指定文件夹的所有 GET/HEAD 请求重定向到新的文件夹规则:
PUT /?website HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}
Content-length: {length}
<WebsiteConfiguration>
<IndexDocument>
<Suffix>index.html</Suffix>
<SupportSubDir>true</SupportSubDir>
</IndexDocument>
<ErrorDocument>
<Key>error.html</Key>
</ErrorDocument>
<RoutingRules>
<RoutingRule>
<Condition>
<KeyPrefixEquals>images/</KeyPrefixEquals>
</Condition>
<Redirect>
<ReplaceKeyWith>examplepage.html</ReplaceKeyWith>
</Redirect>
</RoutingRule>
</RoutingRules>
</WebsiteConfiguration>HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Tue, 19 Jul 2017 09:14:23 GMT
Server: KS3
x-kss-request-id: 54a47bda18ac4e6e91de369add54218***错误码 | HTTP状态码 | 描述 |
|---|---|---|
400 Bad Request | MalformedXML | 请求体不符合 XML 语法。 |
400 Bad Request | InvalidRequest | 请求体为空。 |
404 Not Found | NoSuchBucket | 桶不存在。 |
403 Forbidden | AccessDenied | 缺少权限。 |
400 Bad Request | InvalidArgument | 存在以下场景:
|
纯净模式
