跳至主要內容

CI/CD 流水线设计原则——我见过的最烂和最好的流水线各是什么样的

老张2026/4/30大约 14 分钟

CI/CD 流水线设计原则——我见过的最烂和最好的流水线各是什么样的

适读人群：参与 CI/CD 建设的工程师和架构师 | 阅读时长：约18分钟 | 核心价值：从真实反面案例中学习，掌握流水线设计的核心原则

做了这么多年 DevOps，我见过各种各样的流水线。

有的流水线让人心旷神怡——绿了就是真绿，快速给开发者反馈，出了问题马上报警，一键回滚，整个团队对它充满信任。

有的流水线让人抓狂——经常出现"流水线红了但代码没问题"，大家习惯性地先 rerun 一次看看；部署完全自动化但没有任何保护，某个同事手滑 force push 直接就把生产环境的 DB schema 给改了；每次发布都要等 40 分钟，最后发现其中有 20 分钟是在等一个没人在用的性能测试……

这篇文章我想做一件不太一样的事——把我见过的最烂的流水线和最好的流水线各描述一遍，从中提炼出设计原则。

我见过的最烂的流水线

特征一：Flaky Tests 泛滥，绿灯没有信任

那是一家电商公司，Java 微服务体系，Jenkins 跑 CI。

他们的流水线有一个特征：平均每天有 3-5 个 job 会因为"网络超时"或者"莫名其妙的 NullPointerException"失败，但只要 rerun 一次，大概率就绿了。

这听起来是测试问题，但实际上是流水线信任危机。

一旦大家习惯了"红了先 rerun"，流水线的红灯就失去了意义。某天真的有一个 bug 被捕获了，开发者的本能反应不是去看代码，而是先 rerun。如果 rerun 还红，才去看错误信息。

我问过他们的 tech lead："你们每天有多少次是因为真正的 bug 导致流水线红的？"

他想了很久，说："可能……20% 吧？其余 80% 都是偶发的环境问题。"

20% 的信噪比，这条流水线其实已经基本失效了。

根本原因：测试里有大量依赖外部网络、真实数据库、第三方服务的集成测试，混在单元测试里一起跑，任何外部不稳定性都会让 CI 失败。

特征二：流水线是完全线性的，40 分钟的串行等待

编译(5min) → 单元测试(8min) → 集成测试(12min) → 代码扫描(6min) → 构建镜像(5min) → 部署测试环境(4min)

总计 40 分钟，全部串行。

其中，代码扫描和集成测试完全可以并行。集成测试跑着的同时，完全可以在另一个 agent 上跑代码扫描。这样可以把总时间压缩到 25 分钟左右。

更糟糕的是，"部署测试环境"这一步是每次构建都跑的，包括 feature branch 的 PR 提交。一个 feature branch 改了一行配置，触发了整个流水线，包括部署到测试环境，测试环境随时被覆盖，测试人员完全不知道当前测试环境是哪个版本。

特征三：密钥明文存在 Jenkinsfile 里

我当时在审计这家公司的流水线配置，在一个 Jenkinsfile 里看到了这样的代码：

stage('Deploy') {
    steps {
        sh """
            export DB_PASSWORD=Prod@2023!
            export AWS_SECRET_KEY=wJalrXUtnFEMI/K7MDENG
            ./deploy.sh
        """
    }
}

这段 Jenkinsfile 在 GitHub 公开仓库里。密码、AWS 密钥就这样暴露在互联网上。

我告诉他们的时候，他们的 CTO 脸色变了。那个 AWS 密钥已经暴露了至少半年，好在没有被扫描到滥用（应该是侥幸）。

我见过的最好的流水线

特征一：快速反馈环

那是一家 SaaS 公司，他们的流水线设计遵循了一个核心原则：越快的反馈越靠前。

提交代码
    ↓
[30秒] 代码格式检查 + 静态分析（并行）
    ↓（如果这步失败，立刻终止，不继续）
[3分钟] 单元测试
    ↓
[8分钟] 集成测试 + 代码覆盖率检查（并行）
    ↓
[2分钟] 构建镜像
    ↓
[5分钟] E2E 冒烟测试（仅 main branch）

最快 3 分 30 秒就能拿到反馈（如果代码格式和单元测试都通过）。大部分简单 bug 在 5 分钟内就能被捕获。

特征二：测试分层，Flaky Tests 有追踪机制

