构建 · XB 现场笔记

CI 产物需要明确的交接契约

Fri, 03 Sep 2027 00:00:00 +0000

CI 的上游任务可以成功结束，下游却拿到错误文件。产物是某个步骤生成并保存下来、交给其他任务、人员或发布流程使用的输出，仅靠名字通常不足以识别它。应把交接视为一份契约，说明生产它的运行、源码版本、负载内容、完整性证据、访问策略和可用时间窗口。这样，“下载构建结果”才成为能够核对的操作，而不是在共享目录里猜测哪个文件最新。

分清传递目的与保存期限

产物可以是二进制、测试报告、覆盖率数据，也可以是之后进入发布流程的软件包；不能断言它天然不属于发布输入。依赖缓存的目的则是加速可以重建的工作，二者不应混为一谈。选择存储和保留期之前，先确定审批、诊断和回滚需要哪些文件、需要多久。过期以后重新构建，可能生成不同字节，也需要重新验证，不能把重建视为取回原产物。

GitHub Actions 允许自定义产物保留时间，但受到仓库、组织或企业上限约束。安排流程时，要按真实配置考虑周末和延迟审批；请求一个较长保留值，并不能突破平台上限。确实需要长期留存的发布输入，应转入项目使用的持久发布存储或对象存储，并明确生命周期。短期任务存储即使今天能下载，也不应被说明成无限期的发布归档。

坏掉的样子

随手下载“最近一次成功运行”，可能拿到另一个提交、分支或工作流的文件。应明确解析目标生产任务，并核对它的源码与当前批准发布的变化之间的关系。下游还需要等待所需文件真正产生；空上传、缺失产物不能悄悄变成部署工作区里碰巧残留的旧文件。任务变绿与正确负载已经交付，是需要分别检查的事实。

完整性与来源真实性回答不同问题。校验和可以发现负载变化，但能同时替换文件和校验和的人，也能造出自洽的一对文件。来源声明还需要验证它指向的产物、签名方或工作流身份，以及项目要求的策略。二进制旁边存在一份证明文件，并不代表消费方已经执行了验证。必须看真实的验证结果，而不是只看相关配置或附件存在。

谁能访问产物，取决于平台、仓库可见性与授予的权限，不能一概等同于“能看到工作流的人”。即便如此，也只应上传交接必需的文件。凭据、环境变量全集、私有请求头和未经筛选的日志，一旦打包就可能留下额外副本。保存之前要检查成员列表及其内容，尤其当构建输入来自尚未信任的贡献时，不能只靠压缩包名称判断它是否适合交给下游。

快速验证

保存脚本为 artifacts.py 并执行 python3 artifacts.py，只需 Python 标准库。生产方在临时目录创建 ZIP，包含 app.txt 与清单；清单记录本地运行编号、示意性的源码摘要和负载摘要。消费方只读取约定成员，先比较预期生产者，再返回实际负载。这里没有解压任意归档成员，也没有连接真实 CI 平台。

from hashlib import sha256
from pathlib import Path
from tempfile import TemporaryDirectory
from zipfile import ZipFile
import json

payload = b'local build output\n'
source_digest = sha256(b'example source revision\n').hexdigest()
manifest = {'producer_run': 'local-run-41', 'source_sha256': source_digest,
 'files': {'app.txt': sha256(payload).hexdigest()}}


def produce(path, data):
 with ZipFile(path, 'w') as archive:
 archive.writestr('manifest.json', json.dumps(manifest, sort_keys=True))
 archive.writestr('app.txt', data)


def consume(path, expected_run):
 with ZipFile(path) as archive:
 if sorted(archive.namelist()) != ['app.txt', 'manifest.json']:
 raise ValueError('unexpected member set')
 received = json.loads(archive.read('manifest.json'))
 if (received['producer_run'] != expected_run
 or received['source_sha256'] != source_digest):
 raise ValueError('producer identity mismatch')
 data = archive.read('app.txt')
 if sha256(data).hexdigest() != received['files']['app.txt']:
 raise ValueError('payload digest mismatch')
 return data


with TemporaryDirectory() as directory:
 archive = Path(directory) / 'handoff.zip'
 produce(archive, payload)
 assert consume(archive, 'local-run-41') == payload
 rejected = []
 try:
 consume(archive, 'local-run-42')
 except ValueError as error:
 rejected.append(str(error))
 produce(archive, payload + b'changed\n')
 try:
 consume(archive, 'local-run-41')
 except ValueError as error:
 rejected.append(str(error))
 archive.unlink()
 try:
 consume(archive, 'local-run-41')
 except FileNotFoundError:
 rejected.append('artifact missing')
 assert rejected == ['producer identity mismatch', 'payload digest mismatch', 'artifact missing']
 print(json.dumps({'valid_payload_bytes': len(payload), 'rejected': rejected,
 'platform_retention_tested': False}))

