企业官网建设流程全解析

Apache Airflow 本地复现 CI 完整指南：Breeze 调试失败任务从零到闭环

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

凌晨两点，你的 PR 在 CI 上红了。点开 Actions 日志，几千行滚动输出，失败点埋在中段，你只知道"某个测试挂了"，却不确定是环境差异、依赖版本，还是你自己代码的问题。

重跑一次 CI 要等几十分钟，而且大概率还是红。与其盯着日志盲猜，不如把 CI 用的那个镜像原封不动搬回本地，在完全一致的环境里交互式地复现和修复。

这就是本文的主题：用Breeze（Airflow 团队对 docker 命令的 Python 封装器）把失败的 CI 运行完整本地复现，从"看日志"到"容器里跑通测试"形成闭环。

Breeze 在 CI 链路里扮演什么角色

Breeze是一个命令行工具，本质是 docker 命令的 Python 封装：它替你管理镜像构建、容器启动、环境初始化和测试执行。Airflow 的全部 CI 作业都是通过breeze命令执行的，所以"本地跑 breeze"和"CI 跑 breeze"用的是同一套环境。

链路大致是这样：

CI 作业（GitHub Actions） └─> 执行 breeze 命令（flags + 环境变量） └─> breeze 构建/复用 CI 镜像并启动容器 └─> 容器内运行测试、静态检查

理解这条链路后，你可以区分两种使用场景：

• 日常开发：本地运行与 CI 完全相同的测试，在提交 PR 之前先自我验证；
• CI 失败复现：拉取某次 CI 运行的镜像，进入与线上完全一致的环境交互式调试。

实战：从 CI 日志到本地环境的四步闭环

Step 1：从 CI 日志中提取 flags 与环境变量

在精确复现之前，你要先搞清楚 CI 到底是怎么调用 breeze 的。打开失败作业的日志，找两处信息：传给breeze命令的flags（命令行参数），以及命令执行前设置的环境变量。

两者缺一不可。有些配置走 flags，有些走环境变量；例如VERBOSE在全部 workflow 中被设为true，用于打印内部命令的更详细信息。Airflow 甚至在 CI 日志中自动打印一段本地复现指令，直接照抄即可（生成逻辑见后文进阶部分）。

# 从 CI 日志中抄出的典型 breeze 调用形态 breeze testing core-tests --python 3.10 --backend sqlite --backend-reset

💡 提示：同一作业甚至整个 workflow 的公共配置通常走环境变量，只看 flags 会漏掉一半信息。

Step 2：加载 CI 镜像的完整命令

拿到 PR 号或 Run ID 后，直接下载那次运行产出的镜像工件：

# 按 PR 加载 breeze ci-image load --from-pr 12345 --python 3.10 --github-token <your_github_token> # 或按 Run ID 加载（Run ID 来自 Actions 运行列表） breeze ci-image load --from-run 12538475388 --python 3.10 --github-token <your_github_token>

参数含义：--from-pr/--from-run指定来源；--python选择 Python 版本（镜像文件名按 Python 版本区分）；--github-token用于从 CI 工件下载镜像。

⚠️ 注意：该功能目前仅支持 AMD 架构机器，ARM 架构暂不支持。

Step 3：进入容器交互式调试，不挂载本地源码

镜像加载完成后，进入容器复现失败现场：

breeze shell --mount-sources skip [OPTIONS]

[OPTIONS]应替换为 Step 1 中抄到的那组 flags。--mount-sources skip是关键：它让容器不挂载你本机的源码，容器内的代码就是 CI 运行时的原始内容。此时你甚至没有检出失败 PR 的源码，也能在精确一致的环境里交互式运行任意测试和命令。

Step 4：需要改源码时的切换路径

只读日志和跑测试还不够，最终要改代码。此时检出失败 PR 的分支：

git checkout <pr-branch> breeze testing core-tests --python 3.10 --backend sqlite

检出 PR 分支后，常规 breeze 命令即可复现 CI 环境，无需重建镜像（例如依赖变化、CI 使用了新发布依赖的场景）。你恢复成平时开发 Airflow 的姿势：在 IDE 里编辑本地源码文件，breeze 负责把它挂载进容器执行。

