AWS SDK对接MinIO踩坑：AWS_REQUEST_CHECKSUM_CALCULATION

场景：SpringBoot项目使用AWS Java SDK v2对接MinIO对象存储，升级SDK后遇到上传400问题，梳理相关概念、踩坑原因以及解决方案。

1. 什么是 AWS_REQUEST_CHECKSUM_CALCULATION

AWS_REQUEST_CHECKSUM_CALCULATION 是 AWS SDK / AWS‑CLI 的环境变量 ，控制SDK什么时候自动计算请求payload校验和，主要用于S3上传的数据完整性校验；对应的配置文件参数：request_checksum_calculation。环境变量优先级高于配置文件。

配套对偶变量：AWS_RESPONSE_CHECKSUM_VALIDATION，控制响应payload校验。

可选枚举值

WHEN_SUPPORTED（SDK默认值）
只要该API操作支持校验和特性，SDK就自动为请求体计算校验和（S3默认CRC32），带上校验和头部发给服务端做数据完整性校验。

优点：网络传输出错可以尽早发现
缺点：大文件上传场景会增加CPU开销，需要完整读取一遍数据流计算CRC

WHEN_REQUIRED
仅当服务模型强制要求校验和，或者业务代码主动传入校验算法时，SDK才执行校验和计算。
S3场景行为：关闭SDK自动CRC32计算，不再自动生成请求checksum；只有业务代码显式指定ChecksumAlgorithm才开启校验。

优点：降低高并发大文件上传CPU开销
风险：失去SDK层面自动传输完整性保护，业务层需要自己实现完整性校验逻辑

⚠️重要区分两套哈希，非常容易混淆

x‑amz‑content‑sha256：SigV4签名的payload hash；流式上传会使用UNSIGNED‑PAYLOAD。
x‑amz‑checksum‑crc32：AWS新增HTTP Checksum扩展头(CRC32/CRC32C)，由本环境变量控制，不属于原始S3协议强制项。

设置方式

shell环境变量

bash 复制代码

# linux/mac
export AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED

# windows cmd
set AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED

JVM系统属性（Java SDK v2）

properties 复制代码

-Daws.requestChecksumCalculation=WHEN_REQUIRED

aws shared config 文件 ~/.aws/config

ini 复制代码

[default]
request_checksum_calculation = WHEN_REQUIRED
response_checksum_validation = WHEN_REQUIRED

2. MinIO 与 S3协议相关概念

经常看到一句话：MinIO发起S3上传请求，这个口语很容易产生误解。

角色分清

你的应用程序(AWS‑SDK客户端)：发起请求方；
MinIO：S3兼容服务端，接收上传请求。

✅真实场景A（绝大多数业务场景）：业务应用使用AWS SDK，endpoint指向MinIO地址，向MinIO做文件上传。很多人口语说成"MinIO发起S3上传请求"，属于口误。

踩坑现象：升级AWS SDK版本之后对接老版本MinIO上传返回400 Bad Request

原因：新版SDK默认WHEN_SUPPORTED，自动带上x‑amz‑checksum‑crc32扩展请求头；老版本MinIO不识别这套AWS扩展header，直接返回400。

解决手段：设置AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED关闭SDK自动追加CRC32扩展头；仅保留基础SigV4签名。
⚠️场景B：MinIO作为客户端向外发起S3上传（桶复制Bucket Replication）

MinIO桶复制场景，是MinIO服务内部内置S3客户端主动向远端存储发起上传。

⚠️重点：MinIO内置客户端不会读取AWS这套环境变量！AWS_REQUEST_CHECKSUM_CALCULATION只属于AWS SDK。桶复制遇到checksum问题需要修改MinIO自身配置。

什么是S3协议？什么叫客户端发出S3协议请求？

S3协议(S3 REST API)：亚马逊AWS定义一套基于HTTP/HTTPS的对象存储API规范。

S3本身是AWS对象存储服务，这套接口对外开放；MinIO、阿里云OSS、腾讯COS都实现这套接口，统称为S3兼容存储 。

S3协议不是独立的网络协议，是跑在HTTP/HTTPS之上应用层API规范；核心包含请求约定、参数、返回格式，最重要是SigV4签名规则。

客户端发出S3协议请求含义
客户端就是我们业务应用程序（Java使用AWS‑SDK）。
上传文件流程简述：
1）SDK组装http请求；
2）按照S3协议规则添加约定http header，核心是SigV4签名Authorization头 ；
3）http/https把请求发送给MinIO服务端。

整个行为称之为客户端发起S3协议请求；抓包看到本质就是普通http报文。
PutObject上传示例关键点：

HTTP方法：PUT
请求头：Authorization: AWS4‑HMAC‑SHA256 Credential=xxx，这就是SigV4签名头，S3协议核心鉴权机制。

