如何在GitLab CI中配置SSH连接公网服务器完成Docker镜像部署

前置准备工作 #

• 生成专用CI登录SSH密钥对（全程无密码），将生成的公钥追加到目标远程服务器登录用户的~/.ssh/authorized_keys文件中，确保该密钥可以正常无交互登录服务器
• 打开GitLab项目的「设置-CI/CD-变量」配置页，新增以下三类敏感变量，全部开启掩码保护，避免内容在CI日志中泄露：
  • SSH_PRIVATE_KEY：对应密钥对的完整私钥内容
  • SSH_USER：远程服务器的登录用户名
  • SSH_HOST：远程服务器的公网IP地址

配置改造步骤 #

1. 首先扩展CI的流水线阶段，在原有build阶段后新增deploy部署阶段
2. 新增独立的deploy任务，任务运行时先在轻量容器中安装SSH客户端，临时加载配置好的私钥，跳过SSH首次连接的交互校验，直接远程登录服务器执行部署动作
3. 保持原有build任务的全部逻辑不变，确保镜像正常构建、推送到GitLab容器仓库

改造后完整的.gitlab-ci.yml内容 #

stages:
  - build
  - deploy
cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - .cache/
build:
  image: docker:19.03.12
  stage: build 
  services:
    - docker:19.03.12-dind
  variables:
    IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t registry.gitlab.com/ossama.mahjour97/test-dockerfile/myimage .
    - docker push registry.gitlab.com/ossama.mahjour97/test-dockerfile/myimage
deploy:
  image: alpine:3.19
  stage: deploy
  # 仅在指定分支触发部署任务，避免测试分支误操作生产服务器
  only:
    - main
  script:
    # 安装SSH客户端依赖
    - apk add --no-cache openssh-client
    # 初始化SSH目录结构，配置私钥文件权限
    - mkdir -p ~/.ssh
    - echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
    - chmod 600 ~/.ssh/id_rsa
    # 跳过首次SSH连接的主机指纹交互校验
    - ssh-keyscan -H $SSH_HOST >> ~/.ssh/known_hosts
    # 远程登录服务器执行部署动作
    - ssh $SSH_USER@$SSH_HOST "
      # 拉取最新镜像
      docker pull registry.gitlab.com/ossama.mahjour97/test-dockerfile/myimage:$CI_COMMIT_REF_SLUG
      # 切换到docker-compose配置目录，重启服务
      cd /opt/your-project-dir && docker-compose up -d --remove-orphans
    "

注意事项 #

• 远程服务器需提前完成基础配置：安装docker、docker-compose，为登录用户配置docker操作权限，提前完成GitLab容器仓库的登录凭据配置，避免远程执行命令时出现权限不足、登录拦截的问题
• 如果远程服务器SSH服务端口不是默认的22，需在ssh命令后追加-p 自定义端口号参数
• 加载私钥时必须将文件权限设置为600，SSH协议会拒绝加载权限过松的私钥文件，否则会出现登录失败的问题
• 所有敏感信息（SSH密钥、服务器IP、用户名）全部通过GitLab CI变量传递，禁止明文写入配置文件

内容的提问来源于stack exchange，提问作者Ossama MAHJOUR