镜像构建参数参考¶

以下构建参数（docker build 命令中的 --build-arg）可用于生产镜像。这些参数用于自定义镜像。您可以在从 PyPI 包构建中看到一些示例。

基本参数¶

这些是构建自定义镜像时最常用的参数。

构建参数	默认值	描述
`PYTHON_BASE_IMAGE`	`python:3.9-slim-bookworm`	基础 Python 镜像。
`AIRFLOW_VERSION`	`3.0.0`	Airflow 的版本。
`AIRFLOW_EXTRAS`	（见表格下方）	安装 Airflow 时使用的默认 extras。
`ADDITIONAL_AIRFLOW_EXTRAS`		安装 Airflow 时可选的额外 extras。
`AIRFLOW_HOME`	`/opt/airflow`	Airflow 的 HOME 目录（日志和 SQLite 数据库存储在此处）。
`AIRFLOW_USER_HOME_DIR`	`/home/airflow`	Airflow 用户的 HOME 目录。
`AIRFLOW_PIP_VERSION`	`<LATEST_AVAILABLE_IN_PYPI>`	使用的 PIP 版本。
`AIRFLOW_UV_VERSION`	`<LATEST_AVAILABLE_IN_PYPI>`	使用的 UV 版本。
`AIRFLOW_USE_UV`	`false`	是否使用 UV 构建镜像。这是一个实验性功能。
`UV_HTTP_TIMEOUT`	`300`	UV 拉取请求的超时时间（秒）。
`ADDITIONAL_PIP_INSTALL_FLAGS`		传递给安装命令的额外 `pip` 标志（重新安装 `pip` 本身时除外）
`PIP_PROGRESS_BAR`	`on`	PIP 安装的进度条
`AIRFLOW_UID`	`50000`	Airflow 用户 UID。
`AIRFLOW_CONSTRAINTS`	`constraints`	构建镜像时使用的约束类型。可以是 regular 镜像的 `constraints` 或 slim 镜像的 `constraints-no-providers`。
`AIRFLOW_CONSTRAINTS_REFERENCE`		从 GitHub 获取约束文件的引用（分支或标签）。对于 2.0.* 安装，可以是 `constraints-main` 或 `constraints-2-0`。如果构建特定版本，您需要将其指向特定的标签，例如 `constraints-3.0.0`。如果为空，则自动检测。

注意

在 Airflow 2.2 之前，镜像也有 AIRFLOW_GID 参数，但它没有提供任何额外功能，只会增加混淆，因此已被移除。

生产 Dockerfile 中的默认 extras 列表

aiobotocore
amazon
async
celery
cncf-kubernetes
common-io
common-messaging
docker
elasticsearch
fab
ftp
git
google
google-auth
graphviz
grpc
hashicorp
http
ldap
microsoft-azure
mysql
odbc
openlineage
pandas
postgres
redis
sendgrid
sftp
slack
snowflake
ssh
statsd
uv

镜像优化选项¶

构建 Airflow 镜像的定制方法的主要优点在于，它可以构建高度优化的镜像，因为最终镜像（RUNTIME）可能不包含构建和安装所有其他依赖项（DEV）所需的全部依赖项。这些参数允许控制在 DEV 镜像和 RUNTIME 镜像中安装的内容，从而生成更优化的镜像。请参阅构建优化的镜像了解使用这些参数的示例。

