手把手教你安装与配置 GitLab Runner – wiki基地

作者： /

手把手教你安装与配置 GitLab Runner：从零到一构建强大的 CI/CD 流水线

引言：为什么需要 GitLab Runner？

在现代软件开发实践中，持续集成（Continuous Integration, CI）和持续部署（Continuous Deployment, CD）是不可或缺的一环。它们是 DevOps 文化的核心，旨在通过自动化构建、测试和部署流程，来提高开发效率、保障代码质量并加速产品交付。GitLab 作为一款一体化的 DevOps 平台，其内置的 GitLab CI/CD 功能异常强大和灵活。

然而，GitLab CI/CD 的所有自动化任务（我们称之为 “Jobs”）都需要一个执行环境。这个执行环境，就是 GitLab Runner。

简单来说，GitLab Runner 是一个独立的应用程序，它扮演着“工人”或“执行者”的角色。它会主动向你的 GitLab 实例轮询，询问：“有新的任务需要我处理吗？”。一旦 GitLab 上有新的 Pipeline（流水线）被触发，GitLab 就会根据 .gitlab-ci.yml 文件中的定义，将具体的 Job 分配给一个或多个符合条件的 Runner。Runner 接收到任务后，会在其所在的机器上创建一个隔离的环境，然后执行你在 .gitlab-ci.yml 文件中定义的脚本命令，例如拉取代码、安装依赖、运行测试、构建应用、打包镜像、部署到服务器等。

可以把 GitLab 实例比作“指挥中心”，.gitlab-ci.yml 文件是“作战计划”，而 GitLab Runner 就是在前线冲锋陷阵的“士兵”。没有 Runner，再完美的作战计划也只是纸上谈兵。

本文将以“手把手”的方式，详细引导你完成从准备工作、安装、注册，到高级配置和实际测试的全过程，帮助你彻底掌握 GitLab Runner，为你搭建稳定、高效的 CI/CD 流水线打下坚实的基础。

第一部分：准备工作

在开始安装之前，请确保你已经准备好以下条件：

  1. 一个 GitLab 实例：

    • 你可以使用官方的 gitlab.com（SaaS服务）。
    • 或者你已经部署了自己的私有 GitLab 实例（Self-hosted）。
    • 无论哪种，你都需要有足够的权限（至少是 Maintainer 级别）来访问项目的 CI/CD 设置，以便获取注册 Runner 所需的令牌（Token）。如果你想注册共享型 Runner，则需要 GitLab 的管理员权限。

  2. 一台用于安装 Runner 的服务器/虚拟机/PC：

    • 强烈建议将 GitLab Runner 安装在与 GitLab 实例不同的机器上。这基于安全和性能的双重考量：
      • 安全隔离：CI/CD 任务可能会执行一些高风险操作，将其与你的 GitLab 主服务分离，可以有效防止潜在的安全风险扩散。
      • 资源隔离：CI/CD 任务通常是资源密集型的（CPU、内存、I/O），将其分离可以避免 Runner 的高负载影响 GitLab 服务的稳定性。
    • 这台机器可以是物理服务器、云主机（如阿里云 ECS、腾讯云 CVM）、虚拟机（如 VMware、VirtualBox），甚至是你的个人开发电脑。
    • 操作系统：GitLab Runner 支持多种操作系统，包括 Linux、macOS 和 Windows。本文将以 Ubuntu 20.04/22.04 (Debian系) 为例进行演示，因为这是服务器环境中最常见的选择之一。其他系统的安装方式大同小异，可参考官方文档。

  3. Root 或 Sudo 权限：

    • 你需要在 Runner 的安装机器上拥有 root 或 sudo 权限，以便安装软件和配置系统服务。

  4. 网络连接：

    • 安装 Runner 的机器必须能够通过网络访问到你的 GitLab 实例的 URL。如果是 gitlab.com，则需要能访问外网。如果是私有 GitLab，则需要确保内网或专线网络通畅。

第二部分：安装 GitLab Runner

我们将使用 GitLab 官方推荐的方式，通过添加其软件源来进行安装。这样做的好处是方便后续的更新和管理。

步骤一：添加 GitLab 官方软件源

打开你的 Ubuntu/Debian 服务器终端，执行以下命令来下载并运行 GitLab 的安装脚本。这个脚本会自动检测你的系统版本，并添加相应的 APT 软件源。

“`bash

下载官方安装脚本

curl -L “https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh” | sudo bash
“`

这条命令的解释：
* curl -L ...：curl 是一个强大的网络请求工具，-L 参数表示如果遇到重定向，会自动跟随。这里用它来下载脚本内容。
* | (管道符)：将 curl 下载的脚本内容直接传递给下一个命令。
* sudo bash：以 sudo（超级用户）权限执行 bash 解释器，运行从管道接收到的脚本内容。

