CI/CD 流水线设计

• 分支、标签、MR 三类触发事件在各类 CI 中的含义与优先级
• 环境隔离：feature 分支跑轻量校验、主干跑完整流水线、标签跑发布
• 并发与去重：同一分支多次提交的合并、重复触发抑制

通过触发条件区分事件至少要在三个维度上配置：分支（branch）触发用于日常特性迭代，通常只做编译、单元测试与静态检查；MR/PR 触发用于合并前校验，在交互式场景下还需配置"合并后处理"（post-merge）来跑集成测试；标签（tag）触发用于真正发布，往往仅允许在主干上打符合语义版本规则的标签，并串联完整的构建、镜像推送与发布门禁。GitLab CI 用 rules/only/except，GitHub Actions 用 on.push.branches、on.pull_request、on.tags。执行策略上核心是"分支决定深度、标签决定发布"：feature 分支缩短流水线、主干跑全量、发布标签走受控的晋升流。同时要处理并发去重（同一分支快速连续提交时用 concurrency 组取消旧任务）与受保护分支/标签的权限约束，避免任意分支触发生产发布。

这样设计既保证开发反馈速度（短分支快校验），又保证生产质量（主干全量、发布受控），同时避免重复构建浪费资源。触发事件与执行范围强关联，是"环境即门禁"思想在触发器层面的落地。

• 手动阶段（manual）与自动阶段（automatic）的编排
• 门禁的时机：放在镜像构建与制品晋升之后、真正部署之前
• 权限校验：谁能点、是否二次认证、审批记录留痕

在 GitLab CI 中把发布阶段标记为 when: manual 即可让该阶段暂停、等待人工点击。设计上手动门禁应放在自动阶段完成之后（构建、测试、镜像扫描、制品晋级都通过），作为"部署到生产"前的最后一道人工闸门。门禁作业要绑定到具体执行者，最好配合 allow_failure: false 强制其必须成功，并利用受保护环境（protected environment）限定只有具备发布权限的角色才能批准。更严格的可把手动阶段与审批流（如 Jenkins 的 input、GitHub Environments 的 approval）结合，实现审批留痕与多级审批。

手动门禁解决的是"自动流水线跑完但人不愿直接上生产"的信任缺口，把机器判断与人工判断分离，同时保留审计记录。其本质是"持续交付"与"持续部署"的分界点。

• stages 定义全局阶段顺序，同阶段 job 并行执行
• 失败策略：allow_failure、when（on_failure/on_success/always/manual）
• job 的依赖/制品传递与缓存

GitLab CI 中 stages 定义流水线的全局阶段及其顺序，同一阶段的多个 job 默认并行执行，只有前一阶段全部成功（或按 when 策略允许）才进入下一阶段。jobs 是具体执行单元，每个 job 声明所属 stage、script（命令行序列）、rules/only/except（触发条件）、artifacts（产物传递）与 cache。失败策略由 allow_failure 与 when 控制：when: on_success（默认，前一阶段成功才跑）、when: on_failure（前一阶段失败才跑，用于清理/通知）、when: always（无论成败都跑）、when: manual（手动）。allow_failure: true 允许非关键 job 失败而不阻塞流水线。

stages 体现"阶段串行、同阶段并行"的 DAG 思想，when 策略则表达失败后的分支走向，二者配合才能精确表达"测试失败就停止、通知类任务总是执行"等复杂语义。

• 失败策略：early fail 与容错（small 失败不影响后续）
• 制品不可变：构建一次、晋升传递，禁止重打 tag
• 晋升门禁：产物在环境间只晋升不重建

三条原则共同构成"一次构建、处处晋升"的发布模型。阶段失败策略上，关键路径（编译、单元测试、镜像扫描）应 early fail 快速中断，避免浪费；而低风险任务（如仅文档、静态报表）可 allow_failure 容错。制品不可变传递指同一构建产物（如带 digest 的镜像）只在环境间晋升，绝不重新构建或覆盖 tag，保证测试过的制品与生产完全一致。环境晋升门禁指每次晋升（dev→staging→prod）都要重新验证（重跑必要的测试、扫描、签名校验），并记录晋升者与时间，形成可审计的晋升链。

三条原则是防止"测试环境与生产不一致"的黄金组合：失败策略控制质量可靠性，不可变保证一致性，晋升门禁保证可追溯与可审批。它们共同决定了流水线的可信度与可审计性。

• CI/CD/CD 三者的定义与自动化程度
• 预发（预发布）环境的自动部署
• 生产环境的人工门禁与自动门禁的取舍

