GitLab CI 基础回顾：.gitlab-ci.yml 结构、stages、jobs、runner 概念
在深入服务目录参数配置之前，必须牢固掌握 GitLab CI 的四个核心基础概念：.gitlab-ci.yml 配置文件结构、stages（阶段）、jobs（作业）以及runner（运行器）。它们是整个流水线编排的基石，也是后续参数化配置的载体。
1. .gitlab-ci.yml 文件结构
该文件是 GitLab CI 的“单一事实来源”，采用 YAML 格式，必须放置在项目仓库的根目录下。其顶层结构由 stages 定义和多个 job 定义组成。
核心原则： 每个 job 必须包含一个
script 关键字（定义要执行的命令），并可以关联一个 stage（指定所属阶段）。未指定 stage 的 job 默认属于 test 阶段。
# .gitlab-ci.yml 最小化示例
stages:
- build
- test
- deploy
compile_job:
stage: build
script:
- echo "编译代码..."
- make compile
unit_test_job:
stage: test
script:
- echo "运行单元测试..."
- make test
deploy_prod_job:
stage: deploy
script:
- echo "部署到生产环境..."
- deploy.sh production2. Stages（阶段）与 Jobs（作业）
Stages 定义了流水线的逻辑阶段顺序，而 Jobs 是实际执行任务的最小单元。同一 stage 内的 jobs 默认并行执行，只有当前 stage 所有 jobs 都成功，才会进入下一个 stage。
| 概念 | 作用 | 关键属性 |
|---|---|---|
| stages | 定义流水线的执行阶段顺序 | 全局定义，列表顺序即执行顺序 |
| job | 定义具体执行的任务 | script（必选）、stage、only/except、variables、artifacts |
| 并行与串行 | 同 stage jobs 并行；不同 stages 串行 | 可通过 needs 关键字打破默认顺序 |
实践提示： 在服务目录参数配置中，我们经常利用
parallel 关键字让同一 job 并行运行多个参数组合，从而大幅缩短测试或部署的总体耗时。
3. Runner（运行器）概念
Runner 是实际执行 GitLab CI 作业的代理程序。它从 GitLab 服务器接收作业，在隔离的环境中运行脚本，并将结果（日志、制品、状态）回传。Runner 分为三种类型：
- Shared Runner（共享运行器）： 由 GitLab 实例管理员注册，所有项目均可使用。适合通用任务，但资源隔离性较弱。
- Group Runner（组运行器）： 注册到某个组，该组下的所有项目共享。适合团队级标准环境。
- Specific Runner（特定运行器）： 绑定到特定项目，资源独占，配置灵活。服务目录中的敏感参数或专用环境通常使用此类 Runner。
4. 核心概念关系总结
下图展示了 .gitlab-ci.yml、stages、jobs 和 runner 之间的逻辑关系：配置文件定义阶段和作业，GitLab 服务器解析后调度给合适的 Runner 执行。
常见误区： 初学者容易混淆
stages 和 jobs 的层级关系。请记住：stages 是时间轴上的阶段划分，jobs 是每个阶段内的具体工作单元。一个 job 只能属于一个 stage，但一个 stage 可以包含多个 job。
5. 基础配置清单速查
在开始服务目录参数配置之前，请确保你的项目已满足以下基础条件：
- 仓库根目录 下存在
.gitlab-ci.yml文件。 - 至少定义了一个 runner（共享、组或特定），且状态为
active。 - 流水线中至少包含 1 个 stage 和 1 个 job。
- 每个 job 的
script命令在 runner 环境中可执行。