Bitcoin Core CI 系统实战指南：容器化测试阶段的本地运行、配置矩阵与缓存机制

Bitcoin Core 的 CI（Continuous Integration）系统由 ci/ 目录下的脚本构成，负责在多个平台与编译器配置下构建并验证代码。本文基于 ci/README.md 并结合 ci/test_run_all.sh、ci/test/02_run_container.py 等实现脚本深入解析 CI 的执行流程：你将学会如何在本地运行任意测试阶段（如 ARM 交叉编译、AddressSanitizer 构建）、如何通过 FILE_ENV 配置矩阵控制构建行为，以及 ccache、depends 依赖缓存与 GitHub/WarpBuild 工作流的衔接原理。

一、目录结构与总体架构

ci/ 目录按"构建步骤 + 构建阶段"组织，核心入口与脚本包括：

路径	职责
ci/test_run_all.sh	测试阶段入口：先加载默认环境变量，再调用容器运行器
ci/test/00_setup_env.sh	所有测试阶段共享的默认环境变量与目录约定
ci/test/00_setup_env_*.sh	各具体测试配置（如 00_setup_env_arm.sh、00_setup_env_native_asan.sh、00_setup_env_mac_cross.sh、00_setup_env_win64.sh 等 20 余个文件）
ci/test/01_base_install.sh	镜像构建期/容器内基础软件包安装
ci/test/02_run_container.py	用 Docker buildx 构建并启动 CI 容器、挂载缓存卷、执行测试脚本
ci/test/03_test_script.sh	容器内的真正测试流程：编译、单元/功能/模糊测试
ci/test_imagefile	CI 容器的 Dockerfile（以注释形式的镜像定义）
ci/lint/	lint 阶段脚本（01_install.sh、06_script.sh）与 ci/lint.py
ci/retry/retry	命令重试工具，供容器内网络不稳定时的安装步骤使用，文档见 ci/retry/README.md

入口脚本 ci/test_run_all.sh 逻辑极简，仅三步：设置 LC_ALL=C.UTF-8、source ./ci/test/00_setup_env.sh 加载环境、执行 ./ci/test/02_run_container.py（见 test_run_all.sh 第 7–11 行）。整个 CI 可以概括为三层：宿主机脚本 → 容器镜像构建 → 容器内测试脚本。

二、在本地运行一个测试阶段

ci/README.md 开篇即给出重要警告：测试会在仓库目录中原地（in-place）构建并运行，请谨慎操作。如果仓库不是全新的 git clone，可能需要先清理之前构建或测试留下的文件。

CI 需要执行安装软件包、写用户主目录等系统管理任务，虽然可以在开发机上直接跑，但 README 提醒：CI 脚本相较代码库其他部分审查和测试较少；若要保持工作树干净，建议在 Linux 虚拟机中运行。

2.1 安装依赖

测试阶段需要 bash、docker 和 python3；如需在容器里运行与宿主机不同的 CPU 架构，还需要 qemu。在 Ubuntu 上一键安装：

sudo apt install bash docker.io python3 qemu-user-static

2.2 处理 Sanitizer 与 ASLR 的冲突

对部分 sanitizer 构建，内核的地址空间布局随机化（ASLR）熵值过高可能导致 sanitizer shadow memory 映射失败。本地运行 CI 时可降低熵值：

sudo sysctl -w vm.mmap_rnd_bits=28

2.3 配置 QEMU 用户态静态仿真

运行需要模拟其他 CPU 架构的测试时，依赖容器环境能识别外部可执行文件并自动交给 qemu 运行。执行以下命令完成配置（对 podman 同样有效）：

docker run --rm --privileged docker.io/multiarch/qemu-user-static --reset -p yes

2.4 指定 FILE_ENV 运行测试阶段

README 建议以干净环境运行 CI：env -i 保证只有指定变量被传入本地 CI。以运行 ARM 交叉编译阶段为例：

env -i HOME="$HOME" PATH="$PATH" USER="$USER" FILE_ENV="./ci/test/00_setup_env_arm.sh" ./ci/test_run_all.sh

