持续集成的流水线设计

引言：流水线即产品

大多数团队接触持续集成时，都是从"配一个 CI 文件"开始的。你写几行 YAML，push 到仓库，看到小绿勾亮起来，就觉得 CI 搞定了。之后每一次遇到构建超时、测试失败、缓存失效、并行任务互相踩踏，你才会意识到：持续集成的流水线，不是一个配置文件，而是一个产品。

这个产品有自己的用户（开发团队）、SLA（构建时间、成功率）、可靠性要求（不能被误报淹没）、安全需求（凭证不能泄露）。它需要设计、维护、演进，跟任何一个业务系统一样。区别只在于：大多数团队把流水线当作"CI 工具的配置"而非"需要设计的系统"，所以流水线越跑越慢、越跑越不稳、越跑越没人管。

这篇文章的目标是提供一个系统化的流水线设计框架。从原则到实践，从策略到陷阱，我会用实际经验说明一个"好的"流水线是什么样子——以及为什么大多数团队的流水线值得重做。

一、流水线设计的四项基本原则

在讨论具体的技术方案之前，先确定几条底层原则。这些原则不绑定任何 CI 工具（Jenkins、GitHub Actions、GitLab CI、CircleCI 都适用），它们决定的是设计决策的依据。

1.1 快速反馈：两分钟原则

流水线的核心价值是"反馈"——告诉开发者他的变更有没有问题。反馈越慢，价值越低。

一个粗略的经验是：核心反馈链路的端到端时间不应超过本地编译时间的 2 倍。如果本地编译需要 30 秒，完整的 CI 流水线跑完不应该超过 1 分钟。如果本地编译需要 5 分钟，CI 在 15 分钟内完成是可以接受的。

这个原则有两个含义：

第一，长任务和短任务必须分离。如果把代码检查和全量集成测试放在同一个流水线阶段，那代码检查总要等集成测试跑完才能汇报结果。开发者习惯了所有检查都亮绿灯才算"通过"，但实际等待时间被最长的那个任务拉长了。

分离策略的实践方式是在流水线中设置快速检查门（Fast Gate）：

graph LR
    A[代码提交] --> B{Fast Gate}
    B -->|结果| C[Lint + 单元测试]
    B -->|同时触发| D[构建 + 集成测试]
    C -->|通过✅| E[合并许可]
    D -->|通过✅| F[部署许可]
    E -.-> E
    F -.-> F

Fast Gate 只包含能在 3-5 分钟内完成的任务。它通过后，开发者就知道自己的变更至少没有低级错误——即使后续的集成测试还要跑 20 分钟，他不需要干等。Fast Gate 的结果是"是否允许合并到主线"，而完整流水线的结果才是"是否允许部署到生产"。

第二，反馈的接收者要明确。Lint 失败的反馈发给写代码的人，集成测试失败的反馈发给整个团队，部署失败的反馈发给运维值班人。不同层级的失败需要不同的通知渠道和响应方式。把所有人拉进同一个告警群，等于没有告警。

1.2 幂等性：相同的输入产生相同的输出

这条原则看起来简单，但在实践中经常被违反。

一个幂等的流水线意味着：如果用同一个提交（相同的 git commit SHA）触发两次流水线，两次运行应该产生完全相同的结果。这里说的"结果"包括：构建产物的哈希值、测试通过/失败的状态、部署的目标。

为什么这条原则重要？

因为非幂等的流水线导致不可复现的缺陷。比如测试在一个运行中通过了，在另一个运行中失败了，而代码没有任何变化。这时候你既不能断定测试是稳定的，也不能确信代码是正确的。非幂等性最典型的来源包括：

• 外部依赖的版本漂移：apt-get install、npm install 不锁定版本时，两次安装可能拿到不同的依赖版本。解决方案是锁定依赖版本（lockfile），并用缓存确保同样的依赖包文件。
• 时间戳或随机数：构建过程中生成的时间戳或随机 UUID 会导致两次构建产物不同。如果是测试，解决方案是 mock 时间；如果是构建产物，需要在构建后重新标记版本。
• 顺序依赖的并行任务：两个并行任务都要写同一个文件，谁先写完取决于调度器的随机性。解决方案是分配独立的工作目录，或者在文件操作上做锁保护。

实践中，判断流水线是否幂等有一个简单的验证方法：同一个提交连续跑三次，检查产物哈希是否一致。如果哈希不同，说明有非确定性因素，找到了就要修。

1.3 可追溯性：每个阶段都是证据

流水线的每个阶段都应该留下可审计的证据。这个证据包括：

• 谁触发了这次构建
• 基于哪个提交
• 每个阶段的执行状态（成功/失败/跳过）
• 每个阶段的耗时
• 构建产物在哪里（下载链接）
• 测试报告（哪些用例通过、哪些失败）
• 代码覆盖率报告
• 制品签名和哈希值

这些证据在大多数 CI 工具的 UI 里都能看到，但在实践中的问题是：信息散落在不同地方，出了事很难追溯。

好的做法是汇总到一个构建清单（Build Manifest），作为构建产物的元数据保存。一个典型的构建清单 JSON 大概是这样的：

