云原生【免费下载链接】buildahA tool that facilitates building OCI images.项目地址https://gitcode.com/gh_mirrors/bu/buildah点击查看免费下载本指南面向希望验证 Buildah 构建结果与 Docker 构建结果一致性的开发者。它完整讲解 tests/conformance/README.md 中定义的 Conformance 测试套件的原理、依赖安装、运行方法与扩展方式并结合 tests/conformance/conformance_test.go 源码剖析其双层对比、报告生成与字段豁免机制。读完本文你将掌握如何在本仓库中运行全套一致性测试、按用例名筛选测试、以逐行粒度对比构建层并理解测试用例的组织结构与调试手段。什么是 Buildah/Docker Conformance 测试套件Conformance 测试套件用于验证「使用 Buildah 构建出的镜像与使用 Docker 构建出的镜像等价」。其核心思路是用被测试的 buildah 库构建一个镜像再用 Docker 引擎的 build API 构建同一个镜像最后对两者进行对比。这里的同一个指两者使用相同的 Dockerfile、相同的构建上下文与相同的构建参数从而把差异缩小到纯粹由构建器实现差异所导致的部分。该测试基于go.podman.io/buildah、imagebuildah等库以 Go 测试go test形式运行而不是作为 buildah CLI 的子命令存在。入口函数为 tests/conformance/conformance_test.go 中的TestMain与TestConformance。测试不仅对比 Docker 与 Buildah还可以在开启-compare-imagebuilder时额外引入 openshift/imagebuilder 作为第二参照系形成三方交叉验证。每个测试用例通过testCase结构体描述见 conformance_test.go 中的结构体定义字段包括dockerfile/contextDir构建所用的 Dockerfile 名称或上下文子目录shouldFailAt期望构建在第几行失败从 1 计数0 表示应成功buildahRegex/dockerRegex/imagebuilderRegex校验构建输出中应出现的正则片段withoutDocker/withoutImagebuilder针对依赖 Buildah 专有特性的用例跳过某一参照方dockerUseBuildKit/dockerBuilderVersion要求 Docker 使用 BuildKit 或经典 V1 构建器fsSkip/failOnExtraFSContent声明允许的文件系统差异或要求 Buildah 不得产生 Docker 没有的文件系统条目transientMounts/buildArgs向 Buildah 传入临时挂载或--build-arg类参数。安装依赖运行 Conformance 测试所需的额外依赖只有一个docker。其余依赖buildah 库本身、go-dockerclient、containers/storage 等均已在仓库的 go.mod 中声明。安装 Docker CEConformance 测试使用 Docker CE 构建用于对比的镜像因此需要先安装 Docker CE。可依据发行版选用dnf、yum或apt-get安装并确保docker服务已启动Fedora、RHEL 与 CentOS 默认安装的可能是docker或moby-engine软件包而非 Docker CEDebian 或 Ubuntu 上则可能已有docker.io软件包无论采用哪种来源请确保安装的版本不低于 19.03对应 Docker API 版本需满足测试中对 builder 版本的协商要求见下文源码分析。源码侧对 Docker 版本的要求在 conformance_test.go 中有更具体的体现测试初始化时用mobyclient.New(mobyclient.FromEnv)连接 dockerd 并执行Ping以协商 API 版本若用例要求 BuildKitdockerUseBuildKit或dockerBuilderVersion非空协商出的 API 版本低于 1.38 会直接t.Skipf跳过该用例随后创建固定 API 版本为 1.51 的docker.NewVersionedClientFromEnv(1.51)客户端用于构建与清理镜像。运行 Conformance 测试1. 预拉取基础镜像测试用例会引用多组基础镜像建议在运行前手动拉取避免测试中途因网络或镜像缺失失败docker pull mirror.gcr.io/golang docker pull mirror.gcr.io/alpine docker pull mirror.gcr.io/busybox docker pull quay.io/fedora/python-311:latest docker pull quay.io/libpod/centos:7 docker pull quay.io/libpod/ubuntu:latest docker pull quay.io/libpod/busyboxsha256:32968e717e29f79e5b889721908b3be6d1573992e1f3ba4c9a41718e2728458c docker pull quay.io/libpod/busyboxsha256:1faaf7a75319417261267b3dcef6a2b14c8c5122d7fcc7abeb07a32bc19728fd除手动拉取外测试源码中还有自动兜底逻辑buildUsingDocker会在解析 Dockerfile 阶段逐行识别# syntax指令并调用pullImageIfMissing拉取对应前端镜像同时遍历每个 stage 的FROM基础镜像并确保其已存在见 conformance_test.go 的 buildUsingDocker 实现。2. 准备测试程序输入mount-targets用例需要编译一个辅助测试程序作为少数用例的输入make tests/conformance/testdata/mount-targets/true对应的 Go 源文件位于 tests/conformance/testdata/mount-targets/true.goDockerfile 位于 tests/conformance/testdata/mount-targets/Dockerfile。3. 运行全部测试使用go test运行整套测试需要 root 权限非 root 用户请先执行buildah unshare或podman unsharego test -v -timeout30m -tags $(./btrfs_installed_tag.sh) ./tests/conformance参数说明-tags $(./btrfs_installed_tag.sh)根据本机是否安装 btrfs 支持动态追加对应的 Go build tag脚本位于 btrfs_installed_tag.sh-timeout30m整体超时 30 分钟防止构建或拉取卡死-v输出每个子用例的详细执行结果。4. 运行单个测试用例通过-run标志按用例名筛选。用例名由TestConformance与internalTestCases中的name拼接而成。例如只运行名为shell的用例go test -v -timeout30m -tags $(./btrfs_installed_tag.sh) -run TestConformance/shell ./tests/conformanceshell用例见 testdata/Dockerfile.shell内容为FROM quay.io/libpod/centos:7 SHELL [/bin/bash, -xc] RUN env它在internalTestCases中对应定义conformance_test.go{ name: shell test, dockerfile: Dockerfile.shell, buildahRegex: (?s)[0-9a-z](.*)--, dockerRegex: (?s)RUN env.*?Running in [0-9a-z](.*?)---, },其中buildahRegex/dockerRegex用于校验各自构建日志是否包含预期输出片段。5. 逐行对比构建层如果希望不仅对比最终镜像还按 Dockerfile 逐行逐层构建并对比中间结果追加-compare-layers标志go test -v -timeout60m -tags $(./btrfs_installed_tag.sh) ./tests/conformance -compare-layers该模式将超时延长到 60 分钟因为每个用例会为 Dockerfile 的每一行除首行FROM外单独构建并对比一次。此标志对应源码中的compareLayers变量conformance_test.go在testConformanceInternal中当compareLayers为真时测试会扫描 Dockerfile 字节流在每个换行处截取前缀并逐行t.Run构建对比见 conformance_test.go。测试的内部工作机制双层对比镜像配置与文件系统每个用例的执行流程testConformanceInternal→testConformanceInternalBuild大致如下为用例创建临时目录分别作为构建上下文、buildah 存储根rootDir与运行根runrootDir并用copier.GetContext/copier.PutContext把testdata下的上下文或 Dockerfile 复制到临时目录conformance_test.go初始化storage.GetStore为 buildah 分配独立的图驱动存储并以STORAGE_DRIVER环境变量控制图驱动conformance_test.go分别调用buildUsingDocker、buildUsingBuildah可选buildUsingImagebuilder构建同一镜像构建输出统一写入报告目录-buildah-dir、-docker-dir、-imagebuilder-dir或临时目录见TestMain中的 flag 定义conformance_test.go通过saveReport把每个构建产物的manifest.json、config.json原始 Docker 格式、oci-config.jsonOCI 格式、fs.json文件系统树摘要与build.log、version等落盘conformance_test.go用readReport读回上述文件分别对Docker 格式配置originalSkip豁免集、OCI 格式配置ociSkip豁免集与文件系统树fsSkip豁免集做compareJSON对比conformance_test.go。对比会检查三类差异只出现在 buildah 一侧的字段missKeys、只出现在 Docker 一侧的字段leftKeys、双方都有但值不同的字段diffKeys并通过configCompareResult/fsCompareResult生成可读的失败报告conformance_test.go。报告文件的生成与调试价值即使测试通过报告目录中也会留下每个镜像的完整构建信息。saveReport保存的fs.json结构来自FSTree/FSEntry/FSHeaderconformance_test.go它记录了每一层每个条目的类型、链接名、大小、权限、uid/gid、mtime、设备号、xattr 与内容摘要。applyLayerToFSTree则按RootFS.DiffIDs顺序把各层逐一应用到内存中的文件树处理硬链接、.wh.白化条目与.wh..opq不透明目录conformance_test.go最终得到与真实文件系统等价的摘要树。当测试失败时报告目录中的Dockerfile、build.log与各类 JSON 文件是定位差异的第一手资料。豁免字段为什么要容忍差异测试对比时并非逐字段严格相等而是通过豁免列表声明可以接受的差异这些都定义在 conformance_test.gooriginalSkipDocker 格式配置中的created、container、docker_version、container_config:hostname、config:hostname、config:image、container_config:cmd、container_config:image、history、rootfs:diff_ids、moby.buildkit.buildinfo.v1。这些字段天然反映构建器自身信息或时间戳无法也不应一致ociSkipOCI 格式配置中的created、history、rootfs:diff_idsfsSkip文件系统层面的(dir):dev:mtime、(dir):proc:mtime、(dir):sys:mtime、(dir):etc:mtime——这些是RUN语句执行时挂载或合成目录的时间戳buildah 与 docker build 的处理策略本就不同。compareJSON对嵌套对象采用前缀递归如config:Env对数组采用元素集合相等语义适用于 Labels、Env 等无序集合对mode字段以八进制形式输出差异diffDebugconformance_test.go。用例还可以通过自身的fsSkip字段声明额外的文件系统差异例如某些目录的 mtime 不会被重置见copy file to root等用例的fsSkip: []string{(dir):a:mtime}。新旧行为的兼容矩阵部分用例带有testUsingSetParent或testUsingVolumes标记会在TestConformance中分裂为两个子测试分别以新行为与旧行为运行new-set-parent/old-set-parent通过dockerBuilderVersion docker.BuilderBuildKit新或docker.BuilderV1旧并给 buildah 设置CompatSetParent为false/true验证config.Parent字段的两种处理策略new-volumes/old-volumes同理用 BuildKit 与 V1 构建器配合CompatVolumes的false/true验证VOLUME指令是仅记录配置还是保留卷内容的差异旧行为还追加fsSkipCompatVolumesTrue豁免集conformance_test.go。这一机制保证测试套件在 Docker 构建器新旧交替的过渡期依然能给出确定性的对比结论。SELinux 与临时挂载等平台细节SELinux 相关的差异处理位于 tests/conformance/selinux_linux_test.go当系统启用 SELinux 时selinuxMountFlag()返回:Z用于在挂载卷等场景自动附加重标记选项未启用则返回空串。非 Linux 平台则由 selinux_unsupported_test.go 提供空实现。此外testCase.transientMounts支持TEMPDIR占位符在buildUsingBuildah与buildUsingImagebuilder中都会被替换为实际构建上下文路径conformance_test.go。测试用例的组织与扩展全部内置用例集中在internalTestCasesconformance_test.go 起覆盖 ADD/COPY 的各类路径与权限场景、.dockerignore的各种匹配模式、多阶段构建、通配符与 glob、heredoc、WORKDIR、VOLUME、RUN挂载与临时挂载、符号链接与硬链接、预期失败用例shouldFailAt等。对应的 Dockerfile 与上下文素材均位于 tests/conformance/testdata/ 目录例如copy-escape-globCOPY 中 glob 转义行为素材在 tests/conformance/testdata/copy-escape-glob/dockerignore.dockerignore规则的各种边界情况素材在 tests/conformance/testdata/dockerignore/multistage/copyback多阶段构建中的跨阶段 COPY素材在 tests/conformance/testdata/multistage/copyback/。新增用例的通用做法是在testdata下添加上下文目录或 Dockerfile再在internalTestCases中登记一个testCase视需要补充buildahRegex/dockerRegex、fsSkip、shouldFailAt等字段。测试框架会自动完成上下文复制、双三方构建、报告落盘与对比断言。常见问题与排查建议非 root 环境下权限不足buildah 构建依赖容器存储与挂载能力请使用buildah unshare或podman unshare包裹go test命令再运行Docker daemon 未启动或版本过旧测试初始化会失败或跳过 BuildKit 相关用例确认docker服务已启动且版本 ≥ 19.03并保证 API 协商版本 ≥ 1.38基础镜像拉取失败先执行上文的基础镜像预拉取命令尤其注意两个以 digest 引用的busybox镜像失败信息定位测试失败时日志会打印上下文路径、Dockerfile 内容含末尾无换行提示、.dockerignore内容以及 buildah / docker 的完整构建输出结合报告目录中的fs.json与config.json可逐字段核对差异来源仅看最终镜像还是逐层对比默认对比最终镜像需要定位哪一条指令导致差异时使用-compare-layers逐行构建对比。通过本套件开发者可以在每次改动 buildah 的镜像构建逻辑后快速确认其输出与 Docker 保持等价既服务于回归测试也为镜像兼容性提供了可审计的量化依据。赞分享云原生【免费下载链接】buildahA tool that facilitates building OCI images.项目地址https://gitcode.com/gh_mirrors/bu/buildah点击查看免费下载相关推荐Kubernetes Conformance 镜像完全指南基于 test/conformance/image 构建、发布与运行 E2E 一致性测试Kubernetes Conformance 镜像完全指南基于 test/conformance/image 构建、发布与运行 E2E 一致性测试 导读 云原生容器编排集群管理微服务Pyrefly Conformance 一致性测试套件目录结构、预期错误标记与自动化验证实战Pyrefly Conformance 一致性测试套件目录结构、预期错误标记与自动化验证实战 本篇技术指南围绕 pyrefly 仓库中的 conformanc开发工具静态分析IDE代码质量Nhost Auth 的 OpenID Conformance 认证套件用官方一致性测试验证 OAuth2/OIDC 实现Nhost Auth 的 OpenID Conformance 认证套件用官方一致性测试验证 OAuth2/OIDC 实现 导读 Nhost 是一个开源的 F后端认证鉴权数据库无服务开发工具云原生上一篇Tabby 本地接入 DeepSeek自托管 AI 编码助手的配置与验证下一篇Command Conquer Generals - Zero Hour脚本引擎完全解析终极开发者指南 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考