📚 课程目录第4章 GitLab CI/CD核心概念

4、GitLab CI/CD核心概念：.gitlab-ci.yml文件结构、Pipeline、Job、Stage、Runner的概念与作用，以及Pipeline的触发机制

GitLab CI/CD 是 GitLab 内置的持续集成与持续交付平台，其核心设计理念是“配置即代码”（Configuration as Code）。整个 CI/CD 流程由仓库根目录下的 .gitlab-ci.yml 文件定义，该文件描述了 Pipeline（流水线）的结构、Job（任务）的执行逻辑、Stage（阶段）的先后顺序，以及 Runner（执行器）如何获取并运行这些任务。理解这五个核心概念之间的协作关系，是掌握 GitLab CI/CD 的关键起点。本章将深入剖析这些概念的本质、配置方法、运行机制与触发策略，帮助你在实际项目中构建出清晰、高效、可维护的自动化交付链路。

4.1 核心原理：五个概念如何协同工作

GitLab CI/CD 的架构可以概括为“一个文件驱动、两类角色协作、三级结构执行”。.gitlab-ci.yml 是唯一的事实来源（Source of Truth），它定义了整个流水线的行为；Pipeline 是某次触发后生成的一次完整执行实例；Job 是 Pipeline 中最小的执行单元，包含具体的命令；Stage 是 Job 的逻辑分组，控制执行的先后顺序；Runner 是真正运行 Job 的代理进程。它们之间的关系是：GitLab 服务器解析 YAML 文件后，根据触发事件创建 Pipeline，Pipeline 按照 Stage 顺序调度 Job，Runner 领取并执行 Job，最后将结果回传给 GitLab 展示。

这种设计带来了三个关键优势：并行性（同一 Stage 内的多个 Job 可并行执行）、失败快速反馈（前一 Stage 失败则后续 Stage 不再执行）、环境隔离（不同 Job 可以运行在不同类型的 Runner 上）。理解这些概念时，可以将 Pipeline 想象成一条生产线：Stage 是车间（如组装、质检、包装），Job 是工位上的具体操作（如拧螺丝、贴标签），Runner 是工人（可以同时有多名），而 .gitlab-ci.yml 就是生产流程图。

概念	本质	作用域	关键属性
.gitlab-ci.yml	配置文件	仓库级	stages, variables, include, cache
Pipeline	执行实例	一次触发	status, ref, sha, created_at
Job	最小任务单元	Pipeline 内	script, tags, only/except, artifacts
Stage	Job 的逻辑分组	Pipeline 内	顺序执行，默认 5 个
Runner	执行代理	独立进程	executor, tags, locked, run_untagged

4.2 .gitlab-ci.yml 文件结构详解

.gitlab-ci.yml 使用 YAML 语法，顶层包含若干关键关键字。最基本的结构包含 stages（定义阶段列表）、variables（定义全局变量）、before_script（每个 Job 执行前的公共命令）、after_script（每个 Job 执行后的清理命令），以及若干个 Job 定义。每个 Job 必须包含 script（要执行的命令列表），可选包含 stage（归属阶段）、tags（指定 Runner）、only/except（触发条件）、artifacts（产物保存）、cache（依赖缓存）等。

一个典型的 Java 项目配置示例如下：

stages:
  - build
  - test
  - deploy

variables:
  MAVEN_OPTS: "-Dmaven.repo.local=$CI_PROJECT_DIR/.m2"
  APP_NAME: "demo-app"

before_script:
  - echo "开始执行 CI 流程"
  - java -version