x‑amz‑checksum‑crc32属于AWS后续新增扩展头，不是原始S3协议强制头部，老MinIO不识别。

S3协议是不是更安全？

拆解三层概念：SigV4签名、传输层HTTPS、Checksum完整性校验

SigV4签名（S3协议自带安全机制）
客户端使用accessKey/secretKey做HMAC签名；服务端收到请求重新计算签名对比。

作用：

身份认证：网络不会传递明文secretKey；
防篡改：请求元数据(header、url)一旦中间人篡改，签名校验失败服务直接拒绝。

⚠️注意：SigV4签名保护的是请求元数据；流式上传场景使用UNSIGNED‑PAYLOAD，payload内容不参与签名哈希，不会检测网络传输中文件比特翻转损坏。这也是AWS引入checksum扩展的来由，专门做body数据完整性校验。

传输层安全：HTTPS

S3协议本身不强制加密传输！S3只是API规范。

使用http：明文传输，虽然有SigV4签名，可以防篡改但是报文可窃听；
使用https：TLS加密传输，生产环境对接MinIO强烈建议启用https。

checksum扩展 x‑amz‑checksum‑crc32

这是数据完整性能力，不是身份安全认证 ，用来检测网络传输比特翻转，文件字节悄悄损坏。

设置WHEN_REQUIRED关闭自动CRC32之后：SigV4签名、HTTPS加密依然生效，只是失去SDK自动body完整性检测。业务侧需要自己做校验逻辑，例如上传记录MD5，下载后比对MD5。

3. SpringBoot项目踩坑：application.yaml配置不生效问题

现象：在application.yaml配置文件增加配置 request‑checksum‑calculation: WHEN_REQUIRED，运行程序发现并没有生效，SDK依旧发送x‑amz‑checksum‑crc32请求头。

根本原因

request_checksum_calculation 属于 AWS SDK原生配置项，并不是Spring‑Cloud‑AWS内置的spring boot属性。

写在application.yaml仅仅是自定义普通属性；Spring‑Cloud‑AWS不会自动把yaml属性透传给底层AWS SDK，SDK完全看不到这个配置。
SDK读取该配置优先级从高到低：

代码客户端Builder显式设置（最高优先级）
JVM系统属性 -Daws.requestChecksumCalculation=WHEN_REQUIRED
OS环境变量 AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED
aws共享配置文件 ~/.aws/config

补充区分一个容易混淆属性：spring.cloud.aws.s3.checksum‑validation‑enabled，这个是Spring‑Cloud‑AWS自己封装属性，控制的是【响应侧校验】，不能控制请求侧request_checksum_calculation，无法关闭上传自动CRC32。

四种解决方案

方案1 JVM启动参数，全局生效

bash 复制代码

-Daws.requestChecksumCalculation=WHEN_REQUIRED -Daws.responseChecksumValidation=WHEN_REQUIRED

IDEA：Run Configuration → VM options填入；java‑jar启动命令带上参数。

方案2 设置操作系统环境变量

开发IDE配置环境变量；Docker设置容器环境变量；K8s配置pod env。

注意：application.yaml无法直接设置操作系统环境变量。

方案3 Spring自定义Bean，S3ClientCustomizer（推荐，应用内自包含，不依赖外部环境）

Awspring 3.x 提供S3ClientCustomizer，修改S3ClientBuilder的OverrideConfiguration

java 复制代码

import org.springframework.cloud.aws.s3.S3ClientCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration;
import software.amazon.awssdk.core.checksums.RequestChecksumCalculation;
import software.amazon.awssdk.core.checksums.ResponseChecksumValidation;
import software.amazon.awssdk.services.s3.S3ClientBuilder;

@Configuration
public class S3Config {
    @Bean
    public S3ClientCustomizer s3ClientCustomizer() {
        return (S3ClientBuilder builder) -> {
            ClientOverrideConfiguration overrideConfig = builder.overrideConfiguration()
                    .copy(b -> b
                            .requestChecksumCalculation(RequestChecksumCalculation.WHEN_REQUIRED)
                            .responseChecksumValidation(ResponseChecksumValidation.WHEN_REQUIRED)
                    );
            builder.overrideConfiguration(overrideConfig);
        };
    }
}

优点：配置固化代码，部署环境不需要额外修改启动参数、环境变量，对接MinIO场景稳妥。

方案4 使用本机 ~/.aws/config 文件

适合开发机；容器环境一般不建议使用，容器通常不会携带该配置文件。

验证配置是否生效

抓包观察http请求头：

请求头还存在x‑amz‑checksum‑crc32：配置未生效，仍然是默认WHEN_SUPPORTED；
请求头消失：已经切换为WHEN_REQUIRED。

⚠️风险提示：切换WHEN_REQUIRED关闭SDK自动CRC校验后，业务层建议自行实现文件完整性校验逻辑。