GCS对象签名URL自定义元数据不生效、content-length-range限制异常咨询

问题根因与解决方案 #

1. 自定义元数据未写入GCS #

原因

• 你当前使用POST方法生成签名URL，withExtHeaders配置的扩展头需要客户端在发起上传请求时严格携带对应x-goog-meta-*请求头，缺少这些头的话GCS会忽略元数据配置，不会写入对象属性。
• 如果你使用的是表单形式的POST上传，自定义元数据不能放在请求头中，需要作为表单字段传递，且签名时需要将这些字段纳入策略校验范围。

解决方案

• 若使用POST表单上传：将x-goog-meta-*参数改为表单字段，签名时使用SignUrlOption.withPostPolicyV2()方法配置策略，把自定义元数据字段加入策略的允许/强制字段列表。
• 若使用标准HTTP POST上传：要求客户端上传时必须携带你返回的additionalHeaders里所有的x-goog-meta-*请求头，不能遗漏。
• 也可以直接改用PUT方法生成签名URL，PUT方法下withExtHeaders配置的自定义头只要签名时包含，客户端上传时携带对应头即可生效，逻辑更简单。

2. content-length-range限制不生效 #

原因

• 和元数据问题同理，你只是把x-goog-content-length-range加入了扩展头，既没有在签名策略中强制要求该头存在，客户端上传时也没有携带该头，GCS自然不会触发大小校验。
• POST方法下x-goog-content-length-range的限制需要写入签名的策略条件中，不能仅作为扩展头配置。

解决方案
使用POST策略签名时，在策略中添加content-length-range条件，示例配置：

PostPolicyV2.PostPolicyV2Builder policyBuilder = PostPolicyV2.builder()
    .setBucket(gcpStorageBucket)
    .setObject(storageDocument.getPath())
    .setContentLengthRange(0, maxFileSizeMb * 1048576);
// 加入自定义元数据的匹配条件
policyBuilder.addCustomFieldMatch("x-goog-meta-" + usernameKey, username);
if (StringUtils.hasText(purpose)) {
    policyBuilder.addCustomFieldMatch("x-goog-meta-" + purposeKey, purpose);
}
options.add(Storage.SignUrlOption.withPostPolicyV2(policyBuilder.build()));

配置后GCS会强制校验上传文件大小，不需要客户端额外携带头，只要超出范围就会直接拒绝上传。

3. 上传较大文件时报Metadata part is too large #

原因

• GCS规定POST表单上传时，除文件内容外的所有表单字段总大小不能超过8KiB，如果你把大量元数据字段、签名参数都加入表单，累积大小超过限制就会触发该报错。
• 另一个常见原因是客户端上传时Content-Type设置错误，没有正确配置multipart/form-data和边界值，导致GCS把整个请求（包括文件内容）当成元数据解析，自然会触发大小超限。

解决方案

• 精简上传时的表单字段，只保留必要的策略字段、签名字段和自定义元数据字段，不要冗余参数。
• 要求客户端上传时必须正确设置Content-Type为multipart/form-data; boundary=xxx，边界值要和请求体中的分隔边界完全一致。
• 如果上传文件普遍较大，建议改用PUT方法的签名URL配合分块上传，不会有表单元数据大小限制。

内容的提问来源于stack exchange，提问作者Moritz Schmitz v. Hülst