如何在GitLab CI中使用docker-compose远程部署及多版本配置

一、核心结论 #

完全可以通过GitLab CI运行docker-compose脚本完成远程部署，下面是具体实现步骤和多版本配置方案。

二、部署到远程服务器的具体步骤 #

1. 配置远程服务器的SSH访问权限 #

在GitLab项目的「Settings → CI/CD → Variables」中添加以下变量（敏感变量勾选「Mask variable」）：

• SSH_PRIVATE_KEY：远程服务器的SSH私钥（用于CI环境免密登录）
• REMOTE_HOST：远程服务器的IP或域名
• REMOTE_USER：远程服务器的登录用户名

2. 编写GitLab CI的deploy阶段配置 #

使用包含docker、docker-compose和ssh工具的镜像（比如官方docker:latest镜像，通过apk补充安装依赖），在脚本中完成SSH信任配置、文件传输、远程执行docker-compose命令。

示例gitlab-ci.yml配置：

stages:
  - deploy

deploy_image:
  stage: deploy
  image: docker:latest
  before_script:
    # 安装依赖工具
    - apk add --no-cache docker-compose openssh-client
    # 配置SSH免密登录
    - mkdir -p ~/.ssh
    - echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
    - chmod 600 ~/.ssh/id_rsa
    - ssh-keyscan -H "$REMOTE_HOST" >> ~/.ssh/known_hosts
  script:
    # 将本地docker-compose配置传到远程服务器部署目录
    - scp docker-compose.yml $REMOTE_USER@$REMOTE_HOST:/opt/myapp/
    # 远程执行部署命令：停止旧服务、拉取新镜像、启动新服务
    - ssh $REMOTE_USER@$REMOTE_HOST "cd /opt/myapp/ && docker-compose down && docker-compose pull && docker-compose up -d"
  only:
    - main # 指定触发部署的分支，可根据需求修改

三、针对不同构建版本使用不同docker-compose配置 #

有两种常用方案，可根据场景选择：

方案1：多配置文件分支匹配 #

针对不同环境（生产/测试）或版本，编写独立的docker-compose配置文件（比如docker-compose.prod.yml、docker-compose.staging.yml），在CI中根据分支、标签判断使用哪个配置。

示例CI脚本修改：

script:
  # 根据分支选择对应配置文件
  - if [ "$CI_COMMIT_BRANCH" == "main" ]; then
      CONFIG_FILE="docker-compose.prod.yml";
    elif [ "$CI_COMMIT_BRANCH" == "develop" ]; then
      CONFIG_FILE="docker-compose.staging.yml";
    fi
  # 传输选中的配置文件到远程
  - scp $CONFIG_FILE $REMOTE_USER@$REMOTE_HOST:/opt/myapp/docker-compose.yml
  # 远程执行部署
  - ssh $REMOTE_USER@$REMOTE_HOST "cd /opt/myapp/ && docker-compose down && docker-compose pull && docker-compose up -d"

也可以直接在远程执行时指定配置文件，无需覆盖：

script:
  - scp docker-compose*.yml $REMOTE_USER@$REMOTE_HOST:/opt/myapp/
  - if [ "$CI_COMMIT_BRANCH" == "main" ]; then
      ssh $REMOTE_USER@$REMOTE_HOST "cd /opt/myapp/ && docker-compose -f docker-compose.prod.yml down && docker-compose -f docker-compose.prod.yml pull && docker-compose -f docker-compose.prod.yml up -d";
    else
      ssh $REMOTE_USER@$REMOTE_HOST "cd /opt/myapp/ && docker-compose -f docker-compose.staging.yml down && docker-compose -f docker-compose.staging.yml pull && docker-compose -f docker-compose.staging.yml up -d";
    fi

方案2：环境变量动态替换 #

在基础的docker-compose.yml中使用环境变量占位，在CI中根据构建版本（标签/分支）设置对应变量，远程执行时注入变量生效。

示例docker-compose.yml：

services:
  app:
    image: myapp:${IMAGE_TAG} # 镜像标签由环境变量控制
    ports:
      - "${APP_PORT}:80" # 端口由环境变量控制

示例CI脚本修改：

script:
  # 根据标签或分支设置镜像标签
  - if [ "$CI_COMMIT_TAG" ]; then
      IMAGE_TAG="$CI_COMMIT_TAG";
    else
      IMAGE_TAG="$CI_COMMIT_BRANCH";
    fi
  # 传输基础配置文件到远程
  - scp docker-compose.yml $REMOTE_USER@$REMOTE_HOST:/opt/myapp/
  # 注入环境变量执行部署
  - ssh $REMOTE_USER@$REMOTE_HOST "cd /opt/myapp/ && IMAGE_TAG=$IMAGE_TAG APP_PORT=8080 docker-compose down && docker-compose pull && docker-compose up -d"

注意事项 #

• 远程服务器需提前安装docker和docker-compose，且登录用户需拥有docker命令执行权限（可将用户加入docker组）。
• 若使用私有镜像仓库，需在远程服务器或CI环境中提前完成docker login配置（可在CI变量中添加仓库用户名和密码，脚本中执行登录命令）。
• 敏感变量（如SSH私钥、仓库密码）需在GitLab CI变量中勾选「Mask variable」，避免泄露。

内容的提问来源于stack exchange，提问作者Roman Adigezalov