GitLab Runner 自动化部署配置

GitLab CI/CD 是 GitLab 内置的持续集成与持续部署平台，而 GitLab Runner 是执行 CI/CD 任务的核心组件。通过在搬瓦工 VPS 上部署 GitLab Runner，你可以实现代码推送后自动构建、测试和部署的完整流程。本文将详细讲解 Runner 的安装、注册与 Pipeline 配置。

一、环境要求

操作系统：Ubuntu 20.04+ 或 Debian 11+。
内存：至少 1GB，推荐 2GB 以上。
Docker：推荐使用 Docker 执行器（需先安装 Docker）。
GitLab 实例：GitLab.com 或自建 GitLab 均可。

搬瓦工 VPS 购买地址：bwh81.net，使用优惠码 NODESEEK2026 享受 6.77% 折扣。

二、安装 GitLab Runner

2.1 方式一：包管理器安装

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | bash
apt install gitlab-runner -y

2.2 方式二：Docker 安装

docker run -d \
  --name gitlab-runner \
  --restart=always \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest

2.3 验证安装

gitlab-runner --version
gitlab-runner status

三、注册 Runner

3.1 获取注册令牌

3.2 执行注册命令

gitlab-runner register

按提示依次输入：

GitLab URL：https://gitlab.com/（或你的自建 GitLab 地址）。
Registration token：粘贴刚才复制的令牌。
Description：为 Runner 起个描述名称。
Tags：添加标签，如 docker,linux，用于在 CI 配置中指定使用哪个 Runner。
Executor：选择 docker（推荐）。
Default Docker image：输入 alpine:latest。

3.3 Docker 方式注册

docker exec -it gitlab-runner gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "YOUR_TOKEN" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "bwg-runner" \
  --tag-list "docker,linux" \
  --run-untagged="true"

四、编写 .gitlab-ci.yml

在项目根目录创建 .gitlab-ci.yml 文件定义 CI/CD 流水线：

stages:
  - build
  - test
  - deploy

variables:
  APP_NAME: "my-app"

build:
  stage: build
  image: node:18-alpine
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour

test:
  stage: test
  image: node:18-alpine
  script:
    - npm ci
    - npm run test
  coverage: '/Lines\s*:\s*(\d+\.?\d*)%/'

deploy_staging:
  stage: deploy
  image: alpine:latest
  before_script:
    - apk add --no-cache openssh-client rsync
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | ssh-add -
  script:
    - rsync -avz --delete dist/ user@staging-server:/var/www/app/
  environment:
    name: staging
  only:
    - develop

deploy_production:
  stage: deploy
  image: alpine:latest
  before_script:
    - apk add --no-cache openssh-client rsync
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | ssh-add -
  script:
    - rsync -avz --delete dist/ user@production-server:/var/www/app/
  environment:
    name: production
  only:
    - main
  when: manual

五、Docker 镜像构建与部署

使用 Docker-in-Docker（DinD）在 CI 中构建和推送容器镜像：

build_image:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
  only:
    - main

六、Runner 配置优化

编辑 Runner 配置文件以优化性能：

vim /etc/gitlab-runner/config.toml

关键配置项：

concurrent = 4
check_interval = 3

[[runners]]
  name = "bwg-runner"
  url = "https://gitlab.com/"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    volumes = ["/cache"]
    shm_size = 0
    pull_policy = ["if-not-present"]
  [runners.cache]
    Type = "local"
    Path = "/cache"
    Shared = true

concurrent：并发执行任务数量，根据 VPS 配置调整。
pull_policy：设置为 if-not-present 避免重复拉取镜像。
volumes：配置缓存卷加速依赖安装。

七、CI/CD 变量管理

在 GitLab 项目的 Settings → CI/CD → Variables 中添加敏感变量：

SSH_PRIVATE_KEY：部署用的 SSH 私钥。
DOCKER_USER / DOCKER_PASS：Docker Hub 登录凭据。
DEPLOY_SERVER：部署目标服务器地址。

设置变量时勾选"Protected"确保只在受保护分支中可用，勾选"Masked"在日志中隐藏变量值。

八、常见问题

Runner 未出现在项目中

gitlab-runner verify
gitlab-runner restart

检查注册令牌是否正确，以及 Runner 到 GitLab 服务器的网络连接是否正常。

Docker executor 权限不足

如果遇到 Docker socket 权限问题：

usermod -aG docker gitlab-runner
systemctl restart gitlab-runner

构建缓存无效

确保 config.toml 中配置了缓存路径，并在 .gitlab-ci.yml 中使用 cache 关键字：

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
    - .npm/

总结

GitLab Runner 配合 GitLab CI/CD 可以实现功能强大的自动化工作流。通过合理配置执行器和缓存策略，可以显著提升构建部署效率。搬瓦工 VPS 提供稳定可靠的运行环境，选购方案请参考全部方案，使用优惠码 NODESEEK2026 享受 6.77% 折扣。