全部文档
当前文档
最近更新时间：2025-06-11 14:16:01
为了方便您更好地使用KS3，最大程度上兼容S3协议，支持更多开源工具KS3对部分API进行兼容性优化。
本次兼容性优化类型主要包括：
【重点关注】规则优化： 优化与S3不一致的行为规则。
体验优化： 优化报错信息，更加明确报错原因。
功能优化： 新增功能点，增加接口的适用场景。
注意：KS3兼容性优化内容可能会对您使用KS3带来影响，敬请谅解。
规则优化-主要改动:
Post Object上传成功状态码 由 200 ok —> 204 No Content
例如：Post Policy中关于success_action_status字段设置返回状态码需重新设置
Put Object ACL 设置无效value值或者value置空，由200 ok—> 400 BadRequest
ACL有效的value值：private、public-read、public-read-write（Bucket支持）
Get/Head分块文件，if-match不匹配，由200 ok—> 412 Precondition Failed
Get/Head分块文件，if-none-match不匹配，由200 ok—> 304 Not Modified
例如：Get/Head分块文件时设置if-match或if-none-match，若条件值不匹配，获取失败
Put Object Copy
修复内容 | case | 原始版本 | 修复版本 |
|---|---|---|---|
Content-Length | 不存在 | 报错，411 Length Required | 可以拷贝成功 |
Put Object ACL
修复内容 | case | 原始版本 | 修复版本 |
|---|---|---|---|
预设header:x-kss-acl设置acl | value置空;value填错 | 200 ok 默认设置private | 报错，400 BadRequest |
Body设置acl | permission为空;permission填错 | 200 ok 默认设置private | 报错，400 BadRequest |
预设header:x-kss-acl & Body 同时设置acl | 同时设置正确值 | 200 ok 默认设置private | 生效优先级设置：Header设置>Body设置 |
预设header:x-kss-acl & Body 同时设置acl | Header置空;Body填错 | 200 ok 默认设置private | 报错，400 BadRequest |
预设header:x-kss-acl & Body 同时设置acl | Header置空;Body正确 | 200 ok 默认设置private | 按照Body设置正确值生效 |
预设header:x-kss-acl & Body 同时设置acl | Header填错 | 200 ok 默认设置private | 报错，400 BadRequest |
预设header:x-kss-acl & Grant Header 同时设置acl | 预设Header置空;Grant Header正确 | 200 ok 默认设置private | 按照Grant Header设置的生效 |
预设header:x-kss-acl & Grant Header 同时设置acl | 预设Header正确;Grant Header置空 | 200 ok 默认设置private | 按照预设Header设置的生效 |
预设header:x-kss-acl & Grant Header 同时设置acl | 两个header均不置空 | 200 ok 默认设置private | 报错，400 Bad Request |
指定以下head头设置ACL | x-kss-grant-read-acp;x-kss-grant-write-acp | 授权不生效，但不报错 | 报错，400 BadRequest |
通过Body授权acl | 授权所有用户公开访问权限 | 授权不生效，但不报错 | 授权成功，Get object acl 包含给匿名用户授予的权限:使用aws签名 group 为aws;使用ks3签名 group 为ks3 |
通过Body授权acl | 授权同权限 包含多个grant | 同权限只有一个grant 生效 | 多个grant可以全部生效&相同授权只保留一个 |
Content-type是否必选 | 不存在;value为空;value填错 | 报错 415 Unsupported Media Type | 不报错，返回200 ok |
Put Object
修复内容 | case | 原始版本 | 修复版本 |
|---|---|---|---|
header:x-kss-acl设置acl | value填错 | 200 ok 默认设置为private | 报错，400 BadRequest |
Post Object
修复内容 | case | 原始版本 | 修复版本 |
|---|---|---|---|
Post上传 | 上传成功状态码 | 200 ok | 204 No Content |
Content-type | header不存在;vlaue错误值;value为空 | 报错，404 NotFound | 报错，412 Precondition Failed |
Put Object Tagiing
修复内容 | case | 原始版本 | 修复版本 |
|---|---|---|---|
请求Body设置tagging | Body不携带namespace | 报错，400 Bad Request | 200 ok |
Content-type | header不存在;vlaue错误值;value为空 | 报错，415 Unsupported Media Type | 报错，412 Precondition Failed |
Get Object
修复内容 | case | 原始版本 | 修复版本 |
|---|---|---|---|
获取分块文件 | if-match、if-none-match的条件值不匹配 | 200 ok | 当if-match条件值为false时，报错 412 Precondition Failed;if-none-match条件值为false时，报错 304 Not Modified |
Put Object Copy
错误原因 | 原始版本 | 修复版本 |
|---|---|---|
源信息（桶或者文件）不存在 | 报错响应Body的Resource显示目标信息 | 报错响应Body的Resource显示源信息 |
Put Object
错误原因 | 原始版本 | 修复版本 |
|---|---|---|
header 设置标签个数超过10个 | Status：400 Bad Request;Code：InvalidTaggingFormat | Status:400 Bad Request;Code:BadRequest;Message:Object tags cannot be greater than 10 |
指定加密值错误 | Status:400 Bad Request;Code:AlgorithmInvalidForS3 | Status:400 Bad Request;Code:InvalidEncryptionAlgorithmError;Message:The encryption method specified is not supported，The valid value is AES256 or SM4 |
Post Object
错误原因 | 原始版本 | 修复版本 |
|---|---|---|
content-type不存在 | Status:404 NotFound;Code:NoSuchBucket | Status:412 Precondition Failed;Code:PreconditionFailed;Message:At least one of the pre-conditions you specified did not hold |
content-type的value错误值 | Status:404 NotFound;Code:NoSuchBucket; | Status:412 Precondition Failed;Code:PreconditionFailed;Message:At least one of the pre-conditions you specified did not hold |
content-type的value置空 | Status:404 NotFound;Code:NoSuchBucket; | Status:412 Precondition Failed;Code:PreconditionFailed;Message:At least one of the pre-conditions you specified did not hold |
Put Object Tagging
错误原因 | 原始版本 | 修复版本 |
|---|---|---|
header 设置标签个数超过10个 | Status:400 Bad Request;Code:InvalidTaggingFormat | Status:400 Bad Request;Code:BadRequest;Message:Object tags cannot be greater than 10 |
Put Object Copy
新增功能点 | 功能细节 |
|---|---|
新增if条件匹配 x-kss-copy-source-if-match;x-kss-copy-source-if-none-match;x-kss-copy-source-if-modified-since;x-kss-copy-source-if-unmodified-since | 匹配，拷贝成功 200 ok;不匹配，报错 412 Precondition Failed;同时出现if-match&if-unmodified-since，以if-match为主;同时出现if-none-match&if-modified-since，以if-none-match为主 |
新增修改acl的header：x-kss-acl | value有效值:private、public-read、public-read-write; value置空或者不带header,200 ok 默认继承源object;value填错，报错，400 BadRequest |
Put Object Tagging
新增功能点 | 功能细节 |
|---|---|
key和value命令规则支持@字符 | key支持设置位置:开头、中间、结尾;value支持设置位置:开头、中间、结尾 |
Get Object Tagging
新增功能点 |
|---|
未设置Tagging,返回Body中增加TagSet |
响应示例：
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Tagging>
<TagSet/>
</Tagging>Get Object
新增功能点 |
|---|
if-match、if-unmodified-since 条件值为false时，增加错误响应Body |
响应示例：
<Error>
<Code>PreconditionFailed</Code>
<Message>At least one of the pre-conditions you specified did not hold</Message>
<Condition>If-Match</Condition>
<RequestId>HR229QH520AKHTJ3</RequestId>
</Error>Get Bucket Location
新增功能点 | 功能细节 |
|---|---|
新增允许二级域名访问 | 允许使用二级域名访问;同时也支持三级域名访问 |
纯净模式