本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # Amazon DocumentDB 迁移运行手册 本运行手册为使用 AWS Database Migration Service (DMS) 将 MongoDB 数据库迁移到 Amazon DocumentDB 提供了全面的指南。旨在从初始发现到迁移后验证的整个端到端迁移过程中，为数据库管理员、云工程师和开发人员提供支持。 鉴于 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** + [核心功能兼容性](#w2aac15b9c13c13) + [Amazon DocumentDB 兼容性评测工具](#w2aac15b9c13c15) 从 MongoDB 迁移到 Amazon DocumentDB 时，全面的初始评测和功能兼容性检查是成功迁移的关键。此过程从全面清点您的 MongoDB 功能开始，包括聚合管道运算符、查询模式、索引和数据模型。 由于 Amazon DocumentDB 与 MongoDB 3.6、4.0、5.0 和 8.0 的 API 兼容，因此使用新 MongoDB-specific 功能的应用程序可能需要重构。需要评估的关键领域包括分片机制（Amazon DocumentDB 使用不同的方法）、事务实现、变更流功能以及索引类型（尤其是稀疏索引和部分索引）。 性能特征也存在差异，Amazon DocumentDB 针对企业工作负载进行了优化，性能可预测。测试应包括对两个系统运行具有代表性的工作负载，以识别可能需要优化的查询模式。 在评测阶段，监控执行计划以发现潜在的性能差距非常重要。这有助于制定清晰的迁移路线图，识别必要的应用程序变更以及建立切合实际的时间表，以便实现平稳过渡。 ### 核心功能兼容性 #### 全面功能支持 + **CRUD 操作**：全面支持所有基本的创建、读取、更新和删除操作（包括批量和查询运算符），从而提供无缝的应用程序兼容性。 + **丰富的索引功能**：利用对单字段索引、复合索引、TTL 索引、部分索引、稀疏索引和 2dsphere 索引的全面支持，优化查询性能，以及利用文本索引（版本 5）进行基于文本的查找。 + **Enterprise-grade 复制 ** — 受益于带有只读副本的强大自动故障转移机制，无需运营开销即可实现卓越的高可用性。 + **高级备份解决方案 **-自动备份系统具有 Point-in-Time 恢复 (PITR) 和按需手动快照功能，可保护数据，让您高枕无忧。 #### 增强 AWS-集成功能 + **简化的聚合**：利用最常用的聚合阶段（`$match`、`$group`、`$sort`、`$project` 等），已针对企业工作负载优化性能。 + **事务支持**：实现多文档和多集合事务，非常适合大多数业务应用程序需求。 + **Real-time 数据跟踪 **-通过简单的命令启用变更流，并通过用于实时数据变更监控的简单参数组设置延长变更流保留期。 + **Location-based 服务 ** — 在支持`$geoNear`运算符和 2dsphere 索引的情况下实现地理空间应用程序。 + **文本搜索功能**：利用内置的文本搜索功能满足内容发现需求。 #### 现代架构优势 + **Cloud-native 设计 ** — 享受 AWS经过优化的架构，该架构取代了传统功能，例如 MapReduce 更有效的聚合管道操作。 + **增强的安全性 ** — 受益于 AWS Identity and Access Management (IAM)、 SCRAM-SHA-1、 SCRAM-SHA-256、 X.509 证书身份验证和基于密码的身份验证。 + **可预测的性能**：体验专为企业工作负载而优化的稳定性能。 要全面了解 Amazon DocumentDB 的功能，请参阅 [Amazon DocumentDB 中支持的 MongoDB API、操作和数据类型](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) GitHub 来检查兼容性。运行索引工具来评估不兼容性并相应地规划变通方案。 ### Amazon DocumentDB 兼容性评测工具 [Amazon DocumentDB 兼容性工具](https://github.com/awslabs/amazon-documentdb-tools/blob/master/compat-tool/README.md)可 GitHub 分析您的MongoDB工作负载并报告 Amazon DocumentDB 中不支持或需要更改的操作员、命令和功能。它支持从 3.6 到 8.0.1 的目标版本（默认值：8.0.1）。 **推荐：URI 模式 (MongoDB5.0\+) ** URI 模式直接连接到您的 MongoDB 实例，实时对操作进行示例，无需分析或日志访问权限。 **替代方法** + **Log-based 分析 **-解析MongoDB分析器日志。捕获实际的运行时行为，但需要启用分析，并且仅涵盖日志记录周期。 + **源代码分析 **-扫描应用程序源代码以查找 MongoDB API 使用情况。提供全面的覆盖范围，但可能会标记未使用的代码路径，并且无法检测到动态构造的查询。 **先决条件** + Python3.7\+ + 克隆该工具：`git clone https://github.com/awslabs/amazon-documentdb-tools.git` + 安装依赖项：`pip install -r compat-tool/requirements.txt` 有关完整的使用详情和所有可用选项，请参阅[上的](https://github.com/awslabs/amazon-documentdb-tools/blob/master/compat-tool/README.md) GitHub自述文件。 ## 工作负载发现 从 MongoDB 迁移到 Amazon DocumentDB 需要对现有数据库工作负载有透彻的了解。工作负载发现是分析数据库使用模式、数据结构、查询性能和操作依赖关系的过程，旨在确保以最少的中断实现无缝过渡。本节概述了工作负载发现所涉及的关键步骤，以促进从 MongoDB 到 Amazon DocumentDB 的有效迁移。 **Topics** + [评测现有的 MongoDB 部署](#w2aac15b9c15b7) + [识别数据模型差异](#w2aac15b9c15b9) + [查询和性能分析](#w2aac15b9c15c11) + [安全与访问控制审查](#w2aac15b9c15c13) + [操作和监控注意事项](#w2aac15b9c15c15) ### 评测现有的 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-compatible，但支持的功能有所不同，例如： + **事务**：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 到 Amazon DocumentDB IAM 和 RBAC ** — 将 MongoDB 基于角色的访问控制用户和角色映射到 AWS Identity and Access Management (IAM) 策略和 Amazon 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 服务进行集中备份管理。 + **CloudWatch 指标 ** — 将 MongoDB 监控指标映射到 Amazon DocumentDB 的 CPU、内存、连接和存储 CloudWatch 指标。 + **性能详情**：实施 Amazon DocumentDB 性能详情，以通过详细的查询分析，可视化数据库负载并分析性能问题。 + **Profiler ** — 配置 Amazon DocumentDB 分析器以捕获运行缓慢的操作（类似于 MongoDB 的分析器，但使用亚马逊设置）。 DocumentDB-specific + 通过参数组启用并设置适当的阈值。 + 分析探查器数据以识别优化机会 + **CloudWatch 事件 ** — 为 Amazon DocumentDB 集群事件设置事件驱动的监控。 + 为备份事件、维护时段和失效转移配置通知。 + 与 Amazon SNS 集成以发出警 AWS Lambda 报和自动响应。 + **审计日志记录**：规划审计日志记录配置，以跟踪用户活动和安全相关事件。 + **增强监控 **-以 1 秒为间隔启用对精细 OS-level 指标的增强监控。 ## 创建新的目标集群 按照中的[创建 Amazon DocumentDB 集群](db-cluster-create.md)步骤创建 Amazon DocumentDB 集群。配置集群进行迁移时，请应用以下建议： + **实例类别：**选择 R8G 以获得最佳性能。如果目标区域不可用 R8G，请使用 R6G。选择尽可能大的实例以获得最佳的满载吞吐量。迁移完成后缩小规模。 + **引擎版本：**最新 (8.0.1) + **实例数量：**选择 1 个实例以最大限度地降低迁移期间的成本。满负载迁移完成后，扩展到 3 个实例以实现高可用性。 + **网络设置：**确保您的 Amazon DocumentDB 安全组允许来自 DMS 复制实例的安全组（用于在线迁移）或 EC2 迁移主机（用于使用 mongorestore 的离线迁移）的入站连接。 ## 索引迁移 从 MongoDB 迁移到 Amazon DocumentDB 不仅需要传输数据，还需要传输索引，以保持查询性能和优化数据库操作。本节概述了在确保兼容性和效率的同时，将索引从 MongoDB 迁移到 Amazon DocumentDB 的详细分步流程。 ### 使用 Amazon DocumentDB 索引工具 **克隆[索引工具 ](https://github.com/awslabs/amazon-documentdb-tools/blob/master/index-tool/README.md) GitHub ** ``` git clone https://github.com/awslabs/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 index_export \ --uri 'mongodb://:@:27017' ``` **验证索引** ``` python3 migrationtools/documentdb_index_tool.py \ --show-issues \ --dir index_export ``` **导入索引** ``` python3 migrationtools/documentdb_index_tool.py \ --restore-indexes \ --skip-incompatible \ --dir index_export \ --uri 'mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&retryWrites=false' ``` ## 用户迁移 将用户从 MongoDB 迁移到 Amazon DocumentDB 对于维护访问控制、身份验证和数据库安全至关重要。本节概述了使用 Amazon DocumentDB 导出用户工具成功迁移 MongoDB 用户，同时保留其角色和权限的详细步骤。 ### 使用 Amazon DocumentDB 导出用户工具 将用户和角色从 MongoDB 或 Amazon DocumentDB [`Export Users tool`](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://:@:27017" ``` **步骤 2：编辑用户文件** 出于安全原因，不导出密码。打开`mongodb-users.js`文件并通过替换每条`createUser`语句中的`pwd`值为每个用户添加密码： ``` db.getSiblingDB("admin").createUser({ user: "appuser", pwd: "REPLACE_THIS_PASS", roles: [ { role: "readWrite", db: "mydb" } ] }) ``` **步骤 3：将自定义角色恢复到 Amazon DocumentDB** ``` # Import roles first mongosh \ --tls \ --host :27017 \ --tlsCAFile global-bundle.pem \ --username {{}} \ --password {{}} \ mongodb-roles.js ``` **步骤 4：将用户恢复到 Amazon DocumentDB** ``` # Import users after roles are created mongosh \ --tls \ --host :27017 \ --tlsCAFile global-bundle.pem \ --username {{}} \ --password {{}} \ mongodb-users.js ``` **重要提示** + 出于安全考虑，不会导出密码，必须手动将密码添加到 users.js 文件中。 + 必须先导入角色再导入用户，以确保角色分配正确。 + 该工具生成可以直接使用 mongosh shell 执行的 JavaScript 文件。 + 迁移期间会保留自定义角色及其权限。 + 此方法允许在导入之前查看和修改用户权限。 此方法提供了一种安全且灵活的途径将用户和角色从 MongoDB 迁移到 Amazon DocumentDB，同时允许在迁移过程中重置密码。 ## 数据迁移 **Topics** + [在线迁移](#w2aac15b9c23b5) + [离线迁移](#w2aac15b9c23b7) ### 在线迁移 本节提供详细步骤，使用这些步骤执行从 MongoDB 到 Amazon DocumentDB 的在线迁移，以最大限度 AWS DMS 地缩短停机时间并实现持续复制。首先，您需要将 Amazon DocumentDB 集群设置为目标，并确保将 MongoDB 实例正确配置为源，通常需要副本集模式才能捕获变更数据。接下来，您将创建 DMS 复制实例，并使用必要的连接详细信息定义源端点和目标端点。验证端点后，配置并启动迁移任务，该任务可能包括完全数据加载和/或持续复制。 #### 创建新的目标集群 请参阅[创建新的目标集群](#mig-runbook-configure-target)。 #### 配置源 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: "{{}}", roles: [{ role: "readAnyDatabase", db: "admin" }] }) ``` 配置网络和身份验证。 在为 MongoDB 到 DMS 的迁移配置网络连接时： **EC2-hosted MongoDB 源** + 修改 EC2 安全组以允许来自 DMS 复制实例安全组的入站流量。 + 为 TCP 端口 27017（或您的自定义 MongoDB 端口）添加规则。 + 使用 DMS 复制实例的安全组 ID 作为源，以实现精确访问控制。 + 确保 EC2 实例的子网可路由至 DMS 复制实例的子网。 **On-premises 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 设置和实例大小的最佳迁移基础架构。 GitHub 如果您更喜欢手动配置，请执行以下步骤： 1. 在 AWS DMS 控制台的导航窗格中，选择**迁移或复制**，然后选择**预置实例**。 1. 输入复制实例的详细信息： + **实例名称**：选择唯一名称。 + **实例类**：根据工作负载进行选择。示例：dms.r7i.large（小型工作负载）、dms.r7i.4xlarge（大型工作负载）。 + **引擎版本**：3.5.4 + **分配的存储空间**：默认值为 50 GB（如果需要可以增加）。这取决于文档大小 updates/second 和满载时长。 + **Multi-AZ 部署**：根据需要启用高可用性。 + 选择与 Amazon DocumentDB 相同的 VPC。 + 确保**安全组**允许来自源和 Amazon DocumentDB 的入站流量。 1. 选择**创建复制实例**，然后等待状态变为可用。 #### 创建 DMS 端点 ##### 创建源端点 **对于 MongoDB 源** 1. 在 DMS 控制台的导航窗格中，选择**迁移或复制**，然后选择**端点**。 1. 选择**创建端点**。 1. 在**创建端点**页面上，选择**源端点**。 1. 在**端点配置**部分中： + 输入唯一且有意义的**端点标识符**（例如，“mongodb-source”）。 + 选择 **MongoDB** 作为**源引擎**。 + 对于**端点数据库的访问权限**，请选择**手动提供访问信息**。 + 对于**服务器名称**，输入您的{{MongoDB server DNS name/IP address}}。 + 对于**端口**，输入 **27017**（默认 MongoDB 端口）。 + 对于**身份验证模式**，请为您的应用程序选择相应的模式 (password/SSL)（默认为密钥管理器）。 + 如果**身份验证模式**为**密码**，请提供： + **用户名**和**密码**：输入 MongoDB 凭证。 + **数据库名称**：您的源数据库名称。 + **身份验证机制**： SCRAM-SHA-1 （默认）或相应的机制 1. 对于**元数据模式**，保留**文档**的默认设置。 1. 其他连接属性： + authSource=admin（如果身份验证数据库不同） + replicaSet=（对于 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 证书。 + 对于**身份验证模式**，请为您的应用程序选择相应的模式 (password/SSL)（默认为密钥管理器）。 + 如果**身份验证模式**为**密码**，请提供： + **用户名**和**密码**：输入 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 证书捆绑包。 + 对于**身份验证模式**，请为您的应用程序选择相应的模式 (password/SSL)（默认为密钥管理器）。 + 如果**身份验证模式**为**密码**，请提供： + **用户名**和**密码**：输入 Amazon DocumentDB 凭证。 + **数据库名称**：您的源数据库名称。 + **身份验证机制**： SCRAM-SHA-1 （默认）或相应的机制 1. 对于**元数据模式**，保留**文档**的默认设置。 #### 创建复制任务 1. 在 DMS 控制台的导航窗格中，选择**迁移或复制**，然后选择**任务**。 1. 选择**创建任务**。 1. 在**创建任务**页面的**任务配置**部分中： + 输入唯一且有意义的**任务标识符**（例如，“mongodb-docdb-replication”）。 + 在**源数据库端点**下拉菜单中选择您之前创建的源端点。 + 在**目标数据库端点**下拉菜单中选择您之前创建的目标端点。 + 在**预置实例**下拉菜单中选择您之前创建的复制实例。 + 对于**任务类型**，选择**迁移和复制**。 + 您打算继续从源复制到目标多长时间？****，选择 “**限时使用” **。 1. 在**设置**部分中： + 在 T ** arget 表格准备模式下**，选择 “不**执行任何操作” **。否则，已经创建的集合和索引将被删除。 + 对于**任务日志**，选中**开启 CloudWatch**日志复选框。 + 保留所有其他设置的默认值。 1. 回到**设置**部分的顶部，在**编辑模式下**，选择 ** JSON 编辑器**并设置以下属性： ``` { "TargetMetadata": { "ParallelApplyThreads": 5 }, "FullLoadSettings": { "MaxFullLoadSubTasks": 16 } } ``` `MaxFullLoadSubTasks`根据您的收集数量和实例容量进行设置。对于较少或较小的集合，使用较低的值 (2—4)，对许多大型集合使用较高的值 (8—16)。要自动调整大小，请参阅 [ DMS Buddy ](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/dms_buddy) 开 GitHub启。 1. 在**表映射**部分中，添加新选择规则： + 对于**架构名称**，添加要迁移的源数据库。使用 % 指定多个数据库。 + 对于**架构表**名称，添加要迁移的源集合。使用 % 指定多个集合。 + 对于**操作**，保留默认设置**包含** 1. 对于大型集合（超过 100GB），添加**表设置规则**： + 对于**架构名称**，添加要迁移的源数据库。使用 % 指定多个数据库。 + 对于**架构表**名称，添加要迁移的源集合。使用 % 指定多个集合。 + 对于分区**数量**，根据您的工作负载进行设置。对于少量大型集合，将分区设置为 ≥ `MaxFullLoadSubTasks` 以使所有工作人员忙碌。对于许多并行加载的集合，将分区设置为 ≤，`MaxFullLoadSubTasks`因为集合数本身提供了足够的并行度。 1. 在**迁移前评测**部分中，确保将其关闭。不支持将 Amazon DocumentDB 作为目标进行迁移前评估，必须将其禁用。 ### 离线迁移 本节概述了使用原生 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 集群 请参阅[创建新的目标集群](#mig-runbook-configure-target)。 #### 执行数据转储（mongodump） 选择以下选项之一来创建转储文件： + **选项 1：基本** ``` mongodump \ --uri="mongodb://{{}}:{{}}@{{}}:27017/{{}}" \ --out=/path/to/dump ``` + **选项 2：更优的控制和性能** 使用 gzip 压缩输出，并行转储集合，启用 TLS，并从辅助副本（如果可用）读取： ``` mongodump \ --uri="mongodb://{{}}:{{}}@{{}}:27017" \ --out=/path/to/dump \ --gzip \ --numParallelCollections=4 \ --tls \ --authenticationDatabase=admin \ --readPreference=secondaryPreferred ``` + **选项 3：大型数据库** 转储特定的数据库和集合，按查询筛选文档，并将输出到单个压缩存档中： ``` mongodump \ --host={{}} \ --port=27017 \ --username={{}} \ --password={{}} \ --db={{}} \ --collection={{}} \ --query='{ "date": { "$gt": "2020-01-01" } }' \ --archive=/path/to/archive.gz \ --gzip \ --tls ``` #### 将转储文件传输到恢复环境 根据您的转储大小选择适当的方法： + **小**：直接复制到您的迁移机器（您之前创建的 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" \ --tls \ --tlsCAFile=global-bundle.pem \ /path/to/dump ``` + **选项 2：更优的控制和性能** 通过并行收集和文档插入来恢复 gzip 压缩的转储。由于索引是预先创建的，因此跳过索引恢复： ``` mongorestore \ --uri="mongodb://{{}}:{{}}@{{}}:27017" \ --tls \ --tlsCAFile=global-bundle.pem \ --gzip \ --numParallelCollections=4 \ --numInsertionWorkersPerCollection=4 \ --noIndexRestore \ /path/to/dump ``` + **选项 3：大型数据库或特定控件** 使用命名空间筛选从压缩档案中恢复，以包括或排除特定的数据库和集合。由于索引是预先创建的，因此跳过索引恢复： ``` mongorestore \ --host={{}} \ --port=27017 \ --username={{}} \ --password={{}} \ --tls \ --tlsCAFile=global-bundle.pem \ --archive=/path/to/archive.gz \ --gzip \ --nsInclude="db1.*" \ --nsExclude="db1.sensitive_data" \ --noIndexRestore ``` ## 监控 本节提供了详细的监控流程，以跟踪正在进行的迁移的进度、性能和运行状况。 无论使用哪种迁移方法（AWS DMS、或其他工具） mongodump/mongorestore，监控步骤都适用。 ### AWS DMS 迁移监控（如果适用） 监控以下关键 CloudWatch 指标： **完全加载阶段指标** + **FullLoadThroughputBandwidthTarget**— 满负荷时的网络带宽 (KB/second) + **FullLoadThroughputRowsTarget**— 每秒 rows/documents 加载的次数 + **FullLoadThroughputTablesTarget**— 每分钟 tables/collections 完成的次数 + **FullLoadProgressPercent**— 满负荷完成的百分比 + **TablesLoaded**— tables/collections 成功加载的数量 + **TablesLoading**— tables/collections 当前加载的数量 + **TablesQueued**— tables/collections 等待加载的次数 + **TablesErrored**— 加载 tables/collections 失败的数量 **CDC 阶段指标** + **CDCLatencyTarget**— 源代码更改和目标应用程序之间的时间延迟（秒） + **CDCLatencySource**— 更改源和 DMS 读取之间的时间延迟（秒） + **CDCThroughputRowsTarget**— 在持续复制期间应用的每秒行数 + **CDCThroughputBandwidthTarget**— CDC 期间的网络带宽 (KB/second) + **CDCIncomingChanges**— 从源收到的变更事件的数量 + **CDCChangesMemoryTarget**— 用于在目标端存储更改的内存 (MB) **资源指标 ** + **CPUUtilization**：复制实例的 CPU 使用率 + **FreeableMemory**— 复制实例上的可用内存 + **FreeStorageSpace**— 复制实例上的可用存储 + **NetworkTransmitThroughput**— 复制实例的网络吞吐量 + **NetworkReceiveThroughput**— 复制实例的网络吞吐量 **错误指标** + **ErrorsCount**— 迁移期间的错误总数 + **TableErrorsCount**— 特定表格错误的数量 + **RecordsErrorsCount**— 特定记录错误的数量 为关键指标（例如迁移性能）创建 CloudWatch 警报`CPUUtilization`，`CDCLatencyTarget`并在迁移性能下降时接收通知。 #### DMS 日志（日CloudWatch 志） 1. 前往 Amazon CloudWatch Logs 控制台。 1. 在您的日志组中进行查找和选择。看起来类似于“dms-tasks –”。 1. 查找可能包含错误信息的日志流： + 名称中带有“error”的流 + 带有任务 ID 或端点名称的流 + 迁移期间的最新日志流 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-backed 实例的支持。通过可视化这些指标，团队可以主动识别性能瓶颈，优化资源分配，并确保其 Amazon DocumentDB 部署顺利运行。该工具无需手动创建控制面板，同时在所有环境中提供一致的监控。有关设置说明和高级配置选项，请参阅 [ Amazon DocumentDB 仪表板工具存储库。](https://github.com/awslabs/amazon-documentdb-tools/tree/master/monitoring/docdb-dashboarder) GitHub ## 验证 **Topics** + [验证核对清单](#w2aac15b9c27b9) + [架构和索引验证](#w2aac15b9c27c11) + [数据采样和字段级别验证](#w2aac15b9c27c13) + [使用 DataDiffer 工具进行验证](#w2aac15b9c27c15) 本节提供了详细的验证过程，以确保迁移后的数据一致性、完整性和应用程序兼容性。 无论使用哪种迁移方法（AWS DMS、或其他工具） mongodump/mongorestore，验证步骤都适用。 ### 验证核对清单 验证每个集合中的文档数量在源与目标之间是否匹配： **MongoDB 源** ``` mongosh \ --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --eval "db.{{}}.countDocuments()" ``` **Amazon DocumentDB 目标** ``` mongosh \ --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --tls \ --tlsCAFile global-bundle.pem \ --eval "db.{{}}.countDocuments()" ``` ### 架构和索引验证 请确保： + 所有集合都存在于目标中。 + 索引已正确复制。 + 架构定义（如果强制执行）相同。 **检查集合（源与目标）** ``` mongosh --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --eval "db = db.getSiblingDB('{{}}'); db.getCollectionNames();" mongosh --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --tls --tlsCAFile global-bundle.pem \ --eval "db = db.getSiblingDB('{{}}'); db.getCollectionNames();" ``` **检查索引（源索引与目标索引）** ``` mongosh --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --eval "db.{{}}.getIndexes()" mongosh --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --tls --tlsCAFile global-bundle.pem \ --eval "db.{{}}.getIndexes()" ``` 比较集合列表，确保没有缺失或多余的集合。 通过检查索引名称、键定义、唯一约束和 TTL 索引（如果有）来验证索引。 **检查架构验证规则（如果在 MongoDB 中使用架构验证）** ``` mongosh --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --eval "db.getCollectionInfos({name: '{{}}'})[0].options.validator" mongosh --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --tls --tlsCAFile global-bundle.pem \ --eval "db.getCollectionInfos({name: '{{}}'})[0].options.validator" ``` ### 数据采样和字段级别验证 您可以对文档进行随机采样，并比较源与目标之间的字段。 **手动采样** 获取五个随机文档（源）： ``` mongosh --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --eval "db.{{}}.aggregate([{ \$sample: { size: 5 } }])" ``` 获取相同的文档 ID（目标）： ``` mongosh --host {{}} \ --port 27017 \ --username {{}} \ --password {{}} \ --tls --tlsCAFile global-bundle.pem \ --eval "db.{{}}.find({ _id: { \$in: [{{}}] } })" ``` **自动采样** ``` import pymongo # Connect to source and target source_client = pymongo.MongoClient("{{}}") target_client = pymongo.MongoClient("{{}}", tls=True, tlsCAFile='global-bundle.pem') 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)为比较源数据库和目标数据库之间的数据 GitHub 提供了一种可靠的方法。 #### 先决条件 在安装该 DataDiffer 工具之前，必须满足以下先决条件： + Python3.7\+ + 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://:@:27017/?replicaSet=rs0", "db": "your_database", "collection": "your_collection" }, "target": { "uri": "mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&retryWrites=false", "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 集群上创建所有必需的索引。 + **文档验证结果**：记录每个集合的验证结果，将其作为迁移文档的一部分。