📚 课程目录第2章 GitLab CI基础回顾

2. GitLab CI 基础回顾：.gitlab-ci.yml 核心结构、Job、Stage、Runner 概念

在深入事件触发与 Runbook 联动之前，必须牢固掌握 GitLab CI/CD 的三大基石：.gitlab-ci.yml 文件结构、Job（作业）与 Stage（阶段）的编排逻辑，以及 Runner（运行器）的执行机制。本章将系统梳理这些核心概念，为后续的故障定位实战打下坚实基础。

2.1 .gitlab-ci.yml 核心结构

.gitlab-ci.yml 是 GitLab CI/CD 的“大脑”，它定义了整个流水线的行为。该文件采用 YAML 格式，位于项目仓库的根目录。其核心结构由以下几个顶级关键字构成：

关键字	作用	是否必填
`stages`	定义流水线中所有可用的阶段名称及其执行顺序	推荐
`job_name`	用户自定义的作业名称，包含 `script`、`stage` 等子关键字	是
`before_script`	在每个作业的 `script` 之前执行的命令数组	否
`after_script`	在每个作业的 `script` 之后执行的命令数组	否
`variables`	定义全局或作业级别的 CI/CD 变量	否
`cache`	定义作业间共享的缓存路径，用于加速依赖安装	否
`include`	引入外部 YAML 文件，实现配置复用	否

实战要点：在故障定位场景中，variables 和 include 是排查配置冲突的高频区域。例如，全局变量被作业级变量意外覆盖，或引入的外部模板中包含了错误的 stage 定义，都可能导致流水线异常。

以下是一个最小化的 .gitlab-ci.yml 示例：

stages:
  - build
  - test
  - deploy

build_job:
  stage: build
  script:
    - echo "Compiling application..."
    - make build

test_job:
  stage: test
  script:
    - echo "Running unit tests..."
    - make test

deploy_job:
  stage: deploy
  script:
    - echo "Deploying to production..."
    - make deploy
  only:
    - main

2.2 Job（作业）与 Stage（阶段）

Job 是流水线的最小执行单元，它定义了“做什么”（script）和“在什么条件下做”（rules/only/except）。Stage 是 Job 的逻辑分组，决定了“什么时候做”。

Stage 顺序：所有 Stage 按 stages 列表中定义的顺序串行执行。只有前一个 Stage 中的所有 Job 都成功，下一个 Stage 才会开始。
Job 并行：同一个 Stage 内的所有 Job 默认并行执行，这可以显著缩短流水线总耗时。
失败策略：如果某个 Job 失败，默认情况下其所在 Stage 标记为失败，后续 Stage 不会执行。可以通过 allow_failure: true 改变此行为。

  故障定位关联：当流水线卡在某个 Stage 时，应首先检查该 Stage 内所有 Job 的日志。如果某个 Job 长时间未完成，可能是 Runner 资源不足或 Job 本身存在死循环。如果 Job 快速失败，则需检查 script 命令的返回值或依赖的环境变量。

下面通过一个内联 SVG 图展示 Job 与 Stage 的典型执行流程：

2.3 Runner（运行器）概念

Runner 是实际执行 Job 的代理程序。它从 GitLab 服务器获取 Job，在隔离的环境中运行 script 命令，然后将日志和状态报告回 GitLab。Runner 的类型决定了其可用性和隔离级别。

Runner 类型	执行环境	典型用途	故障排查要点
Shared Runner	GitLab SaaS 提供的共享虚拟机	开源项目、快速验证	环境不可控，依赖预装软件版本
Group Runner	为整个组（Group）注册的专用 Runner	团队内部项目，统一环境	检查 Runner 标签（tags）是否匹配 Job
Specific Runner	为特定项目注册的专用 Runner	生产环境部署、敏感操作	确认 Runner 在线状态和并发数

常见故障场景：Job 一直处于 pending（等待中）状态，最常见的原因是：没有可用的 Runner 匹配 Job 的 tags 要求，或者所有匹配的 Runner 都已达到最大并发数。在 Runbook 联动中，应首先检查 Runner 的在线状态和标签配置。

Runner 的执行模型可以抽象为以下流程：

2.4 核心概念关系总结

将上述三个概念整合，可以得出 GitLab CI 的基本运行逻辑：Pipeline（流水线）由 Stage（阶段）组成，每个 Stage 包含多个 Job（作业），而 Job 由 Runner（运行器）在隔离环境中执行。整个流程由 .gitlab-ci.yml 文件定义。