CI 关注"自动构建+自动测试"，把代码合并到共享主干的错误尽早暴露；持续交付（Continuous Delivery）在 CI 基础上把制品自动部署到预发/验收环境，但生产发布仍由人工/审批触发；持续部署（Continuous Deployment）则把生产发布也完全自动化，只要验证通过就自动上线。三者门槛逐渐提高：CI 的门禁是测试通过，持续交付的门禁是"制品可随时进入生产"，持续部署的门禁是"验证通过即自动发布"。生产发布的自动化程度取决于业务风险、合规要求与回滚能力，通常给生产保留人工批准或分阶段自动发布。

边界核心是"自动化推进到哪一步"。CI 是基础，持续交付保证可发布性，持续部署把发布也自动化。门禁差异本质上是"人机决策分工"的差异，风险越高越保留人工环节。

• Codefresh 的 GitOps 与 Pipeline 双模式
• 镜像构建与缓存（build cache）
• 与 Argo CD/Rollouts 的集成

Codefresh 面向 Kubernetes 提供两条主线：一是传统 Pipeline 流水线，用于构建代码、生成镜像并推送到 registry；二是 GitOps 模式，通过类似 Argo CD 的机制把 Git 仓库中的清单同步到集群。Codefresh 内置了基于容器的构建器，支持 BuildKit 缓存与跨平台构建，能依据 Dockerfile 或 binfmt 构建多架构镜像。在部署环节，Codefresh 可以与 Argo CD/Rollouts 深度集成，把镜像晋级与渐进式发布（金丝雀/蓝绿）编排进同一套交付流程，并支持使用 runtime 环境（如 Kubernetes）来执行构建步骤，实现"在集群内构建、在集群内部署"。

Codefresh 的卖点是"把 CI 与 GitOps 统一"，让镜像构建、制品晋级与部署同步在一个平台上完成，减少工具的切换成本，尤其适合以 Kubernetes 为交付目标的团队。

• Pipeline as Code（Jenkinsfile）与声明式/脚本式语法
• 主从（master/agent）架构与节点标签
• 凭证管理、共享库与留存策略

Jenkins 的核心流程是"写 Jenkinsfile（Pipeline as Code）→ 主节点调度 → 代理节点执行 → 输出制品与报告"。最佳实践包括：用声明式 Pipeline 定义 stages，把流水线模板化并纳入版本控制；用 master/agent 架构把构建任务分发到标签化的 agent 上，避免主节点负载过重；用 Jenkins Credentials 插件管理密钥而非明文；用共享库（Shared Library）复用构建函数；对历史构建与日志设置留存策略，避免磁盘膨胀；用 sh/bat 包装命令并捕获失败状态，确保失败能被正确标记。生产上还应考虑高可用（多控制器、外部存储）与安全（限制 agent 权限、RBAC）。

Jenkins 作为最通用 CI 工具体系成熟，但"自由风格任务"易失控，最佳实践的核心是"流水线即代码、可复用、可审计"，把配置与脚本从点按式界面迁移到代码仓库。

• 阶段粒度与依赖关系（DAG）
• 并行时机：可并行阶段放在同一层
• 失败策略：逐级卡点、审批门禁

阶段划分应遵循"依赖决定串行、无依赖可并行"的原则：构建必须最先且唯一，单元测试依赖构建可并行于其他测试，集成测试依赖单元测试通过（通常串行），发布审批是最后的人工门禁。并行体现在同一阶段内对多个测试任务、多平台矩阵、多分片并行执行，用 DAG 表达依赖关系。失败策略上，构建与单元测试失败应 early fail 阻断下游；集成测试失败也应阻断晋升；发布审批失败则保留制品等待人工决策。关键是要把"耗时长的测试"与"依赖它的门禁"合理分层，避免无谓串行拉长流水线。

阶段划分是对流水线时长的直接优化点：把可并行的任务并行化，把必须串行的依赖关系显式化，并用失败策略区分"致命失败"与"可容忍失败"。

• 依赖缓存（npm/maven/go cache）复用
• 镜像构建缓存（BuildKit remote cache / 分层缓存）
• 测试分片并行以摊薄耗时

降低流水线时长有三类手段：依赖缓存让每次构建复用已下载的依赖包（如 npm cache、maven local repo、go module cache），避免重复下载；构建缓存利用镜像分层缓存（BuildKit 的 --cache-from/remote cache、Docker layer cache）使未变化的层直接复用，大幅缩短镜像构建时间；并行分片把大量测试按文件或用例切分到多个 agent 并行执行，用机器换时间。设计上要为缓存设置 key（如依赖锁文件哈希），保证缓存失效正确，同时控制缓存大小与过期策略，避免缓存与构建环境不一致。

缓存与分片是"时间换成本"的典型手段：缓存复用已算好的结果，分片用并行机器摊平时间。核心难点是缓存命中率与正确性（key 设计、失效时机）。

