Amazon DocumentDB 遷移 Runbook

此 Runbook 提供使用 AWS Database Migration Service (DMS) 將 MongoDB 資料庫遷移至 Amazon DocumentDB 的完整指南。它旨在在整個end-to-end遷移過程中支援資料庫管理員、雲端工程師和開發人員，從初始探索到遷移後驗證。

考慮到 MongoDB 和 Amazon DocumentDB 之間的實作和支援功能差異，此 Runbook 強調結構化和系統化的方法。它概述了必要的遷移前評估、強調相容性考量，並詳細說明確保成功遷移所需的關鍵任務，並將中斷降至最低。

Runbook 會組織成下列主題：

• 相容性 — 了解 Amazon DocumentDB 中支援的 MongoDB 功能和資料類型，並識別潛在的不相容。

• 工作負載探索 — 分析現有的 MongoDB 工作負載，包括讀取/寫入模式、資料磁碟區和效能基準。

• 索引遷移 — 分析擷取和轉換 MongoDB 索引的策略，以在 Amazon DocumentDB 中獲得最佳效能。

• 使用者遷移 — 詳細說明將資料庫使用者、角色和存取控制遷移至 Amazon DocumentDB 的方法。

• 資料遷移 — 涵蓋各種使用 進行資料遷移的方法 AWS DMS，包括完全載入和變更資料擷取 (CDC)。

• 監控 — 詳細說明使用 DMS 或原生工具進行遷移時的各種監控方法。

• 驗證 — 提供遷移後資料完整性檢查、功能驗證和效能比較的程序。

透過遵循此 Runbook 中的指引，團隊可以確保順利、安全且有效率地轉換至 Amazon DocumentDB，同時保留應用程式功能並將風險降至最低。

相容性

從 MongoDB 遷移至 Amazon DocumentDB 時，完整的初始評估和功能相容性檢查對於成功遷移至關重要。此程序從 MongoDB 功能的全面清查開始，包括彙總管道運算子、查詢模式、索引和資料模型。