也可以在不修改配置文件的前提下强制覆盖某个配置项，例如限制并发数为 1：

env -i HOME="$HOME" PATH="$PATH" USER="$USER" MAKEJOBS="-j1" FILE_ENV="./ci/test/00_setup_env_arm.sh" ./ci/test_run_all.sh

三、默认环境变量：00_setup_env.sh 全解

00_setup_env.sh 是整个测试阶段的"公共底座"，被 test_run_all.sh 首先 source，再根据 FILE_ENV 加载具体配置。其中几个关键约定值得理解：

目录约定（00_setup_env.sh 第 11–28 行）：

• BASE_READ_ONLY_DIR：源码根目录（通常只读，CI 会复制它）；
• BASE_ROOT_DIR：容器内目标目录，默认 /ci_container_base，镜像构建时固化，改动需重建镜像；
• DEPENDS_DIR：depends 依赖树目录，默认 $BASE_ROOT_DIR/depends；
• BASE_SCRATCH_DIR：临时文件区（构建结果、测试 datadir 等）。注意其默认名 ci/scratch_ ₿🧪_ 故意包含空格与非 ASCII 符号，用于验证构建与测试对词分割和 UTF-8 的处理正确性——这是本项目 CI 的一个特色设计；
• CCACHE_DIR、BASE_OUTDIR（构建产物）、PREVIOUS_RELEASES_DIR（旧版本二进制，供回归测试）等。

测试开关与资源默认值（第 36–66 行）：

变量	默认值	作用
MAKEJOBS	-j$(nproc)	传给 make 与 test_runner 的并行度
RUN_UNIT_TESTS / RUN_FUNCTIONAL_TESTS	true	是否运行单元测试 / 功能测试
RUN_TIDY / RUN_FUZZ_TESTS	false	是否运行 clang-tidy / 模糊测试
TEST_RUNNER_TIMEOUT_FACTOR	40	功能测试超时缩放系数（应对慢速 CI 机器的 CPU/磁盘 IO）
BOOST_TEST_RANDOM	1	单元测试用例随机化顺序
CCACHE_MAXSIZE	2G	ccache 缓存上限
CI_BASE_PACKAGES	build-essential、pkgconf、cmake、ninja-build 等	基础软件包列表
GOAL	install	构建目标（cmake --target）
CI_IMAGE_PLATFORM	linux	docker build/run --platform，默认 Linux 原生架构

各 00_setup_env_*.sh 文件即在这些默认值之上声明各自的差异。例如：

• 00_setup_env_arm.sh：HOST=arm-linux-gnueabihf，基础镜像 debian:trixie，CI_IMAGE_PLATFORM=linux/arm64（在 arm64 容器上交叉编译 armhf），通过 -DREDUCE_EXPORTS=ON 与 -Wno-psabi 关闭交叉编译的 ABI 告警；
• 00_setup_env_native_asan.sh：ubuntu:24.04，NO_DEPENDS=1（用系统包管理器而非 depends），SANITIZERS=address,float-divide-by-zero,integer,undefined，clang 22 + mold 链接器，并设置 --cap-add SYS_PTRACE（ASan + LSan 需要 ptrace 访问权限）。

四、容器执行器：02_run_container.py 的机制

02_run_container.py 是宿主机的中枢，它做了四件关键的事：

4.1 环境变量白名单

脚本先 grep export ./ci/test/00_setup_env*.sh 收集所有合法导出变量，只把当前环境中属于白名单的变量写入 /tmp/env-{user}-{container} 文件，再经 --env-file 传入容器（第 24–48 行）。这与前面 env -i 的"干净环境"理念呼应：CI 的输入面被严格限定为各配置脚本导出的变量，避免宿主机杂散变量污染构建。

4.2 构建镜像（Docker buildx）

镜像定义在 ci/test_imagefile：FROM ${CI_IMAGE_NAME_TAG} 取自各配置文件的 CI_IMAGE_NAME_TAG，随后拷贝 ci/retry/retry、00_setup_env.sh、对应的 FILE_ENV 与 01_base_install.sh 进镜像，并在镜像构建期以 DANGER_RUN_CI_ON_HOST=1 执行 01_base_install.sh 预装基础包（test_imagefile 第 18–24 行）。运行器无条件使用 docker buildx build（而非 docker build），注释中说明这是为了正确加载驱动以配合 registry 缓存（02_run_container.py 第 64–65 行）。

