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 用的那个镜像原封不动搬回本地在完全一致的环境里交互式地复现和修复。这就是本文的主题用BreezeAirflow 团队对 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 镜像和本地构建镜像都能得到一个可调试的环境但两者并不等价维度breeze ci-image load加载breeze ci-image build本地构建一致性与 CI 运行产出的镜像完全一致依赖当时的 constraints 与 PyPI 状态可能漂移速度下载工件 加载通常更快完整构建耗时更长适用场景失败复现的首选无法获取工件时的兜底方案三个高频坑症状和解法各一句话依赖漂移CI 构建后又有人在 PyPI 发布了新包Airflow 每天发布大量包这非常常见本地构建的镜像与 CI 不一致。解法优先用load加载 CI 工件而不是重新构建。架构不匹配你在 ARM 机器上运行ci-image load失败或行为异常。解法该功能目前仅支持 AMD 架构换机器或等待后续支持。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 命令行参数方便你直接复用到本地命令中。基础配置变量名对应 CLI flag本地默认值CI 默认值说明PYTHON_MAJOR_MINOR_VERSION--python使用的 Python 主/次版本BACKEND--backend测试中使用的后端数据库INTEGRATION--integration测试中使用的集成组件DB_RESET--db-reset/--no-db-resetfalsetrue容器入口是否重置数据库ANSWER--answeryes是否自动回答提问测试行为变量名对应 CLI flag本地默认值CI 默认值说明RUN_DB_TESTS_ONLY--run-db-tests-only数据库测试中为 true是否只执行数据库测试SKIP_DB_TESTS--skip-db-tests非数据库测试中为 true是否跳过数据库测试容器初始化变量名对应 CLI flag本地默认值CI 默认值说明MOUNT_SOURCES--mount-sourcesskip是否把本地源码挂载进容器SKIP_ENVIRONMENT_INITIALIZATION--skip-environment-initializationfalse (*)false (*)跳过测试环境初始化* 在 prek hooks 中为 trueSKIP_IMAGE_UPGRADE_CHECK--skip-image-upgrade-checkfalse (*)false (*)跳过镜像升级检查* 在 prek hooks 中为 trueSKIP_PROVIDERS_TESTSfalsefalse跳过 provider 集成测试非 main 分支SKIP_SSH_SETUPfalsefalse (*)跳过为测试配置 SSH 服务器* 在 GitHub CodeSpaces 中为 trueVERBOSE_COMMANDSfalsefalse是否打印 docker 中执行的每条命令主机信息变量名本地默认值CI 默认值说明HOST_USER_ID宿主机 UID宿主机用户的用户 idHOST_GROUP_ID宿主机 GID宿主机用户的组 idHOST_OS从 os 推导linux宿主机操作系统darwin/linux/windowsCOMMIT_SHAGITHUB_SHA构建所基于的提交 SHA进阶源码里的三个设计细节以下细节面向想深入理解实现的读者源码均在仓库中建议对照阅读。镜像下载与加载的内部流程ci-image load的实现位于 ci_image_commands.py核心流程调用perform_environment_checks()校验本地环境基于--python与--github-repository构建BuildCiParams平台字符串中的/替换为_拼装工件文件名ci-image-save-v3-{platform}-{python}.tar强制 token 校验使用--from-run或--from-pr但未提供--github-token时直接报错退出按来源下载工件from_run走download_artifact_from_run_idfrom_pr走download_artifact_from_pr均位于 github.py执行docker image load -i tar 文件若指定--tag-as则追加docker tag默认删除 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 buildcanary 构建记得加--upgrade-to-newer-dependencies。回到开头那个凌晨的场景日志还是刷屏但你现在有一个和线上分毫不差的容器。复现、修复、提交全程在本地完成——这就是 Breeze 给 Airflow 开发者设计的从失败到闭环的路径。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考