由於 Amazon DocumentDB 與 MongoDB 3.6、4.0 和 5.0 API 相容，因此使用較新 MongoDB 特定功能的應用程式可能需要重構。要評估的關鍵領域包括碎片機制 (Amazon DocumentDB 使用不同的方法）、交易實作、變更串流功能和索引類型 （特別是稀疏和部分索引）。

效能特性也有所不同，Amazon DocumentDB 已針對具有可預測效能的企業工作負載進行最佳化。測試應涉及對兩個系統執行代表性工作負載，以識別可能需要最佳化的查詢模式。

在評估階段期間，監控執行計畫以偵測潛在的效能差距非常重要。這有助於建立明確的遷移路線圖、識別必要的應用程式變更，並建立逼真的時間表，以實現順暢的轉換。

核心功能相容性

全方位功能支援

• CRUD 操作 — 享受對所有基本建立、讀取、更新和刪除操作的完整支援，包括大量和查詢運算子 - 提供無縫的應用程式相容性。

• 豐富的索引功能 — 利用對單一欄位、複合、TTL、部分、稀疏和 2dsphere 索引的全面支援，針對文字型查詢最佳化查詢效能和文字索引 （第 5 版）。

• 企業級複寫 - 受益於強大的自動容錯移轉機制，具有僅供讀取複本，可提供卓越的高可用性，無需營運開銷。

• 進階備份解決方案 — 使用具有Point-in-Time復原 (PITR) 的自動備份系統以及用於資料保護的隨需手動快照，輕鬆休息。

增強 AWS整合功能

• 簡化彙總 — 利用最常用的彙總階段 ($match、$sort、、 $project等）$group，為企業工作負載提供最佳化效能。

• 交易支援 — 實作多文件和多集合交易，非常適合大多數商業應用程式需求。

• 即時資料追蹤 — 透過簡單的命令啟用變更串流，並透過簡單的參數群組設定來增加變更串流保留期間，以進行即時資料變更監控。

• 位置型服務 — 實作地理空間應用程式，並支援$geoNear運算子和 2dsphere 索引。

• 文字搜尋功能 — 利用內建的文字搜尋功能來滿足內容探索需求。

現代架構優勢

• 雲端原生設計 — AWS享受最佳化的架構，可將 MapReduce 等傳統功能取代為更有效率的彙總管道操作。

• 增強安全性 — 受益於 AWS Identity and Access Management (IAM)SCRAM-SHA-1, SCRAM-SHA-256、X.509 憑證身分驗證和密碼型身分驗證。

• 可預測的效能 — 體驗專為企業工作負載最佳化的一致效能。

如需 Amazon DocumentDB 功能的完整概觀，請參閱 Amazon DocumentDB 中支援的 MongoDB APIs、操作和資料類型 Amazon DocumentDB和 功能差異：Amazon DocumentDB 和 MongoDB 以最大化資料庫的潛力。

Amazon DocumentDB 不支援 MongoDB 提供的所有索引。我們提供免費的索引工具來檢查相容性。我們建議您執行索引工具，以評估不相容並相應地規劃解決方法。

Amazon DocumentDB 相容性評估工具

MongoDB 到 Amazon DocumentDB 相容性工具是 GitHub 上提供的開放原始碼公用程式，可透過分析 MongoDB 日誌或應用程式原始碼，協助評估 MongoDB 工作負載與 Amazon DocumentDB 的相容性。

主要功能

• 識別工作負載中的 MongoDB API 使用模式

• 在遷移之前標記潛在的相容性問題

• 產生詳細的相容性報告與建議

• 可作為可在本機執行的獨立公用程式

評估方法

以日誌為基礎的評估

• 專業人員：

  • 擷取實際執行時間行為和查詢模式

  • 識別實際使用頻率和效能特性

  • 偵測來源碼中可能看不到的動態查詢

  • 不需要存取應用程式原始碼

• Cons：

  • 需要存取已啟用分析的 MongoDB 日誌

  • 僅擷取記錄期間發生的操作

  • 可能遺漏不常使用的功能或季節性工作負載

原始程式碼分析

• 專業人員：

  • 全面涵蓋程式碼庫中所有潛在的 MongoDB 操作

  • 可以識別很少執行的程式碼路徑中的問題

  • 偵測可能受 Amazon DocumentDB 差異影響的用戶端邏輯

  • 不需要執行應用程式即可執行評估

• Cons：

  • 可能標記已存在但從未在生產環境中執行的程式碼

  • 需要存取才能完成應用程式原始碼

  • 分析動態建構查詢的能力有限

為了獲得最佳結果，我們建議您盡可能使用兩種評估方法，以在遷移之前完整了解相容性挑戰。

工作負載探索

從 MongoDB 遷移到 Amazon DocumentDB 需要徹底了解現有的資料庫工作負載。工作負載探索是分析資料庫使用模式、資料結構、查詢效能和操作相依性的程序，以確保無縫轉換，並將中斷降至最低。本節概述工作負載探索所涉及的關鍵步驟，以促進從 MongoDB 到 Amazon DocumentDB 的有效遷移。

主題

• 評估現有的 MongoDB 部署

• 識別資料模型差異

• 查詢和效能分析

• 安全性和存取控制檢閱

• 操作和監控考量

評估現有的 MongoDB 部署

在遷移之前，評估目前的 MongoDB 環境至關重要，包括：

• 叢集架構 — 識別節點、複本集和碎片組態的數量。從 MongoDB 遷移至 Amazon DocumentDB 時，了解 MongoDB 碎片組態很重要，因為 Amazon DocumentDB 不支援使用者控制的碎片。專為碎片 MongoDB 環境設計的應用程式將需要架構變更，因為 Amazon DocumentDB 在其儲存型架構中使用不同的擴展方法。移至 Amazon DocumentDB 時，您將需要調整資料分佈策略，並可能合併碎片集合。

• 儲存和資料磁碟區 — 測量叢集的總資料大小和索引大小。搭配 Oplog 檢閱工具來補充這一點，以了解寫入模式和資料成長速度。如需調整叢集大小的詳細資訊，請參閱執行個體大小調整。

• 工作負載模式 — 分析讀取和寫入輸送量、查詢執行頻率和索引效率。

• 操作相依性 — 記錄依賴 MongoDB 的所有應用程式、服務和整合。

識別資料模型差異

雖然 Amazon DocumentDB 與 MongoDB 相容，但支援的功能存在差異，例如：

• 交易 — Amazon DocumentDB 支援 ACID 交易，但有一些 限制。

• 結構描述設計 — 確保文件結構、內嵌文件和參考符合 Amazon DocumentDB 的最佳實務。

查詢和效能分析

了解查詢行為有助於最佳化遷移和遷移後效能。要分析的關鍵領域包括：

• 緩慢查詢 — 使用 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 支援的身分驗證機制。

• 權限差異 — 識別沒有直接 Amazon DocumentDB 對等項目的 MongoDB 權限 （例如，叢集管理角色）。 Amazon DocumentDB

• 應用程式身分驗證 — 更新 Amazon DocumentDB 密碼政策的連線字串和憑證管理。您可以使用秘密管理員來存放您的登入資料並輪換密碼。

• 服務帳戶管理 — 建立管理服務帳戶登入資料的程序 AWS Secrets Manager。

• 最低權限實作 — 檢閱和精簡存取控制，以在新環境中實作最低權限原則。

加密

確保靜態加密和傳輸中加密符合合規要求。

網路組態

規劃 Virtual Private Cloud (VPC) 設定和安全群組規則。

操作和監控考量

為了維護系統可靠性，工作負載探索也應該包含：

• 備份和還原策略 — 評估現有的備份方法和 Amazon DocumentDB 的備份功能。

• AWS Backup 整合 — 利用 AWS Backup 跨 AWS 服務集中備份管理，包括 Amazon DocumentDB。

• CloudWatch 指標 — 將 MongoDB 監控指標映射至 CPU、記憶體、連線和儲存體的 Amazon DocumentDB CloudWatch 指標。

• 績效詳情 — 實作 Amazon DocumentDB 績效詳情，以視覺化資料庫負載，並使用詳細的查詢分析來分析效能問題。

• Profiler — 設定 Amazon DocumentDB Profiler 以擷取慢速執行的操作 （類似於 MongoDB 的 Profiler，但使用 Amazon DocumentDB 特定設定）。

  • 透過具有適當閾值的參數群組啟用 。

  • 分析分析分析器資料以識別最佳化機會

• CloudWatch Events — 設定 Amazon DocumentDB 叢集事件的事件驅動型監控。

  • 設定備份事件、維護時段和容錯移轉的通知。

  • 與 Amazon SNS 整合，用於提醒和 AWS Lambda 自動回應。

• 稽核記錄 — 規劃稽核記錄組態，以追蹤使用者活動和安全相關事件。

• 增強型監控 — 以 1 秒的間隔為精細作業系統層級指標啟用增強型監控。

索引遷移

從 MongoDB 遷移至 Amazon DocumentDB 不僅需要傳輸資料，還包含索引，以維持查詢效能並最佳化資料庫操作。本節概述將索引從 MongoDB 遷移至 Amazon DocumentDB 的詳細step-by-step程序，同時確保相容性和效率。

使用 Amazon 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'

從 Amazon DocumentDB 匯出索引 （如果從 Amazon DocumentDB 遷移）

python3 migrationtools/documentdb_index_tool.py --dump-indexes --dir docdb_index_export --uri
'mongodb://user:[e-mail]-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:[e-mail]-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

使用 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://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

重要備註

• 基於安全考量，密碼不會匯出，而且必須手動新增至 user.js 檔案。

• 必須在使用者之前匯入角色，以確保適當的角色指派。

• 此工具會產生可直接使用 mongo shell 執行的 JavaScript 檔案。

• 自訂角色及其權限會在遷移期間保留。

• 此方法允許在匯入之前檢閱和修改使用者許可。

此方法提供安全且靈活的方法，可將使用者和角色從 MongoDB 遷移至 Amazon DocumentDB，同時允許在遷移程序期間重設密碼。

資料遷移

主題

• 線上遷移

• 離線遷移

• 先決條件

• 準備 Amazon DocumentDB 叢集

• 執行資料傾印 (mongodump)

• 將傾印檔案傳輸到還原環境

• 將資料還原至 Amazon DocumentDB (mongorestore)

線上遷移

本節提供使用 從 MongoDB 到 Amazon DocumentDB 執行線上遷移的詳細步驟 AWS DMS ，以盡可能減少停機時間和持續複寫。首先，您將 Amazon DocumentDB 叢集設定為目標，並確保 MongoDB 執行個體已正確設定為來源，通常需要複本集模式才能擷取變更資料。接著，您可以建立 DMS 複寫執行個體，並使用必要的連線詳細資訊定義來源和目標端點。驗證端點之後，您可以設定並啟動遷移任務，其中包含完整資料載入、持續複寫或兩者。

設定目標 (Amazon DocumentDB)

注意

如果您已佈建要遷移至的 Amazon DocumentDB 叢集，您可以略過此步驟。

建立自訂參數群組

請參閱 中的 AWS Management Console 或 AWS CLI 程序建立 Amazon DocumentDB 叢集參數群組。

建立 Amazon DocumentDB 叢集

注意

雖然本指南中有建立 Amazon DocumentDB 叢集的其他程序，但本節中的步驟特別適用於將大量資料遷移至新叢集的任務。

1. 登入 AWS Management Console，並在 https：//https://console.aws.amazon.com/docdb 開啟 Amazon DocumentDB 主控台。

2. 在導覽窗格中，選擇叢集。

   提示

   如果畫面左側沒有出現導覽窗格，請選擇頁面左上角的功能表圖示 ()。

3. 在 Amazon DocumentDB 管理主控台的叢集下，選擇建立。

4. 在建立 Amazon DocumentDB 叢集頁面上的叢集類型區段中，選擇執行個體型叢集 （這是預設選項）。

5. 在叢集組態區段中：

   • 針對叢集識別符，輸入唯一的名稱，例如 mydocdbcluster。請注意，無論如何輸入叢集名稱，主控台都會將所有叢集名稱變更為小寫。

   • 針對引擎版本，選擇 5.0.0。

6. 在叢集儲存組態區段中，將 Amazon DocumentDB 標準設定保持原狀 （這是預設選項）。

7. 在執行個體組態區段中：

   • 針對資料庫執行個體類別，選擇記憶體最佳化類別 （包括 r 類別） （這是預設值）。

   • 針對執行個體類別，根據工作負載選擇執行個體類別。例如：

     • db.r6g.large：適用於較小的工作負載

     • db.r6g.4xlarge：適用於大型工作負載

     最佳實務是，建議您盡可能選擇最大的執行個體，以獲得最佳的完全載入輸送量，並在遷移完成後縮減規模。

   • 針對執行個體數量，選擇 1 個執行個體。選擇一個執行個體有助於將成本降至最低。我們建議您在完全載入遷移完成後擴展到三個執行個體，以獲得高可用性。

8. 在身分驗證區段中，輸入主要使用者的使用者名稱，然後選擇自我管理。輸入密碼，然後確認。

9. 在網路設定區段中，選擇 VPC 和子網路群組，然後設定 VPC 安全群組。透過更新傳入規則，確保您的 Amazon DocumentDB 安全群組允許來自 DMS 執行個體安全群組的傳入連線。

10. 在Encryption-at-rest區段中，啟用加密 （建議），然後選擇或輸入 KMS 金鑰。

11. 在備份區段中，設定備份保留期 (1-35 天）。

12. 檢閱您的組態，然後選擇建立叢集。

    部署時間通常需要 10 到 15 分鐘，

設定來源

MongoDB 和 Amazon DocumentDB 都可以做為遷移來源，視您的案例而定：

• MongoDB 作為來源 — 從內部部署或自我管理的 MongoDB 遷移到 Amazon DocumentDB 或其他 AWS 資料庫服務時很常見。需要在具有適當大小的 oplog 的複本集模式下執行 （確保其大小在完全載入期間保留所有操作），以支援遷移期間的變更資料擷取。

• Amazon DocumentDB 作為來源 — 通常用於跨區域複寫、版本升級或遷移至其他資料庫服務，例如 MongoDB Atlas。需要啟用變更串流透過在叢集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-hosted MongoDB 來源

• 修改 EC2 安全群組，以允許來自 DMS 複寫執行個體安全群組的傳入流量。

• 新增 TCP 連接埠 27017 （或您的自訂 MongoDB 連接埠） 的規則。

• 使用 DMS 複寫執行個體的安全群組 ID 做為精確存取控制的來源。

• 確保 EC2 執行個體的子網路具有通往 DMS 複寫執行個體子網路的路由。

內部部署 MongoDB 來源

• 設定防火牆以允許來自 DMS 複寫執行個體公有 IP 地址的傳入連線。

• 如果使用 AWS 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 私有連線 (Enterprise 層）。

• 建立具有適當讀取/寫入許可的專用使用者。

• 使用將 SSL 模式設定為 "verify-full" 的 MongoDB Atlas 連線字串。

• 確保遷移持續時間有足夠的oplog大小。

Amazon DocumentDB 來源

設定來源 Amazon DocumentDB 安全群組，以允許來自 DMS 複寫執行個體安全群組的傳入流量。

建立 DMS 複寫執行個體

我們建議您使用 DMS Buddy 來佈建 DMS 基礎設施，因為它會建立具有最佳 DMS 設定和執行個體大小的最佳遷移基礎設施。

如果您想要手動設定 ，請依照下列步驟進行：

1. 開啟 AWS DMS 主控台，然後選擇建立複寫執行個體。

2. 輸入複寫執行個體詳細資訊：

   • 執行個體名稱：選擇唯一的名稱。

   • 執行個體類別：根據工作負載選取 。範例：dms.r5.large （小型工作負載）、dms.r5.4xlarge （大型工作負載）。

   • 引擎版本：3.5.4

   • 配置的儲存：預設值為 100GB （視需要增加）。這取決於文件大小、更新/秒和完全載入持續時間。

   • 異地同步備份部署：視需要啟用 以獲得高可用性。

   • 選擇與 Amazon DocumentDB 相同的 VPC。

   • 確保安全群組允許來自來源和 Amazon DocumentDB 的傳入流量。

3. 按一下建立複寫執行個體並等待狀態可用。

建立 DMS 端點

建立來源端點

對於 MongoDB 來源

1. 在 DMS 主控台的導覽窗格中，選擇遷移或複寫，然後選擇端點。

2. 選擇建立端點。

3. 在建立端點頁面上，選擇來源端點。

4. 在端點組態區段中：

   • 輸入唯一且有意義的端點識別符 （例如，「mongodb-source」)。

   • 選擇 MongoDB 做為來源引擎。

   • 對於端點資料庫的存取，選擇手動提供存取資訊。

   • 在伺服器名稱中，輸入您的 MongoDB 伺服器 DNS 名稱/IP 地址。

   • 針對連接埠，輸入 27017 （預設 MongoDB 連接埠）。

   • 對於身分驗證模式，為您的應用程式選擇適當的模式 （密碼/SSL) （預設為 Secrets Manager)。

   • 如果身分驗證模式是密碼，請提供：

     • 使用者名稱和密碼：輸入 MongoDB 登入資料。

     • 資料庫名稱：您的來源資料庫名稱。

     • 身分驗證機制：SCRAM-SHA-1 （預設） 或適當的機制

5. 對於中繼資料模式，請保留 文件的預設設定。

6. 其他連線屬性：

   • authSource=admin （如果身分驗證資料庫不同）

   • replicaSet=<your-replica-set-name> (CDC 需要）

對於 Amazon DocumentDB 來源

1. 在 DMS 主控台的導覽窗格中，選擇遷移或複寫，然後選擇端點。

2. 選擇建立端點。

3. 在建立端點頁面上，選擇來源端點。

4. 在端點組態區段中：

   • 輸入唯一且有意義的端點識別符 （例如 "docdb-source")。

   • 選擇 Amazon DocumentDB 作為來源引擎。

   • 對於端點資料庫的存取，選擇手動提供存取資訊。

   • 在伺服器名稱中，輸入您的來源 Amazon DocumentDB 叢集端點。

   • 針對連接埠，輸入 27017 （預設 Amazon DocumentDB 連接埠）。

   • 對於 SSL 模式，選擇 verify-full （建議用於 Amazon DocumentDB)。

   • 針對 CA 憑證，選擇 Amazon RDS 根 CA 憑證。

   • 對於身分驗證模式，為您的應用程式選擇適當的模式 （密碼/SSL) （預設為 Secrets Manager)。

   • 如果身分驗證模式是密碼，請提供：

     • 使用者名稱和密碼：輸入 Amazon DocumentDB 登入資料。

     • 資料庫名稱：您的來源資料庫名稱。

     • 身分驗證機制：SCRAM-SHA-1 （預設） 或適當的機制

