将托管在 stv1 平台上的注入 VNet 的 API 管理实例迁移到 stv2

适用于：开发人员 | 高级

本文提供了当实例注入（部署）到外部或内部 VNet 中时，将托管在 stv1 计算平台上的 API 管理实例就地迁移到 stv2 平台的步骤。 确定是否需要这样做。

对于 VNet 注入实例，有以下迁移选项：

• 选项 1：保留相同的子网 - 就地迁移实例并保留实例的现有子网配置。 可以选择是否保留 API 管理实例的原始 VIP 地址（推荐）或是否生成新的 VIP 地址。

• 选项 2：更改为新子网 - 通过在相同或不同的 VNet 中指定其他子网来迁移实例。 迁移后，可以选择迁移回实例的原始子网。 迁移过程会改变实例的 VIP 地址。 迁移后，需要更新全部网络依赖项，包括 DNS、防火墙规则和 VNet，以使用新的 VIP 地址。

如果需要迁移托管在 stv1 平台上的未注入 VNnet 的 API 管理实例，请参阅将未注入 VNet 的 API 管理实例迁移到 stv2 平台。

迁移期间会发生什么情况？

将 API 管理平台从 stv1 迁移到 stv2 仅涉及到更新基础计算，并且不会影响存储层中保留的服务/API 配置。

• 升级过程包括创建与旧计算并行的新计算，这最多可能需要 45 分钟。 需要为多区域部署和涉及多次更改子网的方案规划更长的时间。
• Azure 门户中的 API 管理状态将为“正在更新”。
• 对于某些迁移选项，可以选择保留 VIP 地址或生成新的公共 VIP。
• 对于生成新 VIP 地址的迁移方案：
  • Azure 管理迁移。
  • 如果正在使用自定义域，则网关 DNS 仍指向旧计算。
  • 如果未使用自定义 DNS，则网关和门户 DNS 会立即指向新计算。
  • 对于内部 VNet 模式下的实例，客户管理 DNS，因此 DNS 条目会继续指向旧计算，直到客户更新为止。
  • 它是指向新计算或旧计算的 DNS，因此 API 不会停机。
  • 防火墙规则（如果有）需要更改才能允许新的计算子网访问后端。
  • 成功迁移后，旧计算服务会在短暂的时间后自动停用。 使用门户中的“平台迁移”边栏选项卡更改到新的子网时，可以启用将旧网关保留 48 小时的迁移设置。 48 小时延迟选项仅适用于注入 VNet 的服务。

先决条件

• API 管理实例托管在 stv1 计算平台上。 若要确认实例是否托管在 stv1 平台上，请参阅如何知道哪个平台托管了我的 API 管理实例？
• 实例当前必须部署在外部或内部 VNet 中。

其他先决条件特定于以下部分中的迁移选项。

选项 1：迁移并保留同一子网

可以将 API 管理实例迁移到保留现有子网配置的 stv2 平台，从而简化迁移。 可以使用 Azure 门户中的“平台迁移”边栏选项卡或迁移到 Stv2 REST API 进行迁移。

先决条件

• 必须将网络安全组附加到各个子网，而且必须配置 stv2 平台上用于 API 管理的 NSG 规则。 以下是最低连接设置：

  • 通过端口 443 出站到 Azure 存储
  • 通过端口 1433 出站到 Azure SQL
  • 通过端口 443 出站到 Azure Key Vault
  • 通过端口 6390 从 Azure 负载均衡器入站
  • 通过端口 3443 从 ApiManagement 服务标记入站
  • 对于调用 API 管理服务的客户端，通过端口 80/443 入站
  • 子网必须为 Azure 存储、Azure SQL 和 Azure Key Vault 启用服务终结点

• 每个现有子网的地址空间必须足够大，才能在迁移期间与现有服务并行托管现有服务的副本。

• 其他网络注意事项：

  • 关闭为子网中部署的 API 管理实例配置的任何自动缩放规则。 自动缩放规则可能会干扰迁移过程。
  • 如果同一子网中有多个 API 管理实例，请按顺序迁移每个实例。 我们建议及时迁移子网中的所有实例，以避免同一子网中托管在不同平台上的实例出现任何潜在问题。

• 在 Azure Cloud Shell 中使用 Bash 环境。 有关详细信息，请参阅 Azure Cloud Shell 中的 Bash 快速入门。

  