4.3 缓存卷与固定网络

运行前为容器创建四个 Docker 卷：{container}_ccache、{container}_depends、{container}_depends_sources、{container}_previous_releases，分别挂载到 ccache 目录、depends/built、depends/sources 与旧版本二进制目录（第 85–91 行）。

网络方面，脚本创建两个专用 Docker 网络——IPv6 的 ci-ip6net（1111:1111::/112）与 IPv4 的 ci-ip4net（1.1.1.0/24），并给容器分配固定地址 1111:1111::5 和 1.1.1.5；源码注释明确提醒"部分测试依赖这些 IP，改这里时要保持同步"（第 117–159 行）。这一设计让依赖特定网络拓扑的 P2P/功能测试在容器中获得确定性环境。

另外脚本还支持若干"危险模式"开关：DANGER_RUN_CI_ON_HOST 直接在宿主机运行（跳过 Docker 包装）、DANGER_CI_ON_HOST_FOLDERS 用 bind mount 替代卷、RESTART_CI_DOCKER_BEFORE_RUN 在运行前清理容器等。

4.4 容器内执行链

镜像与容器就绪后，运行器通过 docker exec 在容器内依次执行：rsync 把只读源码目录同步到 BASE_ROOT_DIR（归一化目录）→ 运行 01_base_install.sh 安装该配置特有的包 → 执行 03_test_script.sh（Windows 交叉目标则经 nix-shell 与 shell-win64-cross.nix 进入 mingw 环境）。ci_exec 在容器内统一注入 DANGER_RUN_CI_ON_HOST=1（第 161–173 行）。

五、容器内测试流程：03_test_script.sh

03_test_script.sh 是最终执行构建与测试的脚本，它要求 DANGER_RUN_CI_ON_HOST=1 才肯运行，防止误在宿主机上执行（第 11–14 行）。主要步骤：

1. 环境自检：打印 CPU、内存、磁盘信息，打印完整 env 快照；
2. Sanitizer 选项：统一设置 ASAN_OPTIONS、LSAN_OPTIONS、TSAN_OPTIONS、UBSAN_OPTIONS，抑制文件指向 test/sanitizer_suppressions/（第 19–22 行）；
3. 确定 HOST：交叉编译任务由 FILE_ENV 导出 HOST，原生任务则调用 depends/config.guess 推断（第 46 行）；
4. 构建 depends：make -C depends HOST=$HOST $DEP_OPTS（除非配置中设了 NO_DEPENDS）；
5. CMake 配置：所有阶段共用 -DCMAKE_COMPILE_WARNING_AS_ERROR=ON -DBUILD_BENCH=ON -DBUILD_FUZZ_BINARY=ON，未设 NO_DEPENDS 时追加 -DCMAKE_TOOLCHAIN_FILE=$DEPENDS_DIR/$HOST/toolchain.cmake 使用 depends 生成的工具链文件（第 102–105 行）；
6. 构建：cmake --build --target $GOAL，失败时自动以 -j1 --verbose 重跑一次输出详细日志；构建完成后打印 ccache 命中率，低于 75% 会输出 GitHub 通知（::notice title=low ccache hitrate::）；
7. 单元测试：ctest --stop-on-failure，超时为 TEST_RUNNER_TIMEOUT_FACTOR * 60 秒（第 191–199 行）；
8. 功能测试：运行 test/functional/test_runner.py，带 --failfast 与 --timeout-factor（第 201–214 行）；
9. 可选阶段：RUN_TIDY=true 时构建并运行 bitcoin-tidy 静态检查；RUN_IWYU=true 时按受强制 IWYU 约束的文件模式跑 include-what-you-use；RUN_FUZZ_TESTS=true 时运行 test/fuzz/test_runner.py 并克隆 qa-assets 语料库。