5. 對於中繼資料模式，請保留 文件的預設設定。

建立目標端點 (Amazon DocumentDB)

1. 在 DMS 主控台的導覽窗格中，選擇遷移或複寫，然後選擇端點。

2. 選擇建立端點。

3. 在建立端點頁面上，選擇目標端點。

4. 在端點組態區段中：

   • 輸入唯一且有意義的端點識別符 （例如 "docdb-target")。

   • 選擇 Amazon DocumentDB 作為目標引擎。

   • 針對端點資料庫的存取，選擇您要用來驗證資料庫存取的方法：

     • 如果您選擇 AWS Secrets Manager，請在 Secret 欄位中選擇存放 Amazon DocumentDB 登入資料的秘密。

     • 如果您選擇手動提供存取資訊：

       • 在伺服器名稱中，輸入您的目標 Amazon DocumentDB 叢集端點。

       • 針對連接埠，輸入 27017 （預設 Amazon DocumentDB 連接埠）。

       • 針對 SSL 模式，選擇 verify-full （建議用於 Amazon DocumentDB)。

       • 針對 CA 憑證，下載並指定用於 SSL 驗證的 CA 憑證套件。

       • 對於身分驗證模式，為您的應用程式選擇適當的模式 （密碼/SSL) （預設為 Secrets Manager)。

       • 如果身分驗證模式是密碼，請提供：

         • 使用者名稱和密碼：輸入 Amazon DocumentDB 登入資料。

         • 資料庫名稱：您的來源資料庫名稱。

         • 身分驗證機制：SCRAM-SHA-1 （預設） 或適當的機制