正常交接返回十九字节。用 local-run-42 去领取实际来自 local-run-41 的归档，会得到生产者身份不匹配；保留旧清单、替换文件内容，会得到摘要不匹配；删除归档后继续下载，则得到文件缺失。最终结果必须列出这三种拒绝情况，任何失败都不会转而消费另一个构建。这样可以看清下游契约的失败分支确实执行了。

这是实际的本地归档实验，没有执行 GitHub 的过期服务，也没有生成或验证来源证明。示例源码摘要只是标识符，不是已经核实的 Git 提交。能改写清单的一方仍可能构造一致的谎言。本地删除模拟的是“文件不存在”，不能证明平台会在某个准确时刻执行过期清理。这些界限应随结果一起说明，避免把有限检查扩大成完整供应链验证。

把消费方的发布门写清楚

需要阅读实际下载组件怎样处理失败。GitHub 文档说明，摘要不一致时会在界面和任务日志中展示警告，不能直接假设所有完整性警告都会让部署失败。若发布策略要求拒绝，就应落实对应门禁，并把结果与生产者身份一起保存。还要记录持久发布字节放在哪里、谁能取回，以及临时交接副本什么时候可以过期；这些信息才能让后续审批和恢复真正依赖同一份产物。

来源

GitHub: store and share workflow data，产物传递、保留期限制和摘要校验，已核验 2026-09-13。
GitHub: artifact attestations，构建来源证据及其验证边界，已核验 2026-09-13。

先复制依赖输入，再复制应用代码

Tue, 17 Aug 2027 00:00:00 +0000

Dockerfile 顺序决定昂贵构建操作依赖哪些先前输入。如果应用源码在依赖安装之前被复制，即使依赖声明未变，修改源码也可能让安装重跑。先复制依赖输入、安装依赖，再复制应用代码，可以建立更小的依赖边界，让它与安装器真正需要的工作匹配。这里优化的是依赖关系，而不只是把几行命令挪到看起来更整齐的位置。

坏掉的样子

在软件包安装前使用宽泛的 COPY . .，会让文档、生成输出或无关源码编辑，都可能成为重做昂贵工作的原因。问题不在于 COPY 天生很慢，而在于后续安装依赖了一份包含无关变化的文件系统状态。这些变化并不是选择和安装依赖所必需，却通过前置步骤扩大了失效范围。

如果安装还读取锁文件、本地包源码、补丁、工作区元数据或包管理器配置，仅复制一个清单也不够。遗漏真实输入，可能保留已经不符合构建意图的缓存结果。正确边界必须包含安装器实际使用的全部输入，而不是只选择常见 Dockerfile 示例里出现的某个文件名。否则，表面命中率提高，实际正确性却下降。

缓存顺序也不能修复可变依赖。相同安装命令可能一直保留旧结果，而干净构建却从远端解析到不同内容。固定版本和校验哈希解决产物选择问题，控制 COPY 顺序解决复用问题。两者都需要处理，构建更快并不能证明软件包图可复现，也不能证明依赖已经更新到本次发布要求的版本。

快速验证

使用宿主 Python、Docker 构建器和已取得的固定基础镜像运行脚本。它先通过 HTTPS 下载两个公开的 idna wheel，并在构建前验证固定 SHA-256。容器构建关闭网络，pip 从本地 wheel 目录安装，并强制要求哈希。实测环境为 Docker 29.3.1，Linux arm64 基础镜像内 Python 为 3.11.16：

from pathlib import Path
from tempfile import TemporaryDirectory
from urllib.request import urlopen
import hashlib,json,subprocess,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
WHEELS={
 '3.10':('https://files.pythonhosted.org/packages/76/c6/c88e154df9c4e1a2a66ccf0005a88dfb2650c1dffb6f5ce603dfbd452ce3/idna-3.10-py3-none-any.whl','946d195a0d259cbba61165e88e65941f16e9b36ea6ddb97f00452bae8b1287d3'),
 '3.11':('https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl','771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea')}
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result

