GitLab CI/CD 完全指南：从 Runner 安装到 Pipeline 实践

一、GitLab CI/CD 与 Runner 简介

GitLab CI/CD 是 GitLab 内置的一套强大的持续集成、持续交付和持续部署工具。它通过项目根目录下的一个名为 .gitlab-ci.yml 的文件来定义和管理整个 CI/CD 流水线 (Pipeline)。

GitLab Runner 是执行 .gitlab-ci.yml 文件中定义任务（Jobs）的代理程序。它是一个独立的开源项目，可以安装在与 GitLab 实例不同的服务器上。Runner 接收来自 GitLab 的任务，在指定的环境中执行，并将结果（日志、产物等）回传给 GitLab。

二、安装 GitLab Runner

官方推荐在独立的服务器上安装 GitLab Runner，以避免与 GitLab 实例争抢资源。不建议使用 Docker 或 Kubernetes 安装 Runner，因为这可能会给调用 docker, kubectl 等外部工具带来不便。

1. 使用官方仓库安装 (推荐)

这是在主流 Linux 发行版上最简单的安装方式。

a. 添加 GitLab 官方仓库

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

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

b. 安装 GitLab Runner

# 对于 Debian/Ubuntu/Mint
sudo apt-get install -y gitlab-runner

# 对于 RHEL/CentOS/Fedora
sudo yum install -y gitlab-runner

2. 手动二进制安装

如果你的系统不受支持，或者希望安装特定版本，可以选择手动安装。

# 1. 下载二进制文件 (以 Linux x86-64 为例)
sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64

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

# 3. 创建专用的系统用户
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

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

三、注册 GitLab Runner

安装完成后，你需要将 Runner 注册到你的 GitLab 实例，这样它才能接收任务。

1. 获取注册信息

Runner 分为三种类型，你需要根据需求在 GitLab 界面获取对应的 URL 和 Token。

Shared Runner (共享型): 服务于 GitLab 实例中的所有项目。
- 路径: Admin Area -> CI/CD -> Runners
Group Runner (群组型): 服务于特定群组下的所有项目。
- 路径: Group -> Settings -> CI/CD -> Runners
Specific Runner (特定型): 仅服务于单个项目。
- 路径: Project -> Settings -> CI/CD -> Runners

2. 执行注册命令

在安装了 Runner 的服务器上执行 gitlab-runner register 命令，并根据提示依次输入：

GitLab instance URL: 从 GitLab 界面获取的 URL。
Registration token: 从 GitLab 界面获取的 Token。
Description: Runner 的描述，会显示在 GitLab 界面。
Tags: 为 Runner 打上标签，.gitlab-ci.yml 可以通过 tags 关键字选择在此 Runner 上执行任务。这是实现任务定向分发的关键。
Executor: 选择任务执行器。shell 和 docker 是最常用的两种。
- shell: 直接在 Runner 所在的宿主机上执行命令。简单直接，但隔离性差。
- docker: 在一个临时的 Docker 容器中执行任务。环境隔离，干净可复现。

1 2	sudo gitlab-runner register # ... 按照提示输入信息 ...

四、配置 GitLab Runner

Runner 的主要配置文件位于 /etc/gitlab-runner/config.toml。

1. 调整并发数

默认情况下，一个 Runner 实例只能同时执行一个 Job。你可以通过修改 concurrent 参数来提高并行处理能力。

# /etc/gitlab-runner/config.toml
concurrent = 6 # 全局并发数

[[runners]]
  # ...
  limit = 2 # 单个 runner 的并发数

2. 修改构建目录

默认构建目录在 /home/gitlab-runner，可能会占用大量系统盘空间。建议修改到数据盘。

1 2	# 修改 systemd 服务文件 sudo vim /etc/systemd/system/gitlab-runner.service

在 [Service] 部分添加 Environment="BUILD_DIR=/path/to/your/builds"。

3. 修改运行用户

默认情况下，Runner 使用 gitlab-runner 用户执行任务。如果需要 root 权限，可以修改服务配置。

1 2	# 修改 systemd 服务文件 sudo vim /etc/systemd/system/gitlab-runner.service

将 User=gitlab-runner 修改为 User=root。修改后需要重载服务：

1 2	sudo systemctl daemon-reload sudo systemctl restart gitlab-runner

五、远程部署与 SSH 免密登录

当 CI/CD 流程需要将构建产物部署到其他服务器时，需要配置 Runner 服务器到目标服务器的免密登录。

1. 生成 SSH 密钥

在 Runner 服务器上，切换到 gitlab-runner 用户，并生成 SSH 密钥。

1 2	sudo su - gitlab-runner ssh-keygen -t rsa

2. 配置目标服务器信任

将 Runner 服务器的公钥 (~/.ssh/id_rsa.pub) 内容追加到目标服务器的 ~/.ssh/authorized_keys 文件中。

# 在 Runner 服务器上执行
cat ~/.ssh/id_rsa.pub

# 在目标服务器上执行
echo "ssh-rsa AAAA..." >> ~/.ssh/authorized_keys

3. 设置权限

在目标服务器上，确保 .ssh 目录和 authorized_keys 文件有正确的权限。

1 2	chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys

4. 在 `.gitlab-ci.yml` 中使用

配置完成后，你就可以在脚本中使用 scp 或 ssh 命令进行远程操作了。

deploy_job:
  stage: deploy
  tags:
    - shell-runner
  script:
    - scp ./my-app.jar user@deploy-server:/opt/app/
    - ssh user@deploy-server "systemctl restart my-app"

六、`.gitlab-ci.yml` 语法简介

这是定义 CI/CD 流水线的核心文件，基于 YAML 格式。

stages: 定义流水线的各个阶段，如 build, test, deploy。阶段按顺序执行。
job: 定义一个具体的任务。
- stage: 指定任务所属的阶段。
- script: 任务执行的 shell 命令。
- tags: 指定执行该任务的 Runner 标签。
- artifacts: 定义任务产物，可在后续阶段中传递。
- only/except: 控制任务在哪些分支或标签下执行。