CI 红了别慌手把手用 Breeze 在本地复现 Airflow CI 的完整指南【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow凌晨两点你盯着 Apache Airflow 的 CI 页面一长排红色的叉。翻日志报错信息埋在几千行输出里翻代码也没看出哪儿写错了。你想在本地把测试跑一遍验证一下可本地和 CI 总差那么一点CI 上挂的测试本地反而能过——这就是给 Airflow 贡献代码时最常见的挫败感你复现不了 CI 的现场。这篇文章就用 Airflow 官方工具 Breeze把 Airflow CI 的失败现场原封不动搬到你的机器上怎么加载 CI 构建出的镜像、怎么进入和线上完全一致的环境、哪些参数必须从 CI 日志里抄过来。读完后CI 再红你不用对着日志盲猜直接开终端还原案发现场。认识 Breeze给 Docker 命令配的一个遥控器先别被名字唬住Breeze 的官方定义很朴素一个 docker 命令的 Python 封装器dev/breeze/README.md。打个比方用 Docker 跑一套 Airflow 测试就像按顺序弹一架钢琴——先起容器、再挂载源码、初始化环境、然后跑测试一步错了就全乱。Breeze 就是遥控器你按一个键它替你按完整个组合键。关键是——Airflow 所有的 CI 作业也都是这台遥控器被 CI 系统按键的结果。所以复现 CI没有魔法在本地按一遍同样的组合键就行。官方文档 dev/breeze/doc/ci/07_running_ci_locally.md 把这件事说得明明白白只提醒你抄作业时要看全两处传给breeze命令的flags命令行参数运行breeze时设置的环境变量——比如所有 workflow 都会设VERBOSEtrue让 CI 打印更详细的内部命令。这两样都写在作业的 CI 日志里缺一个复现都不算完整。如何本地复现 Airflow CI三档姿势按成本从低到高动手前先问自己一句我要改代码吗这决定你从哪一档开始。第一档检出 PR 分支用常规 breeze 命令先跑起来什么时候用最常见的场景——你要修 bug需要改代码、快速迭代。操作很朴素检出失败 PR 所在的分支然后用你平时用的breeze命令比如breeze testing core-tests、breeze shell。此时 Breeze 会把本地源码挂载进容器你在 IDE 里像往常一样改文件、跑测试。官方文档指出只要检出了对应分支常规 breeze 命令不需要重建镜像就能复现 CI 环境——尤其是依赖变了、CI 用了新发布的包这类情况。想更进一步的话可以把 breeze 直接配进 IDE 的调试器里断点打在 breeze 自己的 Python 代码上见 dev/breeze/doc/14_advanced_breeze_topics.rst坑在哪这一档给你的是同样的代码 同样的命令不等于同样的依赖版本。如果失败恰恰由某个新包版本引起本地可能复现不出来——那就上第二档。第二档breeze ci-image load 加载 CI 镜像进入失败现场什么时候用同样的代码 命令本地复现不了你需要当年那次运行的原始环境。这是保真度最高的复现手段。CI 跑完会把构建出的镜像作为工件artifact可以理解为 CI 打包上传的产物存下来任何贡献者都能下载回来跑。CI 运行摘要页里就能看到这些工件按 PR 号或 Run ID 二选一下载需要一个有仓库读权限的 GitHub token# 按 PR 号下载镜像 breeze ci-image load --from-pr 12345 --python 3.10 --github-token your_token # 按 CI 运行 ID 下载镜像run id 在 CI 运行列表里能看到 breeze ci-image load --from-run 12538475388 --python 3.10 --github-token your_token加载完成后关键一步是不挂载本地源码地进容器# 进入与 CI 运行完全一致的环境不挂载本地代码 breeze shell --mount-sources skip [OPTIONS]--mount-sources skip的意思是别把我本机的代码挂进去容器里呈现的就是 CI 当年跑的东西——你没检出那个 PR 的源码也没关系可以交互式地跑任意测试、任意命令。这是调试 CI 问题最趁手的工具。坑在哪⚠️ 该功能目前只支持 AMD 架构机器ARM 机器比如 Apple Silicon暂不可用文档注明后续会支持--python必须和那次 CI 用的版本对上镜像是按平台 Python 版本存档的[OPTIONS]换成那次运行中对应作业的 flags去 CI 日志里找别省。第三档breeze ci-image build 本地构建最后的手段什么时候用镜像下不到没 token、工件已过期只能自己造一个。# 检出 PR 分支后在本地构建 CI 镜像 breeze ci-image build但要提前想清楚两件事部分构建根本不用 constraints。canary 构建和部分 PR 在构建时会把UPGRADE_TO_NEWER_DEPENDENCIES环境变量设为true对应--upgrade-to-newer-dependenciesflag。本地要重建这类镜像就必须传同样的 flag否则依赖版本和 CI 对不上。就算 flag 全传对也不是 100% 一致。CI 构建之后只要 PyPI 上有人发了新版本Airflow 每天发布大量包这非常常见你本地构建就会拉到更新的版本。这正是官方文档强调breeze ci-image load比本地 build 更可靠的原因前者直接复用 CI 的产物后者是在当前时刻重新解析依赖。build命令还支持 Python 版本、constraints 来源、构建平台、缓存策略等一串参数完整清单可以看源码 dev/breeze/src/airflow_breeze/commands/ci_image_commands.py。从 CI 红到本地修好Airflow CI 失败调试的完整流程把三档串起来走一遍真实排查路径。假设你提了个 PR测试作业挂了第 1 步在 CI 日志里找案发坐标。打开失败作业的日志找到实际执行的breeze命令记下它的 flags、日志开头的环境变量比如VERBOSEtrue以及该作业用的 Python 版本。这份清单就是你的复现配方。第 2 步加载 CI 镜像保真度优先。# 把那次运行的镜像原样拉到本地 breeze ci-image load --from-run run_id --python 3.10 --github-token your_token第 3 步进容器把失败复现出来。# 把 [OPTIONS] 换成第 1 步记下的 flags 和环境变量 breeze shell --mount-sources skip [OPTIONS]在容器里手动重跑 CI 中失败的那条命令。如果它以一模一样的方式失败恭喜——案发现场到手接下来可以逐行断点调试而不是对着日志猜。第 4 步要改代码验证修复时切回第一档。检出 PR 分支用挂载本地源码的常规breeze命令改代码、跑测试。修好后推上去让 CI 做最后确认。整个过程不离开本地机器这就是 Airflow 把CI 可本地复现写进贡献流程的意义。本地默认值 vs CI 实际值哪些环境变量不一样新手常问命令我照抄了为什么行为和 CI 还不一样——因为有几个环境变量的本地默认值和 CI 实际值并不相同变量本地默认CI 实际值差异意味着什么DB_RESETfalsetrueCI 每次进容器都重置数据库本地默认不重置ANSWER无yesCI 对交互式提问自动作答本地你要自己按回车MOUNT_SOURCES挂载skipCI 不挂载本地源码复现时要传--mount-sources skipCOMMIT_SHA本地 git 推导GITHUB_SHACI 用来标识构建所基于的提交SKIP_SSH_SETUPfalsefalseCodeSpaces 中为true是否为测试配置 SSH 服务器另外HOST_USER_ID、HOST_GROUP_ID、HOST_OS这几个由 Breeze 在本地运行时根据宿主机自动填充你一般不用管。控制测试范围的RUN_DB_TESTS_ONLY只跑数据库测试、SKIP_DB_TESTS跳过数据库测试则由 CI 按作业类型设置本地需要时传对应 flag 即可。完整对照表见官方文档 dev/breeze/doc/ci/07_running_ci_locally.md。深挖CI 日志里那行可直接复制的复现命令是怎么生成的看 Airflow 的 CI 日志会发现它会直接打印一条可以复制即跑的 breeze 命令。这不是人手敲的是自动生成的。实现藏在 dev/breeze/src/airflow_breeze/utils/reproduce_ci.py核心函数build_reproduction_command_from_context从 click 的Context重建 CLI 调用逻辑很干净遍历命令定义的每个参数用ctx.get_parameter_source()问 click这个值从哪来的只输出被显式提供的参数来自命令行、环境变量或交互提问取了默认值的参数一律省略命令因此保持简短--flag/--no-flag成对选项只输出被显式设置的那一侧--verbose、--dry-run这类纯调试参数直接排除不参与复现。所以你在 CI 日志里看到的那条命令本质是当时实际执行命令中显式设置的部分的精确回显——这也是为什么你可以放心把它直接复制到本地执行。breeze 避坑清单新手最常踩的雷Qci-image load报错说必须提供--github-token--from-run/--from-pr要从 GitHub 下载工件必须带 token源码里有一道硬校验缺了就报错退出。先备好一个有仓库读权限的 personal access token。QApple Silicon 上load用不了目前只支持 AMD 架构ARM 机器先用第一档或第三档过渡。Q本地构建的镜像能过CI 还是挂依赖版本没对齐——CI 构建后 PyPI 发过新版包本地 build 拉到的就是新的。要精确对现场还是回到breeze ci-image load。Qbreeze 连 Docker 都调不起来多半是 Docker socket 权限问题。macOS 上可以在 Docker Desktop 的 Advanced 设置里勾选Allow the default Docker socket to be usedQ磁盘写满了breeze 报空间不足CI 镜像和缓存非常吃磁盘。macOS 上可以在 Docker Desktop 的 Disk 设置里调大磁盘配额Q想保留下载下来的镜像 tar 文件load默认下载完就删 tar加--skip-image-file-deletion可以保留--tag-as则能给加载进来的镜像另起一个名字。一句话收束Breeze 背后的设计目标很直白无论 CI 基础设施多复杂任何一次检查都必须能在开发者本地被复现。下次 CI 再红别对着日志猜——在本地按一遍同样的组合键答案自己会浮出来。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考