全部文档
当前文档

暂无内容

如果没有找到您期望的内容,请尝试其他搜索词

文档中心

PUT Bucket Website

最近更新时间:2026-11-16 10:51:00

该接口支持将 Bucket 设置为静态网站托管模式,并设置跳转规则。该模式支持以下功能:

  • 设置默认首页、默认404页。

  • 设置重定向规则。

有关静态网站托管的更多详细信息请参见文档:静态网站托管。

注意事项

  1. 使用该接口的用户必须是主账号或具有ks3:PutBucketWebsite权限的用户。

  2. 仅2026年8月3日及之后创建的桶,支持使用静态网站功能,2026年8月3日前创建的桶,不支持使用静态网站功能。

  3. 静态网站功能必须使用自定义域名访问才会生效,使用非自定义域名访问会当做普通请求处理,静态网站规则不生效。绑定自定义域名详情请请参见文档:域名绑定。

  4. 静态网站功能仅支持匿名用户访问,带签名访问时静态网站功能不生效,当做普通请求处理。因此使用静态网站功能,必须将相关文件的 ACL 权限设置为公开读(或 Bucket Policy 设置支持匿名用户访问)。

  5. 将一个Bucket设置为静态网站托管模式后,对静态网站根域名的匿名GET访问,KS3将返回默认首页页面。对静态网站根域名的签名GET访问,KS3将返回GET Bucket (LIST Objects)的结果。

  6. 如果设置了多个重定向规则(RoutingRule),KS3会从前往后依次匹配,如果匹配成功,则执行此规则,后续的规则不再执行。

  7. 访问返回 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

默认首页的容器。

  • 类型:容器

  • 父节点:WebsiteConfiguration

条件必选,IndexDocument、ErrorDocument、RoutingRules三个容器至少需指定一个。

Suffix

默认首页。访问所有 /结尾的域名或访问结尾不带/的跟域名时,将返回该目录下的 Suffix 对象。例如 Suffix 设置为 index.html 后,访问 http://example.com/docment/ 时,则默认返回根目录下的 index.html 文件。

  • 类型:String

  • 父节点:IndexDocument

  • 字符长度:1~1024

Suffix仅支持填写文件名称,不支持携带斜杠。

条件必选,如果指定了父节点IndexDocument,则必须指定此项。

SupportSubDir

访问子目录时,是否跳转到该子目录下的默认首页文件。取值范围如下:

  • true:跳转到该子目录下的默认首页文件。

  • false(默认):不跳转到该子目录下的默认首页文件(Suffix),而是转到根目录下的默认首页文件(Suffix)。

假设默认首页 Suffix 设置为 index.html,访问http://example.com/subdir/时,如果设置 SupportSubDir 为 false或不设置,则会跳转到http://example.com/index.html。如果设置 SupportSubDir 为 true,则会跳转到http://example.com/subdir/index.html。

  • 类型:布尔

  • 父节点:IndexDocument

否

  • 默认404页 ErrorDocument 的内容

参数名称

描述

是否必选

ErrorDocument

404页面的容器。

  • 类型:容器。

  • 父节点:WebsiteConfiguration

条件必选,IndexDocument、ErrorDocument、RoutingRules三个容器至少需指定一个。

Key

错误页面。指定错误页面后,如果访问(GET/HEAD)的文件不存在,则返回此错误页面。

  • 类型:String

  • 父节点:ErrorDocument

  • 字符长度:1~1024

如果是Range GET请求,文件本身不存在时,会返回错误页面的完整文件。

条件必选,如果指定了父节点ErrorDocument,则必须指定此项。

HttpStatus

返回错误页面时返回的HTTP状态码。

  • 取值:200、404(默认)

  • 父节点:ErrorDocument

否

  • 重定向规则 RoutingRules 的内容

参数名称

描述

是否必选

RoutingRules

RoutingRule 的容器。

  • 类型:容器

  • 父节点:WebsiteConfiguration

条件必选,IndexDocument、ErrorDocument、RoutingRules三个容器至少需指定一个。

RoutingRule

指定跳转规则,最多指定50个RoutingRule。

  • 类型:容器

  • 父节点:RoutingRules

条件必选,如果指定了父节点RoutingRules,则必须指定此项。

Condition

设置重定向规则的匹配条件。只有当设置的条件全部匹配后,才会执行具体的重定向规则(Redirect)。

  • 类型:容器

  • 父节点:RoutingRule

