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/airflow

Breeze 是 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和defaultcontext；Colima 等轻量引擎会创建colimacontext。Breeze 会自动挑选合适的 context，但退出 Docker Desktop 后遗留的desktop-linuxcontext 在 Colima 运行时仍可能"胜出"。此时可以显式指定 Docker socket：

export DOCKER_HOST=unix://$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.0（2022 年 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 2（Windows 开发）

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_caches=3 # 不再使用 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 "uv>=0.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_CHECK=1 \ 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_VERSION="2"），Breeze 启动时会读取该标记并与当前源码中setup_breeze会安装的版本比较，若 shim 过旧则提示重新运行脚本，相关逻辑见 path_utils.py 中的warn_if_shim_outdated()。

shim 的 worktree 解析顺序

从 ADR 0017 与 shim 实际代码可以确认，Breeze 源码的解析顺序为：

1. 当前 git worktree（git rev-parse --show-toplevel），实现每 worktree 隔离；
2. 若当前目录不是 Airflow worktree，则回退到环境变量$AIRFLOW_REPO_ROOT指向的 Airflow worktree（发布文档会导出该变量，保证整个发布流程解析一致）；
3. 若仍不满足，则回退到安装 shim 时所在的 worktree（setup_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/breeze

Windows 用户注意：./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_PYTHON=3.10 breeze ...（也可永久写入 shell rc），uvx 会在下次调用时用该解释器重建缓存环境。
• 传统全局安装：用uv或pipx强制重装：

uv tool install --force -e ./dev/breeze # 或 pipx install --force -e ./dev/breeze

• 指定 Python 版本创建虚拟环境：推荐方案下UV_PYTHON=3.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 --force

（Windows 用户同样将./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 --force

Breeze 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）类型及后端版本。从源码可见其标志包括：

其中 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/移除 breeze）：

uv 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