build-job:
  stage: build
  tags:
    - maven-runner
  script:
    - mvn clean package -DskipTests
  artifacts:
    paths:
      - target/*.jar
    expire_in: 1 week

test-job:
  stage: test
  tags:
    - maven-runner
  script:
    - mvn test
  only:
    - merge_requests

deploy-prod:
  stage: deploy
  tags:
    - k8s-runner
  script:
    - kubectl apply -f deployment.yaml
  only:
    - main
  when: manual

上述配置中，build-job 和 test-job 虽然都使用 maven-runner，但 test-job 仅在合并请求时触发；deploy-prod 被设置为手动执行（when: manual），且只在 main 分支推送时出现。这种声明式配置让团队可以精确控制每个环节的触发时机和执行环境。

经验提醒： 建议在项目初期就定义好 stages 的全局顺序，避免后期频繁调整导致 Pipeline 历史记录混乱。常见的 Stage 划分是 build → test → package → deploy，对于大型项目可以增加 security-scan、performance-test 等阶段。

4.3 Pipeline、Job、Stage 的层级关系与执行规则

Pipeline 是 GitLab 根据一次触发事件（如 push）创建的完整执行流程。一个 Pipeline 包含多个 Stage，每个 Stage 包含一个或多个 Job。Stage 之间是串行关系——只有当前 Stage 的所有 Job 都成功，下一个 Stage 才会开始；同一 Stage 内的 Job 默认并行执行（受 Runner 并发数限制）。这种设计保证了流水线的逻辑严谨性：先编译通过，才能进行测试；测试通过，才能部署上线。

Job 的执行状态直接影响 Pipeline 的状态。当某个 Job 失败时，GitLab 会立即停止当前 Stage 中其他仍在运行的 Job（可配置 allow_failure 来改变此行为），并取消后续 Stage 的调度。Job 的 retry 属性可以配置失败自动重试次数，timeout 属性可以设置单 Job 超时时间，防止任务卡死。

Runner 与 Job 的匹配遵循“标签路由”机制。Runner 在注册时可以设置一个或多个 tags（如 docker、shell、gpu），Job 通过 tags 字段声明自己需要哪种类型的 Runner。如果没有任何 Runner 匹配 Job 的标签，该 Job 将一直处于 pending 状态，直到有合适的 Runner 上线。Runner 还支持 run_untagged 属性，允许执行没有标签的 Job。

风险提示： 不要为所有 Job 都打上相同的标签，否则会导致 Runner 负载不均。例如，将编译任务（CPU 密集）和测试任务（内存密集）都标记为 default，当并发量高时，可能出现资源争抢。建议根据 Runner 的硬件特性分配差异化标签。

4.4 Runner 的类型、注册与执行环境

Runner 是 GitLab CI/CD 的执行引擎，分为共享 Runner（Shared Runner）、组 Runner（Group Runner）和项目 Runner（Project Runner）三种级别。共享 Runner 由 GitLab 管理员维护，可供整个实例的所有项目使用；组 Runner 服务于特定用户组下的所有项目；项目 Runner 则只服务于单个项目。对于企业级应用，通常建议使用项目或组 Runner，以便进行更细粒度的权限和资源控制。

Runner 支持多种执行器（Executor），常见的有：

Shell：直接在 Runner 宿主机上执行命令，简单但环境隔离性差。
Docker：每个 Job 在独立的 Docker 容器中运行，通过 image 关键字指定镜像，隔离性好，是当前最主流的方式。
Kubernetes：动态创建 Pod 执行 Job，适合大规模弹性伸缩场景。
SSH：通过 SSH 连接到远程服务器执行命令，适用于已有物理机集群。

注册 Runner 的过程通常使用 gitlab-runner register 命令，需要提供 GitLab 实例地址和注册令牌。注册完成后，Runner 会定期轮询 GitLab 服务器获取待执行的 Job。对于 Docker 执行器，还需要在 Runner 的 config.toml 中配置 pull_policy（镜像拉取策略）和 volumes（数据卷挂载），以支持缓存和持久化。

4.5 Pipeline 的触发机制与实战场景

Pipeline 的触发方式非常灵活，除了最常见的 git push 自动触发外，还包括：

合并请求事件：通过 only: [merge_requests] 或 rules 配置，在创建或更新 MR 时触发，常用于代码评审阶段的自动化检查。
定时调度：使用 schedule 功能，通过 cron 表达式定义执行时间，适合夜间构建或定期依赖更新。
API 触发：通过 POST /projects/:id/pipeline 接口，携带参数创建 Pipeline，适合外部系统集成。
手动触发：设置 when: manual，在 GitLab 界面上点击“Play”按钮执行，适合生产环境部署等高风险操作。
上游 Pipeline 触发：通过 trigger 关键字实现父子 Pipeline 或多项目 Pipeline 联动。

在实际项目中，合理组合这些触发机制可以构建出高效的交付流程。例如，开发分支的 push 触发快速 CI（编译+单元测试），MR 触发集成测试和代码质量扫描，main 分支的 push 触发构建镜像并部署到预发环境，而生产环境的发布则通过手动确认完成。

  案例拆解： 某互联网公司采用 GitLab CI/CD 管理微服务项目，团队规模 20 人，代码仓库包含 5 个服务模块。初始阶段，所有 Job 都使用共享 Runner，导致高峰期排队严重。优化方案如下：
  背景与约束： 共享 Runner 仅 3 台，每台 4 核 8G；团队要求 PR 合并前必须通过全部测试，且部署窗口为每天 18:00-20:00。
初始现象： 下午 3 点后提交代码，Pipeline 等待时间超过 30 分钟；测试 Job 经常因资源不足而失败。
分析判断： 编译和测试任务对 CPU 和内存需求不同，编译任务耗时约 2 分钟，测试任务耗时约 8 分钟；共享 Runner 无法区分负载类型。
实际操作： ① 申请 2 台专用 Runner，分别标记为 build-runner（4核8G）和 test-runner（8核16G）；② 在 .gitlab-ci.yml 中为编译 Job 添加 tags: [build-runner]，为测试 Job 添加 tags: [test-runner]；③ 将部署 Job 设置为 when: manual，并限定 only: [main]。
结果对比： 优化后，Pipeline 平均等待时间降至 5 分钟以内，测试 Job 失败率从 15% 降至 2%；部署流程增加了人工确认环节，线上事故率下降 40%。
复盘经验： Runner 的标签规划应基于任务的资源特征，而非简单的环境名称；手动部署虽然增加了操作成本，但显著提升了变更安全性。

4.6 常见误区与总结复盘

在实际使用 GitLab CI/CD 时，团队常犯以下错误：

误区一：将所有逻辑写在一个 Job 中。 这会导致 Pipeline 无法并行化，且失败后难以定位问题。正确做法是拆分为多个职责单一的 Job。
误区二：忽略 rules 与 only/except 的区别。 only/except 是简单匹配，而 rules 支持更复杂的条件判断（如变量存在性、分支正则匹配），推荐在新项目中使用 rules。
误区三：不配置 artifacts 和 cache。 这会导致每次 Job 都从零开始，构建速度极慢。应合理利用 cache 缓存依赖包（如 Maven 仓库、npm 包），用 artifacts 传递构建产物。
误区四：所有 Job 都使用同一个 Docker 镜像。 不同阶段可能需要不同的工具链（如编译需要 JDK，测试需要 Python），应根据 Job 需求指定不同的 image。
误区五：忽视 Pipeline 的安全控制。 对于生产部署等敏感 Job，应设置 when: manual 并配置受保护分支（Protected Branch）权限，防止未授权执行。

总结而言，掌握 GitLab CI/CD 的核心概念是构建自动化交付体系的基础。建议团队在项目初期就制定统一的 .gitlab-ci.yml 规范，包括 Stage 命名、Job 命名、标签使用规则和产物保留策略。同时，定期审视 Pipeline 的执行效率，利用 GitLab 提供的 CI/CD 分析报表（如 Job 耗时、Runner 负载）进行持续优化。记住，CI/CD 的目标不仅是“自动化”，更是“快速反馈”和“可靠交付”。