本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Amazon DocumentDB 迁移运行手册

本运行手册为使用 AWS Database Migration Service (DMS) 将 MongoDB 数据库迁移到 Amazon DocumentDB 提供了全面的指南。旨在从初始发现到迁移后验证的整个端到端迁移过程中，为数据库管理员、云工程师和开发人员提供支持。

鉴于 MongoDB 与 Amazon DocumentDB 在实现和支持功能方面的差异，本运行手册强调了结构化和系统化的方法。本运行手册概述了重要的迁移前评测，重点介绍了兼容性注意事项，并详细说明了在最大限度减少中断的情况下确保迁移成功所需执行的关键任务。

本运行手册包含以下主题：

通过遵循本运行手册中的指导，团队可以确保平稳、安全且高效地过渡到 Amazon DocumentDB，同时保留应用程序功能并最大限度地降低风险。

兼容性

从 MongoDB 迁移到 Amazon DocumentDB 时，全面的初始评测和功能兼容性检查是成功迁移的关键。此过程从全面清点您的 MongoDB 功能开始，包括聚合管道运算符、查询模式、索引和数据模型。

由于 Amazon DocumentDB 与 MongoDB 3.6、4.0、5.0 和 8.0 的 API 兼容，因此使用新 MongoDB-specific 功能的应用程序可能需要重构。需要评估的关键领域包括分片机制（Amazon DocumentDB 使用不同的方法）、事务实现、变更流功能以及索引类型（尤其是稀疏索引和部分索引）。

性能特征也存在差异，Amazon DocumentDB 针对企业工作负载进行了优化，性能可预测。测试应包括对两个系统运行具有代表性的工作负载，以识别可能需要优化的查询模式。

在评测阶段，监控执行计划以发现潜在的性能差距非常重要。这有助于制定清晰的迁移路线图，识别必要的应用程序变更以及建立切合实际的时间表，以便实现平稳过渡。

核心功能兼容性

全面功能支持

增强 AWS-集成功能

现代架构优势

要全面了解 Amazon DocumentDB 的功能，请参阅 Amazon DocumentDB 中支持的 MongoDB API、操作和数据类型 和 功能差异：Amazon DocumentDB 和 MongoDB，以最大限度地发挥数据库的潜力。

Amazon DocumentDB 并不支持 MongoDB 提供的所有索引。我们提供了一个免费的索引工具 GitHub 来检查兼容性。运行索引工具来评估不兼容性并相应地规划变通方案。

Amazon DocumentDB 兼容性评测工具

Amazon DocumentDB 兼容性工具可 GitHub 分析您的MongoDB工作负载并报告 Amazon DocumentDB 中不支持或需要更改的操作员、命令和功能。它支持从 3.6 到 8.0.1 的目标版本（默认值：8.0.1）。

推荐：URI 模式 (MongoDB5.0+)

URI 模式直接连接到您的 MongoDB 实例，实时对操作进行示例，无需分析或日志访问权限。

替代方法

先决条件

有关完整的使用详情和所有可用选项，请参阅上的 GitHub自述文件。

工作负载发现

从 MongoDB 迁移到 Amazon DocumentDB 需要对现有数据库工作负载有透彻的了解。工作负载发现是分析数据库使用模式、数据结构、查询性能和操作依赖关系的过程，旨在确保以最少的中断实现无缝过渡。本节概述了工作负载发现所涉及的关键步骤，以促进从 MongoDB 到 Amazon DocumentDB 的有效迁移。

评测现有的 MongoDB 部署

在迁移之前，评估当前的 MongoDB 环境至关重要，包括：

识别数据模型差异

尽管 Amazon DocumentDB 是 MongoDB-compatible，但支持的功能有所不同，例如：

查询和性能分析

了解查询行为有助于优化迁移和迁移后的性能。需要分析的关键领域包括：

安全与访问控制审查

身份验证和授权

加密

确保静态加密和传输中加密符合合规要求。

网络配置

规划虚拟私有云（VPC）设置和安全组规则。

操作和监控注意事项

为了保持系统可靠性，工作负载发现还应包括：

创建新的目标集群

按照中的创建 Amazon DocumentDB 集群步骤创建 Amazon DocumentDB 集群。配置集群进行迁移时，请应用以下建议：

索引迁移

从 MongoDB 迁移到 Amazon DocumentDB 不仅需要传输数据，还需要传输索引，以保持查询性能和优化数据库操作。本节概述了在确保兼容性和效率的同时，将索引从 MongoDB 迁移到 Amazon DocumentDB 的详细分步流程。