{
  "build_id": "20260531-001",
  "commit": "a1b2c3d4e5f6",
  "author": "zhangsan@company.com",
  "branch": "feature/pipeline-redesign",
  "trigger": "push",
  "stages": [
    {"name": "lint", "status": "passed", "duration_sec": 12},
    {"name": "unit_test", "status": "passed", "duration_sec": 45},
    {"name": "build", "status": "passed", "duration_sec": 120},
    {"name": "integration_test", "status": "passed", "duration_sec": 300}
  ],
  "artifacts": [
    {"name": "app.war", "checksum_sha256": "abc...", "size_bytes": 45000000, "url": "..."}
  ]
}

这个清单应该：

1. 随构建产物一起归档（同一个目录）
2. 推送到一个集中的构建数据库
3. 在部署时作为参考数据保存到生产环境

当线上出了 bug，你要回答"这个 bug 对应的构建是什么、基于什么代码、包含哪些制品"时，这个清单就是唯一的权威来源。

1.4 失败快速：尽早发现问题

"失败快速"是 CI 设计中最容易被误解的原则。它不是说"任务要快速失败"（虽然可以理解为做到就快速），而说的是流水线的结构设计要让失败尽早暴露。

假设一个流水线有 5 个阶段：代码检查、单元测试、构建、集成测试、部署。单元测试阶段的错误应该在单元测试阶段暴露，而不是等构建完成后再发现。同理，代码格式错误应该在代码检查阶段暴露，而不是等单元测试跑完。

这听起来像常识，但很多流水线违反这个原则的方式是：把多个阶段的任务塞进同一个步骤里。比如在同一个 shell 脚本里先跑 lint、再跑单元测试、再跑构建。lint 失败了，但 shell 脚本继续执行后续步骤，直到所有步骤跑完才返回失败状态。这不仅浪费资源，更重要的是：开发者的反馈时间是所有步骤的总和，而不是 lint 的几秒钟。

正确的做法是：每个阶段之间设置门禁（Gate）。门禁前的阶段全部通过后才进入下一个阶段。这样最短反馈路径就是第一个失败阶段的耗时。

阶段 1: Lint ──失败→ 终止流水线  → 反馈时间 = 12 秒
         ↓通过
阶段 2: 单元测试 ──失败→ 终止   → 反馈时间 = 45 秒
         ↓通过
阶段 3: 构建 ──失败→ 终止       → 反馈时间 = 2 分钟
         ↓通过
阶段 4: 集成测试 ──失败→ 终止   → 反馈时间 = 5 分钟

GitHub Actions 的 fail-fast: true 和 GitLab CI 的 needs 控制的依赖关系链就是实现这个策略的基础。关键在于：不要在同一个 job 里塞多件事。

二、流水线的阶段划分与设计

一个成熟的流水线不是一系列任务的随意排列，而是经过精心划分的阶段序列。每个阶段有明确的目标、边界和验收标准。

2.1 代码分析阶段（Static Analysis）

这个阶段的任务是在不运行代码的情况下发现潜在问题。它在流水线中处于最前端，因为它的执行成本最低、反馈最快。

应该在这个阶段完成的任务包括：

• 语法检查与格式化：ESLint、Prettier、gofmt、rustfmt 等。这个步骤应该是纯检查模式（check mode），不修改文件。如果开发者本地配置了格式化工具，这一步大部分时候是安静的——但正因为大多数时候安静，它才重要。当有人不小心跳过了本地格式化时，这个门禁能拦住。
• 类型检查：TypeScript 的 tsc --noEmit、Python 的 mypy、Java 的 Checker Framework。类型检查能发现 lint 工具发现不了的问题——比如参数类型的误解、空值处理的遗漏。这个检查应该和 lint 在同一个 stage 但不是同一个 job 里，这样可以并行执行。
• 静态安全扫描：SAST 工具（SonarQube、CodeQL、Semgrep）扫描引入的漏洞模式。这通常比前两项耗时更长，所以需要合理设置超时时间。实践中我的建议是：基础的规则集（比如禁止 eval()、禁止硬编码密码）在快速通道执行，深度分析（数据流分析、跨文件漏洞链路）放在异步通道。
• 代码重复度检查：CI 环境下的重复度检查应该设置一个宽松的阈值（比如 5%），太严格的阈值会导致大量误报，反而降低团队对流水线的信任度。关键不是消除所有重复，而是阻止明显的"复制粘贴式开发"进入主线。

快速通道的并行策略：以上四个检查没有依赖关系，完全可以并行执行。在 GitHub Actions 中可以用矩阵策略并行推进；在 GitLab CI 中每个检查作为一个独立的 job 用 needs: [] 定义依赖关系为空。

2.2 单元测试阶段

单元测试是流水线的第二道防线。它的特点是：执行快、定位准、低开销。理想的单元测试应该在几秒到几十秒内完成，精确告诉你哪个类、哪个方法、哪个条件分支出了问题。

执行策略：

• 增量和全量分离：增量测试只跑变更文件相关的测试用例，全量测试在定时流水线（nightly build）中执行。增量策略大幅缩短反馈时间，但要求测试框架支持测试影响分析（Test Impact Analysis）。对于没有这个能力的框架（或者你的测试代码质量不足以支持精确的影响分析），至少可以用文件路径匹配策略：只跑变更文件目录下的测试。
• 测试分片：当单元测试数量超过几百个，单机顺序执行开始变得不可接受。分片策略在后面的并行化章节展开。
• 随机顺序执行：单元测试的发现模式往往是按文件名或类名排序的。这种确定性顺序会掩盖测试之间的隐式依赖（比如测试 A 设置了某个全局状态，测试 B 依赖于这个状态）。随机顺序执行 + 固定 seed 可以在早期发现这种耦合问题。

