GitLab CI/CD部署AWS EC2报错“aws: not found”求排查

问题根源 #

1. job镜像覆盖全局镜像：你全局指定了带AWS CLI的amazon/aws-cli:latest，但build和deploy job都单独用了docker:latest——这个镜像里根本没装AWS CLI，自然会报"aws: not found"。
2. 凭证硬编码风险：配置里直接写死AWS密钥，既不安全也不符合GitLab最佳实践，应该用CI/CD变量存储。
3. before_script未生效：因为每个job都替换了镜像，全局的before_script不会在build/deploy阶段执行，ECR登录步骤等于缺失。
4. deploy逻辑错误：当前deploy是在GitLab Runner环境里执行docker命令，而非目标EC2实例，根本无法控制EC2上的容器。

修复后的完整配置 #

# 全局使用带AWS CLI的镜像，后续安装Docker满足构建需求
image: amazon/aws-cli:latest

stages:
  - build
  - deploy

variables:
  AWS_DEFAULT_REGION: "ap-northeast-2"
  AWS_ECR_REGION: "us-east-1"
  ECR_REGISTRY: "public.ecr.aws/{here_id}"
  # AWS密钥从GitLab CI/CD变量读取，禁止硬编码！

before_script:
  # 给aws-cli镜像安装Docker（默认未预装）
  - yum install -y docker
  - service docker start
  # 登录ECR公有仓库
  - aws ecr-public get-login-password --region $AWS_ECR_REGION | docker login --username AWS --password-stdin $ECR_REGISTRY

build:
  stage: build
  script:
    - docker build -t frontend_repo .
    - docker tag frontend_repo:latest $ECR_REGISTRY/frontend_repo:latest
    - docker push $ECR_REGISTRY/frontend_repo:latest
  only:
    - main
  # 无需单独指定镜像，继承全局配置

deploy:
  stage: deploy
  script:
    # 通过SSH连接到EC2实例执行部署（需提前在GitLab变量中配置EC2的SSH私钥）
    - eval $(ssh-agent -s)
    - echo "$EC2_SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh && chmod 700 ~/.ssh
    - echo "StrictHostKeyChecking no" >> ~/.ssh/config # 生产环境建议手动添加主机密钥到known_hosts
    # 远程执行EC2上的部署命令
    - ssh ec2-user@<你的EC2公网IP> "
        docker stop frontend_container || true;
        docker rm frontend_container || true;
        docker rmi $ECR_REGISTRY/frontend_repo:latest || true;
        # 若EC2已绑定IAM角色，此处无需密钥即可登录ECR
        aws ecr-public get-login-password --region $AWS_ECR_REGION | docker login --username AWS --password-stdin $ECR_REGISTRY;
        docker pull $ECR_REGISTRY/frontend_repo:latest;
        docker run -t -d -p 80:3000 --restart unless-stopped --name frontend_container $ECR_REGISTRY/frontend_repo:latest;
        docker logs frontend_container
      "
  only:
    - main

必做的额外配置 #

• GitLab变量设置：进入项目Settings > CI/CD > Variables，添加以下受保护变量：
  • AWS_ACCESS_KEY_ID：你的AWS访问密钥ID
  • AWS_SECRET_ACCESS_KEY：你的AWS秘密访问密钥
  • EC2_SSH_PRIVATE_KEY：连接EC2的SSH私钥文本
• EC2权限优化：给EC2实例绑定IAM角色，添加AmazonEC2ContainerRegistryPublicReadOnly权限，这样EC2无需存储AWS密钥即可拉取ECR镜像。
• 可选优化：嫌每次安装Docker麻烦的话，可以使用自带Docker和AWS CLI的自定义镜像，减少构建耗时。

内容的提问来源于stack exchange，提问作者Vlad Skoromnyi