构建参数	默认值	描述
`UPGRADE_RANDOM_INDICATOR_STRING`		如果设置为一个随机的非空值，依赖项将被升级到新版本。在 CI 中，它被设置为构建 ID，以确保后续构建不会重用具有相同值的缓存镜像。
`ADDITIONAL_PYTHON_DEPS`		可选的 Python 包，用于为镜像扩展一些额外依赖项。
`DEV_APT_COMMAND`		在构建镜像中安装 dev 依赖项之前执行的 Dev apt 命令。
`ADDITIONAL_DEV_APT_COMMAND`		在构建镜像中安装 dev 依赖项之前执行的额外 Dev apt 命令。应以 `&&` 开头。
`DEV_APT_DEPS`	空 - 安装默认依赖项（参见 `install_os_dependencies.sh`）	在构建镜像中安装的 Dev APT 依赖项。
`ADDITIONAL_DEV_APT_DEPS`		在构建镜像中安装的额外 apt dev 依赖项。
`ADDITIONAL_DEV_APT_ENV`		安装 dev 依赖项时定义的额外环境变量。
`RUNTIME_APT_COMMAND`		在 `main` 阶段安装依赖项之前执行的 Runtime apt 命令。
`ADDITIONAL_RUNTIME_APT_COMMAND`		在 `main` 阶段安装 runtime 依赖项之前执行的额外 Runtime apt 命令。应以 `&&` 开头。
`RUNTIME_APT_DEPS`	空 - 安装默认依赖项（参见 `install_os_dependencies.sh`）	在 Main 镜像中安装的 Runtime APT 依赖项。
`ADDITIONAL_RUNTIME_APT_DEPS`		在 Main 镜像中安装的额外 apt runtime 依赖项。
`ADDITIONAL_RUNTIME_APT_ENV`		安装 runtime 依赖项时定义的额外环境变量。
`INSTALL_MYSQL_CLIENT`	`true`	是否应该安装 MySQL 客户端。如果未安装客户端，则从 extras 中移除 mysql extra。
`INSTALL_MYSQL_CLIENT_TYPE`	`mariadb`	MySQL 客户端库的类型。可以是 `mariadb` 或 `mysql`。无论参数如何，在 ARM 上始终使用 `mariadb`。
`INSTALL_MSSQL_CLIENT`	`true`	Whether MsSQL client should be installed
`INSTALL_POSTGRES_CLIENT`	`true`	Whether Postgres client should be installed

使用不同方法安装 Airflow¶

这些参数仅当您想使用不同于默认方法（从 PyPI 包安装）来安装 Airflow 时才有用。

这通常只在您有自己的 Airflow 分支并想从这些源代码构建镜像时有用——无论是在本地还是直接从 GitHub 源代码构建。这样，您无需通过 PyPI 发布您的 Airflow 和 Providers，它们可以直接从源代码或 GitHub 仓库安装。另一种安装选项是从之前准备好的二进制 Python 包构建 Airflow，这在需要在高安全性环境中构建 Airflow 时可能有用。

您可以在以下内容中看到一些示例：

构建参数	默认值	描述
`AIRFLOW_INSTALLATION_METHOD`	`apache-airflow`	Apache Airflow 的安装方法。`apache-airflow` 用于从 PyPI 安装。可以是 GitHub 仓库 URL（包含分支或标签）以从该仓库安装，或使用 `.` 从本地源安装。从源代码安装需要设置 `AIRFLOW_SOURCES_FROM` 和 `AIRFLOW_SOURCES_TO` 变量的适当值（见下文）
`AIRFLOW_SOURCES_FROM`	`Dockerfile`	Airflow 的源。当您从本地源安装 Airflow 时，将其设置为 `.`
`AIRFLOW_SOURCES_TO`	`/Dockerfile`	Airflow 源的目标路径。当您从本地源安装 Airflow 时，设置为 `/opt/airflow`。
`AIRFLOW_VERSION_SPECIFICATION`		可选 - 可用于限制 Airflow 版本安装，例如 `<2.0.2` 用于自动化构建。
`AIRFLOW_CONSTRAINTS_LOCATION`		如果不为空，它将使用指定的 URL 或文件覆盖约束文件的源。请注意，文件必须在 Docker 上下文中，因此最好将此类文件放在 `.dockerignore` 文件中包含的文件夹之一中。
`DOCKER_CONTEXT_FILES`	`Dockerfile`	如果设置为一个文件夹（例如 `docker-context-files` 文件夹），则此文件夹将被复制到 docker 上下文内的 `docker-context-files` 中，并且您将能够从其中存在的二进制文件进行安装。默认情况下，我们将其设置为 Dockerfile，因为我们知道该文件在那里，否则 COPY 指令会失败。
`INSTALL_DISTRIBUTIONS_FROM_CONTEXT`	`false`	如果设置为 true，Airflow、provider 和所有依赖项将从放置在 `docker-context-files` 中的本地构建/下载的 .whl 和 .tar.gz 文件安装。

依赖缓存¶

我们使用 --mount-type=cache 卷来加快 Airflow 镜像依赖项的安装。结合 uv 的速度和广泛的缓存使用，以及在 CI 环境中快速恢复缓存，这使得我们能够快速构建镜像——无论是用于 CI 还是本地开发目的。可以通过提供 DEPENDENCY_CACHE_EPOCH 构建参数的新值或在 Dockerfile 中修改它来轻松使缓存失效。

构建参数	默认值	描述

`DEPENDENCY_CACHE_EPOCH`	`"0"`	通过传递新参数允许使缓存失效。