应该在单元测试阶段完成的事情：

• 生成覆盖率报告（增量覆盖率和全量覆盖率分别记录）
• 标记 flaky test（反复通过的测试），自动创建 issue 跟踪
• 记录每个测试用例的执行时间，为后续的测试分片优化提供数据

2.3 构建阶段

构建阶段的目标是生成可部署的制品。这个阶段的问题往往不在"能不能构建成功"，而在于构建的可复现性和构建质量。

构建的可复现性前文已经讨论过，核心是锁定所有依赖版本。这里补充一个经常被忽视的点：构建环境的可复现性。不仅代码依赖要锁定，工具链也要锁定。具体做法：

• 构建容器化：用 Docker 镜像锁定构建环境（Node.js 版本、JDK 版本、GCC 版本）。镜像 tag 指向一个明确构建的版本，而不是 node:18 这种浮动 tag。
• 工具版本管理：asdf、nvm、gvm 等工具管理器配合 .tool-versions 或 .nvmrc 文件锁定运行环境版本。
• 构建参数显式化：不应该有"我本地能跑，CI 跑不了"的情况。构建参数（是否开启 debug、是否启用 profiling、环境标识）全部在流水线配置中显式声明。

构建质量指的是构建产物本身的完整性检查。包括：

• 构建产物签名（用一个 CI 专用的签名密钥对产物进行签名）
• SBOM（Software Bill of Materials）生成：列出制品中包含的所有依赖及其版本
• 构建元数据注入：在产物中嵌入构建时间、commit SHA、CI pipeline ID 等信息，便于运行时定位制品版本

2.4 集成测试与端到端测试阶段

这是流水线中最昂贵的阶段，也是团队最头疼的阶段。集成测试需要外部依赖（数据库、消息队列、第三方服务），执行慢、失败原因多、诊断困难。

分层策略：

集成测试分层

         ┌──────────────────────────────────┐
         │    E2E 测试（真实环境）           │
         │    低频、全量、耗时>30分钟        │
         └──────────┬───────────────────────┘
                    │ 只有 Smoke 测试必须通过
         ┌──────────▼───────────────────────┐
         │    服务集成测试（测试环境）        │
         │    中频、关键路径、耗时5-10分钟    │
         └──────────┬───────────────────────┘
                    │ 必须全部通过
         ┌──────────▼───────────────────────┐
         │   契约测试（Contract Testing）     │
         │    高频、API接口、耗时1-3分钟     │
         └──────────────────────────────────┘

底层：契约测试（Contract Testing）

契约测试验证服务之间的 API 约定是否一致。每个微服务出 API 提供方和消费方的契约，用 Pact 或 Spring Cloud Contract 这类工具验证。它的优势是快速、可靠，不需要启动依赖服务。如果所有服务都通过了契约测试，集成测试阶段的出错概率会大幅下降。

中层：服务集成测试（Service Integration Test）

启动被测服务及其直接依赖（数据库、消息队列），验证服务的核心功能在集成环境中是否正常。这里的关键技巧是：

• 使用 Testcontainers：用容器化依赖（PostgreSQL 容器、Redis 容器）替代真实外部服务，避免共享测试环境的状态污染。每个 CI job 获得独立的数据库实例。
• 测试数据隔离：写完的数据在测试结束后立即清理，或者使用事务回滚让数据库恢复原状。
• 关键路径优先：不要试图覆盖所有场景，只测试用户访问频次最高的 20% 路径。80% 的生产问题来自这 20% 的关键路径。

顶层：端到端测试（E2E Test）

E2E 测试是最慢、最脆弱的测试类型。它的设计哲学应该是"宁少毋滥"。一个经过精心挑选的 20 个 E2E 测试用例，比 200 个随机选择的 E2E 测试有用得多。

E2E 测试的筛选标准：

1. 这个场景被单元测试或集成测试覆盖了吗？→ 覆盖了就不需要 E2E
2. 这个场景包含多个服务的交互吗？→ 没有就不需要 E2E
3. 这个场景在以前的生产事故中出现过吗？→ 出现过才需要 E2E

一个常见的反模式是："上线不放心，加个 E2E 测试安心"。这种心理可以理解，但 E2E 测试不能代替 code review、cannot 代替手动验收、不能代替灰度发布。如果到了上线前还在依赖 E2E 测试发现低级错误，说明前面的阶段设计有问题。

2.5 部署阶段

部署阶段是流水线的终点，也是最容易出现分歧的地方。要不要自动部署？部署到什么环境？谁来决定可以部署？

环境策略可以这样分级：

这个分级的关键是：逐步提升部署的自动化程度，但不剥夺人的最终决策权。完全自动部署到生产是一个值得追求的目标（很多顶尖团队做到了），但达到这个目标需要前面所有阶段的高度成熟。如果你的流水线还存在 flaky test、构建不可复现、测试覆盖不足的问题，贸然推行全自动部署到生产只会增加事故频率。

