镜像 · XB 现场笔记

Docker 构建缓存复用已记录的工作，也可能复用过期结果

Sun, 20 Feb 2028 00:00:00 +0000

Docker 构建缓存保存构建操作的结果，让后续构建在相关输入仍匹配时复用已有工作。缓存命中不表示命令重新运行并生成相同输出，而是构建器接受了一份先前结果。这个区别直接影响软件包安装、生成时间戳、远程下载，以及输出可能变化却没有相应声明输入变化的操作。理解缓存时，首先要区分“再次执行”和“取出已经执行过的结果”。

坏掉的样子

没有变化的 RUN apt-get update 可以直接复用昨天的结果，完全不访问软件仓库。构建器通常不会为了判断这条 RUN 是否仍然新鲜，先检查远端仓库有没有更新。因此，缓存构建成功不能独立证明软件包已经收到最新安全修复。刷新策略必须明确，并与项目要求的可复现性一致，不能依赖某次构建恰好缓存失效。

COPY 的输入不同于普通命令字符串。文件内容和相关元数据参与缓存计算，但源文件修改时间本身不参与。部署脚本如果只是 touch 文件，依赖它的 RUN 仍可能继续命中缓存。反过来，即使文本完全相同，改变可执行权限也可能使 COPY 失效，从而重新执行后续工作。排查时需要比较实际输入，不能只看文件大小和肉眼可见的文字。

基础镜像、步骤实际使用的构建参数和前置依赖也会影响结果。缓存失效沿依赖传播，不能把复杂多阶段构建一律解释成从某行开始全部重做的直线。下面使用简单的单阶段链：复制文件发生变化，就使其后的时间戳 RUN 重新执行，而固定基础镜像的文件系统层仍可继续复用。这种受控结构让实验结论容易对应到真实原因。

快速验证

使用宿主 Python 运行脚本，并连接一个可用于实验的 Docker 构建器。如果本地没有指定摘要，先拉取它。实测环境是 Docker 29.3.1、Buildx 0.32.1，以及 Linux arm64 的 Python 3.11.16 基础镜像。构建和容器均关闭网络。脚本删除自己的临时标签，不清理其他镜像，也不对全局构建缓存执行 prune：

from pathlib import Path
from tempfile import TemporaryDirectory
import json,os,shlex,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-cache-'+uuid.uuid4().hex[:10];tag=name+':probe'
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);app=root/'app.txt';app.write_text('initial '+name);app.chmod(0o644)
 build_code="from pathlib import Path;import time;Path('/built-at').write_text(str(time.time_ns()))"
 (root/'Dockerfile').write_text(f'FROM {BASE}\nCOPY app.txt /app.txt\nRUN python -c {shlex.quote(build_code)}\n')
 def build(*options):return docker('build','--network','none','--progress','plain',*options,'-t',tag,str(root))
 def stamp():return docker('run','--rm','--network','none',tag,'python','-c',"from pathlib import Path;print(Path('/built-at').read_text())").stdout.strip()
 build();initial=stamp();base_layers=inspect(BASE)['RootFS']['Layers']
 result=build();assert stamp()==initial and 'CACHED' in result.stderr
 timestamp=app.stat().st_mtime_ns+10_000_000_000;os.utime(app,ns=(timestamp,timestamp))
 build();assert stamp()==initial
 print('unchanged inputs reuse the RUN result; changing only source mtime also leaves that result cached')
 app.chmod(0o755);build();mode_changed=stamp();assert mode_changed!=initial
 app.write_text('changed '+name);build();content_changed=stamp();assert content_changed!=mode_changed
 print('changing copied-file permissions or content invalidates COPY and reruns the dependent RUN')
 build('--no-cache');assert stamp()!=content_changed
 assert inspect(tag)['RootFS']['Layers'][:len(base_layers)]==base_layers
 print('no-cache reruns the instruction while this pinned base retains the same filesystem layer prefix')
finally:docker('image','rm',tag,check=False)

首次构建把纳秒时间戳写进 /built-at。第二次用相同输入构建，日志出现缓存操作，镜像中的时间戳也完全相同。这比比较构建耗时更有说服力：命令可能执行得很快，但保留下来的同一个时间戳表明，这里复用了之前记录的结果。测试同时看日志和目标文件，避免把其他步骤命中缓存误认为目标 RUN 命中。