六、缓存策略

README 的 "Cache" 一节说明：为避免每次构建都重编译全部依赖，二进制会被缓存并尽量复用；对 ./depends 依赖生成器的任何变更都会触发缓存失效与必要重建。

结合源码可以看到落地机制分三层：

• ccache 编译缓存：CCACHE_DIR 挂在 Docker 卷 {container}_ccache 上，默认 2G 上限、开启压缩（CCACHE_COMPRESS=1）；构建结束后统计命中率并在 CI 日志中低命中率告警；
• depends 构建缓存：depends/built 与 depends/sources 各自独立成卷，依赖工具链的产物跨运行复用，与上游 release 构建使用同一套 ./depends 生成路径，保证测试方与发布构建使用相同版本的依赖；
• 旧版本二进制缓存：PREVIOUS_RELEASES_DIR 单独成卷，由 test/get_previous_releases.py 按需下载，供回归类测试使用。

此外，GitHub 工作流 .github/workflows/ci.yml 层面还叠加了 actions/cache 的 ccache 缓存（restore/save 步骤），以及 WarpBuild 组织运行器上的 registry 缓存（这也是运行器坚持用 buildx 的原因之一）。

七、将你的仓库接入 CI

README 最后一节 "Configuring a repository for CI" 说明了两种部署形态：

7.1 主仓库（Primary repository）

1. 注册 WarpBuild 并购买 runners；
2. 将 WarpBuild GitHub App 安装到组织；
3. 在组织级允许公共仓库使用 runners：Org settings -> Actions -> Runner Groups -> Default -> Allow public repos；
4. 允许以下 actions 运行：
   • actions/cache/restore@*、actions/cache/save@*
   • actions/github-script@*
   • docker/setup-buildx-action@*
   • warpbuilds/cache/restore@*、warpbuilds/cache/save@*

对应地，ci.yml 中 Linux 矩阵任务在主仓库运行于 warp-ubuntu-latest-x64-8x 运行器。

7.2 分支仓库（Fork）

在 fork 中，CI 默认跑在 GitHub 免费托管 runner 上：GitHub 的缓存容量限制可能导致缓存频繁被逐出而失效，工作流仍会运行，但会变慢。若要在 fork 中使用自有 WarpBuild runners，需将 .github/workflows/ci.yml 中对 bitcoin/bitcoin 的引用替换为 fork 名（如 your-org/bitcoin）；注意 WarpBuild runners 仅在组织层面生效，因此 fork 必须位于你自己的组织内。

八、本地运行实践要点小结

• 干净环境：用 env -i 只传 HOME/PATH/USER 与 FILE_ENV，与 CI 的变量白名单机制（第 4.1 节）保持一致，可最大限度复现线上结果；
• 原地构建风险：测试在仓库内就地执行，非干净 clone 请先清理产物；追求隔离时优先用 Linux 虚拟机或仅依赖默认 Docker 卷模式；
• 控制变量：通过 MAKEJOBS、TEST_RUNNER_TIMEOUT_FACTOR、GOAL、BITCOIN_CONFIG（追加 CMake 参数）等导出变量即可微调任意阶段，无需改动 ci/test/ 下的脚本；
• 跨架构运行：先完成 qemu-user-static 注册再选择 CI_IMAGE_PLATFORM 为 linux/arm64 等异构平台的配置；
• Sanitizer 配置：若 shadow memory 映射失败，按第 2.2 节调低 vm.mmap_rnd_bits；
• 失败诊断：构建失败时 03_test_script.sh 会自动以单线程 verbose 重跑，CMake 配置失败时会通过 GetCMakeLogFiles.cmake 汇总日志，配合容器内打印的完整 env 快照可快速定位环境差异。

通过本文，读者既获得了 ci/README.md 中全部本地运行步骤、配置与缓存说明，也掌握了从 FILE_ENV 白名单过滤、buildx 镜像构建、固定 IP 网络与缓存卷挂载，到容器内 CMake 构建与三类测试执行的具体实现链路，足以在本地完整复现 Bitcoin Core 上游 CI 的任意一个测试阶段。