三、并行化策略：将流水线从串行改写为并行

让流水线跑得快的最直接手段是并行化。但并行不是"把任务丢到多台机器上跑"这么简单。不合理的并行化会导致资源争夺、测试结果不稳定、维护成本飙升。

3.1 并行度与资源约束

一个常见的错误是：跑 CI 的机器有 32 个 CPU 核心，所以把所有测试用例分 32 路并行执行。这种做法的代价是：每个 job 分配到的内存和磁盘 IO 被稀释。当测试用例本身需要大量内存（比如前端测试需要启动 Chromium）或大量磁盘 IO（比如数据库测试），过高的并行度反而导致测试执行时间增加——因为资源竞争带来了上下文切换和 IO 等待。

经验法则是：并行度的上限应该根据最重的单个工作负载来设定。具体做法：

1. 先测单个 job 在该测试类型下的资源消耗（CPU、内存、IO）
2. 用（总资源 / 单 job 资源消耗）× 0.8 作为安全并行度上限
3. 在实际运行中监控 job 的等待时间，如果等待时间超过执行时间的 20%，说明并行度太高了

举个例子：你的 CI runner 是 8 核 16G 的机器。一个单元测试 job 平均消耗 1 核 1G 内存。那么理论并行度是 8。考虑 IO 争用的折损，取 6-7 路并行为上限。如果你有 1000 个测试用例，每个用例跑 1 秒，串行需要约 17 分钟。6 路并行后，理论上需要 3 分钟（考虑分片不均匀的折损，实际大约 4-5 分钟）。

3.2 依赖图的构建

流水线的并行化本质上是一个 DAG（有向无环图）的调度问题。每个任务是一个节点，任务之间的依赖关系是边。调度器的目标是在满足依赖关系的前提下，最大化并行执行的任务数量。

构建依赖图的步骤如下：

1. 列出所有任务
2. 识别任务之间的依赖关系（任务 B 依赖任务 A 的输出？依赖任务 C 完成的信号？还是完全独立？）
3. 绘制 DAG，标注每个任务的预估执行时间

一个典型的流水线 DAG 是这样的：

graph TD
    A["代码提交"] --> B["代码检查"]
    A --> C["安全检查"]
    B --> D["单元测试"]
    B --> E["构建"]
    C --> D
    C --> E
    D --> F["集成测试"]
    E --> F
    F --> G["部署到测试环境"]
    G --> H["E2E 测试"]
    H --> I["部署到生产"]

在这个 DAG 中：

• 代码检查和同事是全并行（互相独立）
• 单元测试和构建是全并行（都只依赖代码检查通过，互相不依赖）
• 集成测试依赖单元测试和构建两个前置
• E2E 测试依赖部署到测试环境

如果你的流水线没有明确定义 DAG——所有任务按顺序执行，或者放在同一个 shell 脚本里——那么优化速度的第一步就是拆成 DAG。不需要复杂的调度器，GitHub Actions 的 needs、GitLab CI 的 stages + needs、CircleCI 的 requires 都能表达最基础的 DAG。

3.3 测试分片的进阶策略

测试分片（Test Splitting）是并行化中最实用的技术之一。它的核心思想是：把 N 个测试用例分到 M 个并行 job 中执行，使每个 job 的执行时间接近均值，避免单个 job 成为瓶颈。

最简单的方式：基于文件名的分片

按测试文件名的哈希值分流到不同 job。这种方式不需要测试框架支持，实现成本极低。但问题是：不同测试文件的执行时间差异可能很大。一个包含集成测试的文件可能跑 10 分钟，而一个纯单元测试文件只需 10 秒。如果在同一个 shard 里，这个 shard 的执行时间被最慢的文件拖长了。

推荐的方式：基于历史执行时间的分片

每个 job 的测试框架或 CI 工具记录每个测试用例的历史执行时间。分片时按历史时间的累计值分配，使每个 shard 的期望时间尽可能接近。

在 CircleCI 中，circleci tests split --split-by=timings 使用之前的测试结果时间数据做分片。在 GitHub Actions 中，可以用 jest --shard 配合自定义脚本实现。在 GitLab CI 中，GitLab 16.0+ 支持 parallel:matrix 结合测试报告时间做分片。

测试分片的陷阱：

• 测试之间的时间差异过大：一个 E2E 测试跑 5 分钟，其他单元测试都跑 1 秒。分片后这个 E2E 测试会拖垮整个 shard。解决方案是先按测试类型分 layer（单元 vs 集成 vs E2E），然后在同类型的测试中做分片。
• 测试不是独立的：如果测试 A 设置了全局状态，测试 B 依赖这个状态，把它们分到不同 shard 会导致测试 B 失败。解决方案是确保测试独立，或者在分片时把耦合的测试固定在同一 shard。
• Shard 数量固定但测试集合变化：新增了一个模块，测试用例数量翻倍，但 shard 数量没变。每个 shard 执行时间也翻倍。解决方案是定期根据测试集合变化调整 shard 数量，或者使用自动伸缩的 shard 策略。

3.4 矩阵构建：多维度组合的并行

当你的项目需要在多个维度上构建和测试时（不同的操作系统、不同的编程语言版本、不同的依赖组合），矩阵构建（Matrix Build）是最自然的并行方式。