随后脚本只推进源文件的修改时间，镜像内时间戳保持不变。这直接验证文档所说的 mtime 排除规则，不代表所有文件元数据都被忽略。接着把模式从 0644 改为 0755，时间戳更新，证明本次 COPY 依赖会受到可执行位变化的影响。两步只改变一个因素，能够区分时间与权限的不同作用。

再修改文件文本，会得到另一个时间戳。输入中包含本次实验的唯一名字，避免以前的同类实验碰巧提供初始应用结果。每一步都读取实际镜像内容进行断言，而不是看到构建日志任意位置有 CACHED 就宣布被研究的操作已经复用。对于多条 RUN 的真实项目，也应采用能定位具体步骤的证据。

最后，应用输入保持不变，使用 --no-cache 后 RUN 再次执行。镜像检查仍显示与原来相同的固定基础层前缀。这个选项禁止构建指令复用缓存，不会把明确选择的基础摘要自动替换成另一个新版本。需要更新基础镜像时，应选择预期的新产物；浮动标签是否重新查询，则还涉及单独的拉取策略。

把新鲜度变成明确输入

让稳定的依赖输入先于频繁修改的源码，并通过窄范围 COPY 避免无关文件成为依赖。如果要求重复得到受控结果，就固定软件包版本或经过校验的下载产物。需要主动刷新依赖时，更新这些声明并审阅产物，不应把“这次没有命中缓存”本身当作安全更新策略，因为远端内容和安装规则仍可能不可控。

密钥挂载还需要单独考虑：密钥内容变化不会自动使构建缓存失效。如果密钥影响一次需要刷新的下载，可以使用明确的非敏感修订输入，或显式要求相关步骤重新执行。不要为了改变缓存键，把真实凭据塞进构建参数；缓存控制与凭据传递有不同的安全边界，不应混在一个字段里处理。

缓存命中日志说明性能方面的复用，真正执行的测试说明行为。记录最终产物身份，测试该产物，并保留足以解释它如何生成的构建输入。快速重建只有在复用的工作仍符合本次发布意图时才有价值；否则，速度只是把陈旧结果更快地交给了下一阶段。

来源

Docker build cache invalidation，缓存输入、修改时间、RUN 复用与显式失效，已核验 2026-09-12。
Dockerfile reference，COPY 元数据、RUN 指令与构建参数，已核验 2026-09-12。

ENTRYPOINT 和 CMD 定义可被运行者覆盖的启动默认值

Sun, 03 Oct 2027 00:00:00 +0000

镜像的 ENTRYPOINT 和 CMD 共同参与容器创建时的启动命令。使用 exec 形式 ENTRYPOINT 时，CMD 通常提供追加给入口的默认参数；没有入口时，CMD 可以提供可执行程序及其参数。这些是启动默认值，不是强制执行边界。有权限创建容器的运行者，可以替换入口或参数，因此不能把 ENTRYPOINT 描述成无论如何都不可改变的程序锁。

坏掉的样子

在 docker run image ... 中写到镜像名之后的参数，会替换 CMD，不是自动加到原 CMD 默认值之后。exec 形式入口仍然保留，除非显式覆盖。用户以为自己只是追加一个选项，却可能丢掉全部默认参数。因此，命令行工具需要说明哪些值可省略、哪些必须重新提供，以及自身参数解析器如何处理覆盖。

exec 形式使用 JSON 数组，不会隐式运行 shell。$DEMO 这样的字符串会原样传给程序，而不是自动展开环境变量。管道、重定向和通配符也需要真正的解释器，才会获得相应含义。shell 形式会改变参数和进程语义，所以两种形式之间的切换并不只是语法美化，不能只看命令表面似乎相同。

启动包装脚本还可能让服务藏在不转发停止信号的 shell 后面。Docker 通常向容器主进程发送停止信号，等待配置的超时，必要时强制终止。即使服务自身正确安装了 SIGTERM 处理函数，如果信号只到达另一个不会转发的进程，这个处理函数也无法发挥作用。排查优雅退出失败时，应先确认信号实际发给了谁。

快速验证

先取得固定基础镜像，再用宿主 Python 和 Docker 构建器运行脚本。实测为 Docker 29.3.1、Linux arm64，镜像内 Python 3.11.16。实验创建独立临时容器并关闭网络，等待每个服务打印就绪信息后测试停止，结束时删除自己的容器和镜像标签，不依赖启动后盲目等待固定时长来猜测服务已经准备好：

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,time,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(name):return json.loads(docker('inspect',name).stdout)[0]

name='xbcatm-entrypoint-'+uuid.uuid4().hex[:10];tag=name+':probe';containers=[name+'-exec',name+'-child']
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory)
 (root/'args.py').write_text('import json,sys\nprint(json.dumps(sys.argv[1:]))\n')
 (root/'service.py').write_text('import json,os,signal\ndef stop(signum,frame):\n print("stopped",flush=True)\n raise SystemExit(0)\nsignal.signal(signal.SIGTERM,stop)\nprint(json.dumps({"pid":os.getpid()}),flush=True)\nwhile True:signal.pause()\n')
 (root/'exec.sh').write_text('#!/bin/sh\nexec python /service.py "$@"\n')
 (root/'child.sh').write_text('#!/bin/sh\npython /service.py "$@" &\nwait $!\n')
 (root/'Dockerfile').write_text(f'FROM {BASE}\nCOPY args.py service.py exec.sh child.sh /\nRUN chmod +x /exec.sh /child.sh\nENV DEMO=expanded\nENTRYPOINT ["python", "/args.py"]\nCMD ["default", "$DEMO"]\n')
 docker('build','--network','none','-t',tag,str(root))
 assert json.loads(docker('run','--rm','--network','none',tag).stdout)==['default','$DEMO']
 assert json.loads(docker('run','--rm','--network','none',tag,'changed').stdout)==['changed']
 assert docker('run','--rm','--network','none','--entrypoint','python',tag,'-c','print("override")').stdout.strip()=='override'
 assert docker('run','--rm','--network','none','--entrypoint','/bin/sh',tag,'-c','printf "%s" "$DEMO"').stdout=='expanded'
 print('CMD supplies literal default arguments; trailing arguments replace it; --entrypoint replaces the executable')
 for container,wrapper in zip(containers,['/exec.sh','/child.sh']):
 docker('run','-d','--name',container,'--network','none','--entrypoint',wrapper,tag)
 deadline=time.monotonic()+10
 while time.monotonic()<deadline:
 logs=docker('logs',container).stdout
 if logs.strip():break
 time.sleep(.05)
 else:raise AssertionError('service did not become ready')
 pid=json.loads(logs.splitlines()[0])['pid']
 assert (pid==1)==(wrapper=='/exec.sh')
 docker('stop','--time','1',container)
 state=inspect(container)['State'];logs=docker('logs',container).stdout
 if wrapper=='/exec.sh':assert state['ExitCode']==0 and 'stopped' in logs
 else:assert state['ExitCode']==137 and 'stopped' not in logs
 print('exec makes the handler PID 1 and stops cleanly; the non-forwarding shell wrapper leaves its child unnotified until forced termination')
finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',tag,check=False)

第一部分让镜像命令打印收到的参数列表。不加覆盖时，它收到 default 和字面的 $DEMO，尽管镜像把 DEMO 定义为 expanded。在镜像名后提供 changed，会替换两个默认参数，程序最终只收到一个参数。这些断言检查实际参数向量，避免仅凭 Dockerfile 的外观推测启动结果。

使用 --entrypoint python 并提供明确的 Python 参数，可以运行另一条命令，输出 override。显式调用 /bin/sh -c 则会展开 $DEMO，输出 expanded。两组结果共同说明 ENTRYPOINT 可以被覆盖，也说明变量展开属于被调用的 shell，而不是 exec 形式内部隐藏的自动处理步骤。

第二部分比较两个启动同一服务的包装脚本。exec 版本用 Python 替换自身，服务报告容器内 PID 为一。Docker 停止容器时，已安装的 SIGTERM 处理函数打印 stopped，随后以零状态退出。实验同时核对日志消息和退出码，证明信号实际到达了服务，并走过被设计的结束路径。