name='xbcatm-order-'+uuid.uuid4().hex[:10];tags=[name+':early',name+':late']
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'wheels').mkdir()
 for version,(url,digest) in WHEELS.items():
 with urlopen(url,timeout=40) as response:data=response.read()
 assert hashlib.sha256(data).hexdigest()==digest
 (root/'wheels'/url.rsplit('/',1)[1]).write_bytes(data)
 install='RUN pip install --no-index --no-deps --require-hashes --find-links=/wheels -r /app/requirements.txt && python -c "import time;open(\'/installed\',\'w\').write(str(time.time_ns()))"\n'
 common=f'FROM {BASE}\nLABEL example.run="{name}"\nCOPY wheels /wheels\n'
 (root/'early.Dockerfile').write_text(common+'COPY requirements.txt app.py /app/\n'+install+'CMD ["python", "/app/app.py"]\n')
 (root/'late.Dockerfile').write_text(common+'COPY requirements.txt /app/\n'+install+'COPY app.py /app/\nCMD ["python", "/app/app.py"]\n')
 def requirement(version):
 (root/'requirements.txt').write_text(f'idna=={version} --hash=sha256:{WHEELS[version][1]}\n')
 def application(message):
 (root/'app.py').write_text(f'import idna\nprint({message!r},idna.__version__,idna.encode("bücher.example").decode())\n')
 def build():
 for tag,kind in zip(tags,['early','late']):docker('build','--network','none','-f',str(root/(kind+'.Dockerfile')),'-t',tag,str(root))
 def marks():
 return [docker('run','--rm','--network','none',tag,'cat','/installed').stdout for tag in tags]
 requirement('3.10');application('first');build();first=marks()
 application('second');build();second=marks()
 assert first[0]!=second[0] and first[1]==second[1]
 for tag in tags:assert docker('run','--rm','--network','none',tag).stdout.strip()=='second 3.10 xn--bcher-kva.example'
 print('editing only application code reruns the early-copy dependency install but reuses the late-copy install')
 requirement('3.11');build();third=marks()
 assert all(a!=b for a,b in zip(second,third))
 for tag in tags:assert docker('run','--rm','--network','none',tag).stdout.strip()=='second 3.11 xn--bcher-kva.example'
 print('changing the hashed requirement reruns both installs and actually changes idna from 3.10 to 3.11')
finally:docker('image','rm',*tags,check=False)

提前复制版本的 Dockerfile 在 pip 之前一起复制 requirements.txt 与 app.py。延后复制版本先复制依赖声明，执行相同安装命令，再复制应用。两者都提前加入经过验证的 wheel 目录，因为这些文件确实是安装输入。pip 之后立即写入标记，用来观察安装所在操作是否真的执行，而不是凭耗时猜测。

初始应用使用 idna 3.10 编码 bücher.example。两个镜像都调用实际安装的库，得到预期 ASCII 域名 xn--bcher-kva.example。这验证真实第三方依赖，不用 sleep 代替安装，也不把镜像构建成功直接当成应用能够导入软件包的证明。运行结果同时包含版本，能够确认到底安装了哪个版本。

只把应用消息从 first 改为 second 后，两个镜像都输出新消息和版本 3.10。提前复制的镜像得到新的安装标记，延后复制的镜像保留原标记。程序输出证明源码变更已进入两份镜像，标记比较则指出哪一份布局重复执行了不必要的依赖工作。这样可以排除“缓存太多导致应用没更新”的错误解释。

接着，把依赖声明改为 idna 3.11 和对应哈希。两份安装标记都改变，应用也都报告 3.11，并继续得到相同预期域名转换。这是必须验证的相反情况：真实依赖声明变化，在两种布局下都应让安装失效。如果某个布局忽略了这项输入，即使很快也不正确，不能只用源码修改时的成功缓存来评价它。

两个 wheel 从实验开始就一起提供，因此修改 requirement 不会同时改变 wheel 目录，第二次失效的原因保持明确。结束时清理临时镜像与文件，不清理其他构建器状态。安装时间戳只是测试观测手段，不是建议给生产可复现产物增加的随机输入；正式构建应去掉这类只为证明执行次数而加入的标记。

让缓存边界对应软件包边界

审查安装器会读取什么，再把这些输入放到安装操作之前。让无关文件留在该 COPY 范围之外，并用 .dockerignore 排除构建完全不需要的材料。被忽略的文件之后无法满足必需 COPY，因此当某个依赖明明在工作区却构建不可见时，应检查真实构建上下文，而不是不断加禁用缓存选项。

包管理器缓存挂载，可以在安装确实需要重跑时减少下载，但不能替代正确失效规则或输出校验。依赖安装结果复用与下载缓存复用，是不同层次的优化；修改任意一层后，都应运行最终应用验证。不能因为下载更少，就认定安装状态一定与新的锁文件一致。

用有代表性的构建测量效果：完全相同输入、只改源码、升级依赖。三种情况都保留正确性断言。有效的 Dockerfile 应让必要工作重新执行，让不必要工作继续复用，并提供足够证据区分两者。这样，构建性能的改进才能与实际发布内容保持一致。

来源

Optimize Docker cache usage，稳定依赖层与窄范围 COPY，已核验 2026-09-12。
Docker cache invalidation，变化输入如何使后续依赖工作失效，已核验 2026-09-12。
pip install reference，离线 wheel 安装与强制哈希校验，已核验 2026-09-12。

可复现构建把源码与产物对应起来

Sun, 15 Aug 2027 00:00:00 +0000

可复现构建的含义是：另一方依据声明的源码、构建步骤和相关环境，能够逐字节重建指定产物。这个承诺必须说明比较哪些输出；如果交付的可执行文件不同，只比较目标文件相同是不够的。复现结果为源码与分发内容之间的联系提供证据，而源码审阅、来源证明和签名分别回答其他问题。两次相同的恶意构建仍然有害，被污染的工具链也可能稳定复现自己的异常行为。

