AWS CDK 中 Docker 镜像推送至 ECR 失败的排查与解决方案

在 AWS CDK 项目中使用 ecs.ContainerImage.fromAsset() 方法时，开发者可能会遇到 Docker 镜像推送至 ECR 失败的问题，错误提示为 fail: docker push to ecr unexpected status from PUT request 400 Bad Request。本文将深入分析该问题的成因，并提供多种解决方案。

问题背景

当开发者尝试通过 AWS CDK 部署包含 Docker 镜像的 ECS 服务时，CDK 会自动构建镜像并推送至 ECR。然而在某些环境下，这一过程会失败，具体表现为：

1. 使用 CDK 版本 2.177.0 及以上时出现 400 错误
2. 错误信息指向 ECR 的 PUT 请求失败
3. 手动使用 Docker CLI 推送镜像却能成功

根本原因分析

经过社区和 AWS 团队的调查，发现问题主要与以下因素相关：

1. Docker Desktop 的 containerd 存储驱动：新版本 Docker Desktop 默认启用了 containerd，这与 CDK 的镜像推送流程存在兼容性问题。

2. BuildKit 的 provenance 特性：Docker 的 BuildKit 在构建时会默认生成 provenance 元数据（证明信息），这些附加数据可能导致 ECR 拒绝接收。

3. 0 字节镜像问题：在某些情况下，错误的推送会导致 ECR 中残留 0 字节的镜像，这些无效镜像会"占用"合法的镜像哈希值，导致后续部署失败。

解决方案

方案一：修改 Docker 配置

1. 禁用 containerd 存储驱动：

   • 打开 Docker Desktop 设置
   • 在 General 选项卡中取消勾选 "Use containerd for pulling and storing images"
   • 重启 Docker 服务

2. 禁用 BuildKit 的 provenance： 在构建命令中添加 --provenance=false 参数，或设置环境变量：

   export DOCKER_BUILDKIT=0
   

方案二：清理 ECR 仓库

1. 登录 AWS 控制台，导航到 ECR 服务
2. 找到 CDK 使用的镜像仓库（通常以 cdk/assets 开头）
3. 删除所有 0 字节大小的镜像
4. 删除状态异常的镜像

方案三：替代 Docker 环境

对于 macOS 用户，可以考虑使用替代方案如 Colima：

brew install colima
colima start

方案四：升级 CDK 版本

AWS 团队已在后续版本中修复此问题，建议升级至最新版 CDK：

npm update -g aws-cdk

技术深度解析

当 CDK 执行 fromAsset() 方法时，底层会执行以下流程：

1. 使用 docker build 构建镜像
2. 通过 docker login 获取 ECR 临时凭证
3. 执行 docker push 推送镜像

问题主要出现在第 3 步，当 Docker 尝试推送包含额外元数据的镜像时，ECR 的服务端验证会拒绝这些不符合规范的请求。值得注意的是，这种错误具有以下特点：

• 环境依赖性：仅影响特定 Docker 版本和配置
• 缓存影响：失败的推送仍会生成缓存记录，导致后续部署跳过构建阶段
• 隐式错误：表面上是 400 错误，实际可能由多种因素导致

最佳实践建议

1. 环境一致性：团队内部应统一 Docker 版本和配置
2. 监控 ECR：定期检查 ECR 中的镜像状态
3. 构建日志：在 CI/CD 流程中详细记录构建和推送日志
4. 回滚机制：准备旧版本 CDK 的安装包以备紧急回滚

通过以上分析和解决方案，开发者应能有效解决 AWS CDK 中 Docker 镜像推送至 ECR 失败的问题。AWS 团队已将该修复纳入后续版本，建议关注官方更新公告以获取最新进展。