通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用就地迁移功能将应用服务环境 v1 和 v2 迁移到应用服务环境 v3

  • 项目

注意

本文中所述的迁移功能用于将应用服务环境 v1 和 v2 自动就地（同一子网）迁移到应用服务环境 v3。 如果要查找并行迁移功能的相关信息，请参阅使用并行迁移功能迁移到应用服务环境 v3。 如果要查找有关手动迁移选项的信息，请参阅手动迁移选项。 如果在确定适合你的迁移选项时需要帮助，请参阅迁移路径决策树。 若要详细了解应用服务环境 v3，请参阅应用服务环境 v3 概述。

你可以使用就地迁移功能自动将应用服务环境 v1 和 v2 迁移到应用服务环境 v3。 若要详细了解迁移过程，以及你的应用服务环境目前是否支持迁移，请参阅就地迁移功能概述。

重要

建议在迁移任何生产环境之前先将此功能用于开发环境，以避免意外问题。 请使用页面底部的按钮提供与本文或所介绍功能相关的任何反馈。

先决条件

请确保了解迁移到应用服务环境 v3 对应用程序的影响。 查看迁移过程，了解流程时间线以及需要参与的时间和位置。 另请查看常见问题解答，其中可以回答一些问题。

请确保虚拟网络、资源组、资源或订阅中没有锁定。 在迁移期间，锁会阻止平台操作。

请确保没有 Azure 策略会阻止迁移所需的操作，包括子网修改和 Azure 应用服务资源创建。 阻止资源修改和创建的策略可能会导致迁移停滞或失败。

由于迁移期间阻止了缩放，因此在开始迁移之前，应将环境缩放为所需的大小。 如果需要在迁移后缩放环境，可以在迁移完成后执行此操作。

建议使用 Azure 门户来进行就地迁移体验。 如果决定使用 Azure CLI 进行迁移，请按照本文中的顺序和所写内容执行所述步骤，因为要进行 Azure REST API 调用。 建议使用 Azure CLI 进行这些 API 调用。 有关其他方法的信息，请参阅 Azure REST API 参考。

对于本指南，请安装 Azure CLI，或使用 Azure Cloud Shell 并使用 Bash shell。

注意

我们建议使用 Bash shell 运行本指南中给出的命令。 这些命令可能与 PowerShell 约定和转义字符不兼容。

1. 获取应用服务环境 ID

请运行以下命令，以获取应用服务环境 ID，并将其存储为环境变量。 将名称和资源组的占位符替换为要迁移的应用服务环境的值。 如果虚拟网络和应用服务环境位于同一资源组中，则 ASE_RG 和 VNET_RG 相同。

ASE_NAME=<Your-App-Service-Environment-name>
ASE_RG=<Your-ASE-Resource-Group>
VNET_RG=<Your-VNet-Resource-Group>
ASE_ID=$(az appservice ase show --name $ASE_NAME --resource-group $ASE_RG --query id --output tsv)

2.验证是否支持迁移

以下命令会检查应用服务环境是否支持迁移。 如果收到错误，或者应用服务环境处于不正常或挂起状态，则此时无法迁移。 有关可能会收到的潜在错误消息的说明，请参阅故障排除部分。 如果你的环境不支持使用就地迁移功能进行迁移，或者要在不使用就地迁移功能的情况下迁移到应用服务环境 v3，请参阅手动迁移选项。 此命令还会验证应用服务环境是否在受支持的生成版本中进行迁移。 如果 Azure 应用服务环境不在受支持的生成版本上，则需要自行启动升级，这可能需要 8-12 小时或更长时间，具体取决于环境的大小。 有关迁移前升级的详细信息，请参阅验证是否支持使用就地迁移功能对应用服务环境进行迁移。

az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=validation"

如果没有错误，则表示支持迁移，可以继续执行下一步。

如果需要开始升级来将应用服务环境升级到受支持的生成版本，请运行以下命令。 仅当验证步骤失败，并且系统要求你升级应用服务环境时，才运行此命令。

az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=PreMigrationUpgrade"

3.为新的应用服务环境 v3 资源生成 IP 地址

