RustFS 预签名上传 URL 如何限定最大上传大小
RustFS 预签名上传 URL 如何限定最大上传大小
如果你的后端服务浏览器端上传,常见需求是:签发的预签名 URL 不能被客户端用来上传任意大的文件。RustFS 提供两个 RustFS 专属的查询参数解决这个问题——x-rustfs-max-content-length 限制单个 PutObject 请求能上传的字节数,x-rustfs-max-total-object-size 限制一次分片上传(multipart upload)的最终对象总大小。两者都只能挂在 SigV4 预签名请求上,超限的请求会被服务端拒绝并返回 EntityTooLarge,对象不会被发布。
这两个机制的完整规则见 docs/operations/presigned-size-limits.md,服务端实现入口在 rustfs/src/auth.rs(参数解析)与 rustfs/src/app/object/put.rs(MaxContentLengthStream 流式截断)。
两个参数的适用场景
| V1 单请求 | V2 单上传 | |
|---|---|---|
| 查询参数 | x-rustfs-max-content-length=<u64> |
x-rustfs-max-total-object-size=<u64> |
| 接受在 | 仅 SigV4 预签名 PutObject |
仅 CreateMultipartUpload(签名或预签名 SigV4) |
| 其他操作携带该参数 | InvalidRequest(CopyObject、multipart、GET、HEAD、DELETE、bucket 操作) |
InvalidRequest(UploadPart、CompleteMultipartUpload、AbortMultipartUpload、列操作、copy——这些读的是持久化的会话状态) |
| 计量对象 | 该请求解码后的请求体字节 | 各分片逻辑对象字节(actual_size)之和;不含纠删、加密或压缩引入的字节 |
| 限制存放位置 | 仅该请求 | multipart 会话元数据(SUFFIX_MAX_TOTAL_OBJECT_SIZE),创建时写入 |
| 超限结果 | EntityTooLarge;对象不发布 |
出问题的 UploadPart 返回 EntityTooLarge;若已记录分片总和超限,CompleteMultipartUpload 同样被拒 |
选哪个取决于上传方式:一次性 PUT 用 V1,浏览器分片上传大文件用 V2。
共用的签名规则(两个参数都适用)
这四条规则决定了参数“写在什么时候、怎么写才有效”:
- 后端必须在计算 SigV4 预签名之前把参数追加到请求 URI 上。它是规范化查询串的一部分,签完后追加、删除或修改都会使签名失效,浏览器因此无法篡改该限制。
- RustFS 只在请求被确认为 SigV4 已签名(
VerifiedPresignedRequest/VerifiedSigV4Request请求标记)之后才解析该参数。未签名的请求携带同样查询串会被InvalidRequest拒绝。 - 取值必须是无符号 64 位整数。重复、大小写变体、格式错误、负数或溢出值都返回
InvalidRequest。参数名区分大小写,必须精确为x-rustfs-max-content-length。 - 不携带参数的请求(普通认证或匿名上传)行为不变。
限定单请求上传大小:x-rustfs-max-content-length
文档给出的签发流程(V1 示例,来自 docs/operations/presigned-size-limits.md):
uri = "/photos/avatar.png"
uri += "?x-rustfs-max-content-length=10485760"
presigned_url = sigv4_presign("PUT", uri, credentials)
# Return presigned_url to the browser. Never append the parameter afterwards.
要点:
- 参数在
sigv4_presign("PUT", uri, credentials)之前拼入 URI;签名完成后绝不追加。10485760(10 MiB)是文档示例值,按业务上限替换。 - 行为分两种:请求声明的
Content-Length超过上限时,在写入存储之前就被拒绝;若请求体实际流式发送的字节数超过上限,连接以EntityTooLarge截断,且对象不会被发布。 - 仅限单请求:它不是跨多次 PUT 的累计上限,也不是分片上传上限。
- 不能与归档自动解包(
x-amz-meta-snowball-auto-extract)组合,会返回InvalidRequest。 - 未知长度和 SigV4 streaming-chunked 上传仍在既有 PutObject 准入契约之外,该参数不会使它们可用。
如果后端用 AWS SDK 签发 URL,可在 presign 请求的查询参数中带上 x-rustfs-max-content-length(AWS SDK 的 presigner 支持自定义查询参数,签名会覆盖它)。仓库的 e2e 用例 crates/e2e_test/src/presigned_negative_test.rs 展示了用 aws_sdk_s3::presigning::PresigningConfig 对预签名 URL 做签名与重放的完整接线方式,可作参考。
限定分片上传总大小:x-rustfs-max-total-object-size
文档给出的签发流程(V2 示例):
uri = "/photos/archive.zip?uploads"
uri += "&x-rustfs-max-total-object-size=104857600"
presigned_url = sigv4_presign("POST", uri, credentials)
# Return presigned_url to the browser. Never append the parameter afterwards.
参数只加在 CreateMultipartUpload 这一步(POST /<bucket>/<key>?uploads)。后续流程:
- RustFS 校验 SigV4 请求后,把上限随 upload ID 持久化。
- 浏览器用返回的 upload ID 上传各 part,part 请求本身不携带任何自定义参数。
- 每次
UploadPart(以及指向该上传的UploadPartCopy)只有在“当前累计逻辑总量 + 本分片大小”不超过预算时才被放行。覆盖已存在的 part 号采用替换语义:先释放旧 part 占用的大小,再准入新 part 的大小。 CompleteMultipartUpload会对已记录的分片重新求和,超过上限则拒绝完成。
带上限上传的几个属性:
- 未知长度或负长度的 part 会以
UnexpectedContent拒绝,而不是无界缓冲。 - 未声明长度的分片请求不会被无上限缓存;带上限的 part 在创建临时分片前先获取上传级写锁准入,并持有 per-upload staging 许可以限制本地在途数据。读取请求体期间锁会释放,最终校验和 rename 前再重新获取,因此
Complete和Abort不会被慢上传卡住;客户端停发时,请求体 stall 超时会释放 staging 许可。 - 创建时未携带参数的上传保持无上限。
- 强制检查在 multipart 数据面每个节点执行。滚动升级期间,只把带上限的上传路由到已带 V2 实现的节点;没有该实现的节点会把内部元数据当作未知处理,无法执行限制。
如何验证生效
文档定义的判定标准都体现在 S3 错误码上,用客户端直接观察响应即可:
- 参数没参与签名(或事后追加):请求因签名不匹配被拒绝——这正是该机制的安全设计,客户端无法修改限制值。
- 参数格式非法(重复、大小写变体、负数、溢出、非 u64):返回
InvalidRequest。 - 参数挂在错误的操作上(如
CopyObject、UploadPart):返回InvalidRequest。 - 声明
Content-Length超限 / 分片累计超限:返回EntityTooLarge,对象不发布。 - 分片长度未知或为负:返回
UnexpectedContent。
仓库回归套件 crates/e2e_test/src/presigned_negative_test.rs 的做法值得照搬:向真实服务器发送被拒绝的预签名请求,断言 HTTP 状态码和响应 XML 中的 <Code>...</Code>(如 <Code>EntityTooLarge</Code>、<Code>InvalidRequest</Code>),以此固定拒绝契约,而不依赖底层由谁完成校验。
限制与边界
- 这两个查询参数是 RustFS 专属扩展,不属于 S3 标准参数;参数名区分大小写且只能出现一次。
- V1 参数只对预签名
PutObject生效,普通认证请求携带它同样会被InvalidRequest拒绝。 - 限制计量的是逻辑数据量:V1 计量解码后的请求体字节,V2 计量各分片
actual_size之和,均不含纠删、加密或压缩引入的开销。 - V2 依赖所有节点都具备该实现(
multipart_max_total_object_size/multipart_size_limit_from_metadata,见 crates/ecstore/src/set_disk/ops/multipart.rs);混合版本滚动升级期间,带上限的上传必须只路由到新节点。 - 服务端参数解析细节(
parse_presigned_put_max_content_length、parse_presigned_multipart_max_total_object_size)位于 rustfs/src/auth.rs,V1 的流式截断由MaxContentLengthStream(rustfs/src/app/object/put.rs)实现,需要深入排障时可从这两处入手。