07. Runner 装不好？GitLab Runner 单机/分布式/高可用全攻略

发表于 2026-11-14 分类于 GitLab

Runner 是流水线的发动机，装错就跑不起来。本文覆盖注册、标签、并发、分布式与高可用部署，让你在哪都能跑起 CI。

「GitLab」系列已发布： 00. GitLab 不只是代码托管：一套 DevOps 平台的 6 大核心能力｜ 01. GitLab 怎么装最省心？Omnibus/Docker/K8s 三种姿势｜ 02. 装完 GitLab 先配啥？管理员视角的初始化设置清单｜ 03. GitLab 角色搞不清？Member/Maintainer/Owner 权限全解｜ 04. 从零建好第一个 GitLab 项目：权限、变量、CI 配置入门｜ 05. GitLab MR 代码审查：Code Review 最佳实践｜ 06. CI/CD 到底是什么？GitLab 流水线架构从概念到实战｜ 07. Runner 装不好？GitLab Runner 单机/分布式/高可用全攻略（本文）

Runner 是流水线的发动机，装错就跑不起来。本文覆盖注册、标签、并发、分布式与高可用部署，让你在哪都能跑起 CI。

前置条件

已完成 GitLab 安装部署（第 01 篇），理解 CI/CD 基本概念（第 06 篇）。需要一台独立服务器（Linux/macOS/Windows 都行）来装 Runner。

一、Runner 安装

1.1 Linux (Debian/Ubuntu)

# 加 GitLab 官方仓库
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash

# 安装
sudo apt install gitlab-runner

# 启动并设置开机自启
sudo systemctl start gitlab-runner
sudo systemctl enable gitlab-runner

1.2 macOS

brew install gitlab-runner
brew services start gitlab-runner

1.3 Windows

从 https://gitlab.com/gitlab-org/gitlab-runner/-/releases 下载 .exe 文件，双击安装。

二、Runner 注册

2.1 获取 Registration Token

GitLab 项目 → Settings → CI/CD → Runners → Expand 复制 token。

2.2 执行注册

sudo gitlab-runner register

# 输入 GitLab 地址
Please enter the gitlab-url: https://gitlab.example.com

# 输入 token
Please enter the gitlab-token: xxxxxx

# 输入描述
Please enter the description: my-runner

# 输入 tags
Please enter the tags: docker,linux

# 选择执行器
Please enter the executor: docker

2.3 配置 Docker 执行器


# /etc/gitlab-runner/config.toml
[[runners]]
  name = "my-runner"
  url = "https://gitlab.example.com"
  token = "xxx"
  executor = "docker"
  [runners.docker]
    image = "ubuntu:22.04"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0

三、常用命令


# 查看 Runner 状态
sudo gitlab-runner verify

# 停止 Runner
sudo gitlab-runner stop

# 启动 Runner
sudo gitlab-runner start

# 重启 Runner
sudo gitlab-runner restart

# 卸载 Runner
sudo gitlab-runner uninstall

# 查看日志
sudo gitlab-runner logs

四、执行器类型

执行器	说明	适用场景
shell	直接在宿主机执行	简单项目、调试
docker	Docker 容器执行	主流选择
kubernetes	K8s Pod 执行	云原生环境
docker+machine	Docker + 动态机器	大规模并发

4.1 Docker 执行器配置详解

[runners.docker]
  image = "node:18"                    # 默认镜像
  privileged = false                   # 是否特权模式（Docker in Docker）
  disable_entrypoint_overwrite = false # 不覆盖镜像入口点
  oom_kill_disable = false             # 不禁用 OOM killer
  disable_cache = false                # 启用缓存
  volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"]
  shm_size = 2147483648                # /dev/shm 大小 2GB

4.2 Kubernetes 执行器配置

[runners.kubernetes]
  namespace = "gitlab-runner"
  image = "ubuntu:22.04"
  service_account = "gitlab-runner"
  cpu_limit = "2"
  memory_limit = "4Gi"

五、Runner 类型

5.1 实例级 Runner

注册到整个 GitLab 实例
可被所有项目使用
Admin Area → Runners

5.2 项目级 Runner

注册到特定项目
仅该项目的 Pipeline 可用
Settings → CI/CD → Runners

flowchart TD
    A[GitLab 实例] --> B[实例级 Runner]
    A --> C[项目 A]
    A --> D[项目 B]
    C --> E[项目级 Runner]
    D --> F[项目级 Runner]
    
    B -->|可被所有项目使用| C
    B -->|可被所有项目使用| D
    E -->|仅项目 A 可用| C
    F -->|仅项目 B 可用| D

六、最佳实践

分组管理：按执行器类型分组（Docker、K8s、Shell）
Tag 策略：为不同 runner 打 tag，Job 指定 tag 执行
资源监控：监控 Runner 的 CPU、内存、磁盘使用
自动缩放：大规模并发时使用 Kubernetes 或 Docker Machine

七、文章引用

📌 本文首发于微信公众号 【运维知识点滴】——专注运维实战干货，微信搜索“运维知识点滴”或扫下方二维码关注，更新不迷路。

微信公众号【运维知识点滴】	微信小程序【A5单据合并&大试卷拆分转A4打印】

运维实战干货 · 关注追更	Word 转 PDF · 试卷/发票打印神器 · 免费

💡 小程序【A5单据合并&大试卷拆分转A4打印】是干嘛的？ 一个 Word 转 PDF 的打印神器，专治“文档版式和打印机对不上”：

A3 试卷打不出来？ 学校发的电子版试卷多是 A3，家用打印机只吃 A4——上传 Word 一键转换：可缩到一页 A4（页数不变），也可对半拆成两张 A4（1:1 原大、字更清晰），两种模式自选；

版式不乱：真实渲染引擎原样转换、绝不重排内容，转出的 PDF 和原 Word 排版一致，公式/表格/图片不跑版；

两张 A5 单据拼一张 A4：出租车票、火车票等报销凭证拼版后，一次打印、整齐粘贴；

隐私省心：无需注册，转换结果留存 5 天、最多下载 5 次即自动删除，不留任何历史记录；

微信扫码即用，免费、免安装，支持 doc / docx（≤50MB）。

上一篇：06. CI/CD 到底是什么？GitLab 流水线架构从概念到实战