# 一个简化的矩阵构建配置（GitHub Actions 风格）
matrix:
  os: [ubuntu-latest, windows-latest, macos-latest]
  node: [18, 20, 22]
  include:
    - os: ubuntu-latest
      node: 20
      coverage: true  # 只在 ubuntu+node20 上跑覆盖率

矩阵构建的优化要点：

第一，排除不可能或不合理的组合。如果你的项目不使用 Windows 特有的 API，就没必要在 Windows 上跑全量测试。如果 Python 3.11 和 3.12 的行为几乎一致，只跑一个版本作为代表就够了。矩阵中的每个组合都有资源成本，不要无脑配对。

第二，设置 fail-fast 策略。矩阵中的某个组合失败时，是否终止所有还在运行的组合？这取决于具体情况：

• 如果矩阵中的不同组合测试不同的逻辑分支（比如 Linux 和 Windows 的逻辑差异），一个组合失败不应该终止其他组合——你需要看到所有组合的结果。
• 如果矩阵组合只是为了覆盖不同运行环境（比如 Node 18 和 Node 20），一个组合失败大概率意味着其他组合也会失败，自动终止可以节省资源。

第三，矩阵结果的汇总。矩阵构建完成后，需要统一收集和展示所有组合的结果。不要让开发者去翻几十个 job 的日志才能知道整体状态。创建一个"矩阵概览"页（或 job），汇总每个组合的执行状态和关键指标。

四、缓存策略：用空间换时间

CI 流水线中最耗时的操作往往不是编译或测试本身，而是安装依赖。一个 Node.js 项目 npm ci 可能需要 2-3 分钟，一个 Java 项目 mvn dependency:resolve 可能需要 5 分钟以上。缓存就是用来消除这些重复时间的。

4.1 缓存层级设计

缓存不应该是一个"全有或全无"的决定。好的缓存策略是分层的：

第一层：构建镜像层（最有效）
  内容：操作系统 + 运行时环境 + 基础工具链
  粒度：Docker 镜像层（layer cache）
  失效：工具链升级时
  命中率：极高（因为基础环境很少变）

第二层：依赖缓存层
  内容：npm 的 node_modules、Maven 的 .m2/repository、Go 的 module cache
  粒度：lockfile 的哈希值
  失效：lockfile 变更时
  命中率：高（大多数提交只改代码不改依赖）

第三层：构建缓存层
  内容：编译产物（.o 文件、.class 文件、webpack 的缓存）
  粒度：源码文件的哈希值
  失效：对应源码变更时
  命中率：中（取决于变更范围）

第四层：测试缓存层
  内容：增量测试的计算结果
  粒度：测试文件的修改时间
  失效：测试文件变更时
  命中率：低（因为测试文件经常跟随代码变更）

在配置缓存时，一个原则很重要：不要缓存非确定性的东西。如果某个缓存的内容可能因为外部因素（比如网络请求的响应变化）而不同，那就不要缓存它。比如 Docker 镜像的 apk update 阶段不应该缓存——因为不同的 CI 运行可能拿到不同的包索引。

4.2 缓存命中率优化

缓存无效是比较容易的，但如何提高缓存命中率才是体现设计水平的地方。

锁定镜像版本：Docker 构建使用精确的镜像 tag（比如 node:22.4.1-bookworm-slim），而不是浮动 tag（node:22）。浮动 tag 的变化会导致构建缓存完全失效。精确 tag 的镜像内容不变，缓存可以稳定命中。

分离稳定层和变动层：Dockerfile 书写时将稳定的操作（安装构建工具、设置环境变量）放在前面，变动的操作（COPY 源码、安装项目依赖）放在后面。这样即使依赖变更了，基础的镜像层仍然可以复用。

# 好的 Dockerfile 分层
FROM node:22.4.1-bookworm-slim AS builder

# 第一组：稳定层（很少变更）
RUN apt-get update && apt-get install -y build-essential
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --only=production

# 第二组：变动层（每次代码变更都可能变化）
COPY . .
RUN npm run build

这种做法在 Docker builder cache 机制下效果显著。稳定层的缓存几乎总是命中，只有变动层需要重新构建。

依赖缓存的 key 设计：缓存 key 决定何时命中、何时失效。一个好的依赖缓存 key 应该包含：

• lockfile 的哈希：依赖版本变了，缓存失效
• 运行环境的标识：操作系统变了（比如从 ubuntu 换到 macos），缓存失效
• 工具链版本：Node.js 版本变了，原生模块（.node 文件）需要重新编译

一个典型的 GitHub Actions 缓存 key：

key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
restore-keys: |
  npm-${{ runner.os }}-

这样设计 key 的好处是：lockfile 变更时生成全新的缓存（精确匹配），lockfile 未变更但 runner OS 切换时使用部分匹配的旧缓存兜底（restore-keys）。兜底缓存的准确率可能不高，但总比没有缓存好。

4.3 缓存维护与清理

缓存不是越大越好。过大的缓存会：

1. 增加缓存上传/下载时间：如果缓存需要 2 分钟才能下载下来，而重建它只需要 30 秒，缓存就没有意义了。
2. 占用存储空间：大多数 CI 平台的缓存存储是有限额的（GitHub Actions 每个 repo 最多 10GB 缓存）。