请运行以下命令，以创建新的 IP 地址。 完成此步骤大约需要 15 分钟。 在此期间，请不要缩放或更改现有应用服务环境。

az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=premigration"

请运行以下命令，以检查此步骤的状态：

az rest --method get --uri "${ASE_ID}?api-version=2021-02-01" --query properties.status

如果该步骤正在进行，则会获得 Migrating 状态。 获取 Ready 状态后，请运行以下命令以查看新 IP。 如果未立即看到新 IP，请等待几分钟，然后重试。

az rest --method get --uri "${ASE_ID}/configurations/networking?api-version=2021-02-01"

注意

由于已知 bug，对于 ELB 应用服务环境迁移，在迁移步骤完成后，入站 IP 地址可能会再次更改。 请准备好在迁移步骤完成后使用新的入站 IP 地址再次更新依赖资源。 正在解决此 bug，并会尽快修复。 如果对此问题有任何疑问或担忧，或者需要有关迁移过程的帮助，请开启支持案例。

4. 使用新 IP 更新依赖资源

通过使用新的 IP，更新所有资源或网络组件，确保迁移完成后新环境按预期运行。 你应负责进行所有必要更新。

在迁移到应用服务环境 v3 时，此步骤也是查看入站和出站网络依赖项更改的好时机。 这些更改包括 Azure 负载均衡器的端口更改（现在使用端口 80）。 完成此步骤之前，请勿迁移。

5. 委托应用服务环境子网

应用服务环境 v3 要求其所在子网具有 Microsoft.Web/hostingEnvironments 的单一委托。 以前的版本不需要此委托。 在迁移之前，需要确认子网已正确委派并更新委派（如有必要）。 你可以通过运行以下命令或在 Azure 门户中导航到该子网来更新委托。

az network vnet subnet update --resource-group $VNET_RG --name <subnet-name> --vnet-name <vnet-name> --delegations Microsoft.Web/hostingEnvironments

6. 确认虚拟网络中没有锁

在迁移期间，虚拟网络锁会阻止平台操作。 如果虚拟网络具有锁，则需要在迁移之前将其删除。 如有必要，可以在迁移完成后添加回锁定。

锁定可以存在于三个范围：订阅、资源组和资源。 在父范围应用锁时，该范围内所有资源都会继承相同的锁。 如果在订阅、资源组或资源范围内应用了锁定，则需要在迁移之前将其移除。 有关锁和锁继承的详细信息，请参阅锁定资源以保护基础结构。

请使用以下命令检查虚拟网络是否具有任何锁定：

az lock list --resource-group $VNET_RG --resource <vnet-name> --resource-type Microsoft.Network/virtualNetworks

请使用以下命令删除任何现有的锁定：

az lock delete --resource-group $VNET_RG --name <lock-name> --resource <vnet-name> --resource-type Microsoft.Network/virtualNetworks

有关用于检查订阅或资源组是否具有锁定的相关命令，请参阅 Azure CLI 锁定参考。

7. 准备好配置

如果现有环境位于支持区域冗余的区域，可以将新的应用服务环境 v3 资源设置为区域冗余。 你可以通过将 zoneRedundant 属性设置为 true 来配置区域冗余。

区域冗余是可选的配置。 只能在创建新的应用服务环境 v3 资源期间进行设置， 过后无法将其移除。 有关详细信息，请参阅选择应用服务环境 v3 配置。 如果不想配置区域冗余，请勿包含 zoneRedundant 参数。

如果现有的应用服务环境使用自定义域后缀，需要在迁移过程中为新的应用服务环境 v3 资源配置一个自定义域后缀。 如果未配置但当前要使用自定义域后缀，迁移会失败。 如果在迁移到未配置自定义域后缀的环境中尝试添加自定义域后缀，迁移也会失败。 有关应用服务环境 v3 自定义域后缀的详细信息（包括要求、分步说明和最佳做法），请参阅应用服务环境的自定义域后缀。

注意

如果要配置自定义域后缀，在向 Azure 密钥保管库添加网络权限时，请确保密钥保管库允许从应用服务环境的新出站 IP 地址（在步骤 3 中生成）进行访问。 如果使用专用终结点访问密钥保管库，请确保已正确配置专用访问。

