Apache Airflow Breeze 开发环境安装指南前置条件、资源要求与 uvx shim 安装机制【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowBreeze 是 Apache Airflow 官方基于 Docker Compose 构建的开发与测试环境本地开发与 CI 测试共用同一套镜像目标是让贡献者像一阵微风一样轻松地为 Airflow 贡献代码。本文围绕 Breeze 的安装全流程展开先讲清 Docker Desktop、Docker Compose、WSL 2 等前置条件与资源要求再重点剖析当前推荐的 uvx shim 安装机制ADR 0017最后覆盖breeze setup配置命令、首次运行、自动卸载与故障排查读完即可在任何一台机器上把 Breeze 跑起来并接入 Airflow 贡献流程。前置条件Docker 是 Breeze 的运行时基础Breeze 本质上是一套围绕 Docker 的封装它在本地拉取 Airflow 的 CI 镜像用 Docker Compose 编排出包含 Airflow 源码挂载、元数据库、调度器等组件的完整开发环境。因此在安装 Breeze 之前必须先保证 Docker 环境可用。Docker Desktop版本安装最新的稳定版 Docker Desktop并确保docker命令在 PATH 中。Breeze 会检测 Docker 版本是否过旧并给出升级提示。权限配置为可以直接运行docker命令而无需 root。你的用户应被加入docker组详见下文常见的 Docker 错误小节。磁盘空间macOS 上建议预留至少 20 GB 可用磁盘空间空间不足时可定期清理 Docker 磁盘占用文档中展示的示例配置为给 Docker 分配 200 GB 以上磁盘空间。Docker context新版 Docker Desktop 默认使用desktop-linuxcontext其 docker socket 位于用户主目录下旧版本及纯 Docker Engine 使用/var/run/docker.sock和defaultcontextColima 等轻量引擎会创建colimacontext。Breeze 会自动挑选合适的 context但退出 Docker Desktop 后遗留的desktop-linuxcontext 在 Colima 运行时仍可能胜出。此时可以显式指定 Docker socketexport DOCKER_HOSTunix://$HOME/.colima/default/docker.sock # 或每次调用时传递 breeze --docker-host unix://$HOME/.colima/default/docker.sock shell--builder标志用于选择docker buildx build所用的 Buildx builder / docker context 名称若只需要选择连接哪个引擎 socket优先使用--docker-host/DOCKER_HOST。已知版本问题即使 Docker Desktop 显示运行中也可能报 Docker is not running。这是 Docker Desktop 4.13.02022 年 10 月底发布的已知问题升级到 4.13.1 或更高版本即可解决。常见的 Docker 错误及修复在 Python 虚拟环境中运行 Breeze 时如果 Docker 因权限问题不可用按以下步骤修复# 1. 若 docker 组不存在则创建 sudo groupadd docker # 2. 将当前用户加入 docker 组 sudo usermod -aG docker $USER # 3. 登录到新的 docker 组使组变更生效 newgrp docker # 4. 验证无需 root 即可运行 docker docker run hello-world另外在 Docker Desktop 设置的 Advanced 标签页中确认已勾选 Allow the default Docker socket to be used允许使用默认 Docker socket。Docker Compose版本安装最新稳定版 Docker Compose 并加入 PATH。Breeze 同样会检测 Compose 版本是否过旧并提示升级。权限配置好用户直接执行docker-compose命令的权限。Docker in WSL 2Windows 开发Windows 用户建议按以下路径配置WSL 2 安装安装 WSL 2 及一个 Linux 发行版如 Ubuntu详见微软 WSL 2 安装指南。Windows Home 版与 Pro/Enterprise/Education 版的 Docker Desktop 安装流程不同请按对应指南操作。WSL 集成必须在 Docker Desktop 设置中启用 WSL integration。文件系统性能访问 Windows 宿主文件系统有性能损耗强烈建议在 Linux 文件系统上开发例如cd ~后在 Linux 发行版的家目录下创建开发目录并git cloneAirflow 仓库。Docker mount 错误路径过长时在 Windows 挂载文件系统上启动 Breeze 可能报caused: mount through procfd: not a directory: unknown:因此强烈不建议把 Airflow 检出到 Windows 挂载的文件系统中。若在启动 Breeze 或运行 prek 测试时遇到Cannot create container for service airflow: not a directory或docker: Error response from daemon: not a directory可考虑直接在 WSL 2 内安装 Docker 而非使用 Docker Desktop for Windows。内存占用WSL 2 可能以 Vmmem 进程消耗大量内存开发完成后可用以下方式回收# 在 Linux 发行版中清空缓存的内存 sudo sysctl -w vm.drop_caches3 # 不再使用 Docker 时右键系统托盘图标选择 Quit Docker Desktop # 不再使用 WSL 时在 Windows 宿主上执行 wsl --shutdown在 WSL 2 中开发可以使用全部标准 Linux 命令行工具。VS Code 支持在 Windows 上开发、在 WSL 中远程执行若 Windows 宿主机装了 VS Code在 WSL Linux 发行版的 Airflow 仓库根目录执行code .即可启动 VS Code。使用 Colima 的用户请额外遵循 贡献者快速入门指南 中的 Colima 章节。资源要求内存、磁盘与清理运行完整的 Breeze 环境需要满足最低资源门槛并养成定期清理的习惯。内存Docker Engine 至少需要4 GB RAM才能运行完整 Breeze 环境。macOS 上 Docker 容器默认只有 2 GB 内存可用建议调大4 GB 比较舒适可在 Docker for Mac 的 Advanced 标签页调整。Windows WSL 2 上Linux 发行版加 Docker 容器预计会占用 7–8 GB RAM。磁盘Docker 容器至少需要40 GB 可用磁盘空间。macOS 上空间随时间推移可能恶化需要增大配额或定期执行breeze cleanup。WSL 2 用户可能需要按微软官方指引扩容虚拟硬盘。可用breeze ci resource-check命令检查当前可用资源详见 CI 任务文档。清理环境Breeze 镜像体积不小静态代码分析和 CI 测试所需的两类镜像各约 1.5 GB频繁重建/更新会留下未使用的镜像数据需要偶尔清理# 1. 若 Breeze 正在运行先停止 breeze down # 2. 清理 Docker 环境 breeze cleanup # 3. 验证 Docker 已清理干净两条命令应分别返回空列表 docker images --all docker ps --all若遇到磁盘空间错误可用docker system prune --all修剪 Docker 镜像必要时先重启 Docker Engine 再执行。安装 Breeze首选 uvx shim 方案克隆仓库首先克隆 Airflow 仓库但切勿克隆到家目录否则会报错Your Airflow sources are checked out in /Users/username/airflow, which is also your AIRFLOW_HOME where Airflow writes logs and database files. This setup is problematic because Airflow might overwrite or clean up your source code and .git repository.git clone https://github.com/apache/airflow.git cd airflow推荐方案在~/.local/bin/breeze安装 shim 脚本当前推荐的做法是在~/.local/bin/breeze安装一个极小的shim 脚本它通过uv run --locked从当前 git worktree的dev/breeze目录运行 Breeze所有依赖由已提交的dev/breeze/uv.lock锁定。这样避免了单一全局安装每个 git worktree包括编码 Agent 创建的临时 worktree都拥有与自身源码绑定的 Breeze。由于 shim 是 PATH 上的真实文件pre-commit 钩子、CI 脚本等子进程可以像调用uv tool安装的二进制一样看到它。设计动机详见 ADR 0017。最简单的安装方式是运行仓库自带的辅助脚本./scripts/tools/setup_breeze该脚本scripts/tools/setup_breeze会依次检查uv是否安装缺失时通过python -m pip install uv0.12.10安装检测并拒绝在存在旧版全局 breeze 安装时继续详见下文卸载 Breeze随后把 shim 写入~/.local/bin/breeze并赋予可执行权限最后检查~/.local/bin是否在 PATH 中。手动安装将下面的内容写入~/.local/bin/breeze并chmod x#!/usr/bin/env bash # Apache Airflow breeze shim — managed by scripts/tools/setup_breeze (ADR 0017). set -e repo_root$(git rev-parse --show-toplevel 2/dev/null) || { echo breeze: not inside a git repository — cd into an Airflow worktree first 2 exit 1 } if [ ! -d ${repo_root}/dev/breeze ]; then echo breeze: ${repo_root} is not an Airflow worktree (no dev/breeze) 2 exit 1 fi exec env AIRFLOW_ROOT_PATH${repo_root} SKIP_BREEZE_SELF_UPGRADE_CHECK1 \ uv run --project ${repo_root}/dev/breeze --locked --quiet breeze $安装完成后在任何 Airflow checkout 中调用breeze都会使用该 checkout 的源码。全新 worktree 的首次调用会一次性同步dev/breeze/.venv约 275 MB大多通过 hardlink 复用 uv 缓存被.gitignore和.dockerignore忽略后续调用直接复用该环境。从源码结构看shim 还带有一行# breeze-shim-version: N标记当前为SHIM_VERSION2Breeze 启动时会读取该标记并与当前源码中setup_breeze会安装的版本比较若 shim 过旧则提示重新运行脚本相关逻辑见 path_utils.py 中的warn_if_shim_outdated()。shim 的 worktree 解析顺序从 ADR 0017 与 shim 实际代码可以确认Breeze 源码的解析顺序为当前 git worktreegit rev-parse --show-toplevel实现每 worktree 隔离若当前目录不是 Airflow worktree则回退到环境变量$AIRFLOW_REPO_ROOT指向的 Airflow worktree发布文档会导出该变量保证整个发布流程解析一致若仍不满足则回退到安装 shim 时所在的 worktreesetup_breeze运行时烘焙进 shim 的AIRFLOW_SOURCES。后两级回退仅在当前目录不是 Airflow worktree 时生效因此永远不会覆盖真实 worktree 的隔离性。只有三者都缺失dev/breeze时 shim 才会报错退出。CI 中的安装方式CI 采用与 shim 相同的锁定策略scripts/ci/install_breeze.sh 先卸载可能残留的全局uv tool安装避免其通过~/.local/bin遮蔽 venv 脚本再执行uv sync --locked --project ./dev/breeze/精确安装uv.lock锁定的依赖并把dev/breeze/.venv/bin加入GITHUB_PATH。这正是 ADR 0017 的取舍不用uv tool install是因为它会重新解析依赖导致某个第三方版本在当天发布就会悄悄改变 Breeze 行为——文中记录的 click 8.5.0 事件新增help字段导致命令哈希漂移、所有 PR 静态检查变红就是该问题的实证。备选方案传统的全局安装uv tool 或 pipx如果你偏好 PATH 上单一全局安装ADR 0017 之前的做法仍可用uv tool或pipx安装。但不推荐用于多 checkout 或多 worktree 场景所有 worktree 会共享同一个指向最后一次uv tool install --force源码树的 breeze 二进制且会与上述 shim 方案冲突两者都写入~/.local/bin/breeze。uv tool install -e ./dev/breeze # 或 pipx install -e ./dev/breezeWindows 用户注意./dev/breeze是指向 breeze 源码包的子目录路径Windows 上请使用 Windows 风格路径如uv tool install -e dev\breeze或pipx install -e dev\breeze。升级与版本管理在推荐uvx方案下Breeze 始终从当前 worktree 的dev/breeze运行pyproject.toml/uv.lock一旦变化uv 会自动重建缓存环境无需手动自我升级。在传统全局安装下Breeze 链接到安装时检出的 Airflow 源码依赖更新后breeze命令会提示你运行自我升级也可随时手动执行breeze setup self-upgrade若同时有多个 Airflow 源码检出全局安装会在从不同源码树调用时警告并建议重新安装以确保使用正确版本。可通过设置非空环境变量SKIP_BREEZE_UPGRADE_CHECK跳过升级检查。默认 Breeze 工作在你运行它的 Airflow 版本上若在 Airflow 源码目录之外且从某目录安装了 Breeze则 Breeze 作用于其安装来源的源码。用breeze setup version查看 Breeze 安装自何处、当前作用于哪些源码。处理 Python 版本问题若 Breeze 提示需要比当前环境更新的 Python推荐uvx方案调用前导出UV_PYTHON指定版本例如UV_PYTHON3.10 breeze ...也可永久写入 shell rcuvx 会在下次调用时用该解释器重建缓存环境。传统全局安装用uv或pipx强制重装uv tool install --force -e ./dev/breeze # 或 pipx install --force -e ./dev/breeze指定 Python 版本创建虚拟环境推荐方案下UV_PYTHON3.10.16 breeze ...即为缓存环境选择 Python 版本全局安装默认使用系统 Python可用--python固定uv tool install --python 3.10.16 ./dev/breeze --force # 或 pipx install -e ./dev/breeze --python /Users/airflow/.pyenv/versions/3.10.16/bin/python --forceWindows 用户同样将./dev/breeze替换为dev\breeze。首次运行与自动补全首次运行 Breeze 时会拉取并在本地构建 Docker 镜像它从 GitHub Container Registry 拉取最新的 Airflow CI 镜像再据此构建本地镜像。注意每个 Python 版本的首次运行在高速网络下最多可能需要 10 分钟后续运行会快得多。进入环境后你会落在 Airflow 容器的 bash shell 中可以立即运行测试。安装后建议立即配置命令补全。breeze内置 bash/zsh/fish 自动补全设置命令配置后输入命令时按TAB可查看所有可用开关并能自动补全常用参数值breeze setup autocomplete重新进入 shell 后补全生效按脚本打印的提示操作。若已配置过命令会提示并不重复安装需要强制重装可执行breeze setup autocomplete --forceBreeze setup 命令族配置与维护breeze setup提供了一组用于配置默认值、维护 Breeze 自身行为以及为宿主机配置补全的工具。从 setup_commands_config.py 中的SETUP_COMMANDS可以看到setup子命令包括autocomplete、self-upgrade、cleanup、config、check-all-params-in-groups、regenerate-command-images、synchronize-local-mounts、command-hash-export、version。setup autocomplete配置 shell 自动补全唯一标志为--force强制重装。setup self-upgrade自动自我升级 Breeze重装其全部最新依赖。通常自动进行但安装损坏时可强制升级。可用标志为--use-current-airflow-sources。setup version显示 Breeze 版本加--verbose可输出更多信息Breeze 安装来源、setup 哈希细节等。setup config配置并检查 Breeze 命令的设置Python 版本、后端Backend类型及后端版本。从源码可见其标志包括标志作用--python选择默认 Python 版本--backend选择使用的后端如 PostgreSQL / MySQL / SQLite 等--postgres-version/--mysql-version指定对应数据库后端版本--terminal-multiplexer配置终端复用器--auth-manager配置认证管理器--llm-model配置 LLM 模型用于支持 AI 辅助类功能--cheatsheet启用/禁用 cheatsheet新手提示面板--asciiart启用/禁用启动 ASCII 艺术字--colour启用/禁用彩色消息输出其中 cheatsheet 与 asciiart 属于锦上添花的展示内容cheatsheet 对首次使用者有价值若觉得重复繁琐可以关闭。--no-colour关闭颜色编码消息改用斜体/粗体/下划线等字体方案区分信息、错误、警告与成功消息这对色弱友好。自动化安装在 POSIX 兼容系统Linux、macOS上运行 scripts/tools/setup_breeze 即可自动化安装检查/安装uv、检测到旧版全局 breeze 安装时拒绝继续、然后把 shim 脚本见 ADR 0017写入~/.local/bin/breeze。卸载 Breeze推荐shim方案直接删除 shim 脚本rm ~/.local/bin/breeze如需同时删除缓存环境uv cache clean apache-airflow-breeze传统全局安装使用对应工具卸载同时会从${HOME}/.local/bin/移除 breezeuv tool uninstall apache-airflow-breeze # 或 pipx uninstall apache-airflow-breeze需要特别留意的是setup_breeze会通过uv tool list、uv tool dir及pipx list --short检测残留的全局安装包括环境损坏、已从uv tool list输出中消失的安装检测到后会明确提示先执行上述卸载命令再重跑脚本——因为 shim 与全局安装都写入~/.local/bin/breeze静默覆盖会破坏 uv 的 tool 状态并造成后续升级混乱。下一步安装完成只是开始。接下来可以阅读 自定义 Breeze 环境 指南来配置 Python 版本、后端数据库与挂载选项完整的命令清单与setup子命令的 SVG 参数图位于 dev/breeze/doc/images 目录若需了解 Breeze 的整体定位与优势可阅读 Airflow Breeze 环境总览或查阅dev/breeze/adr目录下的架构决策记录Architecture Decision Records理解各设计取舍。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Apache Airflow Breeze 开发环境安装指南：前置条件、资源要求与 uvx shim 安装机制
Apache Airflow Breeze 开发环境安装指南前置条件、资源要求与 uvx shim 安装机制【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowBreeze 是 Apache Airflow 官方基于 Docker Compose 构建的开发与测试环境本地开发与 CI 测试共用同一套镜像目标是让贡献者像一阵微风一样轻松地为 Airflow 贡献代码。本文围绕 Breeze 的安装全流程展开先讲清 Docker Desktop、Docker Compose、WSL 2 等前置条件与资源要求再重点剖析当前推荐的 uvx shim 安装机制ADR 0017最后覆盖breeze setup配置命令、首次运行、自动卸载与故障排查读完即可在任何一台机器上把 Breeze 跑起来并接入 Airflow 贡献流程。前置条件Docker 是 Breeze 的运行时基础Breeze 本质上是一套围绕 Docker 的封装它在本地拉取 Airflow 的 CI 镜像用 Docker Compose 编排出包含 Airflow 源码挂载、元数据库、调度器等组件的完整开发环境。因此在安装 Breeze 之前必须先保证 Docker 环境可用。Docker Desktop版本安装最新的稳定版 Docker Desktop并确保docker命令在 PATH 中。Breeze 会检测 Docker 版本是否过旧并给出升级提示。权限配置为可以直接运行docker命令而无需 root。你的用户应被加入docker组详见下文常见的 Docker 错误小节。磁盘空间macOS 上建议预留至少 20 GB 可用磁盘空间空间不足时可定期清理 Docker 磁盘占用文档中展示的示例配置为给 Docker 分配 200 GB 以上磁盘空间。Docker context新版 Docker Desktop 默认使用desktop-linuxcontext其 docker socket 位于用户主目录下旧版本及纯 Docker Engine 使用/var/run/docker.sock和defaultcontextColima 等轻量引擎会创建colimacontext。Breeze 会自动挑选合适的 context但退出 Docker Desktop 后遗留的desktop-linuxcontext 在 Colima 运行时仍可能胜出。此时可以显式指定 Docker socketexport DOCKER_HOSTunix://$HOME/.colima/default/docker.sock # 或每次调用时传递 breeze --docker-host unix://$HOME/.colima/default/docker.sock shell--builder标志用于选择docker buildx build所用的 Buildx builder / docker context 名称若只需要选择连接哪个引擎 socket优先使用--docker-host/DOCKER_HOST。已知版本问题即使 Docker Desktop 显示运行中也可能报 Docker is not running。这是 Docker Desktop 4.13.02022 年 10 月底发布的已知问题升级到 4.13.1 或更高版本即可解决。常见的 Docker 错误及修复在 Python 虚拟环境中运行 Breeze 时如果 Docker 因权限问题不可用按以下步骤修复# 1. 若 docker 组不存在则创建 sudo groupadd docker # 2. 将当前用户加入 docker 组 sudo usermod -aG docker $USER # 3. 登录到新的 docker 组使组变更生效 newgrp docker # 4. 验证无需 root 即可运行 docker docker run hello-world另外在 Docker Desktop 设置的 Advanced 标签页中确认已勾选 Allow the default Docker socket to be used允许使用默认 Docker socket。Docker Compose版本安装最新稳定版 Docker Compose 并加入 PATH。Breeze 同样会检测 Compose 版本是否过旧并提示升级。权限配置好用户直接执行docker-compose命令的权限。Docker in WSL 2Windows 开发Windows 用户建议按以下路径配置WSL 2 安装安装 WSL 2 及一个 Linux 发行版如 Ubuntu详见微软 WSL 2 安装指南。Windows Home 版与 Pro/Enterprise/Education 版的 Docker Desktop 安装流程不同请按对应指南操作。WSL 集成必须在 Docker Desktop 设置中启用 WSL integration。文件系统性能访问 Windows 宿主文件系统有性能损耗强烈建议在 Linux 文件系统上开发例如cd ~后在 Linux 发行版的家目录下创建开发目录并git cloneAirflow 仓库。Docker mount 错误路径过长时在 Windows 挂载文件系统上启动 Breeze 可能报caused: mount through procfd: not a directory: unknown:因此强烈不建议把 Airflow 检出到 Windows 挂载的文件系统中。若在启动 Breeze 或运行 prek 测试时遇到Cannot create container for service airflow: not a directory或docker: Error response from daemon: not a directory可考虑直接在 WSL 2 内安装 Docker 而非使用 Docker Desktop for Windows。内存占用WSL 2 可能以 Vmmem 进程消耗大量内存开发完成后可用以下方式回收# 在 Linux 发行版中清空缓存的内存 sudo sysctl -w vm.drop_caches3 # 不再使用 Docker 时右键系统托盘图标选择 Quit Docker Desktop # 不再使用 WSL 时在 Windows 宿主上执行 wsl --shutdown在 WSL 2 中开发可以使用全部标准 Linux 命令行工具。VS Code 支持在 Windows 上开发、在 WSL 中远程执行若 Windows 宿主机装了 VS Code在 WSL Linux 发行版的 Airflow 仓库根目录执行code .即可启动 VS Code。使用 Colima 的用户请额外遵循 贡献者快速入门指南 中的 Colima 章节。资源要求内存、磁盘与清理运行完整的 Breeze 环境需要满足最低资源门槛并养成定期清理的习惯。内存Docker Engine 至少需要4 GB RAM才能运行完整 Breeze 环境。macOS 上 Docker 容器默认只有 2 GB 内存可用建议调大4 GB 比较舒适可在 Docker for Mac 的 Advanced 标签页调整。Windows WSL 2 上Linux 发行版加 Docker 容器预计会占用 7–8 GB RAM。磁盘Docker 容器至少需要40 GB 可用磁盘空间。macOS 上空间随时间推移可能恶化需要增大配额或定期执行breeze cleanup。WSL 2 用户可能需要按微软官方指引扩容虚拟硬盘。可用breeze ci resource-check命令检查当前可用资源详见 CI 任务文档。清理环境Breeze 镜像体积不小静态代码分析和 CI 测试所需的两类镜像各约 1.5 GB频繁重建/更新会留下未使用的镜像数据需要偶尔清理# 1. 若 Breeze 正在运行先停止 breeze down # 2. 清理 Docker 环境 breeze cleanup # 3. 验证 Docker 已清理干净两条命令应分别返回空列表 docker images --all docker ps --all若遇到磁盘空间错误可用docker system prune --all修剪 Docker 镜像必要时先重启 Docker Engine 再执行。安装 Breeze首选 uvx shim 方案克隆仓库首先克隆 Airflow 仓库但切勿克隆到家目录否则会报错Your Airflow sources are checked out in /Users/username/airflow, which is also your AIRFLOW_HOME where Airflow writes logs and database files. This setup is problematic because Airflow might overwrite or clean up your source code and .git repository.git clone https://github.com/apache/airflow.git cd airflow推荐方案在~/.local/bin/breeze安装 shim 脚本当前推荐的做法是在~/.local/bin/breeze安装一个极小的shim 脚本它通过uv run --locked从当前 git worktree的dev/breeze目录运行 Breeze所有依赖由已提交的dev/breeze/uv.lock锁定。这样避免了单一全局安装每个 git worktree包括编码 Agent 创建的临时 worktree都拥有与自身源码绑定的 Breeze。由于 shim 是 PATH 上的真实文件pre-commit 钩子、CI 脚本等子进程可以像调用uv tool安装的二进制一样看到它。设计动机详见 ADR 0017。最简单的安装方式是运行仓库自带的辅助脚本./scripts/tools/setup_breeze该脚本scripts/tools/setup_breeze会依次检查uv是否安装缺失时通过python -m pip install uv0.12.10安装检测并拒绝在存在旧版全局 breeze 安装时继续详见下文卸载 Breeze随后把 shim 写入~/.local/bin/breeze并赋予可执行权限最后检查~/.local/bin是否在 PATH 中。手动安装将下面的内容写入~/.local/bin/breeze并chmod x#!/usr/bin/env bash # Apache Airflow breeze shim — managed by scripts/tools/setup_breeze (ADR 0017). set -e repo_root$(git rev-parse --show-toplevel 2/dev/null) || { echo breeze: not inside a git repository — cd into an Airflow worktree first 2 exit 1 } if [ ! -d ${repo_root}/dev/breeze ]; then echo breeze: ${repo_root} is not an Airflow worktree (no dev/breeze) 2 exit 1 fi exec env AIRFLOW_ROOT_PATH${repo_root} SKIP_BREEZE_SELF_UPGRADE_CHECK1 \ uv run --project ${repo_root}/dev/breeze --locked --quiet breeze $安装完成后在任何 Airflow checkout 中调用breeze都会使用该 checkout 的源码。全新 worktree 的首次调用会一次性同步dev/breeze/.venv约 275 MB大多通过 hardlink 复用 uv 缓存被.gitignore和.dockerignore忽略后续调用直接复用该环境。从源码结构看shim 还带有一行# breeze-shim-version: N标记当前为SHIM_VERSION2Breeze 启动时会读取该标记并与当前源码中setup_breeze会安装的版本比较若 shim 过旧则提示重新运行脚本相关逻辑见 path_utils.py 中的warn_if_shim_outdated()。shim 的 worktree 解析顺序从 ADR 0017 与 shim 实际代码可以确认Breeze 源码的解析顺序为当前 git worktreegit rev-parse --show-toplevel实现每 worktree 隔离若当前目录不是 Airflow worktree则回退到环境变量$AIRFLOW_REPO_ROOT指向的 Airflow worktree发布文档会导出该变量保证整个发布流程解析一致若仍不满足则回退到安装 shim 时所在的 worktreesetup_breeze运行时烘焙进 shim 的AIRFLOW_SOURCES。后两级回退仅在当前目录不是 Airflow worktree 时生效因此永远不会覆盖真实 worktree 的隔离性。只有三者都缺失dev/breeze时 shim 才会报错退出。CI 中的安装方式CI 采用与 shim 相同的锁定策略scripts/ci/install_breeze.sh 先卸载可能残留的全局uv tool安装避免其通过~/.local/bin遮蔽 venv 脚本再执行uv sync --locked --project ./dev/breeze/精确安装uv.lock锁定的依赖并把dev/breeze/.venv/bin加入GITHUB_PATH。这正是 ADR 0017 的取舍不用uv tool install是因为它会重新解析依赖导致某个第三方版本在当天发布就会悄悄改变 Breeze 行为——文中记录的 click 8.5.0 事件新增help字段导致命令哈希漂移、所有 PR 静态检查变红就是该问题的实证。备选方案传统的全局安装uv tool 或 pipx如果你偏好 PATH 上单一全局安装ADR 0017 之前的做法仍可用uv tool或pipx安装。但不推荐用于多 checkout 或多 worktree 场景所有 worktree 会共享同一个指向最后一次uv tool install --force源码树的 breeze 二进制且会与上述 shim 方案冲突两者都写入~/.local/bin/breeze。uv tool install -e ./dev/breeze # 或 pipx install -e ./dev/breezeWindows 用户注意./dev/breeze是指向 breeze 源码包的子目录路径Windows 上请使用 Windows 风格路径如uv tool install -e dev\breeze或pipx install -e dev\breeze。升级与版本管理在推荐uvx方案下Breeze 始终从当前 worktree 的dev/breeze运行pyproject.toml/uv.lock一旦变化uv 会自动重建缓存环境无需手动自我升级。在传统全局安装下Breeze 链接到安装时检出的 Airflow 源码依赖更新后breeze命令会提示你运行自我升级也可随时手动执行breeze setup self-upgrade若同时有多个 Airflow 源码检出全局安装会在从不同源码树调用时警告并建议重新安装以确保使用正确版本。可通过设置非空环境变量SKIP_BREEZE_UPGRADE_CHECK跳过升级检查。默认 Breeze 工作在你运行它的 Airflow 版本上若在 Airflow 源码目录之外且从某目录安装了 Breeze则 Breeze 作用于其安装来源的源码。用breeze setup version查看 Breeze 安装自何处、当前作用于哪些源码。处理 Python 版本问题若 Breeze 提示需要比当前环境更新的 Python推荐uvx方案调用前导出UV_PYTHON指定版本例如UV_PYTHON3.10 breeze ...也可永久写入 shell rcuvx 会在下次调用时用该解释器重建缓存环境。传统全局安装用uv或pipx强制重装uv tool install --force -e ./dev/breeze # 或 pipx install --force -e ./dev/breeze指定 Python 版本创建虚拟环境推荐方案下UV_PYTHON3.10.16 breeze ...即为缓存环境选择 Python 版本全局安装默认使用系统 Python可用--python固定uv tool install --python 3.10.16 ./dev/breeze --force # 或 pipx install -e ./dev/breeze --python /Users/airflow/.pyenv/versions/3.10.16/bin/python --forceWindows 用户同样将./dev/breeze替换为dev\breeze。首次运行与自动补全首次运行 Breeze 时会拉取并在本地构建 Docker 镜像它从 GitHub Container Registry 拉取最新的 Airflow CI 镜像再据此构建本地镜像。注意每个 Python 版本的首次运行在高速网络下最多可能需要 10 分钟后续运行会快得多。进入环境后你会落在 Airflow 容器的 bash shell 中可以立即运行测试。安装后建议立即配置命令补全。breeze内置 bash/zsh/fish 自动补全设置命令配置后输入命令时按TAB可查看所有可用开关并能自动补全常用参数值breeze setup autocomplete重新进入 shell 后补全生效按脚本打印的提示操作。若已配置过命令会提示并不重复安装需要强制重装可执行breeze setup autocomplete --forceBreeze setup 命令族配置与维护breeze setup提供了一组用于配置默认值、维护 Breeze 自身行为以及为宿主机配置补全的工具。从 setup_commands_config.py 中的SETUP_COMMANDS可以看到setup子命令包括autocomplete、self-upgrade、cleanup、config、check-all-params-in-groups、regenerate-command-images、synchronize-local-mounts、command-hash-export、version。setup autocomplete配置 shell 自动补全唯一标志为--force强制重装。setup self-upgrade自动自我升级 Breeze重装其全部最新依赖。通常自动进行但安装损坏时可强制升级。可用标志为--use-current-airflow-sources。setup version显示 Breeze 版本加--verbose可输出更多信息Breeze 安装来源、setup 哈希细节等。setup config配置并检查 Breeze 命令的设置Python 版本、后端Backend类型及后端版本。从源码可见其标志包括标志作用--python选择默认 Python 版本--backend选择使用的后端如 PostgreSQL / MySQL / SQLite 等--postgres-version/--mysql-version指定对应数据库后端版本--terminal-multiplexer配置终端复用器--auth-manager配置认证管理器--llm-model配置 LLM 模型用于支持 AI 辅助类功能--cheatsheet启用/禁用 cheatsheet新手提示面板--asciiart启用/禁用启动 ASCII 艺术字--colour启用/禁用彩色消息输出其中 cheatsheet 与 asciiart 属于锦上添花的展示内容cheatsheet 对首次使用者有价值若觉得重复繁琐可以关闭。--no-colour关闭颜色编码消息改用斜体/粗体/下划线等字体方案区分信息、错误、警告与成功消息这对色弱友好。自动化安装在 POSIX 兼容系统Linux、macOS上运行 scripts/tools/setup_breeze 即可自动化安装检查/安装uv、检测到旧版全局 breeze 安装时拒绝继续、然后把 shim 脚本见 ADR 0017写入~/.local/bin/breeze。卸载 Breeze推荐shim方案直接删除 shim 脚本rm ~/.local/bin/breeze如需同时删除缓存环境uv cache clean apache-airflow-breeze传统全局安装使用对应工具卸载同时会从${HOME}/.local/bin/移除 breezeuv tool uninstall apache-airflow-breeze # 或 pipx uninstall apache-airflow-breeze需要特别留意的是setup_breeze会通过uv tool list、uv tool dir及pipx list --short检测残留的全局安装包括环境损坏、已从uv tool list输出中消失的安装检测到后会明确提示先执行上述卸载命令再重跑脚本——因为 shim 与全局安装都写入~/.local/bin/breeze静默覆盖会破坏 uv 的 tool 状态并造成后续升级混乱。下一步安装完成只是开始。接下来可以阅读 自定义 Breeze 环境 指南来配置 Python 版本、后端数据库与挂载选项完整的命令清单与setup子命令的 SVG 参数图位于 dev/breeze/doc/images 目录若需了解 Breeze 的整体定位与优势可阅读 Airflow Breeze 环境总览或查阅dev/breeze/adr目录下的架构决策记录Architecture Decision Records理解各设计取舍。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考