• 如需在本地运行 CLI 参考命令，请安装 Azure CLI。 如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。 有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。

  • 如果使用的是本地安装，请使用 az login 命令登录到 Azure CLI。 若要完成身份验证过程，请遵循终端中显示的步骤。 有关其他登录选项，请参阅使用 Azure CLI 登录。

  • 出现提示时，请在首次使用时安装 Azure CLI 扩展。 有关扩展详细信息，请参阅使用 Azure CLI 的扩展。

  • 运行 az version 以查找安装的版本和依赖库。 若要升级到最新版本，请运行 az upgrade。

公共 IP 地址选项 - 同一子网迁移

可以选择是否保留 API 管理实例的原始 VIP 地址（推荐）或是否生成新的 VIP 地址。

• 保留虚拟 IP 地址 - 对于外部模式下的 VNet，如果保留 VIP 地址，则 API 请求在迁移期间可以保持响应（请参阅预期停机时间）；对于内部模式下的 VNet，预计会出现暂时停机。 基础结构配置（如自定义域、位置和 CA 证书）将锁定 45 分钟。 迁移后无需进一步配置。

  使用此选项后，系统将在迁移完成后永久删除 stv1 计算。 没有暂时保留的选项。

  下图大致概述了保留 IP 地址时会发生什么情况。

  

• 新建虚拟 IP 地址 - 如果选择此选项，API 管理将为实例生成新的 VIP 地址。 API 请求在迁移期间将会保持响应。 基础结构配置（如自定义域、位置和 CA 证书）将锁定 30 分钟。 迁移后，需要更新任何网络依赖项（包括 DNS、防火墙规则和 VNet）才能使用新的 VIP 地址。

  使用此选项，默认情况下，系统将在迁移完成后保留 stv1 计算一小段时间，以便你验证迁移的实例并确认网络和 DNS 配置。

  下图大致概述了生成新 IP 地址时会发生什么情况。

  

用于迁移的预创建 IP 地址

对于可通过公共 IP 地址访问的 API 管理实例，API 管理会预先为迁移过程创建公共 IP 地址。 在 API 管理实例属性的 JSON 输出中找到预先创建的 IP 地址。 在 customProperties 下，预创建的 IP 地址是 Microsoft.WindowsAzure.ApiManagement.Stv2MigrationPreCreatedIps 属性的值。 对于多区域部署，该值是预先创建的 IP 地址的逗号分隔列表。

使用预先创建的 IP 地址（或多个地址）来帮助管理迁移过程：

• 迁移并保留 VIP 地址时，系统会向新的 stv2 部署临时分配预先创建的 IP 地址，然后再将原始 IP 地址分配给 stv2 部署。 例如，如果防火墙规则限制对 API 管理实例的访问，则可以将预先创建的 IP 地址添加到允许列表，以在迁移期间保留客户端访问的连续性。 迁移完成后，可以从允许列表中删除预先创建的 IP 地址。
• 迁移并生成新的 VIP 地址时，系统会在迁移过程中将预先创建的 IP 地址分配给新 stv2 部署，并在迁移完成后保留。 使用预先创建的 IP 地址更新网络依赖项，例如 DNS 和防火墙规则，以指向新的 IP 地址。

预期的停机时间和计算保留期

迁移注入 VNet 的实例并保留相同的子网配置时，预计 API 网关的停机时间最少或不会停机。 下表汇总了保留同一子网时每个迁移方案的预期停机时间和 stv1 计算保留期：

迁移步骤 - 保留相同的子网

APIM_NAME={name of your API Management instance}
# In PowerShell, use the following syntax: $APIM_NAME={name of your API Management instance}
RG_NAME={name of your resource group}
# Get resource ID of API Management instance
APIM_RESOURCE_ID=$(az apim show --name $APIM_NAME --resource-group $RG_NAME --query id --output tsv)
# Call REST API to migrate to stv2 and preserve VIP address
az rest --method post --uri "$APIM_RESOURCE_ID/migrateToStv2?api-version=2023-03-01-preview" --body '{"mode": "PreserveIp"}'
# Alternate call to migrate to stv2 and change VIP address
# az rest --method post --uri "$APIM_RESOURCE_ID/migrateToStv2?api-version=2023-03-01-preview" --body '{"mode": "NewIp"}'

选项 2：迁移并更改为新子网

使用 Azure 门户，可以通过在同一 VNet 或其他 VNet 中指定不同的子网来迁移实例。 迁移后，可以选择迁移回实例的原始子网。

下图大致概述了迁移到新子网期间发生的情况。

先决条件

• 当前虚拟网络中部署 API 管理实例的每个区域中的新子网。 （或者，在 API 管理实例所在的同一区域和订阅中的不同虚拟网络中设置子网）。 必须将网络安全组附加到各个子网，而且必须配置 stv2 平台上用于 API 管理的 NSG 规则。

