Runner基础 #

一、什么是GitLab Runner？ #

GitLab Runner是执行GitLab CI/CD作业的应用程序，它从GitLab获取作业并在指定环境中执行。

text

┌─────────────────────────────────────────────────────────────┐
│                    GitLab CI/CD 架构                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              GitLab Server                           │   │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐             │   │
│  │  │ 代码仓库 │  │ CI/CD   │  │  作业   │             │   │
│  │  │         │  │ 配置    │  │  队列   │             │   │
│  │  └─────────┘  └─────────┘  └─────────┘             │   │
│  └─────────────────────────────────────────────────────┘   │
│                            │                                │
│                            │ 分配作业                        │
│                            ▼                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              GitLab Runner                           │   │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐             │   │
│  │  │ Executor│  │ Executor│  │ Executor│             │   │
│  │  │ (Shell) │  │(Docker) │  │  (K8s)  │             │   │
│  │  └─────────┘  └─────────┘  └─────────┘             │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
└─────────────────────────────────────────────────────────────┘

二、Runner类型 #

1. Shared Runner（共享Runner） #

所有项目都可以使用
由GitLab管理员配置
适合公共构建环境

2. Group Runner（组Runner） #

组内所有项目可用
由组管理员配置
适合团队共享环境

3. Specific Runner（特定Runner） #

只为特定项目服务
由项目管理员配置
适合特殊构建需求

Runner类型对比 #

类型	可用范围	管理者	适用场景
Shared	所有项目	系统管理员	公共构建环境
Group	组内项目	组管理员	团队共享环境
Specific	特定项目	项目管理员	特殊构建需求

三、Executor类型 #

1. Shell Executor #

直接在Runner主机上执行命令：

yaml

job_name:
  tags:
    - shell
  script:
    - npm test

优点：

配置简单
性能高
无需容器知识

缺点：

环境隔离差
需要手动管理依赖
安全风险较高

2. Docker Executor #

在Docker容器中执行：

yaml

job_name:
  image: node:18
  tags:
    - docker
  script:
    - npm test

优点：

环境隔离好
可重现构建
易于管理依赖

缺点：

需要Docker知识
性能略有损耗
需要管理镜像

3. Docker Machine Executor #

自动创建Docker虚拟机：

优点：

自动扩缩容
弹性资源
支持多云平台

缺点：

配置复杂
需要云平台支持

4. Kubernetes Executor #

在Kubernetes集群中执行：

yaml

job_name:
  image: node:18
  tags:
    - kubernetes
  script:
    - npm test

优点：

自动扩缩容
资源利用率高
适合大规模部署

缺点：

需要K8s知识
配置复杂

5. VirtualBox/Parallels Executor #

在虚拟机中执行：

优点：

完全隔离
安全性高

缺点：

性能损耗大
管理复杂

Executor对比 #

Executor	隔离性	性能	复杂度	适用场景
Shell	低	高	低	简单构建
Docker	中	中	中	标准构建
Docker Machine	中	中	高	弹性构建
Kubernetes	高	高	高	大规模部署
VirtualBox	高	低	高	安全构建

四、安装Runner #

Linux安装 #

bash

# Debian/Ubuntu
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
sudo apt-get install gitlab-runner

# CentOS/RHEL
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh | sudo bash
sudo yum install gitlab-runner

macOS安装 #

bash

# 使用Homebrew
brew install gitlab-runner

# 启动服务
brew services start gitlab-runner

Windows安装 #

powershell

# 下载安装包
# https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-windows-amd64.exe

# 安装服务
.\gitlab-runner-windows-amd64.exe install
.\gitlab-runner-windows-amd64.exe start

Docker安装 #

bash

# 创建配置目录
mkdir -p /srv/gitlab-runner/config

# 启动Runner容器
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

Kubernetes安装 #

bash

# 添加Helm仓库
helm repo add gitlab https://charts.gitlab.io

# 安装Runner
helm install --namespace gitlab-runner gitlab-runner gitlab/gitlab-runner \
  --set gitlabUrl=https://gitlab.example.com \
  --set runnerRegistrationToken=YOUR_TOKEN

五、注册Runner #

获取注册信息 #

进入项目Settings → CI/CD → Runners
展开"Specific runners"部分
复制注册令牌

交互式注册 #

bash

sudo gitlab-runner register

# 输入GitLab URL
Enter the GitLab instance URL:
https://gitlab.example.com

# 输入注册令牌
Enter the registration token:
YOUR_REGISTRATION_TOKEN

