本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Amazon DocumentDB 迁移运行手册
本运行手册提供了使用 (DMS) 将 MongoDB 数据库迁移到 Amazon DocumentDB 的全面指南。 AWS Database Migration Service 它旨在为数据库管理员、云工程师和开发人员提供从初始发现到 end-to-end迁移后验证的整个迁移过程中的支持。
鉴于 MongoDB 与 Amazon DocumentDB 在实现和支持功能方面的差异，本运行手册强调了结构化和系统化的方法。本运行手册概述了重要的迁移前评测，重点介绍了兼容性注意事项，并详细说明了在最大限度减少中断的情况下确保迁移成功所需执行的关键任务。
本运行手册包含以下主题：
+ **[兼容性](#mig-runbook-compatibility)**：了解 Amazon DocumentDB 中支持的 MongoDB 功能和数据类型，识别潜在的不兼容性。
+ **[工作负载发现](#mig-runbook-workload)**— 分析现有 MongoDB 工作负载， read/write 包括模式、数据量和性能基准。
+ **[索引迁移](#mig-runbook-index)**：分析用于提取和转换 MongoDB 索引的策略，以在 Amazon DocumentDB 中实现最佳性能。
+ **[用户迁移](#mig-runbook-user)**：详细介绍将数据库用户、角色和访问控制迁移到 Amazon DocumentDB 的方法。
+ **[数据迁移](#mig-runbook-data)**— 介绍使用各种数据迁移方法 AWS DMS，包括满载和变更数据捕获 (CDC)。
+ **[监控](#mig-runbook-monitoring)**：详细介绍使用 DMS 或原生工具进行迁移时的各种监控方法。
+ **[验证](#mig-runbook-validation)**：提供进行迁移后数据完整性检查、功能验证和性能比较的过程。
通过遵循本运行手册中的指导，团队可以确保平稳、安全且高效地过渡到 Amazon DocumentDB，同时保留应用程序功能并最大限度地降低风险。
## 兼容性
**Topics**
+ [核心功能兼容性](#w2aac25b9c13c13)
+ [Amazon DocumentDB 兼容性评测工具](#w2aac25b9c13c15)
从 MongoDB 迁移到 Amazon DocumentDB 时，全面的初始评测和功能兼容性检查是成功迁移的关键。此过程从全面清点您的 MongoDB 功能开始，包括聚合管道运算符、查询模式、索引和数据模型。
由于亚马逊 DocumentDB 与 MongoDB 3.6、4.0、5.0 和 8.0 API 兼容，因此使用较新 MongoDB 特定功能的应用程序可能需要重构。需要评估的关键领域包括分片机制（Amazon DocumentDB 使用不同的方法）、事务实现、变更流功能以及索引类型（尤其是稀疏索引和部分索引）。
性能特征也存在差异，Amazon DocumentDB 针对企业工作负载进行了优化，性能可预测。测试应包括对两个系统运行具有代表性的工作负载，以识别可能需要优化的查询模式。
在评测阶段，监控执行计划以发现潜在的性能差距非常重要。这有助于制定清晰的迁移路线图，识别必要的应用程序变更以及建立切合实际的时间表，以便实现平稳过渡。
### 核心功能兼容性
#### 全面功能支持
+ **CRUD 操作**：全面支持所有基本的创建、读取、更新和删除操作（包括批量和查询运算符），从而提供无缝的应用程序兼容性。
+ **丰富的索引功能**：利用对单字段索引、复合索引、TTL 索引、部分索引、稀疏索引和 2dsphere 索引的全面支持，优化查询性能，以及利用文本索引（版本 5）进行基于文本的查找。
+ **企业级复制**：受益于强大的自动失效转移机制与只读副本，可实现卓越的高可用性，并且不会产生运营开销。
+ **高级备份解决方案** — 借助具有 Point-in-Time恢复 (PITR) 功能的自动备份系统和按需手动快照来保护数据，让您高枕无忧。
#### 增强 AWS的集成功能
+ **简化的聚合**：利用最常用的聚合阶段（`$match`、`$group`、`$sort`、`$project` 等），已针对企业工作负载优化性能。
+ **事务支持**：实现多文档和多集合事务，非常适合大多数业务应用程序需求。
+ **实时数据跟踪**：通过简单的命令启用变更流，并通过简单的参数组设置来延长变更流保留期，以实现实时数据变更监控。
+ **基于位置的服务**：实现支持 `$geoNear` 运算符和 2dsphere 索引的地理空间应用程序。
+ **文本搜索功能**：利用内置的文本搜索功能满足内容发现需求。
#### 现代架构优势
+ **云原生设计** — 享受 AWS经过优化的架构，该架构可取代传统功能，例如更高效 MapReduce 的聚合管道操作。
+ **增强的安全性** — 受益于 AWS Identity and Access Management (IAM)、SCRAM-SHA-1、SCRAM-SHA-256、X.509 证书身份验证和基于密码的身份验证。
+ **可预测的性能**：体验专为企业工作负载而优化的稳定性能。
要全面了解 Amazon DocumentDB 的功能，请参阅 [在 Amazon Document APIs DB 中支持 MongoDB、操作和数据类型](mongo-apis.md) 和 [功能差异：Amazon DocumentDB 和 MongoDB](functional-differences.md)，以最大限度地发挥数据库的潜力。
Amazon DocumentDB 并不支持 MongoDB 提供的所有索引。我们提供免费的[索引工具](https://github.com/awslabs/amazon-documentdb-tools/blob/master/index-tool/README.md)来检查兼容性。我们建议运行索引工具来评测不兼容性，并据此规划解决方法。
### Amazon DocumentDB 兼容性评测工具
[MongoDB 与 Amazon DocumentDB 的兼容性工具是一个可用的开源工具，它通过分析 MongoD](https://github.com/awslabs/amazon-documentdb-tools/blob/master/compat-tool/README.md) B 日志或应用程序源代码来帮助评估 MongoDB 工作 GitHub 负载与亚马逊 DocumentDB 的兼容性。
**主要特征**
+ 识别工作负载中的 MongoDB API 使用模式
+ 在迁移之前标记潜在的兼容性问题
+ 生成包含建议的详细兼容性报告
+ 可用作在本地运行的独立实用程序
#### 评测方法
**基于日志的评测**
+ 优点：
+ 捕获实际运行时行为和查询模式
+ 识别现实世界的使用频率和性能特征
+ 检测可能在源代码中不可见的动态查询
+ 无需访问应用程序源代码
+ 缺点：
+ 需要访问 MongoDB 日志并启用分析
+ 仅捕获在日志记录期间发生的操作
+ 可能会遗漏不常使用的功能或季节性工作负载
**源代码分析**
+ 优点：
+ 全面覆盖代码库中所有潜在的 MongoDB 操作
+ 可以识别罕见执行的代码路径中的问题
+ 检测可能受 Amazon DocumentDB 差异影响的客户端逻辑
+ 无需运行应用程序即可执行评测
+ 缺点：
+ 可能会标记存在但从未在生产环境中执行的代码
+ 需要访问完整的应用程序源代码
+ 对动态构造的查询进行分析的能力有限
为了获得最佳结果，我们建议尽可能使用这两种评测方法，以便在迁移之前全面了解兼容性挑战。
## 工作负载发现
从 MongoDB 迁移到 Amazon DocumentDB 需要对现有数据库工作负载有透彻的了解。工作负载发现是分析数据库使用模式、数据结构、查询性能和操作依赖关系的过程，旨在确保以最少的中断实现无缝过渡。本节概述了工作负载发现所涉及的关键步骤，以促进从 MongoDB 到 Amazon DocumentDB 的有效迁移。
**Topics**
+ [评测现有的 MongoDB 部署](#w2aac25b9c15b7)
+ [识别数据模型差异](#w2aac25b9c15b9)
+ [查询和性能分析](#w2aac25b9c15c11)
+ [安全与访问控制审查](#w2aac25b9c15c13)
+ [操作和监控注意事项](#w2aac25b9c15c15)
### 评测现有的 MongoDB 部署
在迁移之前，评估当前的 MongoDB 环境至关重要，包括：
+ **集群架构**：确定节点数量、副本集和分片配置。从 MongoDB 迁移到 Amazon DocumentDB 时，了解您的 MongoDB 分片配置非常重要，因为 Amazon DocumentDB 不支持用户控制的分片。为分片 MongoDB 环境设计的应用程序需要进行架构变更，因为 Amazon DocumentDB 在其基于存储的架构中使用了不同的扩展方法。迁移到 Amazon DocumentDB 时，您需要调整数据分配策略，并且可能需要整合分片集合。
+ **存储和数据量**：测量集群的总数据大小和索引大小。配合使用 [Oplog 审查工具](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/mongodb-oplog-review)，以了解写入模式和数据增长速度。有关调整集群大小的更多信息，请参阅 [实例大小调整](best_practices.md#best_practices-instance_sizing)。
+ **工作负载模式**：分析读取和写入吞吐量、查询执行频率和索引效率。
+ **操作依赖关系**：记录依赖于 MongoDB 的所有应用程序、服务和集成。
### 识别数据模型差异
尽管 Amazon DocumentDB 与 MongoDB 兼容，但支持的功能存在差异，例如：
+ **事务**：Amazon DocumentDB 支持 ACID 事务，但存在一些[限制](transactions.md#transactions-limitations)。
+ **架构设计**：确保文档结构、嵌入式文档和参考符合 [Amazon DocumentDB 的最佳实践](https://d1.awsstatic.com/product-marketing/Data%20modeling%20with%20Amazon%20DocumentDB.pdf)。
### 查询和性能分析
了解查询行为有助于优化迁移和迁移后的性能。需要分析的关键领域包括：
+ **慢查询**：使用 MongoDB 的分析工具识别执行时间较长的查询。
+ **查询模式**：对常见的查询类型进行分类，包括 CRUD 操作和聚合。
+ **索引使用情况**：评测索引是否得到有效利用，或者是否需要在 Amazon DocumentDB 中进行优化。要评测索引使用情况并优化 Amazon DocumentDB 中的性能，请在关键查询中将 `$indexStats` 聚合管道阶段与 `explain()` 方法结合使用。首先运行 `db.collection.aggregate([{$indexStats{}}])` 以识别正在使用的索引。您可以通过使用 `explainPlan` 执行最频繁的查询来执行更详细的分析。
+ **并发和工作负载分配**：评估读取和写入比率、连接池和性能瓶颈。
### 安全与访问控制审查
**身份验证和授权**
+ **MongoDB RBAC 到亚马逊 DocumentDB IAM 和 RBAC — 将 MongoDB 基于角色的访问控制用户和角色映射到 (IAM) 策略 AWS Identity and Access Management 和亚马**逊 DocumentDB SCRAM 身份验证用户。
+ **用户迁移策略**：规划将数据库用户、自定义角色和权限迁移到 Amazon DocumentDB 支持的身份验证机制。
+ **权限差异**：识别 MongoDB 权限中没有直接的 Amazon DocumentDB 等效权限（例如，集群管理角色）。
+ **应用程序身份验证**：更新 Amazon DocumentDB 密码策略的连接字符串和凭证管理。您可以使用 Secrets Manager 来存储您的凭证和轮换密码。
+ **服务帐号管理**-在中建立管理服务帐号凭证的流程 AWS Secrets Manager。
+ **最低权限实施**：审查并优化访问控制，以在新环境中实施最低权限原则。
**加密**
确保静态加密和传输中加密符合合规要求。
**网络配置**
规划[虚拟私有云（VPC）](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html)设置和安全组规则。
### 操作和监控注意事项
为了保持系统可靠性，工作负载发现还应包括：
+ **备份和恢复策略**：评估现有的备份方法和 Amazon DocumentDB 的备份功能。
+ **AWS Backup 集成** — 利用 AWS Backup 跨 AWS 服务（包括 Amazon DocumentDB）进行集中备份管理。
+ **CloudWatch 指标** — 将 MongoDB 监控指标映射到 Amazon DocumentDB 的 CPU、内存、连接和存储的指标。 CloudWatch
+ **性能详情**：实施 Amazon DocumentDB 性能详情，以通过详细的查询分析，可视化数据库负载并分析性能问题。
+ **探查器**：配置 Amazon DocumentDB 探查器以捕获运行缓慢的操作（与 MongoDB 的探查器类似，但使用特定于 Amazon DocumentDB 的设置）。
+ 通过参数组启用并设置适当的阈值。
+ 分析探查器数据以识别优化机会
+ **CloudWatch 事件** — 为 Amazon DocumentDB 集群事件设置事件驱动型监控。
+ 为备份事件、维护时段和失效转移配置通知。
+ 与 Amazon SNS 集成，以提供警报和自动响应 AWS Lambda 。
+ **审计日志记录**：规划审计日志记录配置，以跟踪用户活动和安全相关事件。
+ **增强型监控**：启用增强型监控，以 1 秒间隔获取精细操作系统级别指标。
## 索引迁移
从 MongoDB 迁移到 Amazon DocumentDB 不仅需要传输数据，还需要传输索引，以保持查询性能和优化数据库操作。本节概述了在确保兼容性和效率的同时，将索引从 MongoDB 迁移到 Amazon DocumentDB 的详细 step-by-step过程。
### 使用 Amazon DocumentDB 索引工具
**克隆[索引工具](https://github.com/awslabs/amazon-documentdb-tools/blob/master/index-tool/README.md)**
```
git clone https://github.com/aws-samples/amazon-documentdb-tools.git
cd amazon-documentdb-tools/index-tool
```
```
pip install -r requirements.txt
```
**从 MongoDB 导出索引（如果从 MongoDB 迁移）**
```
python3 migrationtools/documentdb_index_tool.py --dump-indexes --dir mongodb_index_export --uri
'mongodb://localhost:27017'
```
**从 Amazon DocumentDB 导出索引（如果从 Amazon DocumentDB 迁移）**
```
python3 migrationtools/documentdb_index_tool.py --dump-indexes --dir docdb_index_export --uri
'mongodb://user:password@mydocdb.cluster-cdtjj00yfi95.eu-west-
2.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=rds-combined-ca-
bundle.pem&replicaSet=rs0&retryWrites=false'
```
**导入索引**
```
python3 migrationtools/documentdb_index_tool.py --restore-indexes --skip-incompatible --dir
mongodb_index_export --uri 'mongodb://user:password@mydocdb.cluster-cdtjj00yfi95.eu-west-
2.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=rds-combined-ca-
bundle.pem&replicaSet=rs0&retryWrites=false'
```
**验证索引**
```
python3 migrationtools/documentdb_index_tool.py --show-issues --dir mongodb_index_export
```
## 用户迁移
将用户从 MongoDB 迁移到 Amazon DocumentDB 对于维护访问控制、身份验证和数据库安全至关重要。本节概述了使用 Amazon DocumentDB 导出用户工具成功迁移 MongoDB 用户，同时保留其角色和权限的详细步骤。
### 使用 Amazon DocumentDB 导出用户工具
将用户和角色从 MongoDB 或 Amazon DocumentDB [https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/export-users](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/export-users)导出 JavaScript 到文件中，然后可以使用这些文件在另一个集群中重新创建它们。
**先决条件**
```
# Clone the repository
git clone https://github.com/awslabs/amazon-documentdb-tools.git
cd amazon-documentdb-tools/migration/export-users
```
```
# Install required dependencies
pip install pymongo
```
**步骤 1：导出用户和角色**
```
# Export users and roles to JavaScript files
python3 docdbExportUsers.py \
--users-file mongodb-users.js \
--roles-file mongodb-roles.js \
--uri "mongodb://admin:password@source-host:27017/"
```
**步骤 2：编辑用户文件**
```
// Example of how to update the users.js file
// Find each user creation statement and add the password
db.getSiblingDB("admin").createUser({
user: "appuser",
// Add password here
pwd: "newpassword",
roles: [
{ role: "readWrite", db: "mydb" }
]
})
```
**步骤 3：将自定义角色恢复到 Amazon DocumentDB**
```
# Import roles first
mongo --ssl \
--host target-host:27017 \
--sslCAFile rds-combined-ca-bundle.pem \
--username admin \
--password password \
mongodb-roles.js
```
**步骤 4：将用户恢复到 Amazon DocumentDB**
```
# Import users after roles are created
mongo --ssl \
--host target-host:27017 \
--sslCAFile rds-combined-ca-bundle.pem \
--username admin \
--password password \
mongodb-users.js
```
**重要提示**
+ 出于安全考虑，不会导出密码，必须手动将密码添加到 users.js 文件中。
+ 必须先导入角色再导入用户，以确保角色分配正确。
+ 该工具生成可以直接使用 mongo shell 执行的 JavaScript 文件。
+ 迁移期间会保留自定义角色及其权限。
+ 此方法允许在导入之前查看和修改用户权限。
此方法提供了一种安全且灵活的途径将用户和角色从 MongoDB 迁移到 Amazon DocumentDB，同时允许在迁移过程中重置密码。
## 数据迁移
**Topics**
+ [在线迁移](#w2aac25b9c21b5)
+ [离线迁移](#w2aac25b9c21b7)
+ [先决条件](#w2aac25b9c21c11)
+ [准备 Amazon DocumentDB 集群](#w2aac25b9c21c13)
+ [执行数据转储（mongodump）](#w2aac25b9c21c15)
+ [将转储文件传输到恢复环境](#w2aac25b9c21c17)
+ [将数据恢复到 Amazon DocumentDB（mongorestore）](#w2aac25b9c21c19)
### 在线迁移
本节提供了从 MongoDB 到 Amazon DocumentDB 的在线迁移的详细步骤，以最大限度地减少停机时间并实现 AWS DMS 持续复制。首先，您需要将 Amazon DocumentDB 集群设置为目标，并确保将 MongoDB 实例正确配置为源，通常需要副本集模式才能捕获变更数据。接下来，您将创建 DMS 复制实例，并使用必要的连接详细信息定义源端点和目标端点。验证端点后，配置并启动迁移任务，该任务可能包括完全数据加载和/或持续复制。
#### 配置目标（Amazon DocumentDB）
**注意**
如果您已预置要迁移到的 Amazon DocumentDB 集群，则可以跳过此步骤。
**创建自定义参数组**
请参阅中的 AWS 管理控制台 或 AWS CLI 程序[创建 Amazon DocumentDB 集群参数组](cluster_parameter_groups-create.md)。
**创建 Amazon DocumentDB 集群**
**注意**
虽然本指南中还有其他用于创建 Amazon DocumentDB 集群的过程，但本节中的步骤专门适用于将大量数据迁移到新集群的任务。
1. [登录 AWS 管理控制台，然后在 /docdb 上打开亚马逊文档数据库控制台。https://console.aws.amazon.com](https://console.aws.amazon.com/docdb)
1. 在导航窗格中，选择**集群**。
**提示**
如果您在屏幕左侧没有看到导航窗格，请在页面左上角选择菜单图标 (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/docdb-menu-icon.png))。
1. 在 Amazon DocumentDB 管理控制台上，**集群**下，选择**创建**。
1. 在**创建 Amazon DocumentDB 集群**页面上，在**集群类型**部分中选择**基于实例的集群**（这是默认选项）。
1. 在集群配置部分中：
+ 在**集群标识符**中，输入唯一名称，例如 **mydocdbcluster**。请注意，无论如何输入，控制台都会将所有集群的名称更改为小写。
+ 对于**引擎版本**，选择 5.0.0。
1. 在**集群存储配置**部分中，按原样保留 **Amazon DocumentDB 标准**设置（此为默认选项）。
1. 在**实例配置**部分：
+ 对于**数据库实例类**，选择**内存优化类（包括 r 类）**（这是默认值）。
+ 对于**实例类**，根据工作负载选择实例类。例如：
+ db.r6g.large：适用于较小的工作负载
+ db.r6g.4xlarge：适用于较大的工作负载
作为最佳实践，我们建议选择尽可能大的实例以获得最佳的完全加载吞吐量，并在迁移完成后缩减规模。
+ 对于**实例数**，选择 1 个实例。选择一个实例有助于成本最小化。我们建议您在完成完全加载迁移后，扩展到三个实例以实现高可用性。
1. 在**身份验证**部分中，输入主要用户的用户名，然后选择**自行管理**。输入密码，然后确认密码。
1. 在**网络设置**部分中，选择 VPC 和子网组，然后配置 VPC 安全组。通过更新入站规则，确保您的 Amazon DocumentDB 安全组允许来自 DMS 实例安全组的入站连接。
1. 在 **E ncryption-at-rest** 部分中，启用加密（推荐），然后选择或输入 KMS 密钥。
1. 在**备份**部分中，设置备份保留期（1 到 35 天）。
1. 检查您的配置，然后选择**创建集群**。
部署时间通常在 10 到 15 分钟之间，
#### 配置源
MongoDB 和 Amazon DocumentDB 都可以充当迁移源，具体取决于您的场景：
+ **MongoDB 作为**源 — 从本地或自行管理的 MongoDB 迁移到 Amazon DocumentDB 或其他数据库服务时很常见。 AWS 需要在副本集模式下运行并具有足够大的 oplog（确保其大小可以容纳完全加载期间的所有操作），以支持迁移期间的变更数据捕获。
+ **Amazon DocumentDB 作为源**：通常用于跨区域复制、版本升级或迁移到 MongoDB Atlas 等其他数据库服务。需要 [启用变更流](change_streams.md#change_streams-enabling)，在集群参数组中设置 `change_stream_log_retention_duration` 参数以捕获迁移期间的持续变更。确保您的 `change_stream_log_retention_duration` 设置足够大，足以覆盖完成完全加载所需要的时间。
在开始迁移之前，请将源配置为允许 AWS DMS 访问。
创建具有适当权限的 MongoDB 用户：
```
db.createUser({
user: "dmsUser",
pwd: "yourSecurePassword",
roles: [{ role: "readAnyDatabase", db: "admin" }]
})
```
配置网络和身份验证。
在为 MongoDB 到 DMS 的迁移配置网络连接时：
**EC2 托管的 MongoDB 源**
+ 修改 EC2 安全组以允许来自 DMS 复制实例安全组的入站流量。
+ 为 TCP 端口 27017（或您的自定义 MongoDB 端口）添加规则。
+ 使用 DMS 复制实例的安全组 ID 作为源，以实现精确访问控制。
+ 确保 EC2 实例的子网可路由至 DMS 复制实例的子网。
**本地 MongoDB 源**
+ 配置您的防火墙以允许来自 DMS 复制实例的公有 IP 地址的入站连接。
+ 如果使用 Direct Connect 或 VPN，请确保您的网络和包含 DMS 实例的 VPC 之间路由正确。
+ 使用 telnet 或 nc 命令测试从 DMS 子网到 MongoDB 服务器的连接。
**MongoDB Atlas 源**
+ 将 DMS 复制实例 IP 地址添加到 MongoDB Atlas IP 允许列表。
+ 如果 Atlas 正在运行，则在 AWS VPC 和 MongoDB Atlas VPC 之间配置 VPC 对等互连。 AWS
+ 如果在其他云提供商上运行，请设置 AWS PrivateLink 私有连接（企业级）。
+ 创建具有适当 read/write 权限的专用用户。
+ 使用 MongoDB Atlas 连接字符串，将“SSL 模式”设置为“verify-full”。
+ 确保迁移期间有足够的 oplog 大小。
**Amazon DocumentDB 源**
配置您的源 Amazon DocumentDB 安全组，以允许来自 DMS 复制实例安全组的入站流量。
#### 创建 DMS 复制实例
我们建议使用 [DMS Buddy](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/dms_buddy) 来预置您的 DMS 基础设施，因为这样可以创建具有最佳 DMS 设置和实例大小的最佳迁移基础设施。
如果您更喜欢手动配置，请执行以下步骤：
1. 打开 AWS DMS 控制台，选择**创建复制实例**。
1. 输入复制实例的详细信息：
+ **实例名称**：选择唯一名称。
+ **实例类**：根据工作负载进行选择。示例：dms.r5.large（小型工作负载），dms.r5.4xlarge（大型工作负载）。
+ **引擎版本**：3.5.4
+ **分配的存储空间**：默认值为 100GB（如果需要可增加）。这取决于文档大小 updates/second 和满载持续时间。
+ **多可用区部署**：如果需要，启用以实现高可用性。
+ 选择与 Amazon DocumentDB 相同的 VPC。
+ 确保**安全组**允许来自源和 Amazon DocumentDB 的入站流量。
1. 单击**创建复制实例**，等待状态变为可用。
#### 创建 DMS 端点
##### 创建源端点
**对于 MongoDB 源**
1. 在 DMS 控制台的导航窗格中，选择**迁移或复制**，然后选择**端点**。
1. 选择**创建端点**。
1. 在**创建端点**页面上，选择**源端点**。
1. 在**端点配置**部分中：
+ 输入唯一且有意义的**端点标识符**（例如，“mongodb-source”）。
+ 选择 **MongoDB** 作为**源引擎**。
+ 对于**端点数据库的访问权限**，请选择**手动提供访问信息**。
+ 在**服务器名称**中，输入您的*MongoDB server DNS name/IP address*。
+ 对于**端口**，输入 **27017**（默认 MongoDB 端口）。
+ 对于**身份验证模式**，为您的应用程序选择适当的模式（密码/SSL）（默认为 Secrets Manager）。
+ 如果**身份验证模式**为**密码**，请提供：
+ **用户名**和**密码**：输入 MongoDB 凭证。
+ **数据库名称**：您的源数据库名称。
+ **身份验证机制**：SCRAM-SHA-1（默认）或适当的机制
1. 对于**元数据模式**，保留**文档**的默认设置。
1. 其他连接属性：
+ authSource=admin（如果身份验证数据库不同）
+ replicaset=< your-replica-set-name >（CDC 是必需的）
**对于 Amazon DocumentDB 源**
1. 在 DMS 控制台的导航窗格中，选择**迁移或复制**，然后选择**端点**。
1. 选择**创建端点**。
1. 在**创建端点**页面上，选择**源端点**。
1. 在**端点配置**部分中：
+ 输入唯一且有意义的**端点标识符**（例如，“docdb-source”）。
+ 选择 **Amazon DocumentDB** 作为**源引擎**。
+ 对于**端点数据库的访问权限**，请选择**手动提供访问信息**。
+ 在**服务器名称**中，输入您的*source Amazon DocumentDB cluster endpoint*。
+ 对于**端口**，输入 **27017**（默认的 Amazon DocumentDB 端口）。
+ 对于 **SSL 模式**，选择 **verify-full**（推荐用于 Amazon DocumentDB）。
+ 对于 **CA 证书**，选择 Amazon RDS 根 CA 证书。
+ 对于**身份验证模式**，为您的应用程序选择适当的模式（密码/SSL）（默认为 Secrets Manager）。
+ 如果**身份验证模式**为**密码**，请提供：
+ **用户名**和**密码**：输入 Amazon DocumentDB 凭证。
+ **数据库名称**：您的源数据库名称。
+ **身份验证机制**：SCRAM-SHA-1（默认）或适当的机制
1. 对于**元数据模式**，保留**文档**的默认设置。
##### 创建目标端点（Amazon DocumentDB）
1. 在 DMS 控制台的导航窗格中，选择**迁移或复制**，然后选择**端点**。
1. 选择**创建端点**。
1. 在**创建端点**页面中，选择**目标端点**。
1. 在**端点配置**部分中：
+ 输入唯一且有意义的**端点标识符**（例如，“docdb-target”）。
+ 选择 **Amazon DocumentDB** 作为**目标引擎**。
+ 对于**访问端点数据库**，选择要用于对数据库的访问进行身份验证的方法：
+ 如果您选择 **AWS Secrets Manager**，请在**密钥**字段中选择其中存储有 Amazon DocumentDB 凭证的密钥。
+ 如果您选择**手动提供访问信息**：
+ 在**服务器名称**中，输入您的*target Amazon DocumentDB cluster endpoint*。
+ 对于**端口**，输入 **27017**（默认的 Amazon DocumentDB 端口）。
+ 对于 **SSL 模式**，选择 **verify-full**（推荐用于 Amazon DocumentDB）。
+ 对于 **CA 证书**，下载并指定用于 SSL 验证的 CA 证书捆绑包。
+ 对于**身份验证模式**，为您的应用程序选择适当的模式（密码/SSL）（默认为 Secrets Manager）。
+ 如果**身份验证模式**为**密码**，请提供：
+ **用户名**和**密码**：输入 Amazon DocumentDB 凭证。
+ **数据库名称**：您的源数据库名称。
+ **身份验证机制**：SCRAM-SHA-1（默认）或适当的机制
1. 对于**元数据模式**，保留**文档**的默认设置。
#### 创建复制任务
1. 在 DMS 控制台的导航窗格中，选择**迁移或复制**，然后选择**任务**。
1. 选择**创建任务**。
1. 在**创建任务**页面的**任务配置**部分中：
+ 输入唯一且有意义的**任务标识符**（例如，mongodb-docdb-replication“”）。
+ 在**源数据库端点**下拉菜单中选择您之前创建的源端点。
+ 在**目标数据库端点**下拉菜单中选择您之前创建的目标端点。
+ 对于**任务类型**，选择**迁移和复制**。
1. 在**设置**部分中：
+ 对于**目标表准备模式**，保留默认设置。
+ 对于**在完全加载完成后停止任务**，保留默认设置。
+ 对于 **LOB 列设置**，按原样保留**受限 LOB 模式**设置。
+ 对于**数据验证**，保留默认设置**关闭**。
+ 对于**任务日志**，请选中 “**打开日 CloudWatch**志” 复选框。
+ 对于**批处理优化的应用**，保留默认设置为未选中（关闭）。
1. 回到**任务设置**部分的顶部，在**编辑模式**中选择 **JSON 编辑器**并设置以下属性：
```
{
"TargetMetadata": {
"ParallelApplyThreads": 5
},
"FullLoadSettings": {
"MaxFullLoadSubTasks": 16
}
}
```
1. 在**表映射**部分中，添加新选择规则：
+ 对于**架构名称**，添加要迁移的源数据库。使用 % 指定多个数据库。
+ 对于**架构表**名称，添加要迁移的源集合。使用 % 指定多个集合。
+ 对于**操作**，保留默认设置**包含**
1. 对于大型集合（超过 100GB），添加**表设置规则**：
+ 对于**架构名称**，添加要迁移的源数据库。使用 % 指定多个数据库。
+ 对于**架构表**名称，添加要迁移的源集合。使用 % 指定多个集合。
+ 对于**分区数**，输入 16（应小于 `MaxFullLoadSubTask`）。
1. 在**迁移前评测**部分中，确保将其关闭。
### 离线迁移
本节概述了使用原生 MongoDB 工具 `mongodump` 和 `mongorestore` 执行从自行管理的 MongoDB 实例到 Amazon DocumentDB 的离线迁移流程。
### 先决条件
**源 MongoDB 要求**
+ 使用适当的权限访问源 MongoDB 实例。
+ 如果需要，请安装 `mongodump`（在 MongoDB 安装期间进行安装）。
+ 确保有足够的磁盘空间来存放转储文件。
**目标 Amazon DocumentDB 要求**
+ 确保您已预置 Amazon DocumentDB 集群。
+ 确保在与 Amazon DocumentDB 相同的 VPC 中存在 EC2 实例，以方便迁移。
+ 您的源环境与 Amazon DocumentDB 之间必须有可用的网络连接。
+ **mongorestore** 必须安装在迁移 EC2 实例上。
+ 必须配置适当的 IAM 权限才能访问 Amazon DocumentDB，
**一般要求**
+ AWS CLI 必须配置（如果使用 AWS 服务进行中间存储）
+ 必须有足够的带宽可用于数据传输。
+ 应批准停机时间（如果要进行实时迁移，请考虑其他方法）
### 准备 Amazon DocumentDB 集群
在 AWS中创建 Amazon DocumentDB 集群：
+ 根据您的工作负载选择合适的实例大小。
+ 配置 VPC、子网和安全组。
+ 通过参数组启用必要的参数。
### 执行数据转储（mongodump）
选择以下选项之一来创建转储文件：
+ **选项 1：基本**
```
mongodump --
uri="mongodb://:@:/" --
out=/path/to/dump
```
+ **选项 2：更优的控制和性能**
```
mongodump \
--uri="mongodb://:@:" \
--out=/path/to/dump \
--gzip \# Compress output
--numParallelCollections=4 \# Parallel collections dump
--ssl \# If using SSL
--authenticationDatabase=admin \ # If auth is required
--readPreference=secondaryPreferred # If replica set
```
+ **选项 3：大型数据库**
```
mongodump \
--host= \
--port= \
--username= \
--password= \
--db= \# Only dump specific DB
--collection= \ # Only dump specific collection
--query='{ "date": { "$gt": "2020-01-01" } }' \ # Filter documents
--archive=/path/to/archive.gz \# Single archive output
--gzip \
--ssl
```
### 将转储文件传输到恢复环境
根据您的转储大小选择适当的方法：
+ **小**：直接复制到您的迁移机器（您之前创建的 EC2 实例）：
```
scp -r /path/to/dump user@migration-machine:/path/to/restore
```
+ **中**：使用 Amazon S3 作为中间存储：
```
aws s3 cp --recursive /path/to/dump s3://your-bucket/mongodb-dump/
```
+ **大型** — 对于非常大的数据库，可以考虑 AWS DataSync 物理传输。
### 将数据恢复到 Amazon DocumentDB（mongorestore）
在开始恢复过程之前，请在 Amazon DocumentDB 中创建索引。您可以使用 [Amazon DocumentDB 索引工具](https://github.com/awslabs/amazon-documentdb-tools/tree/master/index-tool)导出和导入索引。
选择以下选项之一来恢复数据：
+ **选项 1：基本恢复**
```
mongorestore --uri="mongodb://:@:27017"
/path/to/dump
```
+ **选项 2：更优的控制和性能**
```
mongorestore \
--uri="mongodb://:@:27017" \
--ssl \
--sslCAFile=/path/to/rds-combined-ca-bundle.pem \ # DocumentDB CA cert
--gzip \# If dumped with gzip
--numParallelCollections=4 \# Parallel restoration
--numInsertionWorkersPerCollection=4 \# Parallel documents insertion
--noIndexRestore \# skip indexes as they are pre-created
/path/to/dump
```
+ **选项 3：大型数据库或特定控件**
```
mongorestore \
--host= \
--port=27017 \
--username= \
--password= \
--ssl \
--sslCAFile=/path/to/rds-combined-ca-bundle.pem \
--archive=/path/to/archive.gz \# If using archive format
--gzip \
--nsInclude="db1.*" \# Only restore specific namespaces
--nsExclude="db1.sensitive_data" \ # Exclude specific collections if needed
--noIndexRestore \# skip indexes as they are pre-created
--writeConcern="{w: 'majority'}" # Ensure write durability
```
## 监控
本节提供了详细的监控流程，用于跟踪正在进行的迁移的进度、性能和运行状况：
从 **MongoDB** 迁移到 **Amazon DocumentDB**
或者
从 **Amazon DocumentDB** 迁移到 **Amazon DocumentDB**
无论采用哪种迁移方法（AWS DMS、mongodump/mongorestore 或其他工具），监控步骤都适用。
### AWS DMS 迁移监控（如果适用）
监控以下关键 CloudWatch 指标：
**完全加载阶段指标**
+ **FullLoadThroughputBandwidthTarget**— 满负荷期间的网络带宽（KB/秒）
+ **FullLoadThroughputRowsTarget**— 每秒 rows/documents 加载的次数
+ **FullLoadThroughputTablesTarget**— 每分钟 tables/collections 完成的次数
+ **FullLoadProgressPercent**— 满载完成的百分比
+ **TablesLoaded**— tables/collections 成功加载的数量
+ **TablesLoading**— tables/collections 当前加载的数量
+ **TablesQueued**— tables/collections 等待加载的次数
+ **TablesErrored**— 加载 tables/collections 失败的数量
**CDC 阶段指标**
+ **CDCLatency目标**-源更改和目标应用程序之间的时间延迟（秒）
+ **CDCLatency来源-源**变更与 DMS 读取源之间的时间延迟（秒）
+ **CDCThroughputRowsTarget**— 正在进行的复制期间应用的每秒行数
+ **CDCThroughputBandwidthTarget**— CDC 期间的网络带宽（KB/秒）
+ **CDCIncoming更改**-从源收到的变更事件的数量
+ **CDCChangesMemoryTarget**— 用于在目标端存储更改的内存 (MB)
**资源指标**
+ **CPUUtilization**— 复制实例的 CPU 使用率
+ **FreeableMemory**— 复制实例上的可用内存
+ **FreeStorageSpace**— 复制实例上的可用存储空间
+ **NetworkTransmitThroughput**— 复制实例的网络吞吐量
+ **NetworkReceiveThroughput**— 复制实例的网络吞吐量
**错误指标**
+ **ErrorsCount**— 迁移期间的错误总数
+ **TableErrorsCount**— 特定于表格的错误数量
+ **RecordsErrorsCount**— 特定于记录的错误数量
为诸如迁移性能下降之类的关键指标创建 CloudWatch 警报`CPUUtilization`，`CDCLatencyTarget`并在迁移性能下降时接收通知。
#### DMS 日志（日CloudWatch 志）
1. 前往 Amazon CloudWatch 日志控制台。
1. 在您的日志组中进行查找和选择。看起来类似于“dms-tasks –”。
1. 查找可能包含错误信息的日志流：
+ 名称中带有“error”的流
+ 带有任务 IDs 或终端节点名称的直播
+ 迁移期间的最新日志流
1. 在这些流中，搜索关键词，例如：
+ “error”
+ “exception”
+ “failed”
+ “warning”
#### DMS 任务状态（使用 AWS CLI）
```
aws dms describe-replication-tasks --filters Name=replication-task id,Values= --query
"ReplicationTasks[0].Status"
```
预期的状态流：
正在创建 → 就绪 → 正在运行 → 正在停止 → 已停止（或失败）
#### 监视器使用 `docdb-dashboarder`
该`docdb-dashboarder`工具通过自动生成包含基本性能指标的 CloudWatch 控制面板，为 Amazon DocumentDB 集群提供全面监控。这些控制面板显示关键的集群级别指标（副本延迟、操作计数器）、实例级别指标（CPU、内存、连接）以及存储指标（卷使用率、备份存储）。对于迁移场景，该工具提供专用控制面板，可通过 CDC 复制延迟和操作率等指标来跟踪迁移进度。仪表板可以同时监控多个集群，并支持 NVMe由支持的实例。通过可视化这些指标，团队可以主动识别性能瓶颈，优化资源分配，并确保其 Amazon DocumentDB 部署顺利运行。该工具无需手动创建控制面板，同时在所有环境中提供一致的监控。有关设置说明和高级配置选项，请参阅 [Amazon DocumentDB 仪表板](https://github.com/awslabs/amazon-documentdb-tools/tree/master/monitoring/docdb-dashboarder)工具存储库。 GitHub
## 验证
**Topics**
+ [验证核对清单](#w2aac25b9c25c15)
+ [架构和索引验证](#w2aac25b9c25c17)
+ [数据采样和字段级别验证](#w2aac25b9c25c19)
+ [使用 DataDiffer 工具进行验证](#w2aac25b9c25c21)
本节提供详细的验证流程，以确保以下迁移后的数据一致性、完整性和应用程序兼容性：
从 **MongoDB** 迁移到 **Amazon DocumentDB**
或者
从 **Amazon DocumentDB** 迁移到 **Amazon DocumentDB**
无论采用哪种迁移方法（AWS DMS、mongodump/mongorestore 或其他工具），验证步骤都适用。
### 验证核对清单
验证每个集合中的文档数量在源与目标之间是否匹配：
**MongoDB 源**
```
mongo --host --port --username -- password --eval
"db..count()"
```
**Amazon DocumentDB 目标**
```
mongo --host --port --username -- password --eval
"db..count()"
```
### 架构和索引验证
请确保：
+ 所有集合都存在于目标中。
+ 索引已正确复制。
+ 架构定义（如果强制执行）相同。
**检查集合（源与目标）**
```
mongo --host --eval "show collections"
mongo --host --ssl --eval "show collections"
```
**检查索引（源与目标）**
```
mongo --host --eval" db..getIndexes()"
mongo --host --ssl –eval" db..getIndexes()"
```
比较集合列表，确保没有缺失或多余的集合。
通过检查索引名称、键定义、唯一约束和 TTL 索引（如果有）来验证索引。
**检查架构验证规则（如果在 MongoDB 中使用架构验证）**
```
mongo --host --eval" db.getCollectionInfos({name: ''})
[0].options.validator"
mongo --host --ssl –eval" db.getCollectionInfos({name: ''})[0].options.validator"
```
### 数据采样和字段级别验证
您可以对文档进行随机采样，并比较源与目标之间的字段。
**手动采样**
获取五个随机文档（源）：
```
mongo --host --eval "db..aggregate([{ \$sample: { size: 5 } }])"
```
获取相同的文档 IDs （目标）：
```
mongo --host --ssl –eval "db..find({ _id: { \$in: [] } })"
```
**自动采样**
```
import pymongo
# Connect to source and target
source_client = pymongo.MongoClient("")
target_client = pymongo.MongoClient("", ssl=True)
source_db = source_client[""]
target_db = target_client[""]
# Compare 100 random documents
for doc in source_db..aggregate([{ "$sample":
{ "size": 100 } }]):
target_doc = target_db..find_one({ "_id":
doc["_id"] })
if target_doc != doc:
print(f"❌ Mismatch in _id: {doc['_id']}")
else:
print(f"✅ Match: {doc['_id']}")
```
### 使用 DataDiffer 工具进行验证
该[DataDiffer 工具](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/data-differ)提供了一种在源数据库和目标数据库之间比较数据的可靠方法。
#### 先决条件
安装该 DataDiffer 工具之前，必须满足以下先决条件：
+ Python 3.7\$1
+ PyMongo 图书馆
+ 到源 MongoDB 集群和目标 Amazon DocumentDB 集群的网络连接
#### 设置和安装
**克隆存储库并导航到该 DataDiffer 目录**
```
git clone https://github.com/awslabs/amazon-documentdb-tools.git
cd amazon-documentdb-tools/migration/data-differ
```
**安装所需的依赖项**
```
pip install -r requirements.txt
```
#### 运行数据验证
**创建包含连接详细信息的配置文件（例如 config.json）**
```
{
"source": {
"uri": "mongodb://username:password@source-mongodb-
host:27017/?replicaSet=rs0",
"db": "your_database",
"collection": "your_collection"
},
"target": {
"uri": "mongodb://username:password@target-docdb-
cluster.region.docdb.amazonaws.com:27017/?tls=true&tlsCAFile=global-
bundle.pem&replicaSet=rs0",
"db": "your_database",
"collection": "your_collection"
},
"options": {
"batch_size": 1000,
"threads": 4,
"sample_size": 0,
"verbose": true
}
}
```
**运行该 DataDiffer 工具**
```
python differ.py --config config.json
```
**对于大型集合，使用采样来验证数据子集**
```
python differ.py --config config.json --sample-size 10000
```
**要验证多个集合，请创建单独的配置文件或使用批处理模式**
```
python differ.py --batch-config batch_config.json
```
#### 解析结果
工具将输出：
+ 源和目标中的文档总数量
+ 匹配文档的数量
+ 缺失文档的数量
+ 存在差异的文档的数量
+ 详细的差异报告（如果有）
#### 最佳实践
以下是使用该 DataDiffer 工具时的最佳做法：
+ **分阶段运行**：首先验证文档数量，然后对关键文档进行采样，最后根据需要进行全面比较。
+ **检查架构差异**：与 MongoDB 相比，Amazon DocumentDB 有一些限制。该工具将突出显示不兼容的数据类型或结构。
+ **在静默期间进行验证**：在写入操作最少时运行验证以确保一致性。
+ **监控资源使用情况**：比较过程可能占用大量资源。相应地调整批处理大小和线程数。
+ **验证索引**：数据验证后，确保已在目标 Amazon DocumentDB 集群上创建所有必需的索引。
+ **文档验证结果**：记录每个集合的验证结果，将其作为迁移文档的一部分。