• （可选）在 API 管理实例所在的同一区域和订阅中存在新的标准 SKU 公共 IPv4 地址资源。 有关详细信息，请查看网络连接的先决条件。

迁移步骤 - 更改为新子网

1. 在 Azure 门户，导航到 API 管理实例。

2. 在左侧菜单中的“设置”下，选择“平台迁移”。

3. 在“选择迁移”选项下，选择“更改为新子网”。

4. 在“选择符合要求的方案”下，选择两个选项之一，具体取决于是否要在迁移后保持原始 stv1 计算。

   

5. 在“定义每个位置的迁移设置”：

   1. 选择要迁移的位置。
   2. 选择要迁移到的“虚拟网络”、“子网”和可选的“公共 IP 地址”。

   

6. 在“验证子网是否满足迁移要求”下，选择“验证”以在子网上运行自动检查。 如果检测到问题，请调整子网配置并再次运行检查。 对于其他网络依赖项（如 DNS 和防火墙规则），请手动检查。

7. 确认要迁移，然后选择“迁移”。 API 管理实例的状态将更改为“正在更新”。 迁移过程大约需要 45 分钟才能完成。 当状态变为“联机”时，迁移完成。

如果 API 管理实例部署在多个区域中，请重复上述步骤，继续迁移实例剩余位置的 VNet 设置。

（可选）迁移回原始子网

如果已迁移并更改为新子网，可以选择迁移回你在各个区域使用的原始子网。 为此，请再次更新 VNet 配置，这次指定每个区域的原始 VNet 和子网。 与前面的迁移一样，预计操作运行时间较长，而且 VIP 地址预计会更改。

下图大致概述了迁移回原始子网期间发生的情况。

其他先决条件

• 部署 API 管理实例的每个区域中已解锁的原始子网。 必须将网络安全组附加到子网，而且必须配置 API 管理的 NSG 规则。

• （可选）在 API 管理实例所在的同一区域和订阅中存在新的标准 SKU 公共 IPv4 地址资源。

  重要

  • 从 2024 年 5 月开始，在内部模式下的 VNet 中部署（注入）API 管理实例或将内部 VNet 配置迁移到新子网时，不再需要公共 IP 地址资源。 在外部 VNet 模式下，指定公共 IP 地址为可选操作；如果未提供，系统会自动配置 Azure 托管的公共 IP 地址并将其用于运行时 API 流量。 仅当你希望拥有并控制用于 Internet 入站或出站通信的公共 IP 地址时，才提供该公共 IP 地址。
  • 目前，如果在内部模式或外部模式下的 VNet 中为 API 管理实例启用区域冗余，则必须指定新的公共 IP 地址。

更新 VNet 配置

1. 在门户中，导航到原始 VNet。
2. 在左侧菜单中，选择“子网”，然后选择原始子网。
3. 确认原始 IP 地址已由 API 管理释放。 在“可用 IP”下，记下子网中可用的 IP 地址数。 所有地址（Azure 保留地址除外）都应可用。 如有必要，请等待 IP 地址释放。
4. 导航到 API 管理实例。
5. 在左侧菜单的“网络”下，选择“虚拟网络”。
6. 在该位置中选择要更新的网络连接。
7. 选择原始 VNet 网络和子网。 （可选）选择新的公共 IP。 选择“应用”。
8. 如果 API 管理实例部署在多个区域中，请继续配置实例剩余位置的 VNet 设置。
9. 在顶部导航栏中选择“保存”。

更新 VNet 配置后，API 管理实例的状态将更改为“正在更新”。 迁移过程大约需要 45 分钟才能完成。 当状态变为“联机”时，迁移完成。

验证迁移

若要验证迁移是否成功，当状态更改为“联机”时，请检查 API 管理实例的平台版本。 成功迁移后，该值为 stv2 或 stv2.1。

在清除旧网关之前确认设置

对于迁移后暂时保留旧网关的情况，迁移期间创建的新旧计算将在短时间内共存（大约 15 分钟），你可以使用这段时间来验证部署以及应用程序是否按预期工作。 对于某些方案，可以选择通过门户设置将保留期延长到 48 小时。

• 在此窗口期间，新旧网关都处于联机状态并提供流量。 在此期间无需付费。
• 在此窗口期内更新任何网络依赖项（包括 DNS、防火墙规则和 VNet）以使用新的 VIP 地址和子网地址空间。
• 此外，请检查更新后实例的网络状态以确保实例与其依赖项的连接。 在门户中左侧菜单中的“部署和基础结构”下，选择“网络”“网络状态”。 如果需要，请更新 UDR 和 NSG 规则等设置。
• 在该窗口期后，旧网关将停用，新网关是唯一提供流量的网关。

