企业官网建设流程全解析

如何本地复现 Airflow CI 失败：Breeze 完整实战

【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow

CI 又红了，日志翻了三遍还是说不清挂在哪一步，改完代码只能推回 CI 再祈祷一轮。这篇文章把"看到失败 → 加载 CI 运行产出的同款镜像 → 进容器复现并修掉 → 本地验证后提交"这条链路完整走一遍，并解释 CI 日志里那段自动生成的复现指令是怎么拼出来的，让你不用再对着红叉盲猜。

一句话说清 Breeze 是什么

Airflow 的所有 CI 作业最终都是breeze命令在执行——它是 dev/breeze 目录下的一个 Python 封装器，把 docker 命令、docker compose 编排和测试逻辑打包成统一入口。它的角色是让你的开发机跑出一套和 CI 完全同构的容器环境：提交 PR 前用它预跑全部测试，测试失败时用它进入失败现场的精确副本里调试。所有后面要讲的命令都以breeze开头，前提是本地装好 Docker 且能访问 PyPI。

从一条失败日志开始的全链路 🔍

以最常见的场景为例：你的 PR 在测试阶段挂了一个作业，现在要在本地把它修掉。

第 1 步：从失败作业日志里捞复现指令。每个作业日志末尾都会打印一个HOW TO REPRODUCE LOCALLY区块，里面是带完整 flags 的 breeze 命令和git checkout的 commit SHA，这组命令就是 CI 当时真实执行的配置，比自己从日志里翻环境变量可靠得多。判断成功的标准：你拿到了一条形如breeze ... --python 3.10 --backend mysql ...的完整命令，且能确认失败作业对应的 run ID。

# 日志里的复现区块通常长这样，直接照抄 git checkout <commit_sha> # 检出 CI 构建所用的提交 breeze ci-image build --platform linux/amd64 --python 3.10 breeze ... <日志中给出的 flags> # 失败作业实际执行的命令

如果不想按日志里的命令走（比如镜像早已产出、不想重新 build），可以跳到下面直接加载镜像。

第 2 步：按 run ID 加载失败运行产出的镜像。这是保真度最高的方式，因为镜像工件是 CI 当时构建的字节级快照，而不是你现在重新解析依赖的结果。run ID 在 Actions 运行列表里可见。

breeze ci-image load --from-run 12538475388 --python 3.10 --github-token <your_token>

--python必须和 CI 作业使用的 Python 版本一致，因为它直接参与拼装工件文件名ci-image-save-v3-{platform}-{python}.tar，版本不对会因找不到或下载错文件而失败。判断成功的标准：命令结束后docker images里多出一张新镜像（verbose 模式下会直接打印docker images -a）。

第 3 步：进入容器，不挂载本地源码。关键参数是--mount-sources skip：本地源码不进容器，容器内呈现的就是 CI 运行时的原始内容，你调的才是"那个"环境。

breeze shell --mount-sources skip --python 3.10

判断成功的标准：进入交互式 shell 后，pip list里的依赖版本与失败作业日志中打印的一致。

第 4 步：在容器内重放失败。直接跑日志里失败的那条 pytest 命令或脚本，此时环境、依赖、commit 三者都与 CI 对齐，失败应当稳定复现。复现不出来时，先回头检查第 2 步的--python和第 1 步的 commit 是否对得上。

第 5 步：修完切回本地源码模式提交。纯skip模式下你改不了文件，定位到根因后检出 PR 分支，去掉--mount-sources skip用常规breeze shell（默认挂载本地源码），在 IDE 里改代码，用同一套 flags 重跑测试确认转绿，再推回 PR。这一步之所以成立，是因为检出同一分支后常规 breeze 命令可以直接复用 CI 镜像复现环境，不需要重建镜像。

这些变体和坑会改变你的操作路径 ⚠️

如果你只有 PR 编号没有 run ID。用--from-pr替代：

breeze ci-image load --from-pr 12345 --python 3.10 --github-token <your_token>

两种方式都必须带--github-token，缺了会被源码直接拦下报错退出——因为下载工件要调 GitHub API 鉴权。

如果你的机器是 ARM 架构（Apple Silicon 等）。ci-image load目前只支持 AMD 架构机器加载，因为 CI 产出的工件是linux/amd64镜像。在 ARM 机器上走这条路会失败，替代方案是检出 PR 分支后本地breeze ci-image build，或直接用容器模拟跑。文档注明该限制即将解除，以仓库当前版本为准。

