2、GitLab CI基础回顾：GitLab CI架构、.gitlab-ci.yml核心语法、Runner类型与配置、Pipeline与Job概念
在深入平台工程与服务目录之前，必须夯实GitLab CI的核心基础。本章从架构、配置语法、Runner部署到Pipeline执行模型，逐层拆解，为后续跨项目移植建立统一的技术语言。
2.1 GitLab CI架构：组件与通信
GitLab CI并非单一体，而是由GitLab实例、Runner和制品仓库三个核心组件构成的分布式系统。理解它们之间的协作关系，是诊断Pipeline故障和设计高可用Runner池的前提。
架构要点： GitLab实例负责任务调度与状态管理，Runner负责实际执行，制品（Artifacts）与缓存（Cache）通过对象存储或本地磁盘中转。
2.2 .gitlab-ci.yml 核心语法
Pipeline 的定义文件 .gitlab-ci.yml 采用 YAML 格式，位于项目根目录。平台工程视角下，我们关注的是可复用与可移植的语法结构。
2.2.1 基本结构
stages:
- build
- test
- deploy
variables:
APP_ENV: "production"
build-job:
stage: build
script:
- echo "Compiling..."
- make build
artifacts:
paths:
- dist/
test-job:
stage: test
script:
- echo "Running tests..."
- make test
needs: ["build-job"]
deploy-job:
stage: deploy
script:
- echo "Deploying..."
- deploy.sh
only:
- main
2.2.2 关键字速查表
| 关键字 | 作用 | 平台工程关注点 |
|---|---|---|
stages |
定义 Pipeline 阶段顺序 | 跨项目统一阶段命名，便于服务目录编排 |
variables |
全局或 Job 级变量 | 使用 CI/CD 变量模板，避免硬编码 |
script |
Job 执行的 Shell 命令 | 尽量封装为脚本文件，减少内联 |
artifacts |
传递 Job 产物到后续阶段 | 控制过期时间，避免存储膨胀 |
needs |
控制 Job 依赖关系（DAG） | 加速 Pipeline，允许并行执行 |
only/except |
分支/标签触发条件 | 推荐使用 rules 替代，更灵活 |
include |
引入外部 YAML 模板 | 跨项目复用的核心机制 |
平台工程提示：
include 关键字支持 local、file、template、remote 四种来源。服务目录通常将公共 Job 定义为 template 或 file 引用，实现“一次定义，多处运行”。
2.3 Runner 类型与配置
Runner 是 Pipeline 的执行引擎。根据注册范围，分为三种类型，其隔离性与管理成本差异显著。
2.3.1 Runner 类型对比
| 类型 | 注册范围 | 隔离性 | 管理成本 | 适用场景 |
|---|---|---|---|---|
| Shared | 整个 GitLab 实例 | 低 | 低 | 通用任务、开源项目 |
| Group | 指定用户组 | 中 | 中 | 部门级项目、共享缓存 |
| Specific | 单个项目 | 高 | 高 | 敏感环境、定制化配置 |
2.3.2 Runner 配置示例
注册 Runner 时，config.toml 是核心配置文件。以下是一个 Docker 执行器的典型配置：
[[runners]]
name = "docker-runner-01"
url = "https://gitlab.example.com"
= "YOUR_REGISTRATION_"
executor = "docker"
[runners.docker]
image = "alpine:latest"
privileged = false
volumes = ["/cache"]
[runners.cache]
Type = "s3"
Path = "runner-cache"
Shared = true
避坑指南： 在平台工程场景中，不要在 Shared Runner 上运行需要特定环境变量的 Job。推荐使用 Group Runner + 标签（tags）机制，将 Job 路由到正确的执行环境。
2.4 Pipeline 与 Job 概念
Pipeline 是 CI/CD 的一次完整执行过程，Job 是 Pipeline 中的最小执行单元。理解两者的关系，是设计高效流水线的基础。
2.4.1 Pipeline 生命周期
- 创建（Pending）：代码推送后，GitLab 创建 Pipeline 实例。
- 等待（Waiting for resource）：等待 Runner 资源就绪。
- 运行（Running）：Job 按阶段顺序或 DAG 依赖执行。
- 完成（Passed / Failed / Canceled）：所有 Job 执行完毕或中断。
2.4.2 Job 状态机
2.4.3 Pipeline 类型
- 分支 Pipeline：每次推送代码到分支时触发，最常用。
- 合并请求 Pipeline：在 MR 创建或更新时触发，通常包含代码质量检查。
- 定时 Pipeline：通过
schedule功能定期执行，适合清理或报告任务。 - 多项目 Pipeline：跨项目触发，服务目录跨项目移植的核心场景。
平台工程视角： 在服务目录中，每个微服务项目应保持 Pipeline 结构一致（相同的 stages、相似的 Job 命名），差异仅通过变量和
include 模板注入。这是实现“配置即代码”与“可移植性”的基础。