如果迁移不包含自定义域后缀且未启用区域冗余，则可以继续迁移。

若要设置这些配置，请根据你自己的情况创建一个名为“parameters.json”的文件，其中包含以下详细信息。 如果自定义域后缀不适用于你的迁移，请不要包含自定义域后缀的属性。 请注意 zoneRedundant 属性的值，因为迁移后此配置不可逆。 根据现有的应用服务环境版本设置 kind 属性的值。 kind 属性的接受值是 ASEV1 和 ASEV2。

如果要在没有自定义域后缀的情况下迁移，并且要启用区域冗余，请使用以下代码：

{
    "type": "Microsoft.Web/hostingEnvironments",
    "name": "sample-ase-migration",
    "kind": "ASEV2",
    "location": "westcentralus",
    "properties": {
        "zoneRedundant": true
    }
}

如果为自定义域后缀配置使用用户分配的托管标识，并且要启用区域冗余，请使用以下代码：

{
    "type": "Microsoft.Web/hostingEnvironments",
    "name": "sample-ase-migration",
    "kind": "ASEV2",
    "location": "westcentralus",
    "properties": {
        "zoneRedundant": true,
        "customDnsSuffixConfiguration": {
            "dnsSuffix": "internal.contoso.com",
            "certificateUrl": "https://contoso.vault.azure.net/secrets/myCertificate",
            "keyVaultReferenceIdentity": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/asev3-migration/providers/Microsoft.ManagedIdentity/userAssignedIdentities/ase-managed-identity"
        }
    }
}

如果为自定义域后缀配置使用系统分配的托管标识，并且不启用区域冗余，请使用以下代码：

{
    "type": "Microsoft.Web/hostingEnvironments",
    "name": "sample-ase-migration",
    "kind": "ASEV2",
    "location": "westcentralus",
    "properties": {
        "customDnsSuffixConfiguration": {
            "dnsSuffix": "internal.contoso.com",
            "certificateUrl": "https://contoso.vault.azure.net/secrets/myCertificate",
            "keyVaultReferenceIdentity": "SystemAssigned"
        }
    }
}

8.迁移到应用服务环境 v3 并检查状态

完成上述所有步骤后，即可开始迁移。 请确保了解迁移的影响。

对于从 v2 到 v3 的迁移，此步骤需要三到六个小时，对于从 v1 到 v3 的迁移，则最多需要六个小时，具体取决于环境大小。 在此期间，应用程序大约停机一小时。 在此步骤中，会阻止对现有应用服务环境进行缩放、部署和修改。

如果要启用区域冗余和/或配置自定义域后缀，请在以下命令中包含 body 参数。 如果这些配置都不适用于你的迁移，可以从命令中移除该参数。

az rest --method post --uri "${ASE_ID}/migrate?api-version=2021-02-01&phase=fullmigration" --body @parameters.json

运行以下命令，检查迁移的详细状态。 有关状态的信息，请参阅迁移状态说明。

第一个命令获取迁移的操作 ID。 请复制 ID 属性的值。

az rest --method get --uri "${ASE_ID}/operations?api-version=2022-03-01"

将以下命令中操作 ID 的占位符替换为复制的值。 此命令返回迁移的详细状态。 可根据需要运行此命令以获取最新状态。

az rest --method get --uri "${ASE_ID}/operations/<operation-id>/details/default?api-version=2022-09-01"

获得 Ready 状态后，迁移就完成了，你就有了一个应用程序服务环境 v3 资源。 应用现在在新环境中运行。

运行以下命令或转到 Azure 门户即可获取新环境的详细信息。

az appservice ase show --name $ASE_NAME --resource-group $ASE_RG

注意

由于已知 bug，对于 ELB 应用服务环境迁移，在迁移步骤完成后，入站 IP 地址可能会更改。 检查应用服务环境 v3 的 IP 地址，并在 IP 生成步骤发生更改后进行任何所需的更新。 如果对此问题有任何疑问或担忧，或者需要有关确认新 IP 的帮助，请开启支持案例。