实践经验：

• 设置缓存的 TTL：超过一定期限（比如 7 天）的缓存标记为过期。大多数 CI 平台支持自动过期，或者在有新缓存写入时自动淘汰最旧的缓存。
• 不要缓存测试临时文件：测试过程中生成的临时文件、日志文件不应该被缓存。它们不会被复用，只会浪费存储空间。
• 定期重建缓存：即使缓存 key 匹配，也建议每隔一段时间强制重建缓存——这样可以确保缓存内容是最优的（旧的缓存可能包含冗余数据或未清理的临时文件）。

五、失败处理设计

流水线一定会失败。问题的关键不是"如何避免失败"，而是"失败后如何最小化影响、多快恢复、以及如何防止同一类失败反复发生"。

5.1 失败分类与响应策略

不同类型的失败需要不同的响应策略：

5.2 自动重试策略

重试是最常用的失败恢复手段，但也是最容易被滥用的手段。

重试有代价：每次重试都消耗 CI runner 资源和时间。如果整个流水线的重试率超过 5%（每 100 次运行有 5 次需要重试才能通过），说明流水线本身有问题——大部分失败不应该靠重来掩盖。

重试策略的实践指南：

• 基础设施类失败：重试 3 次，间隔 30 秒。这类失败通常是暂时的（网络抖动、资源调度延迟），重试足以解决。
• 测试失败：对于已知的 flaky test，自动重试 1 次。如果重试后通过，自动记录到 flaky test 跟踪表，并给开发者发一条提醒"你的 PR 遇到了一个 flaky test，已自动通过，请关注跟踪表中的记录"。对于首次出现的测试失败，不要自动重试——第一次失败可能是真正的 bug，自动重试会让它被忽略。
• 构建失败：不重试。构建失败通常是不可恢复的（代码错误、配置错误），重试也不会改变结果，只会浪费时间和存储。

重试的折损系数：在重试逻辑中加入一个计数器。同一个提交连续重试 3 次仍失败，标记为"确认为失败"并发送告警。这防止了无限制重试导致的资源耗尽。

5.3 断线重连与恢复机制

分布式系统中常见的"断线重连"概念在流水线中同样适用。当流水线的某个阶段因为外部依赖的短暂不可用而失败时，自动恢复的价值很大。

具体做法：

1. 检查点（Checkpoint）机制：流水线的每个阶段完成后，将进度标记为"已完成"。当外部依赖在阶段 N 失败时，从阶段 N 重新开始，而不是从头开始。
2. 幂等恢复：确保阶段 N 的重启不会导致副作用（比如不会重复发送通知、不会重复创建数据库记录）。这要求每个阶段的状态变化都是幂等的。
3. 超时隔离：当一个阶段依赖的外部服务超时，将该服务的所有请求统一标记为"超时"，而不是让每个测试用例各自等待 30 秒。这能大幅减少失败恢复的时间。

5.4 失败通知的分级与路由

失败通知最重要的设计原则是：通知的接收者应该是能解决问题的人，而不是所有人。

• Lint 失败：通知给提交代码的开发者，私信或 @mention
• 测试失败：通知给提交者 + PR 的 reviewer
• 构建失败：通知给提交者 + 团队负责人
• 部署失败：通知给提交者 + 运维值班人 + 团队负责人
• 生产环境事故：通知给整个团队（包括不活跃的成员）+ 运维值班手机

通知的内容应该包含足够的信息让接收者不需要打开 CI 平台就能诊断问题：

❌ 构建失败
仓库：backend-service
提交：f3a2b1c（main）
阶段：构建失败
错误信息：Webpack build failed - Module not found: 'react-dom/client'
链接：https://ci.company.com/pipelines/12345

不要发送"你的流水线失败了"这样没有任何上下文的通知。开发者收到后需要去 CI 平台翻日志，而打开 CI 平台的延迟就足够让他形成"CI 的通知毫无价值"的认知。

5.5 流水线的熔断机制

当流水线的某个阶段持续失败时（比如外部 API 连续 5 次调用失败），应该启动熔断——自动跳过该阶段，通知维护者，而不是继续重试直到超时。

熔断的好处：

1. 节省资源：既然知道一定会失败，就不要浪费 runner 资源
2. 避免级联失败：一个阶段的重试可能占用资源，导致其他流水线被阻塞
3. 加速反馈：熔断后快速失败，开发者得到的反馈时间更短

熔断的 API 设计类似电路断路器（Circuit Breaker）：

状态机：
  关闭（正常）：每次失败计数 +1
  → 连续 N 次失败 → 切换到"打开"
  打开（熔断）：跳过该阶段，通知维护者
  → 经过 M 分钟后 → 切换到"半开"
  半开（试探）：执行一次该阶段
  → 成功 → 切换到"关闭"，计数清零
  → 失败 → 切换回"打开"

CI 平台本身很少提供断路器功能，但可以通过自定义脚本实现。在 GitHub Actions 中可以用 cache 存储熔断状态，或在外部状态存储（如 Redis）中跟踪。

六、流水线安全

流水线处理凭证、制品、部署权限等敏感资源，是攻击者眼中的高价值目标。2024 年的几次重大供应链攻击都涉及 CI 管道的入侵。