• 过长流水线：把无关步骤都塞进一条流水线
• 脆弱（flaky）测试：随机失败导致不稳定
• 门禁缺失：没有审批或校验就推进

常见误区有三：一是流水线过长——把 lint、文档、多套测试、多环境部署全塞进一条流水线，导致单次运行冗长、反馈慢；改进是按职责拆分流水线（如 PR 轻量校验、主干全量、发布单独流水线），并充分并行。二是脆弱测试——偶发失败让流水线不稳定，团队被迫"重跑直到通过"，掩盖真实问题；改进是引入 flaky 测试治理，标记、隔离并修复。三是门禁缺失——没有环境审批、没有制品校验就盲目推进，导致问题上线；改进是建立明确的环境晋升门禁与制品签名/扫描校验。

这三点分别对应"反馈速度、稳定性、可信度"三大质量维度，改进的核心是"小步快跑、测试可信、门禁阻断"。

• 端到端流水线的整体编排
• 阶段门禁与晋升路径
• 回滚入口的预留

一条完整的"提交到生产"流水线应串联：提交触发 → 构建测试 → 镜像构建与扫描 → 制品晋级（dev→staging→prod）→ 生产部署 → 发布后验证。触发策略决定何时启动（push/PR/tag）；阶段门禁在每级晋升时校验质量（测试通过、扫描无高危漏洞、签名有效）；制品晋级保证同一 digest 只在环境间传递而不重建；回滚入口则必须在发布阶段预留，通常通过保留上一版本制品、定义回滚命令（如 kubectl rollout undo 或切换镜像 tag）以及发布后自动/手动回滚触发，形成"发布即回滚预案"的闭环。

端到端设计的关键是把"往前走（晋升）"与"往后走（回滚）"都纳入同一套流水线体系，保证发布与回滚使用同一可信制品与同一套门禁逻辑。

• 测试金字塔在流水线中的位置
• 各层测试的时长与频率
• flaky 测试的识别与处置

测试分层遵循金字塔：单元测试最底层、最快、运行最频繁，放在流水线最前面并尽量并行；集成测试依赖外部组件（数据库、消息队列），放在单元测试之后、可用 testcontainers 或 staging 环境；E2E 测试最慢、最脆弱，通常只跑在关键路径或每日/发布前执行，并对环境隔离。时长控制上，把慢测试分层到更晚、更少运行的阶段，并用分片并行。flaky 测试治理要识别随机失败（对比重跑、失败率统计），标记为 flaky 放入隔离队列，修复后才恢复到主流水线，避免其污染主链路信号。

测试分层本质是"用速度与成本分层"，把廉价的快速测试尽可能靠前、昂贵的慢测试放在关键节点，而 flaky 治理保证流水线信号可信。

• 覆盖指标：阶段耗时、失败率、队列积压
• 日志检索与关联
• 告警触发与分级

流水线可观测性需要覆盖：指标（阶段耗时、各阶段失败率、构建成功率、runner/队列积压、缓存命中率）、日志（构建日志可检索、可按构建号/提交关联）、事件（触发、失败、手动门禁待审批）。监控方式是把 CI 指标（如 Prometheus 的 jenkins-build-time / gitlab_ci runner 指标）接入统一监控，对失败率突增、队列积压过高、阶段耗时明显变长设置告警，并关联到负责人与提交。日志检索建议接入集中日志（ELK/Loki），把构建号、commit、镜像 digest 作为关联字段，便于从失败回溯到具体代码与制品。

流水线本身也是"系统"，需要可观测性才能及时发现问题：失败率反映质量，队列积压反映资源瓶颈，阶段耗时反映优化空间，日志关联反映排障能力。

• 凭证安全：Vault/K8s Secret 动态注入
• 制品签名：cosign/notary 签名与校验
• runner 隔离：专用 runner、网络与权限隔离

安全基线包含三块：凭证注入方面，用 Vault 或 Kubernetes Secret 集中管理密钥，通过环境变量或挂载方式在运行时注入，禁止把明文凭证写入仓库或日志，并遵循最小权限与轮换；制品签名方面，用 cosign（OCI 签名）或 Notary 对镜像签名，在升级链路上校验签名，防止伪造或篡改的制品进入生产；runner 隔离方面，为不同信任级别（如不可信的外部 PR）使用专用或隔离的 runner，限制其网络、凭据与宿主机权限，避免恶意代码窃取生产凭据或污染构建环境。

三点分别对应"密文安全、制品可信、执行环境可信"，是供应链安全在 CI 落地的基本盘，防止"流水线成为攻击入口"。

• 测试分片：按文件/用例切分并行
• 矩阵构建：多平台/多版本组合
• DAG 并行：按依赖关系展开并行