# 输入描述
Enter a description for the runner:
my-runner

# 输入标签
Enter tags for the runner (comma-separated):
docker,linux

# 选择执行器
Enter an executor:
docker

# 输入默认镜像
Enter the default Docker image:
node:18

非交互式注册 #

bash

sudo gitlab-runner register \
  --non-interactive \
  --url https://gitlab.example.com \
  --registration-token YOUR_REGISTRATION_TOKEN \
  --executor docker \
  --docker-image node:18 \
  --description "my-runner" \
  --tag-list "docker,linux" \
  --run-untagged="true"

Docker容器注册 #

bash

docker exec -it gitlab-runner gitlab-runner register \
  --non-interactive \
  --url https://gitlab.example.com \
  --registration-token YOUR_REGISTRATION_TOKEN \
  --executor docker \
  --docker-image node:18 \
  --description "docker-runner"

六、Runner命令 #

基本命令 #

bash

# 检查状态
sudo gitlab-runner status

# 启动Runner
sudo gitlab-runner start

# 停止Runner
sudo gitlab-runner stop

# 重启Runner
sudo gitlab-runner restart

# 查看版本
sudo gitlab-runner --version

管理命令 #

bash

# 列出所有Runner
sudo gitlab-runner list

# 验证配置
sudo gitlab-runner verify

# 注销Runner
sudo gitlab-runner unregister --name my-runner

# 注销所有Runner
sudo gitlab-runner unregister --all-runners

调试命令 #

bash

# 检查配置
sudo gitlab-runner check

# 以调试模式运行
sudo gitlab-runner --debug run

七、Runner标签 #

标签作用 #

标签用于将作业分配给特定的Runner：

yaml

job_name:
  tags:
    - docker
    - linux
  script:
    - npm test

配置标签 #

bash

sudo gitlab-runner register \
  --tag-list "docker,linux,production"

运行无标签作业 #

Runner可以配置为运行没有标签的作业：

bash

sudo gitlab-runner register \
  --run-untagged="true"

八、Runner配置文件 #

配置文件位置 #

Linux: /etc/gitlab-runner/config.toml
macOS: /usr/local/etc/gitlab-runner/config.toml
Windows: C:\ProgramData\gitlab-runner\config.toml

基本配置 #

toml

concurrent = 4

[[runners]]
  name = "my-runner"
  url = "https://gitlab.example.com"
  token = "YOUR_TOKEN"
  executor = "docker"
  [runners.docker]
    image = "node:18"
    privileged = false
    disable_cache = false
    volumes = ["/cache"]

Docker Executor配置 #

toml

[[runners]]
  name = "docker-runner"
  executor = "docker"
  [runners.docker]
    image = "node:18"
    privileged = true
    disable_cache = false
    volumes = [
      "/var/run/docker.sock:/var/run/docker.sock",
      "/cache:/cache"
    ]
    pull_policy = ["if-not-present"]
    allowed_images = ["node:*", "python:*"]

Kubernetes Executor配置 #

toml

[[runners]]
  name = "kubernetes-runner"
  executor = "kubernetes"
  [runners.kubernetes]
    namespace = "gitlab-runner"
    image = "node:18"
    privileged = true

九、最佳实践 #

1. 选择合适的Executor #

text

简单构建 → Shell Executor
标准构建 → Docker Executor
大规模部署 → Kubernetes Executor

2. 使用标签管理 #

yaml

# 生产环境Runner
tags:
  - production
  - docker

# 测试环境Runner
tags:
  - staging
  - docker

3. 配置并发限制 #

toml

concurrent = 4

[[runners]]
  limit = 2

4. 使用缓存 #

toml

[[runners]]
  [runners.docker]
    disable_cache = false
    volumes = ["/cache:/cache"]

5. 安全配置 #

toml

[[runners]]
  [runners.docker]
    allowed_images = ["node:*", "python:*"]
    allowed_services = ["postgres:*", "redis:*"]
    pull_policy = ["always"]

十、常见问题 #

1. Runner无法连接GitLab #

检查：

网络连接
URL是否正确
防火墙设置

2. Job一直pending #

检查：

Runner是否在线
标签是否匹配
并发限制

3. Docker权限问题 #

toml

[[runners]]
  [runners.docker]
    privileged = true
    volumes = ["/var/run/docker.sock:/var/run/docker.sock"]

下一步 #

现在你已经了解了Runner基础，接下来让我们学习 Runner配置！