Hotdry.

Article

实现 Docker 镜像字节级可复现构建的工程实践

基于 Arch Linux 官方镜像的可复现实践，详解 SOURCE_DATE_EPOCH 与时间戳规范化为核心的工程参数配置。

2026-04-23systems

在软件供应链安全日益受到关注的背景下，字节级可复现构建（bit-for-bit reproducible builds）已经从理想概念走向工程现实。可复现构建的核心目标是：给定同一源代码，在任何时间、任何机器上构建，应得到字节级完全一致的二进制产物。这一特性对于安全审计、供应链验证、CI/CD 可靠性以及离线环境部署具有不可替代的价值。

近期，Arch Linux 维护者 Antiz（Robin Candau）宣布其官方 Docker 镜像实现了字节级可复现构建，并发布于 Docker Hub 的 repro 标签下。这一成果不仅验证了 Docker 容器层面的可复现可行性，也为其他发行版的镜像构建提供了可操作的工程参考。

可复现构建的核心挑战

传统 Docker 构建过程存在多个非确定性来源。时间戳是最常见的干扰因素：文件系统元数据、容器层的时间戳、构建工具生成的文件时间都会导致相同 Dockerfile 产生不同镜像。此外，动态生成的缓存文件（如 ldconfig 辅助缓存）、基础镜像的 tag 引用方式、依赖版本解析的随机性都会破坏可复现性。

Arch Linux 团队在实现 Docker 镜像可复现构建时，首先面对的挑战是构建基础 rootFS 的确定性。他们复用了与 WSL 镜像相同的构建系统，并在 Docker 构建阶段引入了三个关键调整。

核心技术参数配置

时间戳统一化

SOURCE_DATE_EPOCH 是可复现构建领域的标准约定，通过将所有时间戳统一到某一固定 epoch 值，消除构建时间对产物的影响。在 Docker 构建场景中，需要同时在两个层面配置：

构建时传入 SOURCE_DATE_EPOCH 参数，建议使用 Unix 纪元值 0 或固定时间戳：

docker buildx build --no-cache \
  --build-arg SOURCE_DATE_EPOCH=0 \
  --output type=docker,rewrite-timestamp=true .

在 Dockerfile 中接收并传播该参数：

ARG SOURCE_DATE_EPOCH=0
ENV SOURCE_DATE_EPOCH=${SOURCE_DATE_EPOCH}
LABEL org.opencontainers.image.created="${SOURCE_DATE_EPOCH}"

构建工具时间戳重写

Docker Buildx（BuildKit）提供了 --rewrite-timestamp 选项，可将导出层的所有时间戳重写为 SOURCE_DATE_EPOCH 指定的值。这一选项在构建输出阶段生效，确保最终镜像的每一层文件时间戳保持一致。

非确定性文件清理

某些系统文件天然包含随机或时间相关的动态内容。Arch Linux 团队发现 /var/cache/ldconfig/aux-cache 会引入非确定性因素，因而在 Dockerfile 中明确移除该文件。对于其他发行版，可能需要识别并排除类似的动态缓存文件。

依赖与镜像锁定策略

可复现构建要求所有输入必须可预测。基础镜像不应使用 latest 或非固定版本的 tag，而应锁定到具体的 digest：

FROM archlinux:base@sha256:abc123...

依赖管理工具生成的锁文件（package-lock.json、Cargo.lock 等）应纳入版本控制，确保每次构建使用相同的依赖版本。

验证方法与工具链

构建可复现镜像后，必须通过实际重建来验证其可复现性。Arch Linux 团队采用两种验证手段：

一是镜像 digest 比对。对同一 Dockerfile 执行两次无缓存构建，比较生成的镜像 digest：

docker buildx build --no-cache -t archlinux:repro-1 .
docker buildx build --no-cache -t archlinux:repro-2 .
podman inspect --format '{{.Digest}}' archlinux:repro-1
podman inspect --format '{{.Digest}}' archlinux:repro-2

若两次 digest 完全相同，则达到字节级可复现。

二是 diffoci 工具。该工具由 reproducible-containers 社区开发，可详细对比两个镜像的差异并生成结构化报告。Arch Linux 团队在开发过程中使用 diffoci 识别并修复了多个非确定性问题。

工程化参数清单

综合 Arch Linux 的实践经验，以下是实现 Docker 镜像可复现构建的关键工程参数：

构建命令参数方面，使用 --no-cache 强制完整重建；通过 --build-arg SOURCE_DATE_EPOCH=0 统一时间戳基准；启用 --output type=docker,rewrite-timestamp=true 重写层时间戳。

Dockerfile 配置方面，用 ARG SOURCE_DATE_EPOCH=0 声明默认值；在 LABEL 中传播创建时间；显式删除已知非确定性文件如 RUN rm -f /var/cache/ldconfig/aux-cache。

镜像引用方面，使用 digest 而非 tag：FROM image@sha256:...；锁定依赖版本并纳入版本控制。

验证流程方面，至少执行两次无缓存构建并比对 digest；使用 diffoci 进行差异分析。

已知约束与局限

Arch Linux 的可复现镜像目前标记为 repro 而非默认 latest，原因是为保证可复现性必须移除 pacman 密钥环，导致 pacman 无法开箱即用。用户需在容器内手动执行 pacman-key --init && pacman-key --populate archlinux 初始化密钥，这是可复现性与功能便利性之间的工程权衡。

可复现构建是软件供应链安全的关键基础设施。Docker 层面的字节级可复现虽然涉及文件系统层、构建工具链和镜像格式等多个子系统，但通过 SOURCE_DATE_EPOCH、时间戳重写和严格的输入锁定，已具备成熟的工程路径。

参考资料

systems