避坑：本地构建 vs 镜像加载的取舍

"加载 CI 镜像"和"本地构建镜像"都能得到一个可调试的环境，但两者并不等价：

三个高频坑，症状和解法各一句话：

1. 依赖漂移：CI 构建后又有人在 PyPI 发布了新包（Airflow 每天发布大量包，这非常常见），本地构建的镜像与 CI 不一致。解法：优先用load加载 CI 工件，而不是重新构建。
2. 架构不匹配：你在 ARM 机器上运行ci-image load失败或行为异常。解法：该功能目前仅支持 AMD 架构，换机器或等待后续支持。
3. token 缺失：--from-run/--from-pr没配--github-token，命令直接报错退出。解法：下载工件必须带 token，这是源码中的强制校验。

推荐优先级很明确：加载镜像 > 本地构建。只有在确实拿不到工件时，才回退到breeze ci-image build；若失败的是 canary 构建或特殊 PR（使用了UPGRADE_TO_NEWER_DEPENDENCIES），本地构建时还必须追加--upgrade-to-newer-dependenciesflag，因为这类构建不使用 constraints 文件。

速查表：环境变量与 CLI 参数对照

这张表帮你把 CI 日志里出现的环境变量翻译成对应的 breeze 命令行参数，方便你直接复用到本地命令中。

基础配置

测试行为

容器初始化

主机信息

进阶：源码里的三个设计细节

以下细节面向想深入理解实现的读者，源码均在仓库中，建议对照阅读。

镜像下载与加载的内部流程

ci-image load的实现位于 ci_image_commands.py，核心流程：

1. 调用perform_environment_checks()校验本地环境；
2. 基于--python与--github-repository构建BuildCiParams，平台字符串中的/替换为_，拼装工件文件名ci-image-save-v3-{platform}-{python}.tar；
3. 强制 token 校验：使用--from-run或--from-pr但未提供--github-token时直接报错退出；
4. 按来源下载工件：from_run走download_artifact_from_run_id，from_pr走download_artifact_from_pr（均位于 github.py）；
5. 执行docker image load -i <tar 文件>，若指定--tag-as则追加docker tag；
6. 默认删除 tar 文件（--skip-image-file-deletion可保留），verbose 模式下打印docker images -a，并调用mark_image_as_rebuilt标记镜像已重建，避免后续命令误判需要重建。

"本地复现指令"是如何自动生成的

CI 日志里那段HOW TO REPRODUCE LOCALLY区块不是人手写的，而是 reproduce_ci.py 自动打印的。它的逻辑是：从 click 的Context中重建 CLI 调用，遍历命令定义的所有参数，用ctx.get_parameter_source()识别哪些值是用户或 CI 显式提供的（COMMANDLINE / ENVIRONMENT / PROMPT），只输出这些显式参数；取默认值的参数直接省略，--flag/--no-flag成对选项只输出被显式设置的一侧。

所以你看到的复现指令是"这次 CI 实际用了什么就打印什么"，可以放心直接复制到本地执行。

挂载模式 skip 为什么是精确复现的关键

shell_params.py 中mount_sources的取值包括默认挂载选中目录、挂载全部源码、仅挂载 tests 等模式；传入skip时则完全不挂载本地源码。

📌 关键：精确复现的前提是容器内代码与你本地代码无关。--mount-sources skip保证你调试的就是 CI 运行时的原始镜像内容，任何本地未提交改动都不会污染调试环境。

最小操作清单

下次 CI 红了，照这个顺序做：

• 打开失败作业日志，抄下完整 flags 和环境变量（别只看一半）；
• breeze ci-image load --from-run <run_id> --python <version> --github-token <token>加载镜像；
• breeze shell --mount-sources skip [OPTIONS]进入容器，交互式复现失败；
• 需要改源码时，检出 PR 分支，改用常规breeze命令挂载本地源码；
• 实在拿不到工件才考虑breeze ci-image build，canary 构建记得加--upgrade-to-newer-dependencies。

回到开头那个凌晨的场景：日志还是刷屏，但你现在有一个和线上分毫不差的容器。复现、修复、提交，全程在本地完成——这就是 Breeze 给 Airflow 开发者设计的从失败到闭环的路径。

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