Apache Airflow Breeze 的 mprocs 快速参考：在单终端窗口内编排全部 Airflow 组件

Apache Airflow Breeze 的 mprocs 快速参考在单终端窗口内编排全部 Airflow 组件【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow本文以contributing-docs/mprocs/MPROCS_QUICK_REFERENCE.md为骨架结合 Breeze 源码与配置文件系统讲解如何在 Apache Airflow 开发环境中用 mprocs 终端多路复用器一键启动、调试和监控 Scheduler、API Server、Triggerer 等全部核心组件涵盖动态配置生成原理、键盘快捷键、环境变量、调试端口映射与独立运行方式。Apache Airflow 的 Breeze 开发环境默认使用 mprocs 在单个终端窗口中同时运行多个进程让开发者无需手动打开多个终端标签页即可集中观察 Scheduler、API Server、Triggerer 等组件的日志输出。本文将基于当前仓库中的 Breeze 实现从breeze start-airflow的基本用法出发深入 mprocs 的动态配置生成原理、快捷键操作、调试端口映射与独立部署场景帮助你高效使用这套多进程开发编排方案。mprocs 在 Breeze 中的基本用法一键启动breeze start-airflowBreeze 默认使用 mprocs 作为终端多路复用器启动命令非常简单breeze start-airflow该命令会进入 Breeze 容器环境并在 mprocs 会话中启动所有 Airflow 组件见 start_airflow 命令定义。如果你更习惯 tmux也可以显式指定breeze start-airflow --terminal-multiplexer tmux一旦你选择了终端多路复用器Breeze 会记住该选择后续运行breeze start-airflow时会沿用上次的选择无需每次重复指定。切换终端多路复用器breeze setup config除了在启动命令中临时指定你还可以通过配置命令持久化切换默认终端多路复用器breeze setup config --terminal-multiplexer mprocs breeze setup config --terminal-multiplexer tmux该命令对应 Breeze 的 setup 配置流程见 setup_commands.py配置结果会保存在 Breeze 环境变量中供后续会话使用。记住选择背后的实现机制从源码看Breeze 允许的终端多路复用器被定义为常量ALLOWED_TERMINAL_MULTIPLEXERS [mprocs, tmux]定义位置在 global_constants.py。在 shell_params.py 中terminal_multiplexer参数默认取第一个允许值即mprocs在生成容器环境变量时该参数被写入TERMINAL_MULTIPLEXER环境变量见 shell_params.py容器内的启动脚本据此决定使用哪个多路复用器。这解释了选择会被记住的行为选择被持久化为环境变量配置。动态生成 mprocs 配置的原理当 Breeze 使用 mprocs 启动 Airflow 组件时配置不是写死的而是根据当前选择的执行器Executor和选项动态生成。生成的配置文件存放在容器内的files文件夹中因此你也可以在 Breeze 之外复用这份配置。配置生成脚本generate_mprocs_config.py生成逻辑的核心是 generate_mprocs_config.py该脚本根据一系列环境变量构建procs字典最后输出 YAML。其关键流程如下Scheduler默认命令为airflow scheduler若设置了BREEZE_DEBUG_SCHEDULER则切换为debugpy --listen 0.0.0.0:port --wait-for-client -m airflow scheduler。API Server / Web Server 二选一根据USE_AIRFLOW_VERSION判断若不以2.开头则生成 Airflow 3.x 的api_server且默认使用--host 双栈绑定避免 macOS/OrbStack 下localhost解析到 IPv6 时出现浏览器无法访问的问题否则生成 2.x 的webserver。Triggerer默认airflow triggerer支持BREEZE_DEBUG_TRIGGERER调试开关。Celery Worker 与 Flower仅在INTEGRATION_CELERYtrue时生成celery_workerFlower 还需CELERY_FLOWERtrue。Edge Worker当AIRFLOW__CORE__EXECUTOR为airflow.providers.edge3.executors.edge_executor.EdgeExecutor时生成并在非调试模式下先清理数据库/Celery 相关环境变量、重设日志目录再启动airflow edge worker --edge-hostname breeze --queues default。Dag Processor仅当STANDALONE_DAG_PROCESSORtrue时生成默认命令airflow dag-processor。shell始终追加一个bash进程方便在环境中手动执行命令。每个进程统一配置restart: always与scrollback: 100000即进程异常退出后自动重启并保留 10 万行回滚日志。启动入口run_mprocs容器内的启动脚本 run_mprocs 会先调用上述 Python 脚本将配置写入/files/mprocs.yaml再执行exec mprocs --config /files/mprocs.yaml --proc-list-title Apache Airflow也就是说最终呈现的Apache Airflow标题栏、进程列表与日志分区全部来自这份动态生成的 YAML 配置。常用使用模式以下表格总结了 mprocs 在 Breeze 中的常见用法完整命令列表见 MPROCS_QUICK_REFERENCE.md命令说明breeze start-airflow --terminal-multiplexer mprocs使用 mprocs 启动 Airflow并记住选择breeze start-airflow --terminal-multiplexer tmux使用 tmux 启动 Airflow并记住选择breeze start-airflow --debug scheduler使用上次选择的多路复用器调试 schedulerbreeze start-airflow --dev-mode --terminal-multiplexer mprocs在开发模式下使用 mprocs并记住选择其中--dev-mode会启用开发模式从 generate_mprocs_config.py 可以看到DEV_MODEtrue时 API Server 会以airflow api-server --host -d启动-d为 debug/开发参数Web Server 则以airflow webserver -d启动方便热重载开发。mprocs 键盘快捷键速查启动后你可以在 mprocs 界面中使用以下快捷键管理进程按键动作↑↓在进程之间切换r重启选中的进程x停止选中的进程s启动选中的进程a添加新进程q退出 mprocs?显示帮助重要提示停止 Breeze 环境时请按q退出整个 mprocs而不是只停止当前选中的进程。退出 mprocs 后breeze start-airflow容器才会正常退出并释放其转发端口。回到宿主机 shell 后再运行breeze down完成环境清理。mprocs 管理的组件清单Breeze 通过 mprocs 统一管理的组件包括具体生成条件可对照上文动态配置一节scheduler—— Airflow 调度器api_serverAirflow 3.x/webserverAirflow 2.x—— Web 界面服务triggerer—— 处理 deferred延迟任务dag_processor—— 独立 Dag Processor启用时celery_worker—— Celery Worker使用 CeleryExecutor 时flower—— Celery 监控界面启用时edge_worker—— Edge Worker使用 EdgeExecutor 时从源码可以确认Celery 相关组件仅在INTEGRATION_CELERYtrue时生成Flower 还要求CELERY_FLOWERtrueEdge Worker 则由AIRFLOW__CORE__EXECUTOR指向 EdgeExecutor 触发与文档中的使用 CeleryExecutor / EdgeExecutor 时描述完全一致。控制组件启停的环境变量下表汇总了影响 mprocs 生成配置的关键环境变量变量作用TERMINAL_MULTIPLEXER设置为mprocs时使用 mprocsINTEGRATION_CELERY启用 Celery 组件worker 等CELERY_FLOWER启用 Flower UISTANDALONE_DAG_PROCESSOR启用独立 Dag ProcessorBREEZE_DEBUG_*启用对应组件的调试模式DEV_MODE启用开发模式USE_AIRFLOW_VERSION决定生成 api_server3.x还是 webserver2.xAIRFLOW__CORE__EXECUTOR指向 EdgeExecutor 时生成 edge_worker其中BREEZE_DEBUG_*系列在 generate_mprocs_config.py 中分别对应BREEZE_DEBUG_SCHEDULER、BREEZE_DEBUG_APISERVER、BREEZE_DEBUG_WEBSERVER、BREEZE_DEBUG_TRIGGERER、BREEZE_DEBUG_CELERY_WORKER、BREEZE_DEBUG_FLOWER、BREEZE_DEBUG_EDGE、BREEZE_DEBUG_DAG_PROCESSOR每个都支持独立的*_PORT覆盖默认调试端口。调试端口映射当对应组件启用调试模式BREEZE_DEBUG_*时各组件使用以下调试端口组件端口Scheduler50231Dag Processor50232Triggerer50233API Server50234Celery Worker50235Edge Worker50236Web Server50237需要注意的是上述端口表对应 Breeze 对外暴露的调试端口而 generate_mprocs_config.py 中 debugpy 监听的默认端口5678–5685是容器内进程使用的端口两者经由 Breeze 的端口映射衔接。调试模式的核心逻辑是将组件的启动命令包装为debugpy --listen 0.0.0.0:port --wait-for-client -m airflow component从而支持远程附加调试器。安装 mprocsmprocs 已预装在 Breeze 的 CI 镜像中Airflow 3.x 开发版本无需额外安装。对于较旧的镜像或自定义环境可以手动安装# 下载并安装 mprocs MPROCS_VERSION0.7.3 SYSTEM$(uname -s | tr [:upper:] [:lower:]) PLATFORM$([ $(uname -m) aarch64 ] echo arm64 || echo amd64) curl -L https://github.com/pvolok/mprocs/releases/download/v${MPROCS_VERSION}/mprocs-${MPROCS_VERSION}-${SYSTEM}-${PLATFORM}.tar.gz \ | tar -xz -C /usr/local/bin/ mprocs chmod x /usr/local/bin/mprocs该脚本会根据系统架构自动选择arm64或amd64平台包解压出mprocs二进制并安装到/usr/local/bin。macOS 与 iTerm2 的鼠标支持配置macOS 开发者常用的 iTerm2 终端默认无法正确捕获鼠标点击事件而 mprocs 的鼠标复制、点击切换等交互功能依赖终端开启鼠标上报Mouse Reporting。需要在 iTerm2 中开启Enable Mouse reporting选项才能正常使用复制与鼠标操作功能。设置入口位于 iTerm2 的 Preferences → Profiles → Terminal 区域。脱离 Breeze 的独立运行如果你需要在 Breeze 之外自行编排 Airflow 组件可以创建mprocs.yaml配置文件然后启动 mprocsmprocs -f mprocs.yaml仓库的 mprocs.yaml 提供了覆盖所有主要 Airflow 组件的静态示例配置包含 scheduler、api_server、triggerer、dag_processor 以及一个交互式bashshell每个进程均设置了restart: always与scrollback: 100000procs: scheduler: shell: airflow scheduler restart: always scrollback: 100000 api_server: shell: airflow api-server restart: always scrollback: 100000 triggerer: shell: airflow triggerer restart: always scrollback: 100000 dag_processor: shell: airflow dag-processor restart: always scrollback: 100000 shell: shell: bash restart: always scrollback: 100000示例中还注释了 Celery Worker 与 Flower 的可选配置块需要时取消注释即可# # Optional: Uncomment to enable Celery worker (requires CeleryExecutor) # celery_worker: # shell: airflow celery worker # restart: always # scrollback: 100000 # # Optional: Uncomment to enable Flower (requires Celery) # flower: # shell: airflow celery flower # restart: always # scrollback: 100000你可以把该文件复制到其他位置后按需修改调整进程定义、取消注释或新增进程。不过要注意这份静态配置不会根据执行器和选项自动增删组件——如果需要动态适配环境例如根据 Executor 决定是否启用 Celery/Edge Worker应使用容器内脚本 generate_mprocs_config.py 生成动态配置这也是 Breeze 实际采用的方式。小结mprocs 在 Airflow Breeze 中承担了单窗口多进程编排器的角色breeze start-airflow默认即使用 mprocs配合--terminal-multiplexer、--dev-mode、--debug等参数可覆盖日常开发、调试与生产组件验证场景其配置由 generate_mprocs_config.py 根据环境变量动态生成存放于容器/files目录既保证了组件集合随执行器/选项变化也允许脱离 Breeze 独立复用。掌握本文的快捷键、环境变量与端口映射即可在单个终端窗口内高效驾驭 Airflow 的全套运行组件。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考