并行策略的三个层次：测试分片把大量测试按文件或用例切分到多个并行 agent，摊薄单个测试阶段耗时；矩阵构建（matrix）对多平台（linux/win/mac）、多 Python 版本、多 Node 版本等组合生成多个并行 job，验证跨环境兼容性；依赖图并行（DAG）把无依赖关系的 job 在同一阶段并行执行，只有被依赖的 job 先完成。三者需要平衡资源与耗时：并行度越高耗时越短，但占用更多 runner 与算力，需考虑并发上限、quota 与成本；同时要避免过度并行带来的资源争抢与结果不确定性。

并行是"用资源换时间"，关键是要基于依赖图合理展开，避免无效并行浪费资源，同时设置并发上限保护共享 CI 资源。

• DORA 指标定义与采集
• 数据来源与自动化计算
• 用指标驱动改进动作

关键 DORA（DevOps 研究评估）指标包括：变更前置时间（从提交到生产的时长）、变更失败率（已发布变更中出现故障的比例）、恢复时间（剔除故障回到正常服务的时间）、部署频率。采集方式是把 CI/CD 系统事件（commit 时间、merge 时间、部署时间、失败事件）与监控系统（故障发生/恢复时间）关联，自动计算并定期汇总。驱动改进上，看变更前置时间是否过长（优化流水线、减少审批等待）、变更失败率是否偏高（加强测试与门禁）、恢复时间是否过长（优化回滚与应急路径），形成"指标→根因→改进→复测"的闭环。

DORA 指标是衡量交付效能的公共语言，把"快不快、稳不稳、恢复快不快"数字化，用数据而非感觉驱动研发与运维改进。

• 幂等重跑：同一输入可重复执行
• 跳过已成功阶段：制品/缓存复用
• 失败产物：保留、清理与标记

失败重跑要求流水线幂等：同一 commit 重跑应得到一致结果，依赖的制品、缓存、外部副作用（如数据库写入）要可重放。跳过已成功阶段（skip）依靠对已会成功 job 的产物与缓存复用，GitLab 用 needs/artifacts，GitHub 用 cached/rerun-failed-jobs，避免重复执行耗时步骤。失败产物处理上，失败 job 的产物要区分"可保留用于诊断"与"应清理"，通常保留有限期（如 1 天）供排查，超期清理；失败构建的镜像不应被晋级，要标记为失败状态。回滚则针对已部署的版本，通过切换回上一版本镜像或 re-run 上一成功构建。

幂等、跳过与产物管理是"失败重跑"可用的前提，本质是让流水线可重复、可诊断、不留垃圾，保证失败恢复不引入新问题。

• 各触发类型的适用场景
• 合并后主干的全量验证
• 定时触发（夜间/发布窗外）

分支推送触发适合快速反馈，feature 分支只跑轻量校验（编译、单测、lint），减少资源浪费；PR 校验适合合并前门禁，验证待合并代码的兼容性，通常比分支推送更严格；标签触发用于正式发布，只在受控的语义版本标签上触发完整发布流水线；定时触发适合夜间全量测试、端到端回归、依赖更新检查等不需要即时反馈的任务。合并后主干的处理很关键：主干应触发全量流水线（完整测试、镜像构建、预发部署），因为主干是发布与集成的基线，其质量必须被持续验证；同时用 merge 后处理与 PR 校验互补，避免只靠 PR 态漏掉合并后的真实状态。

触发策略要"按事件分级"：即时反馈用 push/PR，质量基线由主干全量保证，周期任务用定时。合并后主干的处理是防止"PR 过了但主干坏了"的关键。

• 构建后扫描（Trivy/Clair/Anchore）
• 漏洞阈值卡点：高危/严重数量阻断
• 例外审批：漏洞豁免与白名单

镜像安全门禁在流水线中通常放置在镜像构建完成之后、推送或晋升之前：用 Trivy、Clair、Anchore 等工具对镜像做漏洞扫描，并解析为可控的阈值门禁。阈值卡点一般按严重度配置，如"严重/高危漏洞数量超过阈值即阻断晋升"，把扫描结果与构建 metadata 关联。例外审批则针对"已知不可修复或因业务必须接受的漏洞"提供豁免通道：管理员在安全平台登记豁免理由与有效期，扫描通过时豁免被允许，但会生成审计记录；越是进入生产越严格，也可在 CI 用 --ignore-unfixed 等参数忽略不可修复漏洞。最终把扫描结果、门禁通过与否、豁免记录写入制品元数据，形成可追溯的安全档案。

安全门禁的核心是"扫描只是信息，门禁才是控制"：把扫描结果转化为可执行的阻断/放行策略，并给不能解决的漏洞提供受控的例外审批，避免一刀切卡死业务。