Apache Airflow 3.0.0 子路径部署任务调度异常问题解析

问题背景

在使用 Docker Compose 部署 Apache Airflow 3.0.0 时，当配置 AIRFLOW__API__BASE_URL 参数设置子路径访问（如 http://mycompany.com/airflow）后，虽然 Web UI 可以正常访问，但触发 DAG 任务时会陷入"queued"状态，最终抛出"ServerResponseError: Not Found"错误。这个现象表明系统在子路径环境下存在 API 通信异常。

技术原理分析

Airflow 的分布式架构中，Web Server 和 Worker 节点需要通过 API 进行通信。当设置子路径时，需要特别注意以下两个关键配置参数：

1. AIRFLOW__API__BASE_URL：控制 Web 界面的基础访问路径
2. AIRFLOW__CORE__EXECUTION_API_SERVER_URL：控制任务执行时 Worker 与 Web Server 的通信路径

这两个参数需要保持同步配置，因为 Airflow 的执行 API 和核心 API 可能部署在不同的服务端点。

解决方案

针对该问题，推荐采用以下配置方案：

environment:
  - AIRFLOW__API__BASE_URL=http://mycompany.com/airflow
  - AIRFLOW__CORE__EXECUTION_API_SERVER_URL=http://mycompany.com/airflow

深入排查建议

如果配置后仍存在问题，建议进行以下排查步骤：

1. 检查 Worker 日志中是否仍存在 404 错误
2. 验证网络连通性，确保 Worker 可以访问配置的执行 API 地址
3. 检查反向代理配置（如 Nginx/Apache）是否正确转发子路径请求
4. 确认 Celery 执行器配置是否正确

版本兼容性说明

该问题在 Airflow 3.0.0 版本中确认存在，后续版本可能已包含相关修复。建议用户关注官方更新，特别是 3.0.1 版本中的相关修复补丁。

最佳实践建议

对于生产环境部署，建议：

1. 保持 Web Server 和 Worker 的配置一致性
2. 使用完整的 URL 路径（包含协议和域名）
3. 在变更配置后重启所有相关服务
4. 考虑使用环境变量管理工具统一管理配置

通过以上措施，可以确保 Airflow 在子路径部署环境下的稳定运行。