如何本地复现 Airflow CI 失败Breeze 完整实战【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowCI 又红了日志翻了三遍还是说不清挂在哪一步改完代码只能推回 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 的默认差异时查这张表变量对应 flagCI 侧典型值什么时候改PYTHON_MAJOR_MINOR_VERSION--python与作业一致换 Python 版本复现BACKEND--backend与作业一致复现特定数据库失败INTEGRATION--integration与作业一致复现特定集成测试DB_RESET--db-reset/--no-db-resettrue本地要保留数据时改 falseANSWER--answeryes本地想交互确认时去掉MOUNT_SOURCES--mount-sourcesskip要改源码时改回默认挂载RUN_DB_TESTS_ONLY--run-db-tests-onlydb 作业 true对齐 db/非 db 作业划分SKIP_DB_TESTS--skip-db-tests非 db 作业 true同上成对理解SKIP_ENVIRONMENT_INITIALIZATION--skip-environment-initializationfalseprek hooks 中为 trueSKIP_PROVIDERS_TESTS无直接 flagfalse跳过 provider 集成测试SKIP_SSH_SETUP无直接 flagCodeSpaces 中 true无 SSH 需求时跳过VERBOSE_COMMANDS无直接 flagfalse想看容器内每条命令时COMMIT_SHA无取自 GITHUB_SHA对齐 CI 构建的提交VERBOSE--verbosetrue全部 workflow 恒为 trueHOST_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_paramsbuild_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-L426MOUNT_ALL挂全部源码MOUNT_TESTS只挂 testsMOUNT_REMOVE挂掉源码卷。skip走的是不挂载的分支容器内就是镜像原始内容。同时该值会被写进容器环境变量MOUNT_SOURCESL697容器内初始化脚本据此调整行为——所以挂载模式不只是宿主机视角的事容器内逻辑也能感知。收尾遇到什么走哪条路CI 红了、只想看失败现场且不打算马上改代码breeze ci-image load --from-run idbreeze shell --mount-sources skipAMD 机器首选这条路。只有 PR 编号、没有 run ID换成--from-pr prtoken 照样必填。ARM 机器加载不了 amd64 工件检出 PR 分支本地breeze ci-image build兜底接受依赖漂移。要复现 canary 或特殊 PR 的构建本地 build 必须追加--upgrade-to-newer-dependencies否则镜像依赖集与 CI 不同。已经检出 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