记录真正影响字节的输入

源码版本与编译器版本只是输入的一部分。依赖、目标架构、SDK、链接器、参数、文件遍历顺序、目录路径、时间戳、区域设置和打包工具，都可能进入最终结果。应固定实际相关的输入，并说明比较边界。容器镜像有助于描述环境，却不会自动消除网络下载、宿主机挂载或变化的时间戳。一个镜像标签也不必然代表永远不变的镜像内容。

时间宏和调试信息是常见差异来源。SOURCE_DATE_EPOCH 为支持该约定的工具提供稳定时间，并不会改写所有程序对当前时间的理解。编译器的前缀映射能够规范化嵌入的源文件路径；链接器还可能独立记录目标文件位置或其他元数据。因此，编译阶段消除了差异，仍应继续检查实际链接输出，不能在中间产物相同时就停止验证。

坏掉的样子

只比较挑选出的某个段，可能掩盖真正发布文件中的不同。应明确可复现性覆盖可执行文件、调试符号、压缩归档还是带签名安装包。如果签名过程加入会变化的数据，就说明并论证可复现负载的边界，同时单独校验签名后的分发包。还应记录 SDK 和链接器的构建标识；仅有编译器版本，无法重建另外两者的输入。不能悄悄删除难以处理的字节，再宣称原始文件完全相等；比较范围本身也是需要审阅的契约。

同一台机器上的两次摘要一致，是这些输入条件下本地重复构建的证据，不等于多个独立构建方已经验证，也不能证明源码与工具正确。反过来，摘要不一致首先意味着需要调查，不能立即断定发生了攻击。应定位差异来自哪个组件，再判断是不是有输入没有纳入环境声明。没有记录 SDK、链接参数或打包规则，可能就足以让相同源码生成不同文件。

快速验证

此前记录的实验使用 arm64 macOS、Apple clang 21.0.0 及其本机链接器；本轮没有重新执行这个平台专用构建。保存为 repro-build.py，安装命令行开发工具后运行 python3 repro-build.py。链接参数属于 Apple 工具链，不应假设 Linux 链接器也接受。脚本创建两个临时构建目录，用三种处理方式编译同一小段 C 程序；目录名差异是刻意保留的输入扰动。

from hashlib import sha256
from pathlib import Path
from tempfile import TemporaryDirectory
import json
import os
import subprocess

source = '#include <stdio.h>\nint main(void) { puts(__FILE__); puts(__DATE__ " " __TIME__); }\n'
with TemporaryDirectory() as directory:
 base = Path(directory)
 hashes = {mode: {'objects': [], 'executables': []}
 for mode in ('unmapped', 'compiler-only', 'complete')}
 output = []
 for name in ('one', 'two'):
 root = base / name
 root.mkdir()
 src = root / 'main.c'
 src.write_text(source)
 env = {'PATH': os.environ['PATH'], 'LC_ALL': 'C', 'SOURCE_DATE_EPOCH': '1700000000'}
 for mode in hashes:
 obj = root / (mode + '.o')
 binary = root / mode
 flags = [] if mode == 'unmapped' else [f'-ffile-prefix-map={root}=/src']
 subprocess.run(['clang', '-g', '-O0', *flags, '-c', str(src), '-o', str(obj)],
 cwd=root, env=env, check=True, capture_output=True)
 os.utime(obj, (1700000000, 1700000000))
 linker = ['-Wl,-reproducible']
 if mode == 'complete':
 linker.append(f'-Wl,-oso_prefix,{root}/')
 subprocess.run(['clang', *linker, str(obj), '-o', str(binary)],
 cwd=root, env=env, check=True, capture_output=True)
 hashes[mode]['objects'].append(sha256(obj.read_bytes()).hexdigest())
 hashes[mode]['executables'].append(sha256(binary.read_bytes()).hexdigest())
 if mode == 'complete':
 output.append(subprocess.check_output([str(binary)], text=True).splitlines())
 equality = {mode: {kind: pair[0] == pair[1] for kind, pair in records.items()}
 for mode, records in hashes.items()}
 assert equality == {'unmapped': {'objects': False, 'executables': False},
 'compiler-only': {'objects': True, 'executables': False},
 'complete': {'objects': True, 'executables': True}}
 assert output == [['/src/main.c', 'Nov 14 2023 22:13:20']] * 2
 print(json.dumps({'sha256': hashes, 'equal_between_directories': equality,
 'complete_program_output': output,
 'same_host_only': True}))

所有处理都使用时间值 1700000000，并固定目标文件的修改时间。没有路径映射时，目标文件和可执行文件都不同。只做编译器映射后，目标文件摘要已经相等，最终可执行文件仍然不同：链接器调试映射中还保留着各自的目标文件路径。这个中间失败说明，编译阶段通过的检查不能直接为实际发布的二进制文件背书。