他们把测试分成三层，在流水线里分别处理：

  1. L1 - 单元测试：纯内存，无外部依赖，强制要求每次提交都绿，任何 flaky 的单元测试必须在一个迭代内修复，否则暂时 skip 并记录 tech debt
  2. L2 - 集成测试：用 TestContainers 启动真实数据库和 Redis，可接受偶发失败，但有自动重试机制（最多重试 2 次），如果重试后仍然失败才算真正失败
  3. L3 - E2E 测试：真实环境，只在 main branch 跑，失败不阻塞 PR merge，但会触发 Slack 告警

这套分层策略让流水线的"真阳性率"保持在 95% 以上——红灯几乎都意味着真正的问题。

特征三：部署环节有完整的保护机制

他们的 Staging 和 Production 部署是这样设计的：

deploy-staging:
  needs: [unit-tests, integration-tests]
  environment: staging
  only:
    - main
  script:
    - ./deploy.sh staging $IMAGE_TAG
    - ./wait-healthy.sh staging 120  # 等待服务健康检查通过
    - ./smoke-test.sh staging

deploy-production:
  needs: [deploy-staging]
  environment: production
  only:
    - tags  # 只有打了 release tag 才能部署生产
  when: manual  # 手动触发，需要审批
  script:
    - ./deploy.sh production $IMAGE_TAG
    - ./wait-healthy.sh production 180
    - ./smoke-test.sh production
  after_script:
    - |
      if [ "$CI_JOB_STATUS" == "failed" ]; then
        ./rollback.sh production
      fi

关键设计点：

  1. 只有 main branch 能部署 Staging
  2. 只有 release tag 能部署 Production
  3. Production 部署是手动触发，需要有权限的人点击
  4. 部署失败自动执行回滚脚本
  5. 每次部署后都有冒烟测试验证

流水线设计的核心原则

经过多年实践，我总结出以下几条我认为最重要的原则：

原则一：快速失败（Fail Fast）

流水线应该把最快能发现问题的检查放在最前面。代码格式检查 30 秒就能完成，如果放在集成测试之后跑，开发者要等 20 分钟才知道自己少了个分号，这是浪费。

# 好的顺序
stages:
  - lint        # 最快，30秒
  - unit-test   # 快，3分钟
  - integration # 中速，10分钟
  - e2e         # 最慢，20分钟

# 坏的顺序（按照我认为重要性而非速度排序）
stages:
  - e2e         # 20分钟后才知道有没有格式问题
  - integration
  - unit-test
  - lint

原则二：并行化一切可以并行的

单元测试和代码质量扫描之间没有依赖关系，应该并行。集成测试和安全扫描之间没有依赖关系，应该并行。

画出流水线的 DAG（有向无环图），识别出哪些步骤可以并行执行，然后真的去并行。每一分钟的构建时间对开发者的体验影响都很直接。

原则三：环境保护要有门禁

Staging 环境、Production 环境，要有明确的准入条件：

  • Staging：只有特定分支（main/develop）能触发，PR 不能直接部署
  • Production：只有打了 release tag 能触发，且需要人工审批

这不是在限制开发者，这是在保护整个团队不因为一次误操作付出惨重代价。

原则四：密钥永远不进代码库

密钥、密码、token，必须通过 CI/CD 平台的 secret 管理功能注入，绝不能硬编码在 YAML 或任何配置文件里。

# 正确
script:
  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY

# 错误，绝对不能这样
script:
  - docker login -u myuser -p MyP@ssw0rd registry.company.com

即使是私有仓库，也要假设有一天代码会泄露——密钥不应该在泄露后立刻造成损失。

原则五：流水线要可观测

好的流水线让你一眼就能看出：

  • 哪个步骤失败了
  • 失败的原因是什么
  • 失败影响了什么

关键指标要收集：每个步骤的执行时间、每日构建数量、成功率、Flaky test 次数。这些数据帮助你持续改进流水线。

踩坑实录

坑一：生产和测试用同一个流水线模板

我见过有人把生产部署和测试环境部署的配置写在同一个 job 里，通过环境变量区分：

deploy:
  script:
    - if [ "$ENV" == "prod" ]; then ./deploy-prod.sh; else ./deploy-test.sh; fi