使用 Amazon DocumentDB 索引工具

克隆索引工具 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://<username>:<password>@<source_endpoint>: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://<username>:<password>@<target_endpoint>: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 导出到 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://<username>:<password>@<source_endpoint>: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 <target_endpoint>:27017 \
  --tlsCAFile global-bundle.pem \
  --username <username> \
  --password <password> \
  mongodb-roles.js

步骤 4：将用户恢复到 Amazon DocumentDB

# Import users after roles are created
mongosh \
  --tls \
  --host <target_endpoint>:27017 \
  --tlsCAFile global-bundle.pem \
  --username <username> \
  --password <password> \
  mongodb-users.js

重要提示

此方法提供了一种安全且灵活的途径将用户和角色从 MongoDB 迁移到 Amazon DocumentDB，同时允许在迁移过程中重置密码。

数据迁移

在线迁移

本节提供详细步骤，使用这些步骤执行从 MongoDB 到 Amazon DocumentDB 的在线迁移，以最大限度 AWS DMS 地缩短停机时间并实现持续复制。首先，您需要将 Amazon DocumentDB 集群设置为目标，并确保将 MongoDB 实例正确配置为源，通常需要副本集模式才能捕获变更数据。接下来，您将创建 DMS 复制实例，并使用必要的连接详细信息定义源端点和目标端点。验证端点后，配置并启动迁移任务，该任务可能包括完全数据加载和/或持续复制。

创建新的目标集群

请参阅创建新的目标集群。

配置源

MongoDB 和 Amazon DocumentDB 都可以充当迁移源，具体取决于您的场景：

在开始迁移之前，将您的源配置为允许 AWS DMS 访问。

创建具有适当权限的 MongoDB 用户：

db.createUser({
  user: "dmsUser",
  pwd: "<password>",
  roles: [{ role: "readAnyDatabase", db: "admin" }]
})

配置网络和身份验证。

在为 MongoDB 到 DMS 的迁移配置网络连接时：

EC2-hosted MongoDB 源

On-premises MongoDB 源

MongoDB Atlas 源

Amazon DocumentDB 源

配置您的源 Amazon DocumentDB 安全组，以允许来自 DMS 复制实例安全组的入站流量。

创建 DMS 复制实例

使用 DMS Buddy 创建具有最佳 DMS 设置和实例大小的最佳迁移基础架构。 GitHub 如果您更喜欢手动配置，请执行以下步骤：

创建 DMS 端点

创建源端点

对于 MongoDB 源

对于 Amazon DocumentDB 源

创建目标端点（Amazon DocumentDB）

创建复制任务

离线迁移

本节概述了使用原生 MongoDB 工具 mongodump 和 mongorestore 执行从自行管理的 MongoDB 实例到 Amazon DocumentDB 的离线迁移流程。

先决条件

源 MongoDB 要求

目标 Amazon DocumentDB 要求

一般要求

准备 Amazon DocumentDB 集群

请参阅创建新的目标集群。

执行数据转储（mongodump）

选择以下选项之一来创建转储文件：

将转储文件传输到恢复环境

根据您的转储大小选择适当的方法：

将数据恢复到 Amazon DocumentDB（mongorestore）

在开始恢复过程之前，请在 Amazon DocumentDB 中创建索引。您可以使用 Amazon DocumentDB 索引工具导出和导入索引。

选择以下选项之一来恢复数据：

监控

本节提供了详细的监控流程，以跟踪正在进行的迁移的进度、性能和运行状况。

无论使用哪种迁移方法（AWS DMS、或其他工具） mongodump/mongorestore，监控步骤都适用。

AWS DMS 迁移监控（如果适用）

监控以下关键 CloudWatch 指标：

完全加载阶段指标

CDC 阶段指标

资源指标

错误指标

为关键指标（例如迁移性能）创建 CloudWatch 警报CPUUtilization，CDCLatencyTarget并在迁移性能下降时接收通知。

DMS 日志（日CloudWatch 志）

DMS 任务状态（使用 AWS CLI)

aws dms describe-replication-tasks \
  --filters Name=replication-task-id,Values=<task_id> \
  --query "ReplicationTasks[0].Status"

预期的状态流：

正在创建 → 就绪 → 正在运行 → 正在停止 → 已停止（或失败）

使用 docdb-dashboarder 进行监控

