4. Pipeline 初始化失败：Agent 离线、资源配额不足、YAML 语法解析错误

Pipeline 初始化失败是 CI/CD 服务目录中最常见的“第一公里”故障。根据平台工程团队的生产统计，超过 60% 的流水线启动失败集中在三类根因：Agent 离线、资源配额不足、YAML 语法解析错误。本章将逐一拆解这三类故障的排查路径、修复策略与预防措施。

4.1 Agent 离线：执行器不可达

Agent（Runner / Worker）是 Pipeline 的实际执行单元。当 CI 平台无法与 Agent 建立连接时，Pipeline 会卡在 Pending 或 Queued 状态，最终超时失败。

4.1.1 典型表现

• Jenkins：节点列表显示红色“×”或“离线”标记；构建日志提示 Node is offline。
• GitLab CI：Runner 状态为 stuck 或 offline；Pipeline 停留在 pending。
• GitHub Actions：Self-hosted Runner 显示 Offline；Actions 日志提示 No runner found。

4.1.2 排查清单

4.1.3 Agent 离线排查流程图

4.2 资源配额不足：CPU/内存/并发超限

在多租户平台工程环境中，资源配额（Resource Quota）是控制 Namespace 或项目资源消耗的核心机制。当 Pipeline 请求的资源超过配额上限时，初始化阶段会直接失败。

4.2.1 常见配额限制类型

4.2.2 排查命令与工具

# Kubernetes 环境：查看 Namespace 配额使用情况
kubectl describe quota -n <namespace>

# 查看当前运行的 Pod 资源请求
kubectl top pod -n <namespace>

# 查看集群节点资源余量
kubectl describe nodes | grep -A 5 "Capacity"

# GitLab CI：查看 Runner 并发配置
cat /etc/gitlab-runner/config.toml | grep concurrent

# Jenkins：查看执行器数量
# 系统管理 → 节点管理 → 对应节点配置

4.2.3 资源配额优化策略

• 设置合理的资源请求：根据构建类型（编译、测试、打包）配置不同的资源模板。
• 启用构建缓存：使用持久化缓存减少重复依赖下载，降低资源消耗。
• 清理历史 Job：定期删除已完成或失败的 Pod，释放 Namespace 配额。
• 水平扩容：增加 Agent 节点或 Runner 并发数，分散负载。
• 优先级调度：为生产环境 Pipeline 设置更高优先级，保障关键构建。

4.3 YAML 语法解析错误：缩进/字段/类型

YAML 语法错误是 Pipeline 初始化失败中排查成本最低但出现频率最高的故障类型。CI 平台在解析 .gitlab-ci.yml、Jenkinsfile 或 workflow.yml 时，任何语法偏差都会导致解析失败。

4.3.1 常见 YAML 错误类型

job:
  script:
 echo "hello"

job:
  script:
    - echo "hello"

job:<TAB>script:

scrpit: echo "test"

script: echo "test"

script: echo "a", echo "b"

script:
  - echo "a"
  - echo "b"

only: yes

only:
  - main

4.3.2 本地校验工具

# 通用 YAML 校验
yamllint .gitlab-ci.yml

# GitLab CI 专用校验
gitlab-ci-local --lint

# GitHub Actions 校验
act --list

# 在线校验（推荐）
# https://www.yamllint.com/
# https://github.com/actions/toolkit/tree/main/packages/yaml

4.3.3 排查步骤

1. 查看 CI 平台报错信息：GitLab CI 会在 Pipeline 页面显示 Invalid YAML 及具体行号；GitHub Actions 在 Actions 标签页显示解析错误详情。
2. 使用在线 YAML 校验器：将 YAML 内容粘贴到校验工具，快速定位缩进或语法问题。
3. 检查特殊字符：确保没有不可见字符（如 BOM 头、零宽空格）混入文件。
4. 验证字段类型：确认 when、only、except 等字段使用正确的值类型（字符串/列表/布尔）。
5. 本地 Lint 验证：在提交前使用 yamllint 或 IDE 插件（如 VSCode YAML 插件）进行预检查。

4.4 综合故障排查矩阵

4.5 预防性配置建议

• Agent 健康检查：配置 Agent 的心跳检测与自动重启机制（如 Systemd 的 Restart=always）。
• 资源配额告警：设置 Namespace 资源使用率的告警阈值（如 80%），提前扩容。
• YAML 模板化：使用 CI/CD 服务目录提供的标准化 Pipeline 模板，减少手写 YAML 的出错概率。
• 预提交 Hook：在 Git 客户端配置 pre-commit hook，自动执行 YAML 校验。
• 定期清理：设置 CronJob 清理超过 7 天的历史构建 Pod 和缓存数据。