脚本执行成功后，你的系统就已经配置好了 GitLab Runner 的官方软件源。

步骤二：安装 GitLab Runner 软件包

现在，你可以像安装其他任何软件包一样，使用 apt 命令来安装 GitLab Runner。

“`bash

更新软件包列表并安装 gitlab-runner

sudo apt-get update
sudo apt-get install gitlab-runner
“`

安装过程会自动完成以下工作：
* 下载并安装 GitLab Runner 的二进制可执行文件（通常在 /usr/bin/gitlab-runner）。
* 创建一个名为 gitlab-runner 的系统用户，Runner 服务将以此用户身份运行。
* 将 GitLab Runner 配置为一个系统服务（通常是 systemd 服务），并设置为开机自启。

步骤三：验证安装

安装完成后，我们可以通过几个命令来验证是否成功。

  1. 查看版本号：

    bash
    gitlab-runner --version

    如果看到类似 Version: 15.x.x 的输出，说明二进制文件已成功安装并加入了系统路径。

  2. 查看服务状态：

    bash
    gitlab-runner status
    或者使用 systemd 的命令：
    bash
    sudo systemctl status gitlab-runner
    如果看到 active (running) 的字样，说明 GitLab Runner 服务已经成功启动并正在后台运行。

至此，GitLab Runner 软件本身已经成功安装到你的服务器上了。但它现在还只是一个“待命”的工人，并不知道要去为哪个“指挥中心”（GitLab 实例）服务。下一步，就是“注册”。

第三部分：注册 GitLab Runner

注册，就是将我们安装好的 Runner 与特定的 GitLab 项目、群组或整个实例关联起来的过程。

步骤一：理解 Runner 类型并获取注册信息

在注册之前，你需要决定这个 Runner 的服务范围。GitLab Runner 分为三种类型：

  1. Specific Runner (特定项目 Runner)：

    • 作用范围：只为一个特定的项目服务。
    • 适用场景：当某个项目有特殊的构建环境、依赖或安全需求时使用。这是最常用的一种类型。
    • 获取信息：进入你的 GitLab 项目 -> Settings -> CI/CD -> 展开 Runners 面板。你会在这里看到该项目专属的 注册 URL 和 注册令牌 (registration token)。

  2. Group Runner (群组 Runner)：

    • 作用范围：为一个群组（Group）下的所有项目服务。
    • 适用场景：当一个团队或部门的多个项目共享相似的构建流程和环境时，可以提高管理效率。
    • 获取信息：进入你的 GitLab 群组 -> Settings -> CI/CD -> 展开 Runners 面板。

  3. Shared Runner (共享 Runner)：

    • 作用范围：为整个 GitLab 实例的所有项目服务（除非项目明确禁用了共享 Runner）。
    • 适用场景：适用于通用的、无特殊要求的构建任务，可以被实例中的任何项目使用。gitlab.com 就提供了大量免费的共享 Runner。
    • 获取信息：需要管理员权限。进入 GitLab Admin Area -> CI/CD -> Runners。

我们以最常见的 Specific Runner 为例。 请根据上面的路径，在你的 GitLab 项目中找到注册 URL 和 Token，并复制下来备用。

步骤二：运行交互式注册命令

回到你的 Runner 服务器终端，执行以下命令启动交互式注册流程：

bash
sudo gitlab-runner register