5. 對於中繼資料模式，請保留 文件的預設設定。

建立複寫任務

1. 在 DMS 主控台的導覽窗格中，選擇遷移或複寫，然後選擇任務。

2. 選擇 Create task (建立任務)。

3. 在建立任務頁面上的任務組態區段中：

   • 輸入唯一且有意義的任務識別符 （例如「mongodb-docdb-replication」)。

   • 在來源資料庫端點下拉式功能表中選擇您先前建立的來源端點。

   • 選擇您先前在目標資料庫端點下拉式功能表中建立的目標端點。

   • 針對任務類型，選擇遷移和複寫。

4. 在設定區段中：

   • 對於目標資料表準備模式，請保留預設設定。

   • 對於完全載入完成後的停止任務，請保留預設設定。

   • 對於 LOB 欄設定，請將有限 LOB 模式設定保持原狀。

   • 對於資料驗證，將預設設定保留為關閉。

   • 針對任務日誌，勾選開啟 CloudWatch 日誌方塊。

   • 對於批次最佳化套用，請保留未勾選的預設設定 （關閉）。

5. 回到任務設定區段頂端，在編輯模式中，選擇 JSON 編輯器並設定下列屬性：

   {
     "TargetMetadata": {
       "ParallelApplyThreads": 5
     },
     "FullLoadSettings": {
       "MaxFullLoadSubTasks": 16
     }
   }

6. 在資料表映射區段中，新增新的選取規則：

   • 針對結構描述名稱，新增要遷移的來源資料庫。使用 % 指定多個資料庫。

   • 針對結構描述資料表名稱，新增要遷移的來源集合。使用 % 指定多個集合。

   • 對於動作，保留 Include 的預設設定

7. 對於大型集合 （超過 100GB)，新增資料表設定規則：

   • 針對結構描述名稱，新增要遷移的來源資料庫。使用 % 指定多個資料庫。

   • 針對結構描述資料表名稱，新增要遷移的來源集合。使用 % 指定多個集合。

   • 針對分割區數量，輸入 16 （應小於 MaxFullLoadSubTask)。

8. 在預遷移評估區段中，確定已關閉。

離線遷移

本節概述使用原生 MongoDB 工具從自我管理的 MongoDB 執行個體執行離線遷移至 Amazon DocumentDB MongoDB 的程序： mongodump和 mongorestore。

先決條件

來源 MongoDB 需求

• 使用適當的許可存取來源 MongoDB 執行個體。

• 視需要安裝 mongodump。 （會在 MongoDB 安裝期間安裝）。

• 請確定傾印檔案有足夠的磁碟空間。

目標 Amazon DocumentDB 需求

• 請確定您已佈建 Amazon DocumentDB 叢集。