6.1 凭证管理

流水线中最常见的错误是把凭证硬编码在 YAML 配置中。不管是 GitHub Actions 的 env 块，还是 GitLab CI 的 variables，都不应该出现明文凭证。

正确的做法：

• CI 平台的 Secrets 管理：使用 CI 平台内置的 secrets 存储（GitHub Secrets、GitLab CI Variables、AWS Secrets Manager），在运行时注入到环境变量中。这些 secrets 在日志中被自动屏蔽（***）。
• 临时凭证：尽可能使用临时凭证（比如 AWS 的 AssumeRole 生成的临时 Token、GitHub 的 GITHUB_TOKEN），而不是长期有效的 API Key。临时凭证过期后即使泄露，影响范围也是有限的。
• 凭证的权限最小化：每个流水线 job 使用的凭证只授予它需要的权限。不要在同一个 job 中使用有"管理员"权限的凭证。一个 job 需要读 S3 桶，就只给 S3 Read 权限；需要发通知，就只给 Webhook 调用权限。
• 分阶段凭证：不同阶段的凭证应该不同。代码检查阶段的凭证不需要部署权限；部署测试环境的凭证不应该能操作生产环境。

6.2 制品签名与完整性验证

构建产物的完整性验证是供应链安全的基石。

制品签署流程：

1. CI 在构建完成后，用私钥对构建产物计算签名
2. 签名文件和构建产物一起归档
3. 部署系统在拉取制品时验证签名
4. 签名验证通过后部署，否则拒绝部署

签名用的私钥必须妥善保管：

• 私钥存储在专门的 secrets store 中
• 私钥不出 CI 环境（签名过程在 CI runner 内完成，结果输出为签名文件）
• 定期轮换私钥

完整性验证的两种方式：

1. 哈希校验：对比构建和部署时分别计算的 SHA-256 哈希值。这是最基础的验证手段，能防止传输过程中的篡改。
2. 数字签名：使用私钥签名，公钥验证。这能防止源头伪造——只有持有私钥的 CI 系统才能生成有效的制品。公钥可以集成到部署工具（Helm、Kustomize、ArgoCD）的验证流程中。

6.3 供应链安全

CI 流水线的依赖链是供应链攻击的主要突破口。npm 的 event-stream 事件、Python 的 ctx 事件都是通过 CI 构建管道植入恶意代码的典型案例。

依赖安全扫描：

• 在代码检查阶段集成 SCA（Software Composition Analysis）工具，扫描依赖的已知漏洞（CVE）。工具包括 Snyk、Dependabot、Renovate、Trivy 等。
• 每次依赖变更（lockfile 更新）都触发自动扫描，阻止已知漏洞进入构建。
• 对于严重漏洞（CVSS >= 9.0），自动阻断流水线并通知安全团队。

依赖源的约束：

• 使用私有镜像仓库（如 Docker Registry、Nexus、Artifactory）作为唯一的外部依赖源。CI runner 不直接访问公网镜像仓库和包管理器注册表。
• 所有依赖包在被拉入私有仓库之前经过扫描和审批。
• 这种做法增加了运维成本（需要维护私有仓库），但对于安全要求较高的系统是值得的。

6.4 流水线配置的安全审查

流水线配置本身需要 code review。这听起来有些过度，但经验表明：CI 配置中的安全漏洞比代码中的更难发现，因为在 CI 配置的环境变量中放一个不需要的 AWS 密钥，比在代码中写一个明显的 bug 更隐蔽。

安全审查的检查清单：

• 所有凭证都使用 CI secrets 机制，没有明文写入 YAML
• 每个 job 的权限范围是最小的
• 不存在条件分支绕过安全扫描的特性（比如 git push -f 后的运行路径）
• 构建产物签名流程已实现
• 依赖锁定文件（lockfile）已生成并提交到仓库
• 没有 ci skip、--no-verify 之类的跳过安全检查的触发器

七、一个完整的流水线示例

理论部分已经足够多，来看看一个具体的流水线设计。假设我们有一个中等规模的 Web 应用（前端 + 后端 monorepo），使用以下技术栈：React 前端、Node.js 后端、PostgreSQL 数据库、Docker 容器化部署。

7.1 快速通道（5-8 分钟）

graph LR
    A["git push"] --> B["代码检查(并行)"]
    B --> C["Lint + 格式化检查"]
    B --> D["TypeScript 类型检查"]
    B --> E["SAST 扫描"]
    C --> F["单元测试(并行)"]
    D --> F
    E --> F
    F --> G{"全部通过?"}
    G -->|是| H["PR 合并许可"]
    G -->|否| I["通知开发者"]

这是一个开发者在每次 push 后都能获得的反馈。如果通过了，他知道代码在语法、类型和单元级别没有明显问题，可以放心地继续开发或请求 review。

7.2 完整通道（15-25 分钟）

PR 合并到 main 分支后触发完整流水线：

graph TD
    A["PR 合并到 main"] --> B["构建(容器化)"]
    B --> C[SBOM 生成]
    B --> D[制品签名]
    C --> E[集成测试]
    D --> E
    E --> F[服务集成测试]
    E --> G[契约测试]
    F --> H[部署到测试环境]
    G --> H
    H --> I[Smoke 测试]
    I --> J{"全部通过?"}
    J -->|是| K[部署到 Staging]
    J -->|否| L[通知团队]
    K --> M[Staging 验证]
    M --> N[等待人工审批]
    N --> O[部署到生产(灰度)]

