本页面介绍了如何将环境升级到新的 Airflow 版本。
升级操作简介
在 Managed Airflow（第 3 代）中，您无需管理环境的 Managed Airflow 版本：
- Managed Airflow 会自动升级环境的基础架构组件。这些组件与 Managed Airflow 功能相关，不会改变 Airflow 的工作方式或 Airflow DAG 的执行方式。
- Managed Airflow 不会自动升级 Airflow 版本和 build、Airflow 组件或与 Airflow 工作负载密切相关的组件。当基础架构组件自动升级时，它们不会发生变化。
- 您可以手动升级到新的 Airflow 版本或 build。
例如，您可以连续几个月使用同一版本和 build 的 Airflow，而无需执行任何升级，并且您的环境仍会收到最新的 Managed Airflow 更新、修复和环境基础架构组件的改进。当您稍后决定改用新版本或新 build 的 Airflow 时，您可以在环境中升级 Airflow 版本。
关于 Airflow 版本升级
您的环境通过以下方式更改 Airflow 的版本或 build：
您可以控制环境的 Airflow 版本（和 build）。当您选择将环境切换到其他 Airflow 版本时，可以执行 Airflow 版本升级操作。例如，如果当前版本和 build 的 Airflow 不再受支持，则可能会发生这种情况。
Managed Airflow 会使用指定的 Airflow 版本和 build 重新部署环境的 Airflow 组件。
如果您的环境在升级前进行了 Airflow 配置更改（例如自定义 PyPI 软件包或 Airflow 配置选项替换），Managed Airflow 会应用这些更改。
Managed Airflow 会更新 Airflow
airflow_db连接，使其指向新的 Cloud SQL 数据库。
更改 Airflow 版本不会改变您连接到环境中的资源（例如环境存储桶的网址或 Airflow Web 服务器）的方式。
关于自动基础架构升级操作
Managed Airflow 会定期运行自动基础架构升级操作：
自动基础架构升级操作会在为环境指定的维护窗口期间定期运行。
在 Managed Airflow（第 3 代）中，无法停用自动基础架构升级。您可以通过为环境指定自定义维护窗口来控制可以运行自动升级的时间段。
此操作在 Cloud de Confiance 控制台和环境日志中可见，就像任何其他长时间运行的操作一样。操作运行时，您无法在环境级层启动其他操作（但您仍然可以运行 Airflow DAG）。
在某些情况下，自动基础架构升级可以重启 Airflow 组件。在这些重启期间，Airflow 工作器会正常终止，宽限期为 24 小时。如果您的任务需要超过 24 小时才能完成，请考虑使用可延期运算符。升级可能会导致环境的基础设施组件（例如环境监控）在短时间内不可用。
升级和回滚操作的限制
升级操作具有以下限制：
Managed Airflow 版本会在几天内逐步发布到 Managed Airflow 支持的所有区域。您所在的区域可能还无法使用正在发布的最新版本。
在 Managed Airflow（第 3 代）中，您可以将升级回滚到更早的 Airflow 版本或 build，但存在以下限制：
- 对于从 Airflow 3 版本或从 Airflow 2 版本（从 airflow-2.7.3-build.0 build 开始）进行的升级，支持回滚。
- 支持回滚升级到目标版本 airflow-2.11.1-build.20 或更高版本、airflow-3.2.2-build.7 或更高版本以及 airflow-3.3.1-build.3 或更高版本。
- 您可以在升级后的 30 天内启动回滚操作。如果目标 Airflow build 已过支持终止日期，您仍然可以回滚到该 build。您可以执行跳过版本的版本回滚。如果您在 30 天内升级了多次，则可以回滚到之前使用的任何版本，只要该版本满足资格限制条件即可。
- 开始回滚时，环境处于
RUNNING状态。
如果 Airflow 数据库包含超过 20 GB 的数据，则无法升级环境。在升级期间，如果 Airflow 数据库大小超过 20 GB，系统会显示警告。在这种情况下，请执行数据库维护以减小数据库大小。
如果您使用 XCom 机制传输文件，请确保按照 Airflow 的准则使用该机制。使用 XCom 传输大文件或大量文件会影响 Airflow 数据库的性能，并可能导致在加载快照或升级环境时失败。建议使用 Cloud Storage 等替代方案来传输大量数据。
准备工作
检查您的环境是否为最新版本
当环境的 Airflow build 接近停止提供支持日期时，Managed Airflow 会显示警告。 您可以使用这些警告来始终保持环境受支持。
Managed Airflow 会跟踪环境所基于的 Airflow 版本和 build。当接近支持结束日期时，您可以在环境列表和环境详情页面上看到警告。
如需检查您的环境是否为最新版本，请执行以下操作：
控制台
在 Cloud de Confiance 控制台中，前往环境页面。
在环境列表中，点击您的环境名称。环境详情页面会打开。
转到环境配置标签页。
映像版本字段中会显示以下消息之一：
最新可用版本。环境映像受到完全支持。
有新版本。环境映像受到完全支持，您可以将其升级到更高版本。
对此映像版本的支持将于…结束 环境映像接近完全支持终止日期。
从…起，此版本将不再受支持环境已超出完全支持期限。
gcloud
此功能无法通过 Google Cloud CLI 使用。您可以改为查看建议的升级，其中会显示可用的新版本。
API
此功能无法通过 API 使用。您可以改为查看建议的升级，其中会显示可用的新版本。
查看建议的升级
Managed Airflow 提供了一个 Airflow build 列表，您可以将环境升级到这些 build。
如需查看建议升级到的 Managed Airflow 版本，请执行以下操作：
控制台
在 Cloud de Confiance 控制台中，前往环境页面。
在环境列表中，点击您的环境名称。环境详情页面会打开。
前往环境配置标签页，然后点击升级映像版本。
如需查看建议的版本列表，请点击 Managed Airflow 映像版本下拉菜单。
gcloud
gcloud composer environments list-upgrades \
ENVIRONMENT_NAME \
--location LOCATION
替换：
ENVIRONMENT_NAME替换为环境的名称。LOCATION替换为环境所在的区域。
示例：
gcloud composer environments list-upgrades example-environment \
--location us-central1
API
您可以查看某个位置的可用版本。为此，请构建 imageVersions.list API 请求。
例如：
// GET https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/imageVersions
检查 PyPI 软件包冲突
您可以检查环境中安装的 PyPI 软件包是否与新 Airflow 版本或 build 中预安装的软件包存在任何冲突。
检查成功意味着当前版本与指定版本之间的 PyPI 软件包依赖项没有冲突。但是，由于其他原因，升级操作可能仍不成功。
控制台
如需为您的环境运行升级检查，请执行以下操作：
在 Cloud de Confiance 控制台中，前往环境页面。
在环境列表中，点击您的环境名称。环境详情页面会打开。
转到环境配置标签页，找到印象版本条目后，点击升级。
在环境版本升级对话框的新版本下拉列表中，选择要升级到的 Airflow 版本或 build。
在 PyPI 软件包兼容性 (PyPI packages compatibility) 部分，点击检查是否存在冲突 (Check for conflicts)。
等待检查完成。如果存在 PyPI 软件包依赖项冲突，则显示的错误消息包含有关冲突软件版包和软件包版本的详细信息。
gcloud
如需对环境运行升级检查，请运行 environments check-upgrade 命令，并指定要升级到的 Airflow 版本或 build。
gcloud composer environments check-upgrade \
ENVIRONMENT_NAME \
--location LOCATION \
--airflow-version VERSION
将
ENVIRONMENT_NAME替换为环境的名称。LOCATION替换为环境所在的区域。- 将
VERSION替换为您要升级到的新 Airflow 版本和 build，格式为airflow-x.y.z-build.t。 您可以使用所有版本别名。
示例：
gcloud composer environments check-upgrade example-environment \
--location us-central1 \
--airflow-version airflow-2.11.1-build.21
输出示例：
Waiting for [projects/example-project/locations/us-central1/environments/
example-environment] to be checked for PyPI package conflicts when upgrading
to composer-3-airflow-2.11.1-build.21. Operation [projects/example-project/locations/
us-central1/operations/04d0e8b2-...]...done.
...
Response:
'@type': type.googleapis.com/
google.cloud.orchestration.airflow.service.v1.CheckUpgradeResponse
buildLogUri: ...
containsPypiModulesConflict: CONFLICT
pypiConflictBuildLogExtract: |-
The Cloud Build image build failed: Build failed; check build logs for
details. Full log can be found at ...
Error details: tensorboard 2.2.2 has requirement
setuptools>=41.0.0, but you have setuptools 40.3.0.
或者，您也可以异步运行升级检查。使用 --async 参数进行异步调用，然后使用 gcloud composer operations describe 命令检查结果。
API
构建 environments.checkUpgrade API 请求。
在 imageVersion 字段中指定映像版本：
{
"imageVersion": "VERSION"
}
将 VERSION 替换为您要升级到的新版本，格式为 composer-3-airflow-x.y.z-build.t。
检查与 Managed Airflow（第 3 代）是否存在冲突
Managed Airflow（第 3 代）是 Managed Airflow 的最新主要版本。您可以通过升级检查来检查 Managed Airflow（第 2 代）环境是否可以升级到 Managed Airflow（第 3 代）。以下说明适用于 Managed Airflow（第 2 代）环境。
虽然无法将环境从 Managed Airflow（第 2 代）就地迁移到 Managed Airflow（第 3 代），但您可以使用升级检查来检查兼容性问题。我们建议您在迁移到 Managed Airflow（第 3 代）之前执行此操作。
如需检查与 Managed Airflow（第 3 代）的兼容性，请对 Managed Airflow（第 2 代）环境进行常规升级检查，并将 Managed Airflow（第 3 代）版本指定为目标。
报告的每个冲突都可能具有以下类型：
BLOCKING冲突报告了 Managed Airflow (Gen 3) 不支持的不兼容环境配置元素。我们建议您在开始迁移到 Managed Airflow（第 3 代）之前解决这些冲突。NON_BLOCKING冲突会报告在 Managed Airflow（第 3 代）中不同且可能导致意外行为的环境配置元素。例如，默认值（如默认维护窗口）的更改会报告为非阻塞冲突。我们建议您在开始迁移流程之前，先检查这些冲突是否会导致问题。此检查还会报告 PyPI 软件包冲突。它们与配置冲突分开报告，方式与常规 PyPI 软件包兼容性检查相同。
控制台
如需检查与 Managed Airflow（第 3 代）的兼容性，请使用 gcloud CLI 或 Cloud Composer API。Cloud de Confiance 控制台仅支持检查 PyPI 软件包兼容性。
gcloud
如需检查与 Managed Airflow（第 3 代）的兼容性，请运行 environments check-upgrade 命令，并将 Managed Airflow（第 3 代）版本指定为目标。
gcloud composer environments check-upgrade \
ENVIRONMENT_NAME \
--location LOCATION \
--image-version COMPOSER_3_VERSION
将
ENVIRONMENT_NAME替换为环境的名称。LOCATION替换为环境所在的区域。- 将
COMPOSER_3_VERSION替换为您要升级到的 Airflow 版本和 build，格式为airflow-x.y.z-build.t。您可以使用所有版本别名。
示例：
gcloud composer environments check-upgrade example-environment \
--location us-central1 \
--image-version composer-3-airflow-2
冲突消息示例：
...
- message: Error validating property [core]unit_test_mode. Overriding [core]
unit_test_mode is not permitted.
type: BLOCKING
- message: Environment variables [GOOGLE_CLOUD_PROJECT] may not be overridden.
type: BLOCKING
- message: You have to specify Worker CPUs to be 0.5, 1.0 or multiples of 2.0.
type: BLOCKING
- message: The environment uses a default maintenance window, which is
different in Composer 2 and Composer 3. Unless set to a custom value, the
maintenance window will be changed to a new default after the upgrade.
type: NON_BLOCKING
...
或者，您也可以异步运行此检查。使用 --async 参数进行异步调用，然后使用 gcloud composer operations describe 命令检查结果。
API
构建 environments.checkUpgrade API 请求。
在 imageVersion 字段中指定映像版本：
{
"imageVersion": "COMPOSER_3_VERSION"
}
将 COMPOSER_3_VERSION 替换为您要升级到的 Airflow 版本和 build，格式为 airflow-x.y.z-build.t。您可以使用所有版本别名。
升级环境
如需将环境升级到新版本或新 build 的 Airflow，请执行以下操作：
控制台
在 Cloud de Confiance 控制台中，前往环境页面。
在环境列表中，点击您的环境名称。环境详情页面会打开。
转到环境配置标签页。
找到映像版本项，然后点击升级。
从映像版本下拉菜单中，选择要升级到的 Airflow 版本或 build。
点击升级。
gcloud
gcloud composer environments update \
ENVIRONMENT_NAME \
--location LOCATION \
--airflow-version VERSION
替换：
ENVIRONMENT_NAME替换为环境的名称。LOCATION替换为环境所在的区域。- 将
VERSION替换为您要升级到的新 Airflow 版本和 build，格式为airflow-x.y.z-build.t。 您还可以使用所有版本别名。
例如：
gcloud composer environments update \
example-environment \
--location us-central1 \
--airflow-version airflow-2.11.1-build.21
API
构建
environments.patchAPI 请求。在此请求中：
在参数
updateMask中，指定config.softwareConfig.imageVersion掩码。在请求正文的
imageVersion字段中，指定要升级到的新版本。
例如：
// PATCH https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment?updateMask=
// config.softwareConfig.imageVersion
{
"config": {
"softwareConfig": {
"imageVersion": "composer-3-airflow-2.11.1-build.21"
}
}
}
Terraform
config.software_config 块中的 image_version 字段控制环境的 Airflow 版本和 build。在此字段中，指定新的 Airflow 版本和 build。
resource "google_composer_environment" "example" {
provider = google-beta
name = "ENVIRONMENT_NAME"
region = "LOCATION"
config {
software_config {
image_version = "VERSION"
}
}
}
将
ENVIRONMENT_NAME替换为环境的名称。LOCATION替换为环境所在的区域。- 将
VERSION替换为您要升级到的新 Airflow 版本和 build，格式为airflow-x.y.z-build.t。 您还可以使用所有版本别名。
示例：
resource "google_composer_environment" "example" {
provider = google-beta
name = "example-environment"
region = "us-central1"
config {
software_config {
image_version = "airflow-2.11.1-build.21"
}
}
}
回滚升级
如果您遇到性能下降、Airflow bug 或 DAG、插件或依赖项的兼容性问题，可以回滚环境升级。
如果环境处于 RUNNING 状态，您可以在升级操作后的 30 天内回滚升级。您可以回滚到已达到支持终止日期的版本。如需了解详情，请参阅升级和回滚操作的限制。
除了回滚单次升级之外，您还可以：
在回滚期间，只有环境的 Airflow build 会还原为指定版本。Managed Airflow 会在回滚期间保留环境的数据和状态：
DAG 文件和执行历史记录：所有 DAG 定义、DAG 运行历史记录、任务实例状态和 XCom 在元数据数据库中保持不变。
环境配置：Airflow 配置替换、环境变量、自定义 PyPI 软件包和伸缩设置会保留。 如果您对自定义 PyPI 软件包使用非严格的 PyPI 软件包版本要求，则回滚后您的环境可能具有不同的软件包版本（此版本仍将满足指定的版本要求）。
如果您在升级期间更改了环境配置，例如修改了环境变量或调整了 Airflow 组件的资源限制，这些更改不会被还原。如果需要，您可以在回滚之前或之后手动还原更改。
日志和监控：存储在 Cloud Logging 中的任务执行日志和 Cloud Monitoring 中的指标历史记录会保留。
Airflow 数据库架构更新（Alembic 迁移）会自动回滚，以匹配目标 Airflow 版本架构。如需查看每个 Airflow 版本中存在的数据库迁移列表，请参阅 Airflow 文档中的 Airflow 数据库迁移。在回滚操作期间，当前 Airflow 版本和目标 Airflow 版本之间列出的所有迁移都会回滚。
查找之前使用的版本
如需查找之前使用的版本，请执行以下操作：
gcloud
您可以在操作中找到有关之前使用的映像版本的信息：
gcloud composer operations list \
--locations LOCATION \
--filter='metadata.resource ~ "environments/ENVIRONMENT_NAME$" (metadata.operationType=UPDATE OR metadata.operationType=CREATE)'
将
ENVIRONMENT_NAME替换为环境的名称。LOCATION替换为环境所在的区域。
输出包含环境操作日志。UPDATE 类型的最后一个操作将是您要回滚的升级。找到它前面的 UPDATE（如果只有一次升级，则为 CREATE）操作。通常，这是列表中的倒数第二项。
在以下示例中，71c3d5c9-5b26-4a98-8b19-7f62e9f4ed51 操作是要回滚的升级，63da3be2-3acf-4fb4-986a-90552a6df8b3 操作是升级到之前使用的版本。
┌──────────────────────────────────────┬───────────────┬─────────────┬──────────────────────────────┬───────────┬─────────────────────────────┐
│ UUID │ TYPE │ LOCATION │ TARGET_ENVIRONMENT │ STATE │ CREATE_TIME │
├──────────────────────────────────────┼───────────────┼─────────────┼──────────────────────────────┼───────────┼─────────────────────────────┤
│ 71c3d5c9-5b26-4a98-8b19-7f62e9f4ed51 │ UPDATE │ us-central1 │ example-environment │ SUCCEEDED │ 2026-10-15T11:18:32.084039Z │
│ 63da3be2-3acf-4fb4-986a-90552a6df8b3 │ UPDATE │ us-central1 │ example-environment │ SUCCEEDED │ 2026-08-15T10:56:10.628514Z │
│ 4ebc18a9-25bb-4325-b4c9-0957c67c078b │ UPDATE │ us-central1 │ example-environment │ SUCCEEDED │ 2026-06-09T11:30:50.922080Z │
│ 8618f807-abb4-4fc8-9f5b-9353079f6e79 │ UPDATE │ us-central1 │ example-environment │ SUCCEEDED │ 2026-05-31T06:57:27.816925Z │
│ 22022864-0fa5-4d1b-92c6-c3f382b43a35 │ UPDATE │ us-central1 │ example-environment │ SUCCEEDED │ 2025-11-17T11:52:36.923698Z │
│ ec5bf071-e6c6-4760-b3c9-4a117cb08f7b │ CREATE │ us-central1 │ example-environment │ SUCCEEDED │ 2025-11-17T11:17:58.133979Z │
└──────────────────────────────────────┴───────────────┴─────────────┴──────────────────────────────┴───────────┴─────────────────────────────┘
描述操作：
gcloud composer operations describe OPERATION_UUID \
--location LOCATION \
--format="value(response.config.softwareConfig.imageVersion)"
将
- 将
OPERATION_UUID替换为通过上一条命令获取的上一次升级操作的 UUID。 LOCATION替换为环境所在的区域。
此命令的输出是之前使用的版本。
运行回滚操作
如需将环境回滚到之前的 Airflow build 或版本，请执行以下操作：
控制台
Cloud de Confiance 控制台不支持回滚升级。请改用 gcloud CLI、API 或 Terraform。
gcloud
gcloud composer environments update \
ENVIRONMENT_NAME \
--location LOCATION \
--airflow-version VERSION
替换：
ENVIRONMENT_NAME替换为环境的名称。LOCATION替换为环境所在的区域。VERSION替换为您要回滚到的新 Airflow 版本和 build，格式为airflow-x.y.z-build.t。无法将版本别名用于回滚操作。
示例：
gcloud composer environments update \
example-environment \
--location us-central1 \
--airflow-version airflow-2.11.1-build.21
API
构建
environments.patchAPI 请求。在此请求中：
在参数
updateMask中，指定config.softwareConfig.imageVersion掩码。在请求正文的
imageVersion字段中，指定要回滚到的版本。
例如：
// PATCH https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment?updateMask=
// config.softwareConfig.imageVersion
{
"config": {
"softwareConfig": {
"imageVersion": "composer-3-airflow-2.11.1-build.21"
}
}
}
Terraform
config.software_config 块中的 image_version 字段控制环境的 Airflow 版本和 build。在此字段中，指定要回滚到的 Airflow 版本和 build。
resource "google_composer_environment" "example" {
provider = google-beta
name = "ENVIRONMENT_NAME"
region = "LOCATION"
config {
software_config {
image_version = "VERSION"
}
}
}
将
ENVIRONMENT_NAME替换为环境的名称。LOCATION替换为环境所在的区域。- 将
VERSION替换为您要回滚到的 Airflow 版本和 build，格式为airflow-x.y.z-build.t。无法将版本别名用于回滚操作。
示例：
resource "google_composer_environment" "example" {
provider = google-beta
name = "example-environment"
region = "us-central1"
config {
software_config {
image_version = "airflow-2.11.1-build.21"
}
}
}
如果回滚操作在执行期间失败，Managed Airflow 会自动尝试将环境恢复到操作前的状态，即回滚开始前使用的 Airflow 版本和 build。查看 Cloud Logging 中的操作出错提示和日志，了解问题排查详情。