如何在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 在阶段间传递产物。

如何在Ubuntu上配置GitLab CI/CD

最新问答

相关标签