2、GitLab Runner部署：Runner类型选择（Shell/Docker/Kubernetes），在Linux/Mac/Windows上安装Runner，注册Runner到GitLab

好，咱们接着聊。上一章我们把GitLab CI的核心概念理清了，这一章就该动手了——部署Runner。

Runner是什么？说白了，它就是替你跑CI/CD任务的“苦力”。你写好了.gitlab-ci.yml，总得有人去执行吧？这个执行者就是Runner。我个人习惯把Runner想象成一个“流水线工人”，你告诉它干什么（Job），它就去干，干完汇报结果。

2.1 Runner类型选择：Shell、Docker、Kubernetes

GitLab Runner支持多种执行环境，也就是“干活的方式”。我挑最常用的三种来讲：Shell、Docker、Kubernetes。

类型 原理 隔离性 适用场景
Shell 直接在宿主机上执行命令 无隔离 简单任务、本地调试、资源受限环境
Docker 每个Job启动一个容器执行 容器级隔离 标准化环境、多项目并行、依赖隔离
Kubernetes 在K8s集群中动态创建Pod执行 Pod级隔离 大规模集群、弹性伸缩、云原生场景

Shell Runner：最简单粗暴。你想想看，它直接在机器上跑命令，跟你在终端里敲命令没区别。我在项目中遇到过，有些嵌入式开发板资源极其有限，装Docker都费劲，这时候Shell Runner反而是最靠谱的选择。但要注意——它没有隔离性，一个Job把环境搞乱了，下一个Job就遭殃。

Docker Runner：这是我最推荐的方式。每个Job启动一个独立的容器，环境完全隔离。你可以在.gitlab-ci.yml里指定image: ubuntu:20.04，Runner就会拉取这个镜像来执行任务。干净、可重复、不互相污染。

Kubernetes Runner：如果你公司已经有K8s集群，那这个就是王炸。Runner会自动向K8s申请Pod资源，任务跑完自动释放。我曾经帮一个团队从20台物理机迁移到K8s，Runner数量从固定20个变成了动态伸缩，高峰期自动扩展到50个，低谷期缩到5个，省了不少钱。

我的建议：

  • 个人项目或小团队：用Docker Runner，省心
  • 嵌入式开发板/资源受限：用Shell Runner，轻量
  • 中大型团队/云原生：用Kubernetes Runner，弹性

2.2 在Linux上安装Runner

Linux是我最常用的环境，也是嵌入式开发的主力。安装过程其实很简单，但有几个坑我得提前告诉你。

先下载二进制文件：

# 下载GitLab Runner二进制文件
sudo curl -L --output /usr/local/bin/gitlab-runner \
    "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64"

# 赋予执行权限
sudo chmod +x /usr/local/bin/gitlab-runner

# 创建GitLab CI用户
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

# 安装并启动服务
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

嗯，这里要注意：--user=gitlab-runner这个参数很关键。我曾经犯过一个错误，直接用root用户安装Runner，结果所有Job都以root权限运行，差点把系统搞崩。后来我学乖了，一定创建一个专用用户，权限最小化。

避坑指南：

我曾经在嵌入式ARM开发板上安装Runner，发现官方没有提供ARM版本的二进制文件。后来我改用gitlab-runner-arm这个分支，才搞定。如果你也遇到类似情况，记得去GitLab的S3存储桶里找对应架构的版本。

2.3 在macOS上安装Runner

macOS用户通常是用作开发机，或者跑一些iOS相关的构建任务。安装方式有两种：Homebrew和手动安装。

方式一：Homebrew（推荐）

# 安装
brew install gitlab-runner

# 启动服务
brew services start gitlab-runner

方式二：手动安装

# 下载
sudo curl --output /usr/local/bin/gitlab-runner \
    "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-darwin-amd64"

# 赋予权限
sudo chmod +x /usr/local/bin/gitlab-runner

# 安装服务
cd ~/
gitlab-runner install
gitlab-runner start

我个人习惯用Homebrew，因为升级方便。但要注意，macOS的权限管理比较严格，有时候需要去“系统偏好设置-安全性与隐私”里允许Runner运行。

2.4 在Windows上安装Runner

Windows在嵌入式开发中也不少见，尤其是做Windows上位机或者某些特定MCU工具链。安装步骤稍微繁琐一点。

# 以管理员身份打开PowerShell

# 下载
Invoke-WebRequest -Uri "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-windows-amd64.exe" -OutFile "C:\GitLab-Runner\gitlab-runner.exe"

# 安装服务
cd C:\GitLab-Runner\
.\gitlab-runner.exe install

# 启动服务
.\gitlab-runner.exe start

小技巧：

Windows上安装Runner，我建议用非系统盘，比如D盘。为什么？因为Windows更新或者系统还原可能会把C盘的服务搞乱。我吃过这个亏，后来都放D盘了。

2.5 注册Runner到GitLab

安装完Runner，它还是个“光杆司令”。你得把它注册到GitLab，告诉GitLab：“嘿，我这儿有个Runner，可以干活了！”

注册需要两个关键信息：

  • GitLab实例URL：比如 https://gitlab.com/ 或者你们公司的自托管地址
  • 注册令牌（Token）：在GitLab项目或组设置里找到

怎么找Token？去GitLab项目页面 -> Settings -> CI/CD -> Runners -> Expand，你会看到一个“Registration token”。

然后执行注册命令：

sudo gitlab-runner register

# 交互式注册过程如下：
# 1. 输入GitLab实例URL: https://gitlab.com/
# 2. 输入注册令牌: xxxxxxxxxxxxxx
# 3. 输入Runner描述: my-embedded-runner
# 4. 输入标签（可选）: embedded, arm, linux
# 5. 选择执行器: docker
# 6. 输入默认镜像: ubuntu:20.04

注册完成后，你可以在GitLab的Runner列表里看到它。状态应该是“绿色”的，表示在线。

非交互式注册：

如果你要批量部署，可以用一行命令搞定：

sudo gitlab-runner register \
    --non-interactive \
    --url "https://gitlab.com/" \
    --registration-token "xxxxxxxxxxxxxx" \
    --description "docker-runner" \
    --tag-list "docker,linux" \
    --executor "docker" \
    --docker-image "ubuntu:20.04"

我个人习惯用非交互式注册，尤其是在自动化部署脚本里。你想想看，几十台机器一台台手动注册，那不得累死？

2.6 验证Runner是否正常工作

注册完了，怎么知道它能不能用？很简单，跑一个测试Job。

在项目根目录创建一个.gitlab-ci.yml：

test-job:
  script:
    - echo "Hello, GitLab Runner!"
    - uname -a

提交代码，去CI/CD页面看Pipeline。如果Runner正常工作，你会看到Job变成“passed”。

常见问题排查：

  • Runner状态显示“never contacted”：检查网络连通性，确保Runner能访问GitLab服务器
  • Job一直pending：可能是没有匹配的Runner，检查标签是否对应
  • Job失败但没日志：检查Runner的日志，sudo gitlab-runner --debug run可以开启调试模式

好了，这一章的内容就到这里。Runner部署是整个CI/CD流水线的基石，搞定了它，后面的事情就顺理成章了。下一章我们聊聊.gitlab-ci.yml的编写，那才是真正发挥CI/CD威力的地方。

← 上一章 📖 返回目录 下一章 →