另一个包装脚本把 Python 作为子进程启动，自己等待，却不转发信号。服务报告的 PID 不是一。使用一秒停止超时后，本次环境记录退出码 137，服务也没有打印 stopped。这里直接观察了强制终止结果，不是仅仅因为看到 shell 脚本存在，就断言服务一定无法优雅停止；具体包装方式和处理规则才决定行为。

Linux PID 命名空间中的 PID 一具有特殊的信号和子进程回收责任。exec 包装脚本可以让服务成为信号接收者，但不会自动实现应用清理、排空在途工作，或回收任意后代进程。服务仍需要合适的行为；如果其进程模型需要初始化或监督机制，应明确选择并测试，而不是认为写上 exec 就完成全部退出设计。

把启动和停止视为同一个接口

exec 形式应使用有效 JSON 数组和双引号字符串。明确可执行程序及稳定参数，并说明调用方如何替换默认值。如果初始化必须使用 shell 包装，而包装脚本最后要把控制权交给单个前台服务，就用适当的 exec 完成交接。转发参数时保留引号，避免原来的参数边界在脚本中再次被拆分。

测试真实部署入口，包括编排配置提供的覆盖。正确的镜像入口可能被配置替换成另一层 shell，覆盖命令也可能遗漏必要初始化。应检查实际进程树，并在具有代表性的活动工作下执行终止验证。只测试一个立即退出的打印命令，无法证明长时间运行服务的停止路径正确。

按照服务契约选择停止信号和宽限时间，分别记录就绪、清理成功和退出状态。容器经过 SIGKILL 最终消失，确实说明它已经停止，但单凭这个观察，不能证明请求完成或缓冲状态被安全处理。只有对应业务结束条件的证据，才能支持“优雅退出已经通过”的结论。

来源

Dockerfile ENTRYPOINT and CMD，exec 与 shell 形式、参数组合以及入口覆盖，已核验 2026-09-12。
Docker container stop，停止信号、等待超时与强制终止，已核验 2026-09-12。
pid_namespaces(7)，命名空间初始进程的信号规则及成员终止，已核验 2026-09-12。

镜像标签可以移动，既有容器仍保留原先选择的镜像

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

镜像标签是与镜像引用关联的可读名字。如果仓库策略没有禁止重新指派，同一个标签之后可以标识另一个产物。v1.4 和 latest 的区别首先是命名惯例，而不是前者天然不可变。要复现部署，需要记录实际选择的产物，以及影响行为的平台和运行配置。只保存一个看起来像版本号的名字，并不足以证明当时运行的是哪些内容。

坏掉的样子

latest 不会要求仓库寻找最新上传镜像或最高语义版本，它是在引用省略标签时采用的惯例默认值。发布另一个版本，不会自动移动 latest；必须有人或自动化更新这个具体引用。如果把每次 push 都解释成自动更新 latest，就会错误理解发布流程，甚至误判为什么一个节点仍然取得旧版本。

标签的本地解析结果，也可能不同于仓库当前结果。拉取策略、本地镜像是否存在，以及编排工具的行为，共同决定何时查询仓库。因此，两台机器运行相同可读标签，仍可能使用不同产物。仅记录命令文本，会留下实际取回什么、是否保留缓存引用等不确定性；排查时应读取所选产物身份。

移动标签不会改写已经创建的容器所选择的镜像。重启该容器，会保留原配置的镜像和可写状态，不会按照标签的新目标重新创建实例。如果更新流程只是重新打标签，然后 restart 旧容器，命令可能成功，应用却仍运行旧内容。标签更新、容器替换和容器重启需要分别判断，不能混成同一个动作。

快速验证

先取得固定基础镜像，再用 Python 和 Docker 构建器运行脚本。实测环境是 Docker 29.3.1、Linux arm64。所有标签使用独特的本地名字，不向仓库推送任何内容；容器关闭网络，清理只删除实验自己的容器与标签。因此可以实际验证移动行为，又不改变已有发布引用：

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(name,kind='image'):return json.loads(docker(kind,'inspect',name).stdout)[0]