1.验证是否支持迁移

在 Azure 门户中，转到要迁移的应用服务环境的“迁移”页面。 你可以通过选择应用服务环境的“概述”页面顶部的横幅，或选择左侧菜单上的“迁移”项，来转到“迁移”页面。

屏幕截图：迁移接入点。

在“迁移”页面中，平台会验证应用服务环境是否支持迁移。 选择“验证”，然后确认要继续验证。 验证过程需要几秒钟的时间。

屏幕截图：用于验证迁移资格的按钮。

如果环境不支持迁移，页面顶部会显示横幅，并包含一条指出原因的错误消息。 有关不符合迁移条件的错误消息的说明，请参阅故障排除。

如果应用服务环境目前不支持迁移，或者环境处于不正常或挂起状态，无法使用迁移功能。 如果你的环境不支持使用就地迁移功能进行迁移，或者要在不使用就地迁移功能的情况下迁移到应用服务环境 v3，请参阅手动迁移选项。

屏幕截图：内容为“迁移功能不支持应用服务环境”的示例门户消息。

如果需要启动升级以将应用服务环境升级到受支持的生成版本上，系统会提示启动升级，这可能需要 8-12 小时或更长时间，具体取决于环境的大小。 选择“升级”以启动升级。 升级完成后，你会通过验证，并且可以使用迁移功能启动迁移。

如果应用服务环境支持迁移，请继续执行该过程的下一步。 “迁移”页面会指导执行一系列步骤以完成迁移。

屏幕截图：一个示例迁移页，其中包含过程中未完成的步骤。

2.为新的应用服务环境 v3 资源生成 IP 地址

在“获取新的 IP 地址”下，确认你了解含义并选择“开始”按钮。 完成此步骤大约需要 15 分钟。 在此期间，无法缩放或更改现有应用服务环境。

3. 使用新 IP 更新依赖资源

上一步完成后，将显示新应用服务环境 v3 资源的 IP 地址。 请使用这些新 IP 更新任何资源和网络组件，以便新环境在迁移完成后按预期运行。 你应负责进行所有必要更新。

在迁移到应用服务环境 v3 时，此步骤也是查看入站和出站网络依赖项更改的好时机。 这些更改包括 Azure 负载均衡器的端口更改（现在使用端口 80）。 在确认已进行这些更新之后，再继续下一步。

显示预迁移期间生成的示例 IP 的屏幕截图。

4. 委托应用服务环境子网

应用服务环境 v3 要求其所在子网具有单一委派 Microsoft.Web/hostingEnvironments。 以前的版本不需要此委托。 在迁移之前，需要确认子网已正确委派并更新委派（如有必要）。 门户将显示子网链接，以便你可以根据需要进行确认和更新。

屏幕截图：门户中的子网委派。

5. 确认实例大小更改

应用服务计划会从“独立”转换为相应的“独立 v2 层”。 例如，I2 会转换为 I2v2。 应用可能会在迁移后出现过度预配，因为“独立 v2 层”的每个相应实例大小具有更多的内存和 CPU。 迁移完成后，你有机会根据需要缩放环境。 有关详细信息，请查看定价详细信息。

屏幕截图：迁移时确认实例大小更改。

6.确认虚拟网络没有锁定

在迁移期间，虚拟网络锁会阻止平台操作。 如果虚拟网络具有锁，则需要在迁移之前将其删除。 如有必要，可以在迁移完成后添加回锁定。

锁定可以存在于三个范围：订阅、资源组和资源。 在父范围应用锁时，该范围内所有资源都会继承相同的锁。 如果在订阅、资源组或资源范围内应用了锁定，则需要在迁移之前将其移除。 有关锁和锁继承的详细信息，请参阅锁定资源以保护基础结构。

有关如何检查订阅或资源组是否具有锁的详细信息，请参阅配置锁。

显示在何处查找和删除虚拟网络锁的屏幕截图。

7. 选择配置

如果现有环境位于支持区域冗余的区域，可以将新的应用服务环境 v3 资源设置为区域冗余。 区域冗余是可选的配置。 只能在创建新的应用服务环境 v3 资源期间进行设置， 过后无法将其移除。 有关详细信息，请参阅选择应用服务环境 v3 配置。

