Jenkins从节点推送镜像至ECR失败：无基础认证凭证排查

这种情况我之前帮不少开发者排查过，ECR插件本身是支持从节点推送的，问题大概率出在你的从节点环境没拿到正确的认证信息，或者配置有遗漏。咱们一步步拆解可能的原因和解决办法：

1. 确保ECR登录操作在从节点执行 #

ECR插件的登录动作是和执行节点绑定的——你在主节点登录时，认证信息只会存在主节点的~/.docker/config.json里，从节点完全拿不到。所以必须把登录步骤指定到从节点上运行：

• 如果是自由风格项目，给ECR登录步骤设置节点标签，约束它在目标从节点执行；
• 如果是流水线，把登录步骤放在从节点的agent块里，确保上下文是从节点环境。

2. 检查从节点的Docker配置权限 #

CloudBees Build and Publish插件依赖从节点本地的Docker客户端配置文件（~/.docker/config.json），如果出现权限问题，插件就读不到认证信息：

• 确认Jenkins agent的运行用户有权限读取~/.docker/config.json（比如如果Docker用root运行，而Jenkins agent是普通用户，更安全的做法是把Jenkins用户加入docker组，而非直接用root运行agent）；
• 可以在从节点手动执行ECR提供的临时登录命令，再跑docker push测试，如果命令行能成功，说明认证没问题，问题出在插件配置。

3. 验证环境变量是否正确继承 #

ECR登录后会设置DOCKER_CONFIG等环境变量，告诉Docker客户端去哪里找认证信息。如果从节点的Jenkins agent没继承这些变量，CloudBees插件就会找不到凭证：

• 在流水线里加一步打印环境变量的操作（比如sh 'printenv'），检查是否存在DOCKER_CONFIG，且指向的目录包含正确的config.json；
• 如果没有这个变量，可以手动在登录步骤后设置，比如sh 'export DOCKER_CONFIG=$HOME/.docker'。

4. 换用原生Docker命令验证 #

如果上面的方法都没解决，可以暂时绕过CloudBees插件，直接用原生Docker命令在从节点执行构建和推送：

docker build -t your-ecr-repo/your-image:tag .
docker push your-ecr-repo/your-image:tag

• 如果命令行能成功推送，说明是CloudBees插件的配置问题（比如没指定正确的Docker registry地址，或者没关联ECR的凭证）；
• 如果命令行也失败，那就是从节点的ECR登录没生效，需要重新检查登录步骤的配置。

流水线示例（Declarative Pipeline） #

给你一个完整的流水线示例，确保所有步骤都在从节点执行：

pipeline {
  agent { label 'your-slave-node-label' }
  environment {
    ECR_REPO = '123456789012.dkr.ecr.us-east-1.amazonaws.com/your-image'
    AWS_REGION = 'us-east-1'
  }
  stages {
    stage('ECR Login') {
      steps {
        script {
          // 这里的登录会在从节点执行，自动生成config.json
          docker.withRegistry("https://${ECR_REPO}", "ecr:${AWS_REGION}:your-jenkins-ecr-credential-id") {
            echo "Successfully logged into ECR on slave node"
          }
        }
      }
    }
    stage('Build & Push') {
      steps {
        cloudBeesDockerBuildAndPublish(
          repositoryName: "${ECR_REPO}",
          tag: "${BUILD_NUMBER}",
          dockerFile: 'Dockerfile',
          registryCredentialsId: "ecr:${AWS_REGION}:your-jenkins-ecr-credential-id"
        )
      }
    }
  }
}

内容的提问来源于stack exchange，提问作者Franz Ebner