Web 栈

配置

有时您希望在可变的 URL 路径前缀后部署后端和前端。为此，您可以配置 URL base_url，例如将其设置为 https://:28080/d12345。所有 API 路由现在都可以通过额外的 d12345 前缀访问。无需重新构建前端，XHR 请求和静态文件查询应指向带前缀的 URL 并成功提供。

您还需要更新执行 API 服务器的 URL execution_api_server_url，以便任务能够使用新前缀访问 API。

分离 API 服务器

默认情况下，核心 API 服务器和执行 API 服务器一起提供服务

airflow api-server
# same as
airflow api-server --apps all
# or
airflow api-server --apps core,execution

如果您想将核心 API 服务器和执行 API 服务器分离，可以将它们单独运行。这在需要独立扩展它们或在不同机器上部署时会很有用。

# serve only the Core API Server
airflow api-server --apps core
# serve only the Execution API Server
airflow api-server --apps execution

已知问题

与 `PYTHONASYNCIODEBUG` 和 `PYTHONDEVMODE` 不兼容

警告

当环境变量 PYTHONASYNCIODEBUG=1 被设置，或在 Python 3.12 及以上版本下运行 PYTHONDEVMODE 时，API 服务器可能因段错误而崩溃。这是因为 uvloop（Uvicorn 用于提升性能的库）与 Python 的 asyncio 调试模式不兼容。

如果您需要调试 API 服务器中的 asyncio 问题，请考虑

在应用层面进行调试，而不是依赖 PYTHONASYNCIODEBUG 或 PYTHONDEVMODE
搭建一个未安装 uvloop 的开发环境

此限制已在 issue #61214 中记录。

服务器类型

API 服务器支持两种服务器类型：uvicorn（默认）和 gunicorn。

Uvicorn（默认）

Uvicorn 是默认的服务器类型。它设置简单，且可在包括 Windows 在内的所有平台上运行。

airflow api-server

Gunicorn

Gunicorn 为生产部署提供了额外功能

内存共享：工作进程在 fork 后通过写时复制共享内存，降低总体内存占用
滚动工作进程重启：零停机时间的工作进程循环，以防止内存累积
正确的信号处理：SIGTTOU 会杀掉最旧的工作进程（FIFO），实现真正的滚动重启

注意

Gunicorn 需要额外安装 gunicorn：pip install 'apache-airflow-core[gunicorn]'

Gunicorn 仅在 Unix 上可用，无法在 Windows 上运行。

启用 gunicorn 模式

export AIRFLOW__API__SERVER_TYPE=gunicorn
airflow api-server

滚动工作进程重启

启用周期性工作进程循环（对长期运行的进程有助于防止内存累积）

export AIRFLOW__API__SERVER_TYPE=gunicorn
export AIRFLOW__API__WORKER_REFRESH_INTERVAL=43200  # Restart workers every 12 hours
export AIRFLOW__API__WORKER_REFRESH_BATCH_SIZE=1   # Restart one worker at a time
airflow api-server

滚动重启过程

在杀死旧进程之前生成新进程（零停机）
等待新进程准备就绪（检查进程标题）
执行 HTTP 健康检查，以验证工作进程能够处理请求
杀死旧进程（最旧的优先）
重复上述步骤，直到所有原始工作进程全部被替换

配置选项

以下配置选项可在 [api] 部分使用

server_type：uvicorn（默认）或 gunicorn
worker_refresh_interval：工作进程刷新周期之间的秒数（0 = 禁用，默认）
worker_refresh_batch_size：每个周期刷新的工作进程数量（默认：1）
reload_on_plugin_change：插件文件变更时重新加载（默认：False）

何时使用 Gunicorn

在以下情况下使用 gunicorn：

长期运行的 API 服务器进程，内存累积是关注点时
需要内存共享的多工作进程部署
生产环境中需要零停机时间的工作进程循环

在以下情况下使用默认的 uvicorn：

运行在 Windows 上
在开发或测试环境中运行
运行短暂的容器（例如会被回收的 Kubernetes Pod）

在 Kubernetes 上运行 Uvicorn

当在 Kubernetes 上使用 server_type = uvicorn 运行 API 服务器时，服务器在每个 Pod 中以单一长期进程形式运行，且不支持类似 gunicorn 那样的滚动工作进程重启。

在长期运行的 Kubernetes 部署中，这可能导致内存逐渐增长或内部状态随时间变得陈旧。因此，使用 uvicorn 时建议定期重启 API 服务器 Pod。

推荐的做法包括：

Kubernetes 滚动重启 API Server Deployment，以在不中断服务的情况下回收 Pod。
Helm based restarts，例如在 Helm 升级期间触发 rollout，或通过修改重启注解实现。
集群级别机制（例如计划性重启），在长期运行 uvicorn 时使用。

例如，触发 API Server Pod 的滚动重启可以这样做：

kubectl rollout restart deployment airflow-api-server

在许多 Kubernetes 环境中，仅依赖 Kubernetes OOM kill 或崩溃重启并不推荐，因为内存增长未必会触发 OOM 事件。对于需要在不重启 Pod 的情况下自动回收工作进程的生产部署，请考虑改用 server_type = gunicorn。