7.3 夜间通道（通宵运行）

每天凌晨定时触发的全量验证：

1. 全量单元测试（包含所有历史用例）
2. 全量集成测试（覆盖所有服务端点和数据路径）
3. 全量 E2E 测试（核心业务流程的全部路径）
4. 安全扫描（深度分析 + 全量依赖 CVE 扫描）
5. 性能测试（API 响应时间、数据库查询性能基准）
6. 报告生成（覆盖率趋势、测试通过率、构建时间趋势）

夜间通道的结果在第二天早上汇总到团队 Slack/Feishu 频道。夜间通道不应阻塞白天的主线发布——它的作用是"今早发现的问题昨天就存在了"。

八、常见的反模式

经验和教训都是从反模式中积累的。以下是流水线设计中我见过最多的反模式，每条都是实际踩过的坑。

反模式一：一切都在一个 job 里。把 lint、测试、构建、部署写到一个 shell 脚本或者一个 YAML job 里。结果是每个步骤失败都要从头跑，不能并行，反馈路径总是最长的那个步骤。根本原因是对 CI 平台的 DAG 支持不了解，或者懒得拆分。

反模式二：无限重试。任何失败都自动重试 3 次，期望"多跑几次就过了"。结果是真的 bug 被掩盖，问题在延迟后爆发。而 flaky test 因为被自动重试掩盖，无人修复，逐渐积累到一个失控的程度。

反模式三：不锁版本。Docker Hub 的 FROM node:latest 或者 FROM ubuntu:latest。今天构建通过了不代表明天也能通过。某个依赖的上游版本更新可能带来破坏性变化，影响的是所有不锁版本的流水线。修复方式是锁定精确版本号并使用 Dependabot 或 Renovate 定期更新。

反模式四：生产环境的部署和测试环境用同一个构建产物。听起来是好事（保证一致性），但是测试环境构建失败了，也会影响生产部署。"同一次构建通用于所有环境"的前提是：这个构建通过了所有阶段的测试。如果测试环境部署失败，这个构建还没有被打上"已验证"的标签，不能用于生产。一个好的做法是：构建阶段生成一个"原始制品"，测试阶段通过后对原始制品进行"签名标记"标记为已验证，部署环境只接受已验证的制品。

反模式五：在 CI 里跑所有测试。不是所有测试都需要在每次 push 上运行。运行成本高、执行时间长、不稳定的测试应该从快速通道移到定时通道。作为更激进的策略，可以考虑在 CI 中只跑变更相关的影响测试，全量测试只在夜间和发版前执行。

反模式六：共享测试环境导致竞态。PR-A 和 PR-B 同时在同一个测试数据库上跑集成测试。PR-A 创建的测试数据干扰了 PR-B 的测试结果。修复方法是每个 CI job 使用独立的测试环境（用 Testcontainers 或动态分配沙箱环境）。

反模式七：CI 当成运维工具。在 CI 里跑数据库迁移、生产环境配置更新、数据导出这类运维操作。CI 的职责是验证代码变更的可靠性，而不是执行运维任务。运维操作应该使用专门的部署工具（Ansible、Terraform、Argo Workflows），经过单独的审批流程。

结论：流水线的生命周期

这篇文章从原则到实践、从策略到陷阱，覆盖了持续集成流水线设计的主要维度。但最后我想提醒一点：流水线不是一次性设计的产品，它是一个需要持续演进的系统。

一个成熟的流水线会经历这样的生命周期：

1. 创建期：写几行 YAML，跑通最基本的构建 + 测试
2. 稳定期：引入代码检查、分阶段执行、开始关注执行时间
3. 优化期：引入并行化、缓存、测试分片、Fast Gate
4. 安全期：引入安全扫描、制品签名、凭证管理、依赖约束
5. 自治期：自动修复 flaky test、自动熔断不可用依赖、自动调整并行度

大多数团队停留在第 2-3 阶段，足够解决日常问题。但如果你正在为 CI 流水线的频繁失败、逐渐增加的执行时间、偶发的环境问题而烦恼，不要只想着"修好这个 bug"——退一步，重新审视你的流水线设计。

流水线的质量决定了团队的生产力天花板。一个设计良好的流水线，会让开发团队感到"有依靠"——知道自己的变更会快速得到反馈，知道部署是安全的，知道出了问题可以快速恢复。一个设计糟糕的流水线，会让开发团队感到"有障碍"——提交变更后要等半小时才能得到反馈，部署流程要手工记十几个步骤，出了事故找不到责任人。

技术选型（用 GitHub Actions 还是 GitLab CI 还是 Jenkins）不重要。真正重要的是你有没有把流水线当作一个产品来设计——有用户视角、有边界、有演进计划。流水线是你的团队交付软件的核心基础设施。值得花时间设计好它。

---

这篇文章是"基础设施即代码"系列的一部分。相关主题包括：配置即代码的隐患、日志系统的结构化设计、错误处理的韧性设计、多 Agent 系统的协调者困境。