如果你选择本地 build 而不是 load。要接受两个事实：其一，canary 构建和部分 PR 使用--upgrade-to-newer-dependencies（对应UPGRADE_TO_NEWER_DEPENDENCIES环境变量为true），这类构建不用 constraints 锁版本，你本地重建时必须带上同名 flag，否则依赖集合完全不同；其二，普通构建虽然用 constraints，但 constraints 本身会随时间变化，且 PyPI 上 Airflow 每天发布大量包，你构建出来的镜像大概率与 CI 当时的不同。正因如此，能用 load 就不要用 build。

如果你不需要镜像工件、只需要环境。检出 PR 分支后，常规breeze命令就能在镜像已存在时直接复现环境并挂载本地源码，这是日常修复的主路径；只有"连 PR 源码都没检出、只想看失败环境"时，load +--mount-sources skip才更划算。

镜像加载后的两个实用参数。--tag-as给镜像打一个自己好认的 tag；--skip-image-file-deletion保留下载下来的 tar 文件（默认加载完即删），适合网络贵、要反复加载的场景。

什么时候翻这张表

当你把 CI 日志里的 flags 翻译成自己机器上的breeze shell命令、或需要确认某个环境变量在本地与 CI 的默认差异时，查这张表：

HOST_USER_ID、HOST_GROUP_ID、HOST_OS这类主机变量由 breeze 在本地运行时自动探测注入，只有跨环境跑（比如 macOS 上模拟 Linux CI 行为）才需要手动覆盖。

源码走读：三处决定复现保真度的实现

load命令为什么敢自称"精确复现"。ci_image_commands.py 中的load走一条很短的路径：先拼出与 CI 命名规范一致的 tar 文件名（平台串里的/替换为_，如linux/amd64→linux_amd64），按--from-run或--from-pr分流下载工件，然后执行docker image load -i。整个流程不做任何依赖解析，这就是它比build保真的全部原因——镜像字节是 CI 时刻的产物，与"现在 PyPI 上有什么"无关。命令末尾的mark_image_as_rebuilt(ci_image_params=build_ci_params)（L643）容易被忽略：它把镜像标记为"已重建"，否则后续breeze命令会依据本地镜像的陈旧标记误判需要重建，把你刚加载的 CI 镜像又换掉。

日志里那段复现指令是怎么生成的。reproduce_ci.py 的 docstring 自述用途：在 CI 日志中打印本地复现指令。核心函数build_reproduction_command_from_context遍历 click 命令的每个参数，用ctx.get_parameter_source()区分来源，只保留COMMANDLINE / ENVIRONMENT / PROMPT三种显式来源的值（L47-L53），取默认值的参数一律省略；对--flag/--no-flag成对选项，只输出被显式设置的那一侧（L95-L100）。另一个值得注意的守卫：should_print_local_reproduction要求CI与GITHUB_ACTIONS同时为 true 才打印（L192-L196），所以本地跑 breeze 看不到这段区块——它是写给 CI 日志的，本地人拿日志当输入即可。

--mount-sources skip在容器编排里做了什么。shell_params.py 中mount_sources默认值是MOUNT_SELECTED，即挂载本地源码；取值不同时，代码选择不同的 docker compose 附加文件（L417-L426）：MOUNT_ALL挂全部源码，MOUNT_TESTS只挂 tests，MOUNT_REMOVE挂掉源码卷。skip走的是不挂载的分支，容器内就是镜像原始内容。同时该值会被写进容器环境变量MOUNT_SOURCES（L697），容器内初始化脚本据此调整行为——所以"挂载模式"不只是宿主机视角的事，容器内逻辑也能感知。

收尾：遇到什么走哪条路

1. CI 红了、只想看失败现场且不打算马上改代码：breeze ci-image load --from-run <id>+breeze shell --mount-sources skip，AMD 机器首选这条路。
2. 只有 PR 编号、没有 run ID：换成--from-pr <pr>，token 照样必填。
3. ARM 机器加载不了 amd64 工件：检出 PR 分支，本地breeze ci-image build兜底，接受依赖漂移。
4. 要复现 canary 或特殊 PR 的构建：本地 build 必须追加--upgrade-to-newer-dependencies，否则镜像依赖集与 CI 不同。
5. 已经检出 PR 分支、要边改边测：放弃 skip 模式，用常规breeze命令挂载本地源码，复用现有 CI 镜像，改完直接提交。

下次 CI 再红，先别推代码赌运气：日志里那段HOW TO REPRODUCE LOCALLY已经把复现命令写好了，把它落到ci-image load和breeze shell上，红叉就能在你自己的终端里变成绿色的通过记录。

【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow