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

亚马逊 DocumentDB 迁移操作手册

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

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

运行手册分为以下主题：

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

兼容性

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

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

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

在评估阶段，监控执行计划以发现潜在的绩效差距非常重要。这有助于创建清晰的迁移路线图，确定必要的应用程序变更并为平稳过渡制定切合实际的时间表。

核心功能兼容性

全面的功能支持

增强 AWS的集成功能

现代建筑的优势

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

亚马逊 DocumentDB 不支持 MongoDB 提供的所有索引。我们提供免费的索引工具来检查兼容性。我们建议运行索引工具来评估不兼容性并相应地计划变通方案。

亚马逊 DocumentDB 兼容性评估工具

MongoDB 与 Amazon DocumentDB 的兼容性工具是一个可用的开源工具，它通过分析 MongoD B 日志或应用程序源代码来帮助评估 MongoDB 工作 GitHub 负载与亚马逊 DocumentDB 的兼容性。

主要特征

评估方法

基于日志的评估

源代码分析

为了获得最佳结果，我们建议尽可能使用这两种评估方法，以便在迁移之前全面了解兼容性挑战。

工作负载发现

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

评估现有的 MongoDB 部署

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

识别数据模型差异

尽管亚马逊 DocumentDB 与 MongoDB 兼容，但支持的功能还是存在差异，例如：

查询和性能分析

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

安全和访问控制审查

身份验证和授权

加密

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

网络配置

规划虚拟私有云 (VPC) Privat e Cloud 的设置和安全组规则。

操作和监控注意事项

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

索引迁移

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

使用亚马逊 DocumentDB 索引工具

克隆索引工具

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'

从亚马逊 DocumentDB 导出索引（如果从亚马逊 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 用户，同时保留其角色和权限的详细步骤。

使用亚马逊 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://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 步：将自定义角色恢复到亚马逊 DocumentDB

# Import roles first
mongo --ssl \
--host target-host:27017 \
--sslCAFile rds-combined-ca-bundle.pem \
--username admin \
--password password \
mongodb-roles.js

步骤 4：将用户恢复到亚马逊 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

重要注意事项

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

数据迁移

在线迁移

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

配置目标 (亚马逊 DocumentDB)

创建自定义参数组

请参阅中的 AWS Management Console 或 AWS CLI 程序创建 Amazon DocumentDB 集群参数组。

创建 Amazon DocumentDB 集群

配置源

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

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

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

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

配置网络和身份验证。

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

EC2-托管的 MongoDB 源代码

本地 MongoDB 来源

MongoDB Atlas 来源

亚马逊 DocumentDB 来源

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

创建 DMS 复制实例

我们建议使用 DMS Buddy 来配置您的 DMS 基础架构，因为它可以创建具有最佳 DMS 设置和实例大小的最佳迁移基础架构。

如果您更喜欢手动配置，请按照以下步骤操作：

创建 DMS 终端节点

创建源端点

对于 MongoDB 来源

对于亚马逊 DocumentDB 来源

创建目标终端节点 (亚马逊 DocumentDB)

创建复制任务

离线迁移

本节概述了使用原生 MongoDB 工具执行从自我管理的 MongoDB 实例到亚马逊文档数据库的离线迁移的过程：和。mongodump mongorestore

先决条件

来源 MongoDB 要求

瞄准亚马逊 DocumentDB 要求

一般要求

准备亚马逊文档数据库集群

在以下位置创建 Amazon DocumentDB 集群： AWS

执行数据转储（mongodump）

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

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

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

将数据恢复到亚马逊 DocumentDB（mongorestore）

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

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

监控

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

MongoDB 到亚马逊 DocumentDB

或

亚马逊 DocumentDB 到亚马逊 DocumentDB

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

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由支持的实例。通过可视化这些指标，团队可以主动识别性能瓶颈，优化资源分配，并确保他们的 Amazon DocumentDB 部署顺利运行。该工具无需手动创建仪表板，同时可在所有环境中提供一致的监控。有关设置说明和高级配置选项，请参阅 Amazon DocumentDB 仪表板工具存储库。 GitHub

验证

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

MongoDB 到亚马逊 DocumentDB

或

亚马逊 DocumentDB 到亚马逊 DocumentDB

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

验证清单

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

MongoDB 来源

mongo --host <source_host> --port <port> --username <user> -- password <password> --eval
"db.<collection>.count()"

亚马逊 DocumentDB 目标

mongo --host <target_host> --port <port> --username <user> -- password <password> --eval
"db.<collection>.count()"

架构和索引验证

请确保：

检查集合（来源与目标）

mongo --host <source_host> --eval "show collections"
mongo --host <target_host> --ssl --eval "show collections"

检查索引（源与目标）

mongo --host <source_host> --eval" db.<collection>.getIndexes()"
mongo --host <target_host> --ssl –eval" db.<collection>.getIndexes()"

比较馆藏列表，确保没有丢失或多余的藏品。

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

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

mongo --host <source_host> --eval" db.getCollectionInfos({name: '<collection>'})
[0].options.validator"
   mongo --host <target_host> --ssl –eval" db.getCollectionInfos({name: '<collection>'})[0].options.validator"

数据采样和现场级验证

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

手动采样

随机获取五份文档（来源）：

mongo --host <source_host> --eval "db.<collection>.aggregate([{ \$sample: { size: 5 } }])"

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

mongo --host <target_host> --ssl –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>", ssl=True)
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 工具提供了一种在源数据库和目标数据库之间比较数据的可靠方法。

先决条件

安装该 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-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 工具时的最佳做法：