接下来，终端会依次向你提问，你需要根据提示输入信息：

  1. Enter the GitLab instance URL:
    输入你刚刚在 GitLab 页面上看到的 URL。例如：https://gitlab.com/ 或 http://your-private-gitlab.example.com/。
    Enter the GitLab instance URL (for example, https://gitlab.com/):
    https://gitlab.com/

  2. Enter the registration token:
    输入你复制的项目注册令牌。
    Enter the registration token:
    glrt-xxxxxxxxxxxxxxxxxxxx

  3. Enter a description for the runner:
    为这个 Runner 起一个有意义的名字，方便你在 GitLab UI 中辨认。例如：my-project-builder-ubuntu。
    Enter a description for the runner:
    my-project-builder-ubuntu

  4. Enter tags for the runner:
    这是非常重要的一步！ 标签（Tags）用于将 CI Job 精确地分配给特定的 Runner。你可以输入一个或多个标签，用逗号分隔。例如，你可以根据操作系统、环境或能力来打标签：docker,linux,ubuntu,build。在 .gitlab-ci.yml 文件中，你可以通过 tags 关键字指定 Job 必须由包含特定标签的 Runner 来执行。
    Enter tags for the runner (comma-separated):
    docker,linux,build

  5. Enter optional maintenance note for the runner:
    可选的维护说明，可以直接回车跳过。

  6. Enter an executor:
    这是最核心的配置！ 执行器（Executor）决定了 Runner 如何执行你的 Job。不同的执行器有不同的隔离级别和功能。
    常见的 Executor 有：

    • shell: 直接在 Runner 所在的宿主机上执行脚本。优点是简单直接，性能好。缺点是缺乏隔离，所有 Job 共享宿主机的环境，容易造成依赖冲突和安全问题。不推荐在生产环境或共享环境中使用。
    • docker: 强烈推荐！ 每个 Job 都会在一个全新的、干净的 Docker 容器中运行。优点是环境隔离性极好，依赖通过 Docker 镜像管理，安全可靠，是目前最主流的选择。
    • docker-windows: docker executor 的 Windows 版本。
    • kubernetes: 将每个 Job 作为 Pod 在 Kubernetes 集群中运行，适用于大规模、高弹性的 CI/CD 系统。
    • virtualbox, parallels: 在虚拟机中运行 Job，隔离性最强，但资源开销和启动速度也最大。

    我们选择 docker。
    Enter an executor: docker, ssh, virtualbox, kubernetes, custom, parallels, shell, docker-windows:
    docker

  7. Enter the default Docker image:
    如果你选择了 docker 作为执行器，系统会要求你提供一个默认的 Docker 镜像。当 .gitlab-ci.yml 中的 Job 没有指定 image 时，就会使用这个默认镜像。你可以根据你项目的主要技术栈来选择，例如 node:16-alpine, ruby:3.0, python:3.9-slim。这里我们使用一个轻量的 alpine 镜像作为示例。
    Enter the default Docker image (for example, ruby:2.7):
    alpine:latest

输入最后一个信息后，回车。如果一切顺利，你会看到 Runner registered successfully. 的提示。

步骤三：验证注册结果

  1. 检查配置文件：
    注册成功后，所有的配置信息都会被写入到 GitLab Runner 的主配置文件 /etc/gitlab-runner/config.toml 中。你可以查看这个文件：
    bash
    sudo cat /etc/gitlab-runner/config.toml
    你会看到类似下面这样的内容，其中包含了全局设置和一个 [[runners]] 配置块，对应你刚刚注册的 Runner。

  2. 刷新 GitLab 页面：
    回到你刚才获取 Token 的 GitLab 页面，刷新一下。你应该能在 “Available specific runners” 列表中看到你新注册的 Runner。它前面会有一个绿色的圆点，表示它处于在线和活动状态。

第四部分：config.toml 配置文件详解

虽然交互式注册很方便，但要进行更精细的控制，你需要了解并手动编辑 /etc/gitlab-runner/config.toml 文件。

一个典型的 config.toml 示例如下：

“`toml

全局配置

concurrent = 4 # 这台机器上所有 Runner 并发执行 Job 的最大数量
check_interval = 0 # Runner 向 GitLab 轮询新 Job 的频率（秒），0 表示尽快
log_level = “info” # 日志级别

[session_server]
session_timeout = 1800

Runner 配置块，可以有多个

[[runners]]
name = “my-project-builder-ubuntu”
url = “https://gitlab.com/”
id = 12345
token = “xxxxxxxxxxxxxxxxxxxx” # 注意：这是 Runner 专属的认证 token，不是注册 token
token_obtained_at = “2023-10-27T10:00:00Z”
executor = “docker”
[runners.custom_build_dir]
[runners.cache] # 缓存配置
[runners.cache.s3]
[runners.cache.gcs]
[runners.cache.azure]
[runners.docker] # Docker Executor 的专属配置
tls_verify = false
image = “alpine:latest” # 默认镜像
privileged = false # 是否以特权模式运行容器，构建 Docker 镜像时可能需要设为 true
disable_entrypoint_overwrite = false
oom_kill_disable = false
disable_cache = false
volumes = [“/cache”] # 挂载卷，可以用于缓存或共享 Docker socket
shm_size = 0
“`

关键配置项解读：
* concurrent: 非常重要的性能参数。表示这台机器上总共可以同时运行多少个 Job。你需要根据服务器的 CPU 核心数和内存大小来合理设置。例如，一台 4 核 8G 内存的服务器，设置为 4 是一个不错的起点。
* [[runners]]: 每个 [[runners]] 代码块代表一个已注册的 Runner。你可以在同一台机器上注册多个 Runner（例如，一个用 Docker，一个用 Shell），它们会各自拥有一个配置块。
* [runners.docker] 部分：
* image: 默认的 Docker 镜像。
* privileged: 是否启用特权模式。当你需要在 CI Job 中构建 Docker 镜像时（Docker-in-Docker, or DinD），通常需要将此项设为 true，并配合 volumes = ["/var/run/docker.sock:/var/run/docker.sock"] 来共享宿主机的 Docker 服务。请注意，这有严重的安全隐患，请谨慎使用。
* volumes: 用于将宿主机的目录挂载到 Job 的容器中。除了共享 Docker Socket，最常见的用途是持久化缓存。

修改完 config.toml 文件后，需要重启 GitLab Runner 服务使配置生效：
bash
sudo systemctl restart gitlab-runner

第五部分：创建 .gitlab-ci.yml 测试 Runner

现在万事俱备，只欠东风。让我们在项目中创建一个简单的 .gitlab-ci.yml 文件来验证我们的 Runner 是否能正常工作。

在你的 GitLab 项目根目录下，创建（或修改）名为 .gitlab-ci.yml 的文件，内容如下：

“`yaml

定义流水线的各个阶段

stages:
– build
– test

第一个 Job，属于 build 阶段

build-job:
stage: build
tags:
– docker # 关键！指定这个 Job 必须由带有 “docker” 标签的 Runner 执行
script:
– echo “Hello, this is the build job.”
– echo “I am running on a Runner with the ‘docker’ tag.”
– echo “Compiling the code…”
– sleep 10
– echo “Build complete.”

第二个 Job，属于 test 阶段

test-job:
stage: test
tags:
– docker # 同样指定给我们的 Runner
script:
– echo “Hello, this is the test job.”
– echo “Running unit tests…”
– uname -a # 查看容器的内核信息
– cat /etc/os-release # 查看容器的操作系统信息
– echo “Tests passed.”
“`

文件解析：
* stages: 定义了流水线执行的顺序，这里先执行 build 阶段的所有 Job，成功后再执行 test 阶段的所有 Job。
* build-job 和 test-job: 定义了两个具体的任务。
* tags: ["docker"]: 这是连接计划与执行者的关键。它告诉 GitLab，这个 Job 必须 分配给一个拥有 docker 标签的 Runner。这正是我们刚才注册时设置的标签！
* script: 定义了 Job 要执行的 shell 命令列表。

将这个文件提交并推送到你的 GitLab 仓库。推送后，GitLab 会自动检测到 .gitlab-ci.yml 文件并触发一个新的流水线。

进入项目的 CI/CD -> Pipelines 页面，你会看到一个新的流水线正在运行。点击进去，可以看到 build-job 正在被执行。在 Job 详情页的右侧，你可以看到是哪个 Runner（我们刚注册的那个）在处理这个任务。等待 Job 执行完成，日志会实时打印在页面上，你可以看到我们 script 中定义的 echo 命令的输出。

当 build-job 成功后，test-job 会自动开始。一切顺利的话，整个流水线会显示为 passed。恭喜你，你的 GitLab Runner 已经成功配置并完成了它的第一个任务！

第六部分：高级主题与最佳实践

  • 安全第一：尽量避免使用 shell executor。使用 docker executor 时，谨慎开启 privileged 模式。为不同的项目或团队设置不同的 Specific/Group Runner，以实现权限隔离。
  • 善用缓存：对于需要反复下载的依赖（如 Node.js 的 node_modules，PHP 的 vendor），使用 GitLab CI 的 cache 关键字可以极大地提升流水线速度。
  • 并发与性能调优：根据你的服务器硬件配置，合理调整 config.toml 中的 concurrent 值。同时，在 [[runners]] 级别，也可以通过 limit 参数来限制单个 Runner 的并发数。
  • 维护与清理：Docker executor 会在宿主机上留下很多无用的容器和镜像。定期运行 docker system prune -a 等命令来清理，可以释放大量磁盘空间。
  • 监控：GitLab Runner 提供了 Prometheus 指标，你可以将其接入你的监控系统，来监控 Runner 的健康状况和负载情况。

总结

搭建 GitLab Runner 是实现自动化 CI/CD 的第一步，也是最关键的一步。通过本文的详细介绍，你应该已经掌握了从安装、注册到配置和测试 GitLab Runner 的全套流程。你现在拥有了一个强大的自动化引擎，可以开始探索更多复杂的 CI/CD 场景，如自动化测试、Docker 镜像构建、多环境部署等。

GitLab CI/CD 的世界广阔而深邃，而 Runner 则是你探索这个世界的可靠伙伴。不断实践，不断优化，你将能构建出真正符合你团队需求的、高效稳定的自动化工作流，从而在 DevOps 的道路上走得更远。

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部