上一篇已经建立第 3 层交付能力。本篇聚焦“可复现的制品链路”：不是展示一个绿色图标，而是建立可解释、可复现、失败后能安全停止的工程契约。读完后，读者应能把示例中的阶段、证据和门槛迁移到自己的语言与平台，并知道每个选择为何存在。
一、痛点：先定义流水线要消除的风险
本篇要处理的是一次构建、摘要校验、依赖缓存与不可变制品。CI/CD 的价值不在于把手工命令搬到云端，而在于缩短“变更产生—风险暴露—责任人修复”的闭环。如果输入版本不明确、结果没有证据、失败仍允许后续写操作，自动化只会更快地放大错误。把缓存当制品传递，容易让旧文件混入新版本并制造幽灵故障。因此，设计的第一步应是写下输入、输出、失败语义和责任人，而不是先选择某个市场插件。
一个可以迁移的判断方法，是把每个作业当成函数：输入是提交、锁文件、配置版本和上游制品；输出是制品清单以及机器可判定的状态；副作用则单独列出。纯验证节点只读，发布节点才允许写，并且写权限只在运行到该节点时取得。这样做让代码审查者能回答“绿灯证明了什么”，也让事故处理者能回答“哪一个边界失效”。
还要区分速度与吞吐。增加并行度能缩短总耗时，却不能让有依赖的步骤乱序；缓存能减少下载，却不能替代可追溯制品；自动重试能缓解短暂网络抖动，却不能掩盖确定性测试失败。优化前先记录基线，重点观察构建耗时、失败率、排队时间和恢复时间，随后只改变一个变量。
二、原理：把概率和环境差异关进确定性契约
可靠流水线由三个相互咬合的契约组成。触发契约说明什么事件、分支和路径会启动工作；执行契约说明工具版本、权限、超时及依赖；晋级契约说明必须携带哪些证据才能进入下一阶段。任一契约缺失，团队都会依赖“大家默认知道”的隐性规则，而隐性规则无法自动审计。
一次构建、摘要校验、依赖缓存与不可变制品之所以需要单独设计，是因为交付系统连接了源码、依赖、运行器、制品库和生产环境。每跨越一个边界，都应验证身份、版本和完整性。提交 SHA 适合标识源版本，内容摘要适合标识不可变制品，运行 ID 适合串联日志；三者用途不同，不能只保留一个可变标签。环境配置也应被版本化，但不得把明文密钥写入版本库。
门禁应靠前且由快到慢排列。语法、格式和静态检查先给出秒级反馈，单元测试验证局部行为，集成测试验证边界，部署后探针验证真实运行状态。互不依赖的检查可以并行；只有消费同一份已验证输出时才建立依赖。这个结构既压缩反馈时间，也保留清楚的因果链。
权限则按阶段递增：PR 验证通常只需读取源码，构建可能写入临时制品，发布才访问目标环境。来自 fork 的代码、第三方 Action 输出和制品内容都应视为不可信输入。最小权限不是附加装饰，而是保证某个验证脚本被篡改后仍无法直接控制生产的隔离带。
三、实现：两个可独立运行的最小程序
第一个程序用纯标准库表达三个阶段。每个阶段返回明确布尔值，失败立即停止；最终状态同时检查阶段数量和结果，避免“中途退出却被误记成功”。真实项目可以把函数体替换成 lint、测试或制品校验命令，但应保留统一结果契约。
from dataclasses import dataclass
from typing import Callable
@dataclass(frozen=True)
class Stage:
name: str
check: Callable[[], bool]
def source_ok() –> bool:
return True
def evidence_ok() –> bool:
return True
def policy_ok() –> bool:
return True
stages = [
Stage("source", source_ok),
Stage("evidence", evidence_ok),
Stage("policy", policy_ok),
]
results: list[tuple[str, bool]] = []
for stage in stages:
passed = stage.check()
results.append((stage.name, passed))
print(f"stage={stage.name} passed={passed}")
if not passed:
break
status = "passed" if len(results) == len(stages) and all(v for _, v in results) else "blocked"
print("article=294")
print("artifact=制品清单")
print(f"pipeline={status}")
运行输出：
stage=source passed=True
stage=evidence passed=True
stage=policy passed=True
article=294
artifact=制品清单
pipeline=passed
这段程序刻意不捕获所有异常。基础设施异常与业务不通过应在适配层转换成不同错误类别，顶层再决定是否重试。只有确认是短暂网络故障时才做有限次数、带退避的重试；断言失败、摘要不匹配和权限拒绝必须直接阻断。迁移时还应把 article、提交标识、阶段名、耗时和工具版本写入结构化报告。
第二个程序与第一个完全独立，演示晋级门槛。门槛在运行前声明，观察值只能接受或拒绝，不能看到结果后临时移动阈值。对于构建耗时，示例使用整数便于运行；生产中应从可信监控或测试报告读取，并保存查询窗口与数据来源。
from dataclasses import dataclass
@dataclass(frozen=True)
class Observation:
name: str
value: int
limit: int
lower_is_better: bool
def acceptable(item: Observation) –> bool:
if item.lower_is_better:
return item.value <= item.limit
return item.value >= item.limit
observations = [
Observation("primary", 11, 12, True),
Observation("error_count", 0, 0, True),
]
failed: list[str] = []
for item in observations:
ok = acceptable(item)
print(f"metric={item.name} value={item.value} accepted={ok}")
if not ok:
failed.append(item.name)
decision = "promote" if not failed else "hold"
reason = "all_gates_passed" if not failed else ",".join(failed)
print("article=294")
print(f"decision={decision}")
print(f"reason={reason}")
运行输出：
metric=primary value=11 accepted=True
metric=error_count value=0 accepted=True
article=294
decision=promote
reason=all_gates_passed
把它迁移到真实流水线时，应让 decision 成为后续作业的显式输入。promote 仅表示满足当前门槛，不等于取得无限权限；部署作业仍需受保护环境、短期身份和并发锁。hold 则应保留证据并给出责任范围，不能只打印一个没有上下文的“失败”。
四、踩坑：不要让绿色状态掩盖错误语义
最常见的坑是用命令退出码代表全部事实。测试命令成功，只能证明它执行过并满足当前断言，不能证明测试覆盖了关键风险；上传成功也不能证明内容来自当前提交。解决方法是同时检查文件存在性、版本字段、内容摘要和生成步骤，让证据能独立验证。
第二个坑是盲目重跑。重跑后变绿可能意味着外部服务抖动，也可能意味着测试依赖时间、顺序或共享状态。应记录首次失败，按错误类别统计不稳定率，并给不稳定测试明确修复期限。无限重试会让反馈变慢，还会把真实缺陷伪装成基础设施问题。
第三个坑是把优化变成隐式共享状态。运行器残留目录、未纳入键值的缓存、可变标签和手工改过的环境都会破坏复现。每次运行都应从声明的输入开始；缓存命中后仍执行完整性验证，缓存未命中也必须能正确构建。是否使用缓存只能影响速度，不能影响最终内容。
五、验证：用故障注入证明边界真的工作
验收不能只跑成功路径。先让 source 阶段失败，确认后续阶段没有执行；再篡改证据字段，确认策略拒绝；最后把观测值调到门槛之外，确认 decision 变为 hold。还要模拟超时、权限不足和重复触发，检查并发控制是否取消过时运行、失败日志是否足够定位且不泄露凭据。
团队落地时可从一个服务和一项关键指标开始，连续记录两周基线，再逐步收紧门槛。每次变更流水线本身也必须经过审查和版本化。回滚目标是恢复上一份已验证的配置与制品，而不是在生产机器上临时修改。最终交付物应包括任务契约、依赖锁定、制品清单、门槛定义、责任人、观测面板和故障手册。
下一篇将在这个输出契约上继续增加控制面，而不是另起一套流水线。系列承接的核心不是复用一份越来越长的 YAML，而是复用稳定接口：前一阶段只输出经过验证的事实，后一阶段依据事实做有限决策。这样更换语言、CI 平台或部署目标时，治理逻辑仍然成立。
参考来源
- GitHub Actions dependency caching
- SLSA specification
👍 觉得有用就点个 赞 + 收藏，方便回头查阅；有疑问直接在评论区留言，我看到都会回。
🚀 本文属于 《CI/CD 流水线实战》 系列，持续更新，关注不迷路。
📌 文章里的代码都能直接跑。想要可直接 clone 的完整工程 + 配套部署脚本 / 踩坑清单？评论一声或发邮件到 cj2664@qq.com，我免费发你。 如果你正好在做类似系统、或有工程化难题想找人做，也欢迎邮件聊一句——我按实际情况评估，能落地的就接单或出方案。评论和邮件都能直接找到我，不用跳别的平台。
