从 Azure Cosmos DB for MongoDB 迁移到 Azure DocumentDB

使用本指南，您可以使用内置于服务和 Azure 门户的工具，将现有的集合从 Azure Cosmos DB for MongoDB 迁移到 Azure Cosmos DB。

先决条件

• Azure 订阅服务

  • 如果没有 Azure 订阅，可在开始前创建一个试用帐户。

• 目标 Azure DocumentDB 群集

  • 如果还没有群集， 请创建新的 Azure DocumentDB 群集。

  • 确保具有连接到群集所需的 本机身份验证凭据 。

• Azure 密钥保管库 帐户

  • 确保为基于角色的访问控制启用 密钥保管库 帐户。 有关详细信息，请参阅 Azure 密钥保管库 中基于角色的访问控制。

设置 Azure 密钥保管库

首先，需要配置源 Azure Cosmos DB for MongoDB 帐户，以将目标 Azure DocumentDB 群集的本机身份验证凭据存储在现有密钥保管库中。

1. 登录到 Azure 门户 (https://portal.azure.cn)。

2. 进入您的 Azure Cosmos DB for MongoDB 帐户。

3. 在源帐户中，导航到 “设置 > 标识”。

4. 通过将“状态”选项设置为“打开”，为源帐户启用系统分配的托管标识。 记下本指南稍后要使用的 对象（主体）ID 的值。

   

   小窍门

   如果改用用户分配的托管标识，请确保至少将一个用户分配的托管标识分配给源帐户。

5. 导航到现有的密钥保管库。

6. 如果 密钥保管库 使用 Role-Based 访问控制（RBAC） 权限模型，请在资源菜单中选择 访问控制（IAM） 选项，并将 密钥保管库 机密用户 角色分配给用于源帐户的托管标识的主体 ID（对象 ID）。 否则，请使用资源菜单中的 “访问策略 ”选项创建具有 “获取 和 列出机密 ”权限的访问策略，然后将其分配给主体 ID（对象 ID）。

7. 运行命令更新源帐户，并将首选标识机制设置为默认标识。

   az cosmosdb update \
       --resource-group "<resource-group-name>" \
       --name "<source-account-name>" \
       --default-identity "SystemAssignedIdentity"
   

   小窍门

   如果改用用户分配的托管标识，请运行以下命令：

   az cosmosdb update \
       --resource-group "<resource-group-name>" \
       --name "<source-account-name>" \
       --default-identity "UserAssignedIdentity=<fully-qualified-resource-id-of-user-assigned-managed-identity>"
   

8. 返回到密钥保管库，导航到 “对象 > 机密”。

9. 然后选择“ 生成/导入 ”以创建新机密。 将以下值用于机密：

   	Description
   名称	机密名称用于标识机密，只能包含字母数字字符和短划线。 此值最终在迁移作业的 “机密名称 ”字段中使用。
   机密值	在此处粘贴 Azure Cosmos DB for MongoDB 目标群集的本机身份验证凭据。

10. 在新创建的机密中，获取 保管库 URI 的值。 此值最终在迁移作业的 保管库 URI 字段中使用。

创建迁移作业

首先，使用开始将数据迁移到目标群集所需的配置创建迁移作业。

1. 登录到 Azure 门户 (https://portal.azure.cn)。

2. 请重新访问您的 Azure Cosmos DB for MongoDB 帐户。

3. 在帐户页上，从资源菜单中选择 “迁移到 DocumentDB ”。

   

4. 选择“ 启动新的迁移作业”。

选择迁移模式

“选择迁移模式”部分用于提供最适合迁移需求的迁移模式。

1. 从以下选项中选择适当的模式：

   	Description
   离线	脱机迁移在开始时捕获集合的快照，这种方法更简单且可预测。 在允许使用集合的静态副本且实时更新非必要时，它可以很好地运行。 将此选项用于非生产迁移。
   在线	在线迁移会复制集合数据，确保在此过程中也会复制更新。 此方法的优势在于停机时间最小，确保持续运行以实现业务连续性。 如果正在进行的操作至关重要，需要优先考虑减少停机时间，则可以使用此选项。

   

   重要

   连续备份是联机迁移的先决条件。 有关详细信息，请参阅 连续备份。

2. 选择“下一步”。

配置目标迁移凭据

“选择目标帐户”部分用于提供目标 Azure DocumentDB 群集的连接详细信息。 迁移作业可以使用目标 DocumentDB 的本机身份验证凭据或使用 Microsoft Entra ID 进行连接。

作为安全最佳做法，Microsoft Entra ID 是首选的身份验证机制。

使用 DocumentDB 的本机身份验证进行配置

1. 将 保管库 URI 和 机密名称 字段设置为本指南前面记录的值。

   

2. 选择“下一步”。

使用 Microsoft Entra ID 身份验证进行配置

1. 请确保在源帐户上配置的托管标识在 目标 DocumentDB 群集上分配了读写权限。

2. 设置 Azure DocumentDB（使用 MongoDB 兼容性）帐户名称 字段值。

配置网络安全

“配置网络安全”部分可确保目标Azure DocumentDB 群集的网络配置允许迁移作业进行连接。 根据目标群集的网络配置选择以下选项之一。

在目标上启用公用网络访问 - 使用防火墙规则

默认情况下，Azure DocumentDB 群集已锁定。 若要启用来自 MongoDB 帐户Azure Cosmos DB的通信，请将此步骤中显示的 IP 地址添加到 Azure DocumentDB 防火墙。

1. 观察此步骤中的 IP 地址 。

2. 使用其他浏览器窗口或选项卡导航到目标 Azure DocumentDB 群集。

3. 在资源菜单的“设置”部分选择“网络”。

4. 添加规则以允许访问迁移作业的 IP 地址。 有关详细信息，请参阅 管理群集级防火墙规则。

   注释

   如果在 Azure 密钥保管库 上启用了网络安全，请确保也会将相同的 IP 添加到 Azure 密钥保管库 防火墙 。

5. 使用迁移作业配置步骤导航回浏览器窗口或选项卡。

6. 选择“下一步”。

目标上的公共网络访问已禁用 — 请使用 Entra ID 和网络旁路

当目标Azure DocumentDB 群集上禁用公共网络访问时，网络旁路模式提供了添加防火墙规则的安全替代方法。 绕过模式允许受信任的Azure Cosmos DB服务访问群集，同时阻止本机身份验证和所有其他公共访问，而不是打开防火墙规则。 这会创建一个专门用于迁移的安全通道。 有关详细信息，请参阅 网络旁路模式。

1. 按照 “启用网络绕过模式” 部分中的步骤配置目标群集。

2. 使用迁移作业配置步骤导航回浏览器窗口或选项卡。

3. 选择“下一步”。

配置和启动作业

使用 “选择集合 ”和 “确认和提交 ”部分完成作业的配置。

1. 在 “选择集合” 部分选择要迁移的集合。

   

2. 选择“下一步”。

3. 查看作业配置并提供唯一的作业名称。

   重要

   1. 迁移作业不会将索引传输到目标集合。 在继续作之前，请使用此示例 迁移脚本 在目标集合上创建索引。 索引准备就绪后，请选中该复选框。
   2. 迁移作业不支持更改分片键。 如果需要不同的分片键，请将数据迁移为未分片集合。 迁移完成后，使用所需的分片键对目标上的集合进行分片。

4. 选择 “提交 ”以创建并启动作业。

监视迁移作业

提交任务后，您可以监视新创建任务的状态以及其他挂起或已完成的任务。

1. 进入您的 Azure Cosmos DB for MongoDB 帐户。

2. 在帐户页上，从资源菜单中选择 “迁移到 DocumentDB ”。

3. 选择“监视现有迁移作业”。

   

4. 列出为当前源帐户创建的所有迁移作业。

5. （可选）若要更改作业的状态，请选择与特定作业对应的上下文菜单（..）。 选项包括：

   选项	Description
   暂停	暂时暂停当前正在运行的作业
   简历	恢复暂停的作业
   取消	永久取消当前正在运行的作业
   直接转换	在确认源和目标完成同步后完成迁移

   注释

   切换选项仅适用于联机迁移。 切换完成后，源帐户与目标群集之间的同步将结束。 执行切换后，应更新客户端应用程序中的凭据以切换到新的 Azure DocumentDB 群集。

网络旁路模式

当目标Azure DocumentDB 群集上禁用公共网络访问时，网络旁路模式提供了添加防火墙规则的安全替代方法。 绕过模式允许受信任的Azure Cosmos DB服务通过AzureCosmosDB服务标记访问群集，同时阻止本机身份验证和所有其他公共访问，而不是打开防火墙规则。 这会创建一个专门用于迁移的安全通道。

网络旁路模式的先决条件

在启用网络旁路模式之前，必须在目标群集上满足以下三个条件：

启用网络旁路模式

按顺序完成以下步骤。 等待群集在每个步骤之间达到 成功的 预配状态。

删除所有防火墙规则

列出现有防火墙规则：

az rest --method get \
  --url "https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/mongoClusters/{clusterName}/firewallRules?api-version=2026-02-01-preview"

对于返回的每个规则，请将其删除：

az rest --method delete \
  --url "https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/mongoClusters/{clusterName}/firewallRules/{ruleName}?api-version=2026-02-01-preview"

禁用公共网络访问

az rest --method patch \
  --url "https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/mongoClusters/{clusterName}?api-version=2026-02-01-preview" \
  --body '{"properties": {"publicNetworkAccess": "Disabled"}}'

此操作通常在 2-5 分钟内完成。

切换到仅使用 Microsoft Entra ID 的身份验证

az rest --method patch \
  --url "https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/mongoClusters/{clusterName}?api-version=2026-02-01-preview" \
  --body '{"properties": {"authConfig": {"allowedModes": ["MicrosoftEntraID"]}}}'

此操作通常在 5-10 分钟内完成。

设置网络旁路模式

az rest --method patch \
  --url "https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/mongoClusters/{clusterName}?api-version=2026-02-01-preview" \
  --body '{"properties": {"networkBypassMode": "AzureCosmosDB"}}'

验证配置

az rest --method get \
  --url "https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/mongoClusters/{clusterName}?api-version=2026-02-01-preview"

确认响应中包括：

{
  "properties": {
    "networkBypassMode": "AzureCosmosDB",
    "publicNetworkAccess": "Disabled"
  }
}

验证后，返回到迁移向导，然后选择 “下一步 ”继续。

绕过模式处于活动状态时的副作用

当 networkBypassMode 设置为 AzureCosmosDB 时：

• 防火墙规则：创建、更新或删除防火墙规则将返回错误。 列出规则返回空列表。
• 公用网络访问：在禁用绕过模式之前，将阻止重新启用公用网络访问。

排查网络绕过模式问题

迁移后的操作

迁移成功完成后，请完成以下步骤以还原任何临时配置更改。

禁用网络绕过模式

如果在迁移过程中启用了 网络绕过模式 ，请禁用它以还原标准网络规则。

az rest --method patch \
  --url "https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/mongoClusters/{clusterName}?api-version=2026-02-01-preview" \
  --body '{"properties": {"networkBypassMode": "None"}}'

此操作通常在 5-10 分钟内完成。 禁用绕过模式没有任何先决条件，可以随时完成。 服务 AzureCosmosDB 标记将从 NSG 中删除，并恢复正常的网络规则。

重新启用公用网络访问（可选）

az rest --method patch \
  --url "https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/mongoClusters/{clusterName}?api-version=2026-02-01-preview" \
  --body '{"properties": {"publicNetworkAccess": "Enabled"}}'

重新启用本机身份验证（可选）

az rest --method patch \
  --url "https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/mongoClusters/{clusterName}?api-version=2026-02-01-preview" \
  --body '{"properties": {"authConfig": {"allowedModes": ["NativeAuth"]}, "administrator": {"userName": "{adminUser}", "password": "{adminPassword}"}}}'