• 確保與 Amazon DocumentDB 相同的 VPC 中有 EC2 執行個體，以利遷移。

• 您的來源環境和 Amazon DocumentDB 之間必須具備網路連線能力。

• mongorestore 必須安裝在遷移 EC2 執行個體上。

• 必須設定適當的 IAM 許可以存取 Amazon DocumentDB、

一般要求

• AWS CLI 必須設定 （如果使用 AWS 服務進行中繼儲存）

• 必須有足夠的頻寬才能進行資料傳輸。

• 應核准停機時間時段 （如果進行即時遷移，請考慮其他方法）

準備 Amazon DocumentDB 叢集

在 中建立 Amazon DocumentDB 叢集 AWS：

• 根據您的工作負載適當執行個體大小。

• 設定 VPC、子網路和安全群組。

• 透過參數群組啟用必要的參數。

執行資料傾印 (mongodump)

選擇下列其中一個選項來建立傾印檔案：

• 選項 1：基本

  mongodump --
  uri="mongodb://<source_user>:<source_password>@<source_host>:<source_port>/<database>" --
  out=/path/to/dump

• 選項 2：更好的控制和效能

  mongodump \
  --uri="mongodb://<source_user>:<source_password>@<sourcehost>:<source_port>" \
  --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=<source_host> \
  --port=<source_port> \
  --username=<source_user> \
  --password=<source_password> \
  --db=<specific_db> \# Only dump specific DB
  --collection=<specific_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 索引工具來匯出和匯入索引。