迁移失败时自动还原

如果在迁移过程中出现故障，实例将自动还原到 stv1 平台。 如果迁移成功完成（实例的平台版本显示为 stv2 或 stv2.1，并且状态显示为“联机”），则无法回滚到 stv1 平台。

如果迁移失败，请联系 Azure 支持以获取帮助。

如果需要手动回滚功能，建议与原始 API 管理实例并行部署新的 stv2 实例。

帮助和支持

我们将在此处帮助你迁移到 stv2 平台，同时将对服务造成的干扰降至最低。

如果有疑问，请从 Microsoft Q&A 中的社区专家那里快速获取解答。 如有支持计划并需要技术帮助，请创建支持请求。

1. 对于“摘要”，请键入问题的说明，例如“stv1 停用”。
2. 在“问题类型”下，选择“技术”。
3. 在“订阅”下，选择自己的订阅。
4. 在“服务”下，选择“我的服务”，然后选择“API 管理服务”。
5. 在“资源”下，选择要为其创建支持请求的 Azure 资源。
6. 请在“问题类型”处选择“管理”。
7. 对于“问题子类型”，选择“升级、缩放或 SKU 更改”。

常见问题

• 需要哪些信息来选择迁移路径？

  • API 管理实例的网络模式是什么？
  • 是否配置了自定义域？
  • 是否涉及防火墙？
  • 上游/下游对所涉及的 IP 是否有任何已知的依赖项？
  • 是多区域部署吗？
  • 我们可以修改现有实例吗？还是需要并行设置？
  • 会有故障时间吗？
  • 迁移是否可以在非业务时间内完成？

• 迁移的先决条件是什么？

  对于注入 VNet 的实例，请参阅迁移和保留相同子网或迁移和更改为新子网的先决条件。

• 迁移是否会产生故障时间？

  迁移注入 VNet 的实例并保留相同的子网配置时，预计 API 网关的停机时间最少或不会停机。 请参阅“预期停机时间”中的摘要表。

  迁移并更改为新的 VIP 地址时，如果默认主机名正在使用，则不应停机。 至关重要的是，要使受影响的 API 正常运行，必须提前处理好所有网络依赖项。 但是，如果正在使用自定义域，它们将在更新前持续指向被清除的计算，这可能会导致停机。 或者，对于某些迁移选项，启用迁移设置以将旧网关保留 48 小时。 让旧计算和新计算共存将促进验证，然后可以随时更新自定义 DNS 条目。

• 我的流量通过防火墙强制隧道传输的。 需要哪些更改？

  • 首先，请确保用于迁移的子网保留以下配置（如果你正在迁移并保留当前子网，则这些选项应该已经配置就绪）：
    • 如此处所述启用服务终结点
    • UDR（用户定义的路由）具有从 ApiManagement 服务标记设置为“Internet”的跃点，而不仅仅是防火墙地址
  • 无论你是否有防火墙，stv2 的 NSG 配置要求保持不变；确保新子网包含它
  • 应更新引用 API 管理实例的当前 IP 地址范围的防火墙规则，以使用新子网的 IP 地址范围。

• 迁移期间是否可能发生数据或配置丢失？

  stv1 到 stv2 迁移涉及仅更新计算平台，内部存储层不会更改。 因此，在迁移过程中，所有配置都是安全的。 这包括系统分配的托管标识，如果启用，则会保留该标识。

• 如何确认迁移已完成且成功

  当概述页中的状态显示“联机”，并且平台版本为 stv2 或 stv2.1 时，迁移被视为已完成且成功。 此外，请验证“网络”边栏选项卡中的网络状态是否对所有必需连接显示绿色。

• 是否可以使用门户执行迁移？

  是的，可以使用“平台迁移”边栏选项卡迁移注入 VNet 的实例。

• 是否可以保留实例的 IP 地址？

  是的，门户中的“平台迁移”边栏选项卡和 REST API 提供保留 IP 地址的选项。

• 是否存在不修改现有实例的迁移路径？

  是的，需要并行迁移。 这意味着，可以与当前实例并行创建新的 API 管理实例，并将配置复制到新实例。

• 如果迁移失败，会发生什么情况？

  如果在启动迁移后，API 管理实例的平台版本未显示为 stv2 或 stv2.1，并且状态未显示为“联机”，则迁移可能失败。 服务会自动回滚到旧实例，不会做出任何更改。

• 迁移期间，哪些功能不可用？

  API 请求在迁移期间将会保持响应。 基础结构配置（如自定义域、位置和 CA 证书）锁定 30 分钟。