三种处理均已开启链接器的可复现模式；完整处理还从它记录的目标文件调试映射里去除构建目录前缀。此时两边的目标文件与可执行文件摘要都相等。执行完整处理后的程序，两次均输出 /src/main.c 和 Nov 14 2023 22:13:20。断言比较的是整个文件，包括生成的 Mach-O 元数据，而不是构建完成后再剪掉差异位置。

这些结果只覆盖本机的一个编译器、SDK、架构和简单程序，没有证明大型安装包、另一种工具链或独立签名发布也能复现。脚本打印每个摘要和相等判断，让中间与最终结果都可检查。读者在不同环境执行时，应先确认工具版本和参数语义，再讨论结果差异；不能把这里出现的某个摘要当成所有平台必须一致的常量。

定位差异后再扩大承诺

生产比较失败时，应保留两份产物及各自的构建输入记录，逐步定位归档、段和元数据中的差异，再控制相应输入并重新构建。调查过程中保持声明的输出集合不变，避免通过减少比较对象来制造成功。本地可重复之后，再由独立环境按照公开步骤重建并比较相应发布产物。这样增加的是另一方能够复现结果的证据，而不是用可复现性取代安全审阅或来源验证。

来源

Reproducible Builds: definitions，明确产物范围并逐字节重建的定义，已核验 2026-10-15。
Reproducible Builds: build path，编译器和调试信息中嵌入路径的影响，已核验 2026-10-15。
Reproducible Builds: SOURCE_DATE_EPOCH，由支持该约定的工具使用稳定时间戳，已核验 2026-10-15。
Clang command-line reference，编译阶段的路径映射参数，已核验 2026-10-15。
Apple ld64 options，可复现模式将调试映射的修改时间清零，已核验 2026-10-15。
Apple ld64 manual，OSO 调试映射路径前缀移除，已核验 2026-10-15。

固定基础镜像只固定一个输入，完整发布还需要其他记录

Fri, 30 Apr 2027 00:00:00 +0000

按摘要固定容器基础镜像，可以选择确定的镜像对象，避免依赖会移动的标签。这消除了一类意外构建变化，但不会让所有派生镜像或运行实例都完全相同。应用源码、构建参数、下载依赖、目标平台、运行配置和持久数据，仍可能改变构建结果及其行为。因此，基础镜像不可变是一个明确的输入约束，不是完整发布已经可复现的证明。

坏掉的样子

两个 Dockerfile 可以使用相同 FROM 摘要，却生成不同应用。即使 Dockerfile 一样，构建参数变化或未固定的下载取得新内容，也可能改变输出。所以，仅声明基础镜像不可变，无法证明完整构建是确定性的。决定这个性质的是全部输入，以及施加在输入上的转换过程；遗漏任何真正影响结果的部分，都会留下解释缺口。

完全相同的应用镜像，在不同环境变量下运行，也可能选择不同端点、功能行为或存储。可写绑定挂载还能替换镜像内已经测试过的文件。把配置留在镜像外通常有价值，但只要配置参与定义发布行为，它仍然需要版本管理和审阅。外置不等于无须控制，更不意味着配置变化不会影响同一镜像的实际表现。

普通容器还拥有可写文件系统层。紧急编辑可以改变一个实例，而镜像和其他实例保持原样。之后从未修改的镜像替换实例，编辑就会消失。因此，不可变部署实践需要把产物替换与受控运行状态结合起来；只在 FROM 后写摘要，无法自动强制团队遵守这种操作方式，也无法阻止容器内手工修补。

快速验证

使用宿主 Python、Docker 构建器和已取得的固定基础镜像运行脚本。此前记录的实测环境为 Docker 29.3.1、Linux arm64，镜像内 Python 3.11.16；本轮没有重跑 Docker。容器网络与构建 RUN 网络被关闭，但镜像解析仍可能访问仓库；构建步骤没有下载软件包。实验结束删除自己的临时容器和标签，不修改任何既有服务，以便把观察限定在明确的受控输入上：

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def inspect(image):return json.loads(docker('image','inspect',image).stdout)[0]