name='xbcatm-tags-'+uuid.uuid4().hex[:10];tags=[name+':one',name+':two',name+':release',name+':latest'];container=name+'-old'
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory)
 (root/'Dockerfile').write_text(f'FROM {BASE}\nCOPY version.txt /version.txt\nCMD ["cat", "/version.txt"]\n')
 for tag,version in zip(tags,['one','two']):
 (root/'version.txt').write_text(version+'\n');docker('build','--network','none','-t',tag,str(root))
 one=inspect(tags[0])['Id'];two=inspect(tags[1])['Id'];assert one!=two
 docker('image','tag',tags[0],tags[2]);docker('image','tag',tags[0],name)
 assert inspect(tags[2])['Id']==inspect(tags[3])['Id']==one
 docker('create','--name',container,'--network','none',tags[2])
 docker('image','tag',tags[1],tags[2])
 assert inspect(tags[2])['Id']==two and inspect(tags[3])['Id']==one
 assert inspect(container,'container')['Image']==one
 assert docker('start','--attach',container).stdout.strip()=='one'
 assert docker('run','--rm','--network','none',tags[2]).stdout.strip()=='two'
 assert docker('run','--rm','--network','none',tags[3]).stdout.strip()=='one'
 print('moving release changes newly created containers; the existing container still runs its original image')
 print('omitting a tag selected latest, but updating release did not update latest')
 docker('image','rm',tags[2]);assert inspect(tags[1])['Id']==two
 print('removing one tag leaves another reference to the same image intact; all operations stayed local')
finally:
 docker('rm','-f',container,check=False);docker('image','rm',*tags,check=False)

脚本构建两个镜像，/version.txt 分别包含 one 与 two，镜像身份不同。它先让 release 指向第一份镜像，再用没有显式标签的仓库名标记同一镜像。检查确认，省略标签会得到 latest，而这两个引用最初都选择第一份镜像。这里直接验证默认标签规则，不靠名字含义猜测。

移动 release 之前，脚本从该引用创建一个容器，但暂不启动。随后把 release 移到第二份镜像。此时 release 选择新产物，latest 仍选择第一份。实验把标签重新指派与默认标签惯例分开，说明相关名字不会自动一起移动；如果生产流程会同时更新多个标签，那是流程自身明确执行的行为。

启动先前创建的容器，输出 one；从 release 新建容器，输出 two；从 latest 新建容器，则输出 one。容器检查也保留最初所选的镜像身份。这些断言对照实际运行结果，因此不只是根据标签表的显示推理。尤其是“创建后尚未运行”的旧容器，仍然不会因标签移动而更换镜像。

删除 release 标签后，第二份镜像仍通过 two 标签可用。标签是引用，删除一个引用，不一定删除共享内容或所有其他名字。实际回收取决于剩余引用和引擎存储规则；本实验不会清理构建缓存，也不测量物理空间回收。不能把取消一个标签直接当作磁盘上的全部层已经消失。

实验比较当前引擎返回的身份，但不假定 inspect 的 Id 在所有版本和存储方式下都等于 OCI 配置摘要。现代镜像存储可能暴露不同对象层次。仓库索引、平台清单、镜像配置和层数据，各自都有摘要，所以说明身份时应保留对象类型与引用上下文。相同哈希格式不能代替对象含义。

提升经过测试的同一产物

通过仓库部署时，从发布流程记录带仓库名的摘要引用。摘要可能标识包含多个平台清单的镜像索引，因此仍要选择预期平台。保留对应产物及其必需数据，才能让后续回滚真正拉取成功；单独保存哈希无法恢复已经不可取得的内容。产物身份确定与产物持续可用，是不同的要求。

标签可以继续用于人类查找。如果发布流程承诺版本标签永不移动，就应配置并验证仓库的不可变策略，而不是看到版本形状就认定承诺成立。固定摘要也不会证明作者是谁或软件安全，来源证明与行为验证分别回答这些问题。内容寻址解决的是选择哪份对象，不会替代整个发布审查。

部署后，把运行工作负载选择的产物及其预期行为，与发布记录逐一对照。标签已更新、拉取成功和容器正在运行，是三个独立观察。只有把它们连接到同一份通过验证的产物，才能确认本次发布真正生效，而不是仅仅完成了若干看起来相关的命令。

来源

