RustFS 预签名上传 URL 如何限定最大上传大小

原创2026-09-09 20:09:112,195 阅读
文章标签:对象存储存储云原生分布式文件系统分布式数据库

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。

共用的签名规则(两个参数都适用)

这四条规则决定了参数“写在什么时候、怎么写才有效”:

  1. 后端必须在计算 SigV4 预签名之前把参数追加到请求 URI 上。它是规范化查询串的一部分,签完后追加、删除或修改都会使签名失效,浏览器因此无法篡改该限制。
  2. RustFS 只在请求被确认为 SigV4 已签名(VerifiedPresignedRequest / VerifiedSigV4Request 请求标记)之后才解析该参数。未签名的请求携带同样查询串会被 InvalidRequest 拒绝。
  3. 取值必须是无符号 64 位整数。重复、大小写变体、格式错误、负数或溢出值都返回 InvalidRequest。参数名区分大小写,必须精确为 x-rustfs-max-content-length。
  4. 不携带参数的请求(普通认证或匿名上传)行为不变。

限定单请求上传大小: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)。后续流程:

  1. RustFS 校验 SigV4 请求后,把上限随 upload ID 持久化。
  2. 浏览器用返回的 upload ID 上传各 part,part 请求本身不携带任何自定义参数。
  3. 每次 UploadPart(以及指向该上传的 UploadPartCopy)只有在“当前累计逻辑总量 + 本分片大小”不超过预算时才被放行。覆盖已存在的 part 号采用替换语义:先释放旧 part 占用的大小,再准入新 part 的大小。
  4. 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)实现,需要深入排障时可从这两处入手。
登录后查看全文
rustfs