name='xbcatm-pinning-'+uuid.uuid4().hex[:10];tags=[name+':one',name+':two'];container=name+'-running'
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory)
 (root/'Dockerfile').write_text(f'FROM {BASE}\nARG MESSAGE\nRUN printf "%s" "$MESSAGE" > /built-message\nENV MODE=default\nCOPY app.py /app.py\nCMD ["python", "/app.py"]\n')
 (root/'app.py').write_text('from pathlib import Path\nimport os\nprint(Path("/built-message").read_text(),os.environ["MODE"])\n')
 layers=inspect(BASE)['RootFS']['Layers']
 for tag,message in zip(tags,['one','two']):
 docker('build','--network','none','--build-arg','MESSAGE='+message,'-t',tag,str(root))
 assert inspect(tag)['RootFS']['Layers'][:len(layers)]==layers
 assert inspect(tags[0])['Id']!=inspect(tags[1])['Id']
 assert docker('run','--rm','--network','none',tags[0]).stdout.strip()=='one default'
 assert docker('run','--rm','--network','none',tags[1]).stdout.strip()=='two default'
 assert docker('run','--rm','--network','none','-e','MODE=changed',tags[0]).stdout.strip()=='one changed'
 print('both builds use the same pinned base layers; different build arguments produce different artifacts')
 print('the identical application image behaves differently when runtime configuration changes')
 docker('run','-d','--name',container,'--network','none',tags[0],'python','-c','import time;time.sleep(60)')
 docker('exec',container,'python','-c','from pathlib import Path;Path("/built-message").write_text("edited")')
 assert docker('exec',container,'python','/app.py').stdout.strip()=='edited default'
 assert docker('run','--rm','--network','none',tags[0]).stdout.strip()=='one default'
 failed=docker('run','--rm','--network','none','--read-only',tags[0],'python','-c','from pathlib import Path;Path("/built-message").write_text("edited")',check=False)
 assert failed.returncode!=0 and 'Read-only file system' in failed.stderr
 print('a writable container can drift while its image stays unchanged; a read-only root rejects that particular write')
finally:
 docker('rm','-f',container,check=False);docker('image','rm',*tags,check=False)

两次构建使用相同基础引用和应用源码，选择的构建差异只有 MESSAGE；Dockerfile 把它写入 /built-message。第一份镜像输出 one default，第二份输出 two default。完整镜像身份不同，但检查确认它们有序的基础文件系统层前缀完全一致。这里同时对照了公共输入和最终行为，避免把基础相同误当成全部相同。

这组结果证明的范围很明确：基础没有变化，但另一项显式输入改变了派生产物。它没有试图证明所有输入固定时，多次构建必然逐字节相同。要验证后者，还需要控制时间戳、依赖获取、工具链行为，以及构建器生成的元数据。不能把一次相同基础层检查扩展成未经执行的完整可复现构建结论。

接着，第一份应用镜像覆盖 MODE 为 changed，没有重新构建，却输出 one changed。这把产物身份与发布配置分开。仓库摘要可以标识应用字节，但不能单独告诉事故调查者，当时用了哪些环境值、凭据、挂载配置或外部服务。对于影响行为的输入，发布记录必须补上相应身份和管理位置。

随后，脚本从第一份镜像启动一个长时间运行容器，并修改其中的消息文件。该容器内应用输出 edited default，从未改变的镜像新建容器则仍输出 one default。修补只存在于被编辑实例的可写状态，不会自动进入替换实例。这个差异解释了为什么只修线上容器、没有生成新产物，会让相同故障在重建后再次出现。

最后，启用只读根文件系统，尝试相同编辑，会得到只读文件系统错误。这证明该镜像路径受到一个实际有效的写入限制，而不是证明所有运行状态都已冻结。显式可写挂载、外部数据库、环境设置和宿主内核，仍是独立的执行环境组成部分，需要按各自契约控制，不能从一次写入失败推断全部不可变。

记录发布，再替换对应实例

发布记录应连接经过测试的应用摘要、目标平台、配置修订和数据兼容要求。OCI 索引可以包含多个平台的清单，因此固定索引后，运行时仍会选择平台镜像。架构影响复现或诊断时，应记录实际选择，而不只记录一个跨平台索引摘要。这样，同一发布名字下的不同执行环境才有可追踪的解释。

需要的变更应进入新产物，经验证后通过部署机制替换实例。持久数据使用具有独立生命周期和恢复计划的存储，不要把容器可写层当成唯一持久副本，也不要在宣称属于同一固定发布的实例背后，悄悄修改共享配置。应用产物、数据和配置分别受控，才能让替换行为真正可预测。

固定摘要还意味着新的基础修复不会自动到来。需要持续跟踪更新、审阅新摘要、重建依赖应用，并在提升前测试。保留已知输入很有价值，但永远保留过期输入，不等于维护安全发布。固定与更新不是互相排斥，而是要求每次更新成为明确、可审阅的变更。

调查漂移时，分别比较产物、配置、挂载和运行时修改，因为它们有不同的负责人和证据来源。用可审阅发布替代随手修改实例，可以让差异变得可解释，同时承认相同镜像字节并不意味着外部状态相同，也不保证在所有负载下表现完全一样。这是控制边界，而不是夸大不可变镜像的能力。

来源

Docker build best practices，基础镜像摘要固定与主动更新流程，已核验 2026-10-15。
Docker container run，运行环境覆盖与可写或只读文件系统，已核验 2026-10-15。
The Twelve-Factor App: build, release, run，区分构建产物、发布配置与执行，已核验 2026-10-15。
OCI image index 1.1.1，镜像索引中的平台选择，已核验 2026-10-15。
Docker container run reference，只读根文件系统与单独可写卷，已核验 2026-10-15。
Docker build networking，–network 为 RUN 指令选择网络模式，已核验 2026-10-15。