選擇下列其中一個選項來還原資料：

• 選項 1：基本還原

  mongorestore --uri="mongodb://<docdb_user>:<docdb_password>@<docdb_endpoint>:27017"
  /path/to/dump

• 選項 2：更好的控制和效能

  mongorestore \
  --uri="mongodb://<docdb_user>:<docdb_password>@<docdb_endpoint>: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=<docdb_endpoint> \
  --port=27017 \
  --username=<docdb_user> \
  --password=<docdb_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 — 每秒載入的資料列/文件數

• FullLoadThroughputTablesTarget — 每分鐘完成的資料表/集合數量

• FullLoadProgressPercent — 已完成完全載入的百分比

• TablesLoaded — 成功載入的資料表/集合數目

• TablesLoading — 目前正在載入的資料表/集合數量

• TablesQueued — 等待載入的資料表/集合數目

• TablesErrored — 無法載入的資料表/集合數量

CDC 階段指標

• CDCLatencyTarget — 來源變更與目標應用程式之間的時間延遲 （秒）

• CDCLatencySource — 來源變更和 DMS 讀取之間的時間延遲 （秒）

• CDCThroughputRowsTarget — 持續複寫期間每秒套用的資料列數

• CDCThroughputBandwidthTarget — CDC 期間的網路頻寬 (KB/秒）

• CDCIncomingChanges — 從來源接收的變更事件數目

• CDCChangesMemoryTarget — 用於儲存目標端變更的記憶體 (MB)

資源指標

• CPUUtilization — 複寫執行個體的 CPU 用量

• FreeableMemory — 複寫執行個體上的可用記憶體

• FreeStorageSpace — 複寫執行個體上的可用儲存體

• NetworkTransmitThroughput — 複寫執行個體的網路輸送量

• NetworkReceiveThroughput — 複寫執行個體的網路輸送量

錯誤指標

• ErrorsCount — 遷移期間的錯誤總數

• TableErrorsCount — 資料表特定錯誤的數量

• RecordsErrorsCount — 記錄特定錯誤的數量

為 CDCLatencyTarget和 等關鍵指標建立 CloudWatch 警示CPUUtilization，以便在遷移效能降低時接收通知。

DMS 日誌 (CloudWatch 日誌）

1. 前往 Amazon CloudWatch Logs 主控台。

2. 在您的日誌群組上尋找並選擇 。它看起來類似於「dms-tasks –」。

3. 尋找可能包含錯誤資訊的日誌串流：

   • 名稱中有「錯誤」的串流

   • 具有任務 IDs串流

   • 遷移期間的最新日誌串流

4. 在這些串流中，搜尋關鍵字，例如：

   • 「錯誤」

   • 「例外狀況」

   • 「失敗」

   • 「警告」

DMS 任務狀態 （使用 AWS CLI)

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

預期的狀態流程：

建立 → ready → running → stop → stop （或失敗）

使用 監控 docdb-dashboarder

該docdb-dashboarder工具透過自動產生具有基本效能指標的 CloudWatch 儀表板，為 Amazon DocumentDB 叢集提供全面的監控。這些儀表板會顯示關鍵叢集層級指標 （複本延遲、操作計數器）、執行個體層級指標 (CPU、記憶體、連線） 和儲存指標 （磁碟區使用量、備份儲存）。對於遷移案例，該工具提供專門的儀表板，使用 CDC 複寫延遲和操作速率等指標來追蹤遷移進度。儀表板可以同時監控多個叢集，並包含對 NVMe 後端執行個體的支援。透過視覺化這些指標，團隊可以主動識別效能瓶頸、最佳化資源配置，並確保其 Amazon DocumentDB 部署的順暢操作。該工具無需手動建立儀表板，同時在所有環境中提供一致的監控。如需設定說明和進階組態選項，請參閱 Amazon DocumentDB Dashboarder Tool GitHub 儲存庫。

驗證

主題

• 驗證檢查清單

• 結構描述和索引驗證

• 資料取樣和欄位層級驗證

• 使用 DataDiffer 工具進行驗證

本節提供詳細的驗證程序，以確保從下列位置遷移後的資料一致性、完整性和應用程式相容性：

MongoDB 到 Amazon DocumentDB

或

Amazon DocumentDB 到 Amazon DocumentDB

無論遷移方法為何 (AWS DMS、mongodump/mongorestore 或其他工具），驗證步驟都適用。

驗證檢查清單

確認每個集合中的文件數量符合來源和目標：

MongoDB 來源

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

Amazon 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 工具之前，必須符合下列先決條件：

• Python 3.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://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 工具時的最佳實務：

• 分階段執行 — 首先驗證文件計數，然後範例金鑰文件，並視需要執行完整比較。

• 檢查結構描述差異 — Amazon DocumentDB 與 MongoDB 相比有一些限制。工具會反白顯示不相容的資料類型或結構。

• 在靜止期間驗證 — 在寫入操作最少時執行驗證，以確保一致性。

• 監控資源用量 — 比較程序可能會耗費大量資源。相應地調整批次大小和執行緒計數。

• 驗證索引 — 驗證資料之後，請確定已在目標 Amazon DocumentDB 叢集上建立所有必要的索引。

• 文件驗證結果 — 將每個集合的驗證結果記錄為遷移文件的一部分。