如果要配置区域冗余，请选中“已启用”复选框。

屏幕截图：用于在受支持的区域中为应用服务环境启用区域冗余的复选框。

如果环境位于不支持区域冗余的区域，则该复选框不可用。 如果需要区域冗余的应用服务环境 v3 资源，请使用手动迁移选项之一，并在支持区域冗余的区域之一中创建资源。

如果现有的应用服务环境使用自定义域后缀，则必须为新的应用服务环境 v3 资源配置一个自定义域后缀。 如果你是这种情况，系统会显示自定义域后缀的配置选项。 在提供所需信息之前，无法进行迁移。

如果要使用自定义域后缀，但当前未配置任何此类后缀，可以在迁移完成后配置一个。 有关应用服务环境 v3 自定义域后缀的详细信息（包括要求、分步说明和最佳做法），请参阅应用服务环境的自定义域后缀。

注意

如果要配置自定义域后缀，在向 Azure 密钥保管库添加网络权限时，请确保密钥保管库允许从应用服务环境的新出站 IP 地址（在步骤 2 中生成）进行访问。 如果使用专用终结点访问密钥保管库，请确保已正确配置专用访问。

屏幕截图：用于添加自定义域后缀的链接。

添加自定义域后缀的详细信息后，“迁移”按钮将可用。

屏幕截图：已添加配置详细信息，并且环境已做好迁移准备。

8. 迁移到应用服务环境 v3

完成上述所有步骤后，即可开始迁移。 请确保了解迁移的含义，包括在此期间会发生的情况。

对于从 v2 到 v3 的迁移，此步骤需要三到六个小时，对于从 v1 到 v3 的迁移，则最多需要六个小时，具体取决于环境大小。 在此步骤过程中，会阻止对现有应用服务环境进行缩放和修改。

注意

在极少数情况下，开始迁移后，你可能会在门户中看到一条通知，显示“迁移到应用服务环境 v3 失败”。 存在已知 bug，即使迁移正在进行，也可能会触发此通知。 检查应用服务环境的活动日志以确定此错误消息的有效性。 在大多数情况下，刷新页面可以解决问题，错误消息会消失。 如果错误消息仍然存在，请联系支持人员获取帮助。

屏幕截图：迁移启动后可能会出现的错误通知。

目前，只有在使用 Azure CLI 时，才会显示详细的迁移状态。 有关详细信息，请参阅有关迁移到应用服务环境 v3 的 Azure CLI 部分。 即使使用门户进行迁移，也可以使用 CLI 检查迁移的状态。

迁移完成后，你便会拥有应用服务环境 v3 资源，并且所有应用都将在新的环境中运行。 可以通过查看应用服务环境的“配置”页来确认环境的版本。

注意

由于已知 bug，对于 ELB 应用服务环境迁移，在迁移步骤完成后，入站 IP 地址可能会更改。 检查应用服务环境 v3 的 IP 地址，并在 IP 生成步骤发生更改后进行任何所需的更新。 如果对此问题有任何疑问或担忧，或者需要有关确认新 IP 的帮助，请开启支持案例。

如果迁移包含自定义域后缀，相应域会显示在应用服务环境 v1/v2 门户“概述”页面的“基本信息”部分中，但在应用服务环境 v3 中不再显示在此处。 对于应用服务环境 v3，请转到“自定义域后缀”页面，确认已正确配置自定义域后缀。 如果不再需要该配置，也可以将其删除，或者如果以前没有该配置，可以配置一个。

屏幕截图：应用服务环境 v3 的自定义域后缀配置页面。

注意

如果迁移包含自定义域后缀，则迁移完成后，自定义域后缀配置可能会因已知 bug 显示为已降级。 应用服务环境仍应按预期工作。 已降级状态应在 6-8 小时内自行解决。 如果配置在 8 小时后降级，或者自定义域后缀不起作用，请联系支持人员。

已降级自定义域后缀配置示例的屏幕截图。

后续步骤

使用应用服务环境 v3 资源

应用服务环境 V3 网络

自定义域后缀