这样的问题是：改了测试环境的部署逻辑，直接影响到了生产环境的部署脚本，因为它们是同一个文件。建议把不同环境的部署逻辑完全分开，宁可有一些重复，也要保持独立性。

坑二：构建产物（artifact）没有版本标识

有人把所有分支的构建产物都发布为 latest tag。结果测试环境永远不知道自己跑的是什么版本，出了问题也无法精确回滚。

正确做法：至少用 commit SHA 或者 build number + commit SHA 来标识每一个构建产物。

坑三：流水线没有超时设置

有一个集成测试步骤，因为测试代码里有个死锁 bug，job 跑到一半就挂住了，一挂就是两个小时，把 Runner 的并发槽位给占满了，后续所有构建都在排队。

所有 job 都要设置合理的超时时间。集成测试最多跑 30 分钟，E2E 测试最多跑 60 分钟，超时就强制失败，不要让 job 无限期运行。

深度解析：从"流水线"到"工程能力平台"的思维跃迁

很多团队把 CI/CD 流水线理解为"自动化脚本"——把原来手工做的事情用脚本自动化。这个理解没有错，但层次不够深。

更成熟的理解是：CI/CD 流水线是团队工程能力的外化表达。一条流水线的设计，反映了团队对质量、安全、效率的认知水平。

举个例子：一个团队有完善的代码覆盖率门禁、SonarQube 质量检查、Trivy 镜像扫描、Staging 自动部署、生产人工审批，这说明这个团队已经把"质量、安全、效率"内化成了工程流程。而一个团队的流水线只有"编译、打包、上传"，说明质量和安全还停留在"靠人自觉"的阶段。

从这个角度看，优化流水线不只是技术问题，更是文化问题。你需要团队认同"快速反馈有价值"、"测试覆盖率值得投入"、"安全扫描不是拖后腿"，流水线才能真正运转起来。

深度解析：流水线的分支策略

流水线的行为和分支策略是高度相关的。两种常见的分支策略对流水线设计的影响：

功能分支（Feature Branch）策略

每个新功能在独立的 feature branch 开发，PR 合并到 main 之前需要 CI 绿。

这种策略下，流水线在 PR 阶段的职责是：快速给反馈（单元测试、代码格式检查），帮助 reviewer 判断代码质量（覆盖率、SonarQube）。不要在 PR 阶段部署到 Staging——PR 数量可能很多，频繁部署 Staging 会让测试环境混乱。

主干开发（Trunk-based Development）策略

所有开发者直接提交到 main（或者使用很短命的 feature branch，最多存在一两天）。

这种策略下，流水线要求更高：CI 必须非常快（因为每次提交都触发），测试覆盖率要足够高（因为没有长时间的 PR review 保护），功能开关（Feature Flags）是标配（未完成的功能用 flag 关掉）。

这两种策略没有优劣之分，但要根据选择的策略来设计流水线，不能混用。

如何评估你的流水线健康度

流水线的设计原则讲清楚了，但如何知道自己现在的流水线处于什么水平？

我用一套简单的问卷来评估：

信任度问卷

  • 流水线红了，你的第一反应是去看代码，还是先 rerun？
  • 过去一个月，有没有因为"反正流水线经常误报"而手动 push 到主干绕过检查？
  • 你能说出流水线每个步骤的作用吗？

效率问卷

  • 从 PR 提交到得到反馈，要等多久？
  • 每天最多能发布多少次？
  • 一次发布失败后，回滚需要多少步骤？

安全问卷

  • 任何人都能部署生产环境吗？
  • 有没有密钥可能存在于代码仓库里？
  • 发布失败后，有自动回滚机制吗？

如果这三个维度的问题大部分答案让你觉得不安，说明你的流水线需要改造了。

一个完整的、可以直接用的流水线框架

光讲原则不够，我把一个实际的 GitLab CI 流水线结构分享出来，可以直接参考改造：

# .gitlab-ci.yml 框架

# 全局变量
variables:
  IMAGE_TAG: $CI_COMMIT_SHORT_SHA
  DOCKER_REGISTRY: registry.company.com

# Stage 定义（按速度排序，最快的靠前）
stages:
  - lint           # 最快：代码格式、静态检查
  - unit-test      # 较快：单元测试
  - build          # 中速：编译、构建镜像
  - integration    # 较慢：集成测试
  - security       # 并行：安全扫描
  - staging-deploy # 部署 Staging
  - e2e            # E2E 测试
  - prod-deploy    # 手动：部署生产