Docker image tag，本地标签创建与默认 latest 标签，已核验 2026-09-12。
Docker image pull，按标签或摘要拉取仓库产物，已核验 2026-09-12。
OCI image index 1.1.1，索引引用不同平台镜像清单的结构，已核验 2026-09-12。
OCI image manifest 1.1.1，清单对配置与层对象的引用，已核验 2026-09-12。

后续镜像层删除文件，并不会擦除先前层的原始字节

Mon, 16 Aug 2027 00:00:00 +0000

容器镜像层描述按顺序应用的文件系统变化。一层可以新增或替换文件，也可以记录某个先前路径应从合并文件系统中消失。普通容器进程看到的是最终合并视图，但这个视图不等于随镜像分发的全部字节历史。因此，仅检查运行中的容器，可能遗漏早期层仍然保留的数据，尤其容易误判删除操作的实际效果。

坏掉的样子

把凭据复制进镜像，再通过后续 RUN 删除，不会从早期不可变层中移除凭据。能够取得相关层的人，仍可能恢复原始字节。同样，把很大的构建压缩包放进某层，再在下一条指令里删除，最终路径虽然不存在，分发内容仍可能包含整个压缩包。目录看起来干净，并不能证明镜像已经没有这份数据。

镜像层是文件系统变更集，不一定是紧凑的二进制差分。替换大文件，可能把替换后的完整内容放入另一层。删除通过 whiteout 标记，在应用层时屏蔽原有路径。OCI 还规定了隐藏下层目录内容的不透明目录规则，所以不能把正确应用镜像层简化成反复普通解压 tar；删除和覆盖语义需要被专门处理。

不是每条 Dockerfile 指令都会创建文件系统层。ENV、LABEL 和 CMD 改变镜像配置，可以产生标记为 empty_layer 的历史条目。因此，Dockerfile 行数、构建历史条目数，都不能可靠地替代根文件系统层数。即使没有增加应用文件字节，这些配置变化仍然影响执行方式和产物身份，不应被当成无关信息。

快速验证

使用 Python、Docker 构建器和固定摘要的基础镜像运行脚本。实测为 Docker 29.3.1，采用 containerd 镜像存储，基础镜像内为 Linux arm64 的 Python 3.11.16。标记内容特意设为公开文本。脚本构建并保存一个临时镜像，直接读取归档成员，不把归档解压到宿主文件系统，结束时删除自己的标签：

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=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-whiteout-'+uuid.uuid4().hex[:10];tag=name+':probe';marker=b'PUBLIC_DEMONSTRATION_BYTES\n'
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'original.txt').write_bytes(marker)
 (root/'Dockerfile').write_text(f'FROM {BASE}\nCOPY original.txt /demo/original.txt\nRUN rm /demo/original.txt\nENV EXAMPLE_MODE=demo\nLABEL example.purpose="public fixture"\nCMD ["python", "-c", "from pathlib import Path;assert not Path(\'/demo/original.txt\').exists();print(\'absent\')"]\n')
 docker('build','--network','none','-t',tag,str(root))
 assert docker('run','--rm','--network','none',tag).stdout.strip()=='absent'
 archive=root/'image.tar';docker('image','save','-o',str(archive),tag)
 with tarfile.open(archive) as outer:
 manifests=json.load(outer.extractfile('manifest.json'));assert len(manifests)==1
 manifest=manifests[0];config=json.load(outer.extractfile(manifest['Config']))
 assert len(manifest['Layers'])==len(config['rootfs']['diff_ids'])
 assert len(manifest['Layers'])==len(inspect(BASE)['RootFS']['Layers'])+2
 found_data=False;found_whiteout=False
 for layer in manifest['Layers'][-2:]:
 with tarfile.open(fileobj=outer.extractfile(layer),mode='r:*') as contents:
 for entry in contents:
 path=entry.name.removeprefix('./')
 if path=='demo/original.txt':found_data=contents.extractfile(entry).read()==marker
 if path=='demo/.wh.original.txt':found_whiteout=True
 assert found_data and found_whiteout
 assert all(item.get('empty_layer') for item in config['history'][-3:])
 print('the final container hides the removed file, but the older layer still contains the exact public marker')
 print('the deletion layer contains a whiteout; ENV, LABEL and CMD add metadata history without filesystem layers')