• 迁移需要多长时间？

  迁移到新 VNet 配置的预期持续时间约为 45 分钟。 检查迁移是否已执行的指示器是检查实例的状态是否返回到“联机”，而不是“正在更新”。 需要为多区域部署和涉及多次更改子网的方案规划更长的时间。

• 尝试迁移之前，是否有方法验证 VNet 配置？

  如果计划在迁移期间更改子网，可以使用将用于实际迁移的 VNet、子网和（可选）IP 地址资源部署新的 API 管理实例。 部署完成后导航到“网络状态”页，并验证每个终结点连接状态是否为绿色。 如果是，则可以删除此新的 API 管理实例，然后继续执行原始 stv1 托管服务的实际迁移。

• 如果需要，是否可以回滚迁移？

  如果在迁移过程中出现故障，实例将自动回滚到 stv1 平台。 但是，在服务成功迁移后，无法回滚到 stv1 平台。

• 自定义域/专用 DNS 区域是否需要任何更改？

  在内部模式下使用注入 VNet 的实例并更改为新 VIP 时，需要将专用 DNS 区域更新为迁移后获取的新 VNet IP 地址。 请注意也更新非 Azure DNS 区域（例如，指向 API 管理专用 IP 地址的本地 DNS 服务器）。 但是，在外部模式下，迁移过程将在使用时自动更新默认域。

• 我的 stv1 实例部署到多个 Azure 区域（多区域）。 如何升级到 stv2？

  多区域部署包括部署在其他位置的更多托管网关。 使用门户中的“平台迁移”边栏选项卡进行迁移时，可以单独迁移每个位置。 迁移到 Stv2 REST API 只需一次调用即可迁移所有位置。 仅当迁移所有位置时，该实例才会被视为迁移到新平台。 所有区域网关都将在整个迁移过程中继续正常运行。

• 是否可以将 stv1 实例升级到同一子网？

  是的，使用门户中的“平台迁移”边栏选项卡，或使用“迁移到 stv2 REST API”。

• 是否可以在切换实时流量之前在新子网中测试新网关？

  • 迁移到新子网时，默认情况下，旧托管网关和新托管网关将共存 15 分钟，这是验证部署的一个小的时间窗口。 可以启用将旧网关保留 48 小时的迁移设置。 此更改会使旧托管网关和新托管网关保持活动状态，以接收流量并促进验证。
  • 迁移过程会自动更新默认域名，如果使用，流量会立即路由到新网关。
  • 如果使用自定义域名，则如果不使用 CNAME，则可能需要使用新的 IP 地址更新相应的 DNS 记录。 在进行切换之前，客户可以将其主机文件更新到新的 API 管理 IP 并验证实例。 在此验证过程中，旧网关继续为实时流量提供服务。

• 在新子网中使用默认域名时是否有任何注意事项？

  在外部模式下使用默认 DNS 名称的实例由迁移过程自动更新 DNS。 此外，迁移过程会自动更新始终使用默认域名的管理终结点。 由于成功迁移后会立即进行切换，因此新实例会立即开始接收流量，任何网络限制/依赖项都需提前处理，以避免受影响的 API 不可用。

• 我们应考虑哪些自承载网关？

  无需在自承载网关中执行任何操作。 只需迁移 Azure 中运行的、受 stv1 平台停用影响的 API 管理实例。 请注意，API 管理实例的配置终结点可能存在新的 IP，并且应更新固定到 IP 的任何网络限制。

• 开发人员门户如何受到迁移的影响？

  对开发人员门户没有影响。 如果使用自定义域，应在迁移后使用有效的 IP 更新 DNS 记录。 但是，如果默认域正在使用，则会在成功迁移时自动更新它们。 在迁移过程中，开发人员门户没有故障时间。

• 迁移到 stv2 后，是否会对成本产生任何影响？

  对于 stv2，计费模型保持不变，迁移期间和之后不会再产生任何费用。

• stv1 到 stv2 的迁移需要哪些 RBAC 权限？

  进行迁移的用户/进程需要对 API 管理实例的写入权限。 此外，还需要以下两个权限：

  • Microsoft.Network/virtualNetworks/subnets/join/action
  • Microsoft.Network/publicIPAddresses/join/action

相关内容

• 如何知道哪个平台托管了我的 API 管理实例？

• API 管理 stv2 计算平台的优势

• stv1 平台停用 - 全球 Azure（2024 年 8 月）

• stv1 平台停用 - Azure 政府和由世纪互联运营的 Azure（2025 年 2 月）