使用 GitHub Codespaces 搭建 Apache Airflow 开发环境从 Fork 到 Breeze 的完整指南【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowApache Airflow 的贡献者环境依赖 Docker、Python 工具链与多组件协同本地搭建成本较高。本指南基于仓库中的 contributors_quick_start_codespaces.rst 官方文档讲解如何用 GitHub Codespaces 在云端浏览器中获得开箱即用的 VS Code 开发界面从 Fork 仓库、创建 Codespace到进入 Breeze 环境运行测试与排障帮你在一台没有本地 Docker 的机器上完成 Airflow 的开发与贡献。为什么选择 Codespaces 开发 AirflowAirflow 是一个由调度器Scheduler、Web 服务器Webserver、执行器Executor等组件构成的工作流平台其贡献者环境Breeze依赖 Docker 容器来统一版本与依赖。GitHub Codespaces 提供的云容器天然具备零本地依赖不需要在本地安装 Docker Desktop、Python 或 uv所有工具链都预置在云端容器中浏览器即开发环境Codespaces 以 VS Code Web 界面呈现操作方式与本地 VS Code 完全一致与仓库 devcontainer 配置无缝衔接仓库根目录下的 .devcontainer/devcontainer.json 定义了 Codespaces 启动时的容器编排基于scripts/ci/docker-compose/devcontainer.yml使 Codespaces 一启动就处于可开发状态。仓库还提供了 SQLite 与 PostgreSQL 两种 devcontainer 变体.devcontainer/postgres/devcontainer.json默认的 .devcontainer/devcontainer.json 使用 SQLite 后端适合快速起步。第一步Fork 与创建 Codespace1. Fork Apache Airflow 仓库进入 Apache Airflow 的 GitHub 仓库页面点击右上角Fork按钮将项目复制到你的 GitHub 账号下。这一步是提交 Pull Request 的前提——你无法直接向 Apache 官方仓库推送代码。2. 从你的 Fork 创建 Codespace创建 Codespace 有两种常用入口一键按钮点击仓库 README 或官方文档提供的 Open in GitHub Codespaces 徽章https://github.com/codespaces/new?hide_repo_selecttruerefmainrepo33884891直接以main分支为基准创建手动创建在 Fork 仓库页面点击Code → Codespaces → New codespace。创建过程会读取仓库根目录的 .devcontainer/devcontainer.json 并拉取 CI 镜像ghcr.io/apache/airflow/main/ci/python3.10定义于 scripts/ci/docker-compose/devcontainer.yml因此首次启动需要等待镜像拉取与容器初始化通常需要几分钟。3. 容器启动后你得到什么Codespace 启动后终端默认已经处于Breeze 环境环境变量文件 scripts/ci/docker-compose/devcontainer.env 中BREEZEtrue、DEV_MODEtrue你可以在 VS Code 界面中直接编辑代码并运行测试无需再手动安装任何基础工具。devcontainer 配置还做了几件关键事情将仓库挂载到容器内/opt/airflowworkspaceFolder与 Codespaces 主机的/workspaces/airflow保持同步通过docker-outside-of-dockerfeature 把 Docker socket 传入容器使容器内可以运行 DockerBreeze 依赖此能力构建/启动 Airflow 镜像预装 VS Code 扩展包括ms-python.python、ms-python.vscode-pylance、ms-azuretools.vscode-docker、mtxr.sqltools等转发端口8080Web UI、5555Flower、5432PostgreSQL、6379Redis自动继承你本地的git configuser.email / user.name保证提交记录署名正确。第二步在 Codespaces 中初始化环境Codespaces 的基础容器已经包含 Breeze 所需的大部分工具但若要完整运行测试与代码质量检查建议按官方 03a_contributors_quick_start_beginners.rst 的 Codespaces 路径补齐工具链# 安装 Docker Buildx 插件Breeze 构建镜像需要 mkdir -p ~/.docker/cli-plugins BUILDX_VERSIONv0.16.2 curl -SL https://github.com/docker/buildx/releases/download/${BUILDX_VERSION}/buildx-${BUILDX_VERSION}.linux-amd64 -o ~/.docker/cli-plugins/docker-buildx chmod x ~/.docker/cli-plugins/docker-buildx docker buildx version # 安装 Docker Compose v2 插件Breeze 编排多容器需要 curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s | tr [:upper:] [:lower:])-$(uname -m) -o ~/.docker/cli-plugins/docker-compose chmod x ~/.docker/cli-plugins/docker-compose docker compose version接着安装 Python 包管理器 uv、代码质量检查工具 prek 以及 Breezecurl -LsSf https://astral.sh/uv/install.sh | sh uv tool install prek prek install -f prek install -f --hook-type pre-push # 推送时自动运行 mypy 等检查 ./scripts/tools/setup_breeze # 安装 Breeze shim uv run dev/ide_setup/setup_vscode.py # 将 src/ 与 tests/ 配置为 VS Code 源码根说明uv是 Airflow 社区推荐的高性能 Python 包管理器prek负责在提交前运行格式化、Lint 与静态检查减少 CI 返工setup_vscode.pydev/ide_setup/setup_vscode.py会将项目的src/与各tests/目录注册为源码根目录解决 Airflow 3 中 Provider 作为独立发行版拆分后的导入解析问题详见下文 VS Code 小节。第三步启动 Airflow 与日常开发启动 Breeze 开发环境breeze start-airflow该命令默认使用mprocs多终端管理器在一个窗口内同时启动 Scheduler、Webserver 等所有必要组件也可以指定--terminal-multiplexer tmux改用 tmux。启动完成后可以在浏览器访问http://localhost:28080打开 Airflow Web UI管理员账号密码均为admin/admin。常用变体breeze start-airflow --dev-mode # 开发模式便于调试 breeze start-airflow --load-example-dags # 加载仓库中的示例 DAG方便探索功能退出时在mprocs界面按q然后清理资源breeze down挂载 DAG 与运行测试放置自己的 DAG将 DAG 文件放入仓库中的files/dags/目录该目录会被自动挂载进 Breeze 容器调度器会立即拾取在 Web UI 中即可看到运行测试使用 Breeze 的测试命令例如breeze testing core-tests运行核心测试breeze testing --help可查看所有可用测试分组。创建分支与提交在 VS Code 状态栏点击分支符号输入分支名并 checkout完成修改后通过 Source Control 侧边栏提交并推送GitHub 会提示 Compare pull request 按钮点击即可发起 PR。第四步Codespaces 中的 Docker 故障排查在 Codespaces 中运行 Breeze 命令时最常见的报错是 Docker is not running。按以下顺序排查1. 验证 Docker 是否可用docker info如果命令失败说明 Docker 守护进程不可访问。2. 检查 Docker socket 是否存在ls -la /var/run/docker.sockdevcontainer 通过docker-outside-of-dockerfeature 将宿主机的 socket 挂载进容器见 .devcontainer/devcontainer.json此文件存在是容器内使用 Docker 的前提。3. 检查用户权限groups $USER输出列表中应包含docker组。如果不在将当前用户加入 docker 组sudo usermod -aG docker $USER加入组后需要重新登录会话或重启 Codespace 才能生效。4. 重建容器或重启 Codespace如果上述步骤均无效使用命令面板Command Palette执行Codespaces: Rebuild Container或在 GitHub Codespaces 仪表盘中重启该 Codespace。重建会基于 devcontainer 配置重新初始化环境可解决镜像缓存或容器状态异常问题。进阶用 VS Code 界面做深度开发Codespaces 的界面就是 VS Code官方文档 contributors_quick_start_vscode.rst 提供了两个与 Codespaces 高度相关的进阶技巧配置 Pylance 的 Extra PathsAirflow 3 将各个 Provider 拆分为独立的发行版各自带独立的pyproject.toml因此 Provider 的测试代码使用from unit.postgres.hooks.test_postgres import ...这类导入时需要让 Pylance 知道测试目录的位置。打开File → Preferences → Settings在Workspace层级导航到Extensions → Pylance在Python → Analysis: Extra Paths中添加你想开发的 Provider 的tests目录路径例如providers/postgres/tests然后重启 VS Code 使配置生效。若使用 pyright 作为 LSP可在pyrightconfig.json中以同样的方式配置extraPaths。调试示例 DAG将airflow/example_dags/目录下的任意示例 DAG 复制到files/dags/在 DAG 文件末尾追加__main__块使其可独立运行回填任务if __name__ __main__: dag.test()在 Run 视图创建launch.json添加AIRFLOW__CORE__EXECUTOR: LocalExecutor到env字段并将program指向示例 DAG{ configurations: [ program: ${workspaceFolder}/files/dags/example_bash_operator.py, env: { PYTHONUNBUFFERED: 1, AIRFLOW__CORE__EXECUTOR: LocalExecutor }, python: ${env:HOME}/.pyenv/versions/airflow/bin/python ] }调试运行后可在dag_run、xcom等表中查看任务执行产生的记录。下一步完整的贡献流程上述内容只覆盖了开发环境的搭建。日常开发任务如写代码、跑测试、提 PR、Review 等的完整流程请参阅 03a_contributors_quick_start_beginners.rst15 分钟首个 PR 指南与 03_contributors_quick_start.rst如果你更喜欢在本地机器上开发也可以参考 contributors_quick_start_vscode.rst 的本地配置章节或 contributors_quick_start_gitpod.rst 使用 Gitpod 方案。整个开发环境的设计与命令细节还可以在 dev/breeze 与 scripts/ci 目录中找到对应实现。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/12 9:35:17 · 阅读 1.2k 使用 GitHub Codespaces 搭建 Apache Airflow 开发环境：从 Fork 到 Breeze 的完整指南
使用 GitHub Codespaces 搭建 Apache Airflow 开发环境从 Fork 到 Breeze 的完整指南【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowApache Airflow 的贡献者环境依赖 Docker、Python 工具链与多组件协同本地搭建成本较高。本指南基于仓库中的 contributors_quick_start_codespaces.rst 官方文档讲解如何用 GitHub Codespaces 在云端浏览器中获得开箱即用的 VS Code 开发界面从 Fork 仓库、创建 Codespace到进入 Breeze 环境运行测试与排障帮你在一台没有本地 Docker 的机器上完成 Airflow 的开发与贡献。为什么选择 Codespaces 开发 AirflowAirflow 是一个由调度器Scheduler、Web 服务器Webserver、执行器Executor等组件构成的工作流平台其贡献者环境Breeze依赖 Docker 容器来统一版本与依赖。GitHub Codespaces 提供的云容器天然具备零本地依赖不需要在本地安装 Docker Desktop、Python 或 uv所有工具链都预置在云端容器中浏览器即开发环境Codespaces 以 VS Code Web 界面呈现操作方式与本地 VS Code 完全一致与仓库 devcontainer 配置无缝衔接仓库根目录下的 .devcontainer/devcontainer.json 定义了 Codespaces 启动时的容器编排基于scripts/ci/docker-compose/devcontainer.yml使 Codespaces 一启动就处于可开发状态。仓库还提供了 SQLite 与 PostgreSQL 两种 devcontainer 变体.devcontainer/postgres/devcontainer.json默认的 .devcontainer/devcontainer.json 使用 SQLite 后端适合快速起步。第一步Fork 与创建 Codespace1. Fork Apache Airflow 仓库进入 Apache Airflow 的 GitHub 仓库页面点击右上角Fork按钮将项目复制到你的 GitHub 账号下。这一步是提交 Pull Request 的前提——你无法直接向 Apache 官方仓库推送代码。2. 从你的 Fork 创建 Codespace创建 Codespace 有两种常用入口一键按钮点击仓库 README 或官方文档提供的 Open in GitHub Codespaces 徽章https://github.com/codespaces/new?hide_repo_selecttruerefmainrepo33884891直接以main分支为基准创建手动创建在 Fork 仓库页面点击Code → Codespaces → New codespace。创建过程会读取仓库根目录的 .devcontainer/devcontainer.json 并拉取 CI 镜像ghcr.io/apache/airflow/main/ci/python3.10定义于 scripts/ci/docker-compose/devcontainer.yml因此首次启动需要等待镜像拉取与容器初始化通常需要几分钟。3. 容器启动后你得到什么Codespace 启动后终端默认已经处于Breeze 环境环境变量文件 scripts/ci/docker-compose/devcontainer.env 中BREEZEtrue、DEV_MODEtrue你可以在 VS Code 界面中直接编辑代码并运行测试无需再手动安装任何基础工具。devcontainer 配置还做了几件关键事情将仓库挂载到容器内/opt/airflowworkspaceFolder与 Codespaces 主机的/workspaces/airflow保持同步通过docker-outside-of-dockerfeature 把 Docker socket 传入容器使容器内可以运行 DockerBreeze 依赖此能力构建/启动 Airflow 镜像预装 VS Code 扩展包括ms-python.python、ms-python.vscode-pylance、ms-azuretools.vscode-docker、mtxr.sqltools等转发端口8080Web UI、5555Flower、5432PostgreSQL、6379Redis自动继承你本地的git configuser.email / user.name保证提交记录署名正确。第二步在 Codespaces 中初始化环境Codespaces 的基础容器已经包含 Breeze 所需的大部分工具但若要完整运行测试与代码质量检查建议按官方 03a_contributors_quick_start_beginners.rst 的 Codespaces 路径补齐工具链# 安装 Docker Buildx 插件Breeze 构建镜像需要 mkdir -p ~/.docker/cli-plugins BUILDX_VERSIONv0.16.2 curl -SL https://github.com/docker/buildx/releases/download/${BUILDX_VERSION}/buildx-${BUILDX_VERSION}.linux-amd64 -o ~/.docker/cli-plugins/docker-buildx chmod x ~/.docker/cli-plugins/docker-buildx docker buildx version # 安装 Docker Compose v2 插件Breeze 编排多容器需要 curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s | tr [:upper:] [:lower:])-$(uname -m) -o ~/.docker/cli-plugins/docker-compose chmod x ~/.docker/cli-plugins/docker-compose docker compose version接着安装 Python 包管理器 uv、代码质量检查工具 prek 以及 Breezecurl -LsSf https://astral.sh/uv/install.sh | sh uv tool install prek prek install -f prek install -f --hook-type pre-push # 推送时自动运行 mypy 等检查 ./scripts/tools/setup_breeze # 安装 Breeze shim uv run dev/ide_setup/setup_vscode.py # 将 src/ 与 tests/ 配置为 VS Code 源码根说明uv是 Airflow 社区推荐的高性能 Python 包管理器prek负责在提交前运行格式化、Lint 与静态检查减少 CI 返工setup_vscode.pydev/ide_setup/setup_vscode.py会将项目的src/与各tests/目录注册为源码根目录解决 Airflow 3 中 Provider 作为独立发行版拆分后的导入解析问题详见下文 VS Code 小节。第三步启动 Airflow 与日常开发启动 Breeze 开发环境breeze start-airflow该命令默认使用mprocs多终端管理器在一个窗口内同时启动 Scheduler、Webserver 等所有必要组件也可以指定--terminal-multiplexer tmux改用 tmux。启动完成后可以在浏览器访问http://localhost:28080打开 Airflow Web UI管理员账号密码均为admin/admin。常用变体breeze start-airflow --dev-mode # 开发模式便于调试 breeze start-airflow --load-example-dags # 加载仓库中的示例 DAG方便探索功能退出时在mprocs界面按q然后清理资源breeze down挂载 DAG 与运行测试放置自己的 DAG将 DAG 文件放入仓库中的files/dags/目录该目录会被自动挂载进 Breeze 容器调度器会立即拾取在 Web UI 中即可看到运行测试使用 Breeze 的测试命令例如breeze testing core-tests运行核心测试breeze testing --help可查看所有可用测试分组。创建分支与提交在 VS Code 状态栏点击分支符号输入分支名并 checkout完成修改后通过 Source Control 侧边栏提交并推送GitHub 会提示 Compare pull request 按钮点击即可发起 PR。第四步Codespaces 中的 Docker 故障排查在 Codespaces 中运行 Breeze 命令时最常见的报错是 Docker is not running。按以下顺序排查1. 验证 Docker 是否可用docker info如果命令失败说明 Docker 守护进程不可访问。2. 检查 Docker socket 是否存在ls -la /var/run/docker.sockdevcontainer 通过docker-outside-of-dockerfeature 将宿主机的 socket 挂载进容器见 .devcontainer/devcontainer.json此文件存在是容器内使用 Docker 的前提。3. 检查用户权限groups $USER输出列表中应包含docker组。如果不在将当前用户加入 docker 组sudo usermod -aG docker $USER加入组后需要重新登录会话或重启 Codespace 才能生效。4. 重建容器或重启 Codespace如果上述步骤均无效使用命令面板Command Palette执行Codespaces: Rebuild Container或在 GitHub Codespaces 仪表盘中重启该 Codespace。重建会基于 devcontainer 配置重新初始化环境可解决镜像缓存或容器状态异常问题。进阶用 VS Code 界面做深度开发Codespaces 的界面就是 VS Code官方文档 contributors_quick_start_vscode.rst 提供了两个与 Codespaces 高度相关的进阶技巧配置 Pylance 的 Extra PathsAirflow 3 将各个 Provider 拆分为独立的发行版各自带独立的pyproject.toml因此 Provider 的测试代码使用from unit.postgres.hooks.test_postgres import ...这类导入时需要让 Pylance 知道测试目录的位置。打开File → Preferences → Settings在Workspace层级导航到Extensions → Pylance在Python → Analysis: Extra Paths中添加你想开发的 Provider 的tests目录路径例如providers/postgres/tests然后重启 VS Code 使配置生效。若使用 pyright 作为 LSP可在pyrightconfig.json中以同样的方式配置extraPaths。调试示例 DAG将airflow/example_dags/目录下的任意示例 DAG 复制到files/dags/在 DAG 文件末尾追加__main__块使其可独立运行回填任务if __name__ __main__: dag.test()在 Run 视图创建launch.json添加AIRFLOW__CORE__EXECUTOR: LocalExecutor到env字段并将program指向示例 DAG{ configurations: [ program: ${workspaceFolder}/files/dags/example_bash_operator.py, env: { PYTHONUNBUFFERED: 1, AIRFLOW__CORE__EXECUTOR: LocalExecutor }, python: ${env:HOME}/.pyenv/versions/airflow/bin/python ] }调试运行后可在dag_run、xcom等表中查看任务执行产生的记录。下一步完整的贡献流程上述内容只覆盖了开发环境的搭建。日常开发任务如写代码、跑测试、提 PR、Review 等的完整流程请参阅 03a_contributors_quick_start_beginners.rst15 分钟首个 PR 指南与 03_contributors_quick_start.rst如果你更喜欢在本地机器上开发也可以参考 contributors_quick_start_vscode.rst 的本地配置章节或 contributors_quick_start_gitpod.rst 使用 Gitpod 方案。整个开发环境的设计与命令细节还可以在 dev/breeze 与 scripts/ci 目录中找到对应实现。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考