# 通用缓存配置（减少依赖下载时间）
.maven-cache:
  cache:
    key:
      files: [pom.xml]
    paths: [.m2/repository/]

# Lint：30秒内给出反馈
lint:
  stage: lint
  image: maven:3.9-eclipse-temurin-17
  extends: .maven-cache
  cache:
    policy: pull
  script:
    - mvn checkstyle:check -B  # 代码格式
    - mvn pmd:check -B         # 静态分析
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"

# 单元测试：3分钟内给出反馈
unit-test:
  stage: unit-test
  image: maven:3.9-eclipse-temurin-17
  extends: .maven-cache
  cache:
    policy: pull
  script:
    - mvn test -B
  artifacts:
    reports:
      junit: target/surefire-reports/TEST-*.xml

# 构建镜像（仅 main branch 和 release tag）
build-image:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_HOST: tcp://docker:2375
  script:
    - docker build -t $DOCKER_REGISTRY/myapp:$IMAGE_TAG .
    - docker push $DOCKER_REGISTRY/myapp:$IMAGE_TAG
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/

# 集成测试和安全扫描：并行运行
integration-test:
  stage: integration
  extends: .maven-cache
  image: maven:3.9-eclipse-temurin-17
  services:
    - name: postgres:15
      alias: postgres
  variables:
    SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/testdb
  script:
    - mvn verify -Pintegration -B
  retry:
    max: 2
    when: runner_system_failure  # 只重试系统问题，不重试代码问题

security-scan:
  stage: integration  # 与集成测试并行
  image: aquasec/trivy:latest
  script:
    - trivy fs --exit-code 1 --severity CRITICAL .
  allow_failure: false

# Staging 部署：自动，仅 main branch
deploy-staging:
  stage: staging-deploy
  image: bitnami/kubectl:latest
  script:
    - kubectl set image deployment/myapp myapp=$DOCKER_REGISTRY/myapp:$IMAGE_TAG -n staging
    - kubectl rollout status deployment/myapp -n staging --timeout=3m
    - ./smoke-test.sh staging
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  environment:
    name: staging
    url: https://staging.company.com

# E2E：部署后跑
e2e-test:
  stage: e2e
  script:
    - ./e2e-tests.sh staging
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  allow_failure: true  # E2E 偶发失败不阻塞，但发告警

# 生产部署：手动审批，仅 release tag
deploy-production:
  stage: prod-deploy
  image: bitnami/kubectl:latest
  when: manual  # 人工审批
  script:
    - kubectl set image deployment/myapp myapp=$DOCKER_REGISTRY/myapp:$IMAGE_TAG -n production
    - kubectl rollout status deployment/myapp -n production --timeout=5m
    - ./smoke-test.sh production
  after_script:
    - |
      if [ "$CI_JOB_STATUS" == "failed" ]; then
        kubectl rollout undo deployment/myapp -n production
      fi
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
  environment:
    name: production
    url: https://app.company.com

这个框架体现了所有前面讲的原则：

  • Lint 最先，给出最快反馈
  • 集成测试和安全扫描并行
  • Staging 自动，Production 手动
  • 集成测试有自动重试（针对环境问题），但不无限重试
  • 生产部署失败自动回滚

流水线的"技术债"

很多团队的流水线就像老旧的代码库——功能在运转，但没人敢动，因为不知道改哪里会出问题。

定期对流水线做"回顾"是很必要的：

  • 每个月看一次构建时间趋势，有没有越来越慢的步骤？
  • 每个月统计 Flaky test 数量，有没有需要修复的？
  • 每个季度 review 一次整个流水线设计，有没有过时的步骤？

把流水线当代码来维护，而不是配置一次就再也不碰。

总结

好的流水线和烂的流水线，差距不在工具，在于设计理念。

最核心的理念：流水线是团队的安全网，不是摆设，也不是负担。 设计流水线的时候，要时刻问自己：这个流水线能让团队更有信心地发布，还是在给团队制造焦虑？

如果你的团队现在习惯了"先 rerun 再说"，那是时候认真重构你的流水线了。

从上面分享的框架开始，先把最关键的原则落地——快速反馈、并行化、环境保护——然后再一步步优化细节。流水线的改进没有终点，和业务一起持续演进才是正确的姿态。

编辑此页
最近更新:
贡献者: xiaozhangge