finally:docker('image','rm',tag,check=False)

Dockerfile 先把 original.txt 复制到 /demo，再在后续 RUN 删除。容器默认命令断言路径不存在，并输出 absent。这验证最终运行视图，却不能证明镜像归档里也没有对应字节，所以实验接下来单独检查保存后的表示。把两个观察拆开，是避免将“看不见”误判为“没有保存”的关键。

归档的 manifest.json 指明配置文件和有序层文件。脚本读取配置中的 rootfs.diff_ids，检查文件系统层数量与清单一致，再读取最后两个层归档。在这个特定构建中，它们分别对应 COPY 新增与后续删除。实验依赖的是保存产物的实际清单，而不是猜测某个长哈希文件名一定属于哪条指令。

新增层仍包含完全相同的 PUBLIC_DEMONSTRATION_BYTES 标记。删除层则包含 demo/.wh.original.txt，指示应用层时隐藏下层文件，而不是原地编辑那个旧层。这两个事实都有直接断言，因此不能把容器中文件缺失当作安全擦除证据。真实凭据若曾进入分发层，之后删除路径并不能撤销已经发生的暴露。

配置历史的最后三条分别对应 ENV、LABEL 和 CMD，并被标记为不产生文件系统层。相对于基础镜像，本次只增加两个文件系统层，而不是五个。这为“每条 Dockerfile 指令必然追加文件系统差分”的说法提供了明确反例，同时保留配置历史和文件系统内容之间的关系，便于解释 inspect 与 history 为什么计数不同。

归档表示和运行时存储是不同接口。这里检查的是实测 Docker 版本生成的 image-save 格式，以及 OCI 变更集语义。实验没有假定快照存储内部也必须用同样可见的 .wh. 文件名保存删除标记，也没有测量某台宿主实际分配了多少磁盘块。内部实现细节不能仅凭归档内容反推。

在字节进入镜像之前排除无用内容

选择合适的构建上下文和忽略规则，避免无关文件进入 COPY 输入。构建凭据通过构建器的密钥机制传递，并确保命令没有把凭据写入保留输出。如果真实凭据已经进入发布层，需要轮换并处理已有副本；补一个删除层不是完整修复，因为旧字节可能仍在仓库、缓存或此前下载者手里。

只在某次操作期间需要的软件包索引或临时归档，应在同一次构建操作中创建并删除。独立最终阶段可以只复制必要运行产物，而不继承构建阶段的文件系统层。不过，仍要检查导出的缓存和复制输出，因为早期构建材料可能留在构建器，或者经另一种导出路径传播。多阶段结构不会自动证明所有输入都已保密。

最终应根据真实产物和运行依赖判断结果。层数更少，本身不能保证下载更小、启动更快或内容更安全。真正需要回答的是：哪些字节随产物分发，哪些路径在运行时可见，以及每一份保留文件是否具有必要用途。这样才能把空间优化、运行正确性与敏感内容处理放在各自准确的证据上。

来源

OCI filesystem layer changesets 1.1.1，文件新增、修改、删除及 whiteout 应用规则，已核验 2026-09-12。
OCI image configuration 1.1.1，根文件系统 DiffID 与不产生文件层的历史条目，已核验 2026-09-12。
Dockerfile reference，COPY、RUN、ENV、LABEL 和 CMD 的行为，已核验 2026-09-12。

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

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 现场笔记

Docker 构建缓存复用已记录的工作，也可能复用过期结果

坏掉的样子

快速验证

把新鲜度变成明确输入

延伸阅读

来源

ENTRYPOINT 和 CMD 定义可被运行者覆盖的启动默认值

坏掉的样子

快速验证

把启动和停止视为同一个接口

来源

镜像标签可以移动，既有容器仍保留原先选择的镜像

坏掉的样子

快速验证

提升经过测试的同一产物

延伸阅读

来源

后续镜像层删除文件，并不会擦除先前层的原始字节

坏掉的样子

快速验证

在字节进入镜像之前排除无用内容

来源

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

坏掉的样子

快速验证

构建并替换预期产物

延伸阅读

来源

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

坏掉的样子

快速验证

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

延伸阅读

来源