该docdb-dashboarder工具通过自动生成包含基本性能指标的 CloudWatch 控制面板，为 Amazon DocumentDB 集群提供全面监控。这些控制面板显示关键的集群级别指标（副本延迟、操作计数器）、实例级别指标（CPU、内存、连接）以及存储指标（卷使用率、备份存储）。对于迁移场景，该工具提供专用控制面板，可通过 CDC 复制延迟和操作率等指标来跟踪迁移进度。仪表板可以同时监控多个集群，并包括对 NVMe-backed 实例的支持。通过可视化这些指标，团队可以主动识别性能瓶颈，优化资源分配，并确保其 Amazon DocumentDB 部署顺利运行。该工具无需手动创建控制面板，同时在所有环境中提供一致的监控。有关设置说明和高级配置选项，请参阅 Amazon DocumentDB 仪表板工具存储库。 GitHub

验证

本节提供了详细的验证过程，以确保迁移后的数据一致性、完整性和应用程序兼容性。

无论使用哪种迁移方法（AWS DMS、或其他工具） mongodump/mongorestore，验证步骤都适用。

验证核对清单

验证每个集合中的文档数量在源与目标之间是否匹配：

MongoDB 源

mongosh \
  --host <source_endpoint> \
  --port 27017 \
  --username <user> \
  --password <password> \
  --eval "db.<collection>.countDocuments()"

Amazon DocumentDB 目标

mongosh \
  --host <target_endpoint> \
  --port 27017 \
  --username <user> \
  --password <password> \
  --tls \
  --tlsCAFile global-bundle.pem \
  --eval "db.<collection>.countDocuments()"

架构和索引验证

请确保：

检查集合（源与目标）

mongosh --host <source_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --eval "db = db.getSiblingDB('<database>'); db.getCollectionNames();"

mongosh --host <target_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --tls --tlsCAFile global-bundle.pem \
  --eval "db = db.getSiblingDB('<database>'); db.getCollectionNames();"

检查索引（源索引与目标索引）

mongosh --host <source_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --eval "db.<collection>.getIndexes()"

mongosh --host <target_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --tls --tlsCAFile global-bundle.pem \
  --eval "db.<collection>.getIndexes()"

比较集合列表，确保没有缺失或多余的集合。

通过检查索引名称、键定义、唯一约束和 TTL 索引（如果有）来验证索引。

检查架构验证规则（如果在 MongoDB 中使用架构验证）

mongosh --host <source_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --eval "db.getCollectionInfos({name: '<collection>'})[0].options.validator"

mongosh --host <target_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --tls --tlsCAFile global-bundle.pem \
  --eval "db.getCollectionInfos({name: '<collection>'})[0].options.validator"

数据采样和字段级别验证

您可以对文档进行随机采样，并比较源与目标之间的字段。

手动采样

获取五个随机文档（源）：

mongosh --host <source_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --eval "db.<collection>.aggregate([{ \$sample: { size: 5 } }])"

获取相同的文档 ID（目标）：

mongosh --host <target_endpoint> \
  --port 27017 \
  --username <username> \
  --password <password> \
  --tls --tlsCAFile global-bundle.pem \
  --eval "db.<collection>.find({ _id: { \$in: [<list_of_ids>] } })"

自动采样

import pymongo

# Connect to source and target
source_client = pymongo.MongoClient("<source_uri>")
target_client = pymongo.MongoClient("<target_uri>",
                                    tls=True,
                                    tlsCAFile='global-bundle.pem')
source_db = source_client["<db_name>"]
target_db = target_client["<db_name>"]

# Compare 100 random documents
for doc in source_db["<collection>"].aggregate([{"$sample": {"size": 100}}]):
    target_doc = target_db["<collection>"].find_one({"_id": doc["_id"]})
    if target_doc != doc:
        print(f"Mismatch in _id: {doc['_id']}")
    else:
        print(f"Match: {doc['_id']}")

使用 DataDiffer 工具进行验证

该DataDiffer 工具为比较源数据库和目标数据库之间的数据 GitHub 提供了一种可靠的方法。

先决条件

在安装该 DataDiffer 工具之前，必须满足以下先决条件：

设置和安装

克隆存储库并导航到该 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_endpoint>:27017/?replicaSet=rs0",
    "db": "your_database",
    "collection": "your_collection"
  },
  "target": {
    "uri": "mongodb://<username>:<password>@<target_endpoint>: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 工具时的最佳做法：