如何在Ubuntu上配置GitLab CI/CD

在 Ubuntu 上配置 GitLab CI/CD 的完整步骤

一 环境准备与安装

• 准备一台 Ubuntu 20.04/22.04/24.04 服务器，建议至少 2 核 CPU / 4GB 内存 / 20GB 磁盘，并开放 HTTP/HTTPS/SSH 端口。
• 安装 GitLab Runner（执行 CI/CD 任务的代理）：
  • 安装依赖与仓库：

    sudo apt-get update
    sudo apt-get install -y curl ca-certificates
    curl -L --output /usr/share/keyrings/gitlab-runner-archive-keyring.gpg \
      https://packages.gitlab.com/gitlab/gitlab-runner/gpgkey
    echo "deb [signed-by=/usr/share/keyrings/gitlab-runner-archive-keyring.gpg] \
      https://packages.gitlab.com/gitlab/gitlab-runner/ubuntu $(lsb_release -cs) main" | \
      sudo tee /etc/apt/sources.list.d/gitlab-runner.list > /dev/null
    sudo apt-get update
    

  • 安装 Runner：

    sudo apt-get install -y gitlab-runner
    sudo systemctl enable --now gitlab-runner
    

• 若你同时需要在本机安装 GitLab（自托管实例），可使用官方脚本安装 GitLab CE 并配置 EXTERNAL_URL，安装完成后通过浏览器访问并完成初始化设置。

二 注册 GitLab Runner

• 获取 Runner 注册信息：
  • 使用 GitLab.com：在项目页面进入 Settings → CI/CD → Runners，复制 URL 与 Registration token。
  • 使用 自托管 GitLab：进入 Admin Area → Runners 获取，或在项目级 Runners 页面获取。
• 注册 Runner（交互式）：

  sudo gitlab-runner register
  

  按提示依次输入：
  • GitLab 实例 URL（如：https://gitlab.com 或 https://your-gitlab.example.com）
  • Registration token
  • Runner 描述与标签（如：ubuntu-runner, docker, shell）
  • 执行器（建议优先 docker，或 shell 用于本机脚本）
  • 若选择 docker，指定默认镜像（如 alpine:latest 或 ubuntu:22.04）
• 验证注册结果：

  sudo gitlab-runner list
  

  在 GitLab 项目的 Runners 页面应能看到已注册并 在线 的 Runner。

三 创建 GitLab CI/CD 流水线

• 在项目根目录创建 .gitlab-ci.yml，示例（Node.js + Docker 构建推送）：

  stages:
    - build
    - test
    - deploy
  
  variables:
    NODE_VERSION: "18"
  
  build_job:
    stage: build
    image: node:$NODE_VERSION
    script:
      - npm ci --quiet
      - npm run build --if-present
    artifacts:
      paths:
        - dist/
      expire_in: 1 week
  
  test_job:
    stage: test
    image: node:$NODE_VERSION
    script:
      - npm test -- --ci
  
  deploy_job:
    stage: deploy
    image: docker:24.0
    services:
      - docker:24.0-dind
    variables:
      DOCKER_HOST: tcp://docker:2375
      DOCKER_TLS_CERTDIR: ""
    script:
      - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
      - docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" .
      - docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
    only:
      - main
  

• 将代码推送到仓库后，GitLab 会自动触发流水线，可在 CI/CD → Pipelines 查看任务状态与日志。

四 配置 CI/CD 变量与权限

• 在 GitLab 项目页面进入 Settings → CI/CD → Variables，添加所需变量，例如：
  • CI_REGISTRY_USER / CI_REGISTRY_PASSWORD：用于登录 GitLab 容器镜像仓库（启用 Container Registry 后可用）
  • SSH_PRIVATE_KEY：用于部署到目标服务器的 SSH 登录
  • SERVER_HOST / SERVER_USER：目标部署主机与用户
• 建议将敏感变量标记为 Masked 与（必要时）Protected，仅对受保护分支与受保护 Runner 可见。

五 部署与常见问题排查

• 示例：使用 SSH 部署到生产服务器
  • 在 Variables 中配置 SSH_PRIVATE_KEY，并在 Runner 主机安装公钥到目标服务器 ~/.ssh/authorized_keys。
  • 在 .gitlab-ci.yml 增加部署任务：

    deploy_prod:
      stage: deploy
      image: alpine:latest
      before_script:
        - apk add --no-cache openssh
        - mkdir -p ~/.ssh
        - echo "$SSH_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa
        - chmod 600 ~/.ssh/id_rsa
        - ssh-keyscan -H "$SERVER_HOST" >> ~/.ssh/known_hosts
      script:
        - rsync -avz --delete dist/ "$SERVER_USER@$SERVER_HOST:/var/www/myapp/"
        - ssh "$SERVER_USER@$SERVER_HOST" "sudo systemctl restart myapp || true"
      only:
        - main
    

• 常见问题与处理要点：
  • Runner 离线：检查 gitlab-runner status，确认服务运行与网络连通，必要时执行 gitlab-runner restart。
  • Docker-in-Docker：确保 docker:dind 服务已启用，且设置 DOCKER_TLS_CERTDIR=“”（或正确配置 TLS）；Runner 以 privileged 模式运行更安全。
  • 权限问题：SSH 部署需保证私钥正确、目标主机 authorized_keys 配置无误，且 CI 用户具备相应 sudo 权限（或免密执行特定命令）。
  • 缓存与加速：为 npm/maven/gradle 等添加缓存，提高构建速度；合理使用 artifacts 在阶段间传递产物。