多阶段构建需要经过测试的运行边界

Fri, 25 Sep 2026 00:00:00 +0000

多阶段 Dockerfile 可以在一个阶段编译软件，再把选定输出复制到另一个运行阶段。最终阶段继承自己的基础镜像和明确复制的文件，而不会自动继承构建器里的编译器、源码目录和软件包缓存。这建立了有用的边界，但作者仍必须识别程序真正执行时需要的一切。文件复制成功，只能证明文件已进入产物，不能证明运行环境已经完整。

坏掉的样子

即使 ELF 解释器和共享库缺失，COPY 仍可成功把动态链接程序放进 scratch 镜像。构建可能正常结束，因为复制不会执行程序，也不会验证全部运行依赖图。随后启动却可能报告 no such file or directory，尽管配置路径上的可执行文件确实存在。此时需要检查解释器和库，而不是只反复确认程序文件是否被复制。

脚本需要解释器，应用可能需要证书根或时区数据，还有程序只在特定请求路径上加载插件或资源。简单启动测试可能漏掉这些较晚发生的需求。选择小型运行基础镜像，只有在它满足应用真实契约时才有价值，包括受支持架构和必要文件路径。不能因为某个镜像最小，就默认它适合所有应用。

早期阶段不属于最终镜像的继承链，也不意味着它被安全擦除。构建缓存和明确导出的中间镜像，仍可能保留其内容。敏感构建输入需要正确的密钥传递方式，复制输出也必须检查是否意外包含不该分发的材料。多阶段结构控制最终文件系统组成，却不会自动保证整个构建过程的保密性。

快速验证

历史 Docker 示例保持原样；当前没有 Docker 运行环境，因此本次没有重跑。

使用 Python、Docker、固定的 Python 基础镜像，以及供构建阶段安装 Debian 软件包的网络运行脚本。运行容器关闭网络。实测是 Docker 29.3.1、Linux arm64，GCC 为 Debian 12.2.0-14+deb12u1 包提供的 12.2.0。软件仓库是实时仓库，因此实验验证运行组成，不承诺未来永远取得完全相同的编译器字节：

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,tarfile,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=360)
 if check:assert result.returncode==0,result.stderr
 return result
def inspect(image):return json.loads(docker('image','inspect',image).stdout)[0]

name='xbcatm-stages-'+uuid.uuid4().hex[:10];tags=[name+':builder',name+':good',name+':bad'];container=name+'-inspect'
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory)
 (root/'square.c').write_text('#include <stdio.h>\n#include <stdlib.h>\n#include <errno.h>\nint main(int argc,char **argv){\n char *end;long value;\n if(argc!=2){fprintf(stderr,"one integer required\\n");return 2;}\n errno=0;value=strtol(argv[1],&end,10);\n if(errno||end==argv[1]||*end||value<0||value>100){fprintf(stderr,"range 0..100\\n");return 2;}\n printf("%ld\\n",value*value);return 0;\n}\n')
 (root/'Dockerfile').write_text(f'''FROM {BASE} AS builder
RUN apt-get update && apt-get install -y --no-install-recommends gcc libc6-dev && rm -rf /var/lib/apt/lists/*
WORKDIR /source
COPY square.c .
RUN gcc -O2 -Wall -Wextra -Werror -static -o /square-static square.c && gcc -O2 -Wall -Wextra -Werror -o /square-dynamic square.c
FROM scratch AS good
COPY --from=builder /square-static /square
USER 65532:65532
ENTRYPOINT ["/square"]
FROM scratch AS bad
COPY --from=builder /square-dynamic /square
USER 65532:65532
ENTRYPOINT ["/square"]
''')
 for tag,target in zip(tags,['builder','good','bad']):docker('build','--target',target,'-t',tag,str(root))
 print('compiler:',docker('run','--rm','--network','none',tags[0],'gcc','--version').stdout.splitlines()[0])
 for argument,expected in [('0','0'),('7','49'),('100','10000')]:
 assert docker('run','--rm','--network','none',tags[1],argument).stdout.strip()==expected
 for argument in ['7x','-1','101','','999999999999999999999999999']:
 invalid=docker('run','--rm','--network','none',tags[1],argument,check=False)
 assert invalid.returncode==2 and 'range 0..100' in invalid.stderr
 invalid=docker('run','--rm','--network','none',tags[1],check=False)
 assert invalid.returncode==2 and 'one integer required' in invalid.stderr
 invalid=docker('run','--rm','--network','none',tags[1],'7','8',check=False)
 assert invalid.returncode==2 and 'one integer required' in invalid.stderr
 good=inspect(tags[1]);builder=inspect(tags[0]);assert good['Size']<builder['Size'] and len(good['RootFS']['Layers'])==1
 assert good['Config']['User']=='65532:65532'
 docker('create','--name',container,tags[1],'7');archive=root/'rootfs.tar';docker('export','-o',str(archive),container)
 with tarfile.open(archive) as contents:
 names={entry.name.removeprefix('./') for entry in contents}
 assert 'square' in names and 'usr/bin/gcc' not in names and 'source/square.c' not in names
 bad=docker('run','--rm','--network','none',tags[2],'7',check=False)
 assert bad.returncode!=0 and 'no such file or directory' in bad.stderr
 print('the static final image runs valid input, rejects invalid input, and contains one application layer without compiler or source')
 print('recorded image sizes:',builder['Size'],'builder bytes;',good['Size'],'final bytes')
 print('the dynamic scratch image builds successfully but cannot start because its interpreter/runtime was not copied')