如果Condition内的子节点均不填写或填写值均为空,表示针对所有请求(GET/HEAD)均进行重定向规则。

条件必选,如果指定了父节点RoutingRule,则必须指定此项。

KeyPrefixEquals

只有匹配此前缀的Object才会执行重定向规则。

  • 类型:String

  • 父节点:Condition

如果设置KeyPrefixEquals的同时也设置了HttpErrorCodeReturnedEquals,则两个条件同时匹配时,才会执行重定向规则。

否

HttpErrorCodeReturnedEquals

只有匹配此 HTTP 状态码的请求才会执行重定向规则。例如设置HttpErrorCodeReturnedEquals 为 404,表示当访问指定对象不存在时,执行重定向规则(Redirect)。

  • 取值范围:仅支持填写4XX状态码,如403或404

  • 类型:String

  • 父节点:Condition

如果设置HttpErrorCodeReturnedEquals的同时也设置了KeyPrefixEquals,则两个条件同时匹配时,才会执行重定向规则。

否

Redirect

设置重定向规则。

  • 类型:容器

  • 父节点:RoutingRule

条件必选,如果指定了父节点RoutingRule,则必须指定此项。

Protocol

重定向请求时使用的协议,支持 http 和 https 协议。默认使用 http 协议。

  • 取值:http(默认)、https

  • 父节点:Redirect

否

HostName

跳转时的域名。

  • 类型:String

  • 父节点:Redirect

1. 未配置HostName时,默认继承原请求的域名。

2. HostName不能包含斜杠。

3. 假设要访问的文件为test,设置Hostname为example.com,并且设置Protocol为https,则返回的Location头为https://example.com/test。

否

HttpRedirectCode

跳转时返回的状态码。

  • 取值:301(默认)、302、307

  • 类型:String

  • 父节点:Redirect

否

ReplaceKeyPrefixWith

重定向时 Object 的前缀将替换成该值。替换方式为替换原始请求中所匹配到的前缀部分( KeyPrefixEquals)。注意ReplaceKeyPrefixWith 不能与 ReplaceKeyWith 同时设置。

  • 类型:String

  • 父节点:Redirect

1. 假如要访问的 Object 为 abc/test.txt,如果设置 KeyPrefixEquals为abc/,ReplaceKeyPrefixWith 为 def/,则 Location 头为http://example.com/def/test.txt。

2. 当 ReplaceKeyPrefixWith 和 ReplaceKeyWith 均不填写时,重定向会保留原始请求的路径(默认不带查询参数),仅更换指定域名(HostName)。

3. 如果 KeyPrefixEquals 值为空或不使用 KeyPrefixEquals 参数,则会将 ReplaceKeyPrefixWith 设置的值插入 Key 的前面,等同于添加前缀。

4. ReplaceKeyPrefixWith 支持设置值为空,为空表示删除指定前缀(keyPrefixEquals)。

否

ReplaceKeyWith

所有命中请求的 Object,完整的 Key 将替换成 ReplaceKeyWith 指定的值。替换方式为替换整个原始请求 Object 的 Key。注意 ReplaceKeyWith 不能与 ReplaceKeyPrefixWith 同时设置。

  • 类型:String

  • 父节点:Redirect

1. ReplaceKeyWith 支持设置变量,目前支持的变量为 ${key},表示该请求 Object 的 Key。比如要访问的 Object 为 test,如果设置 ReplaceKeyWith 设置为prefix/${key}.suffix,则返回 Location 的头为http://example.com/prefix/test.suffix。

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

执行跳转规则时,是否携带请求参数,默认不携带。

  • 取值:true、false(默认)

  • 父节点:Redirect

比如用户请求 KS3 时携带了请求参数?a=b&c=d,并且设置 PassQueryString 为 true,则跳转的 Location 头中会添加此请求参数。

否

响应

响应头

该接口仅返回常用响应头部。

响应体

该接口不返回响应体。

示例

请求示例

示例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

存在以下场景:

  • 重定向规则的数量(RoutingRule)超过50个。

  • 参数值为空、无效、不合法、重复。

  • 缺少必填参数。

  • 同时设置ReplaceKeyPrefixWith 和 ReplaceKeyWith。

  • 桶不支持开启静态网站托管功能。仅2026年8月3日及之后创建的桶,支持使用静态网站功能,2026年8月3日前创建的桶,不支持使用静态网站功能。

文档导读
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