finally:
 docker('rm','-f',container,check=False);docker('image','rm',*tags,check=False)

构建阶段把同一个小型 C 程序分别静态链接和动态链接。程序接受一个零到一百范围内的整数，并输出平方。编译开启警告且把警告视为错误。两个有名字的最终目标各自只把对应可执行文件复制到 scratch，并选择数值用户和组 65532。这样，构建工具与运行产物的交接在 Dockerfile 中清楚可见。

静态最终镜像对输入零、七、一百分别输出 0、49、10000。尾随文本、负数、超范围值、空参数，以及超出 strtol 可表示范围的整数，都返回状态二；缺少参数或参数过多也返回状态二。这些检查直接在最终镜像中覆盖合法边界和拒绝路径，而不只测试构建阶段能够运行程序。

镜像检查确认最终产物只有一个文件系统层，并配置了预期的非 root 数值身份。导出一个已创建容器后，可以看到 /square，却没有构建阶段路径下的编译器和源码文件。实验直接读取归档，不把它解压覆盖宿主文件系统。这独立验证最终组成，而不是因为 Dockerfile 看起来简洁，就假定没有多余文件。

既有记录中 Docker 报告构建镜像为 109,490,331 字节，静态最终镜像为 312,508 字节。这些是引擎的镜像大小字段，不是独占物理磁盘分配量，也不是网络传输耗时测量。真正有意义的不变量，是最终镜像排除了工具链，并在相同统计口径下更小。不同存储实现或压缩方式下，不应直接照搬绝对数字。

动态最终目标也能成功构建，但启动时因为未复制解释器及运行库而出现缺失文件错误。这是关键反例，失败是预期且经过断言的结果。它推翻了“最终 COPY 成功后，构建器就会自动提示补齐运行库”的说法。构建系统无法仅根据文件复制，保证应用执行过程中需要的所有资源都已满足。

验证最后阶段真正执行的内容

应选择适合应用的运行镜像。静态链接适合这里的小计算程序，但不证明所有静态服务都不需要外部文件或运行时加载组件。动态应用需要兼容的运行库或合适的运行基础镜像，并在最终产物内执行有代表性的功能。不要只在工具齐全的构建阶段测试，然后把结果直接转移到环境不同的最终阶段。

使用命名阶段和窄范围 COPY，让审阅者清楚看到交接内容。避免复制整个构建目录，悄悄带入测试、凭据、缓存或无用工具。工作目录、可写路径、用户身份和启动参数，都应按真实运行需求设置。最小化文件与维持可诊断、可运行的服务契约，需要一起判断。

依赖或编译器更新后，应重新测试最终阶段，包括错误输入，以及会额外加载资源的不常见路径。把所选产物身份与结果一起保存。镜像变小只有在继续满足服务契约时才是有效结果；构建成功本身无法证明这个契约，更不能替代最终镜像的启动和功能验证。

来源

Docker multi-stage builds，命名阶段、目标选择与选择性复制产物，已核验 2026-09-12。
Dockerfile reference，COPY –from、scratch、USER 与 exec 形式入口，已核验 2026-09-12。
execve(2)，可执行文件解释器缺失及执行错误，已核验 2026-09-12。

构建 · XB 现场笔记

CI 产物需要明确的交接契约

分清传递目的与保存期限

坏掉的样子

快速验证

把消费方的发布门写清楚

延伸阅读

来源

先复制依赖输入，再复制应用代码

坏掉的样子

快速验证

让缓存边界对应软件包边界

延伸阅读

来源

可复现构建把源码与产物对应起来

记录真正影响字节的输入

坏掉的样子

快速验证

定位差异后再扩大承诺

延伸阅读

来源

固定基础镜像只固定一个输入，完整发布还需要其他记录

坏掉的样子

快速验证

记录发布，再替换对应实例

延伸阅读

来源

相关镜像共享文件层，运行中的容器各自保存修改

坏掉的样子

快速验证

构建并替换预期产物

延伸阅读

来源

多阶段构建需要经过测试的运行边界

坏掉的样子

快速验证

验证最后阶段真正执行的内容

延伸阅读

来源