本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Amazon DocumentDB 遷移 Runbook 此 Runbook 提供使用 AWS Database Migration Service (DMS) 將 MongoDB 資料庫遷移至 Amazon DocumentDB 的完整指南。它旨在在整個end-to-end遷移過程中支援資料庫管理員、雲端工程師和開發人員，從初始探索到遷移後驗證。 考慮到 MongoDB 和 Amazon DocumentDB 之間的實作和支援功能差異，此 Runbook 強調結構化和系統化的方法。它概述了必要的遷移前評估、強調相容性考量，並詳細說明確保成功遷移所需的關鍵任務，並將中斷降至最低。 Runbook 會組織成下列主題： + **[相容性](#mig-runbook-compatibility)** — 了解 Amazon DocumentDB 中支援的 MongoDB 功能和資料類型，並識別潛在的不相容。 + **[工作負載探索](#mig-runbook-workload)** — 分析現有的 MongoDB 工作負載，包括讀取/寫入模式、資料磁碟區和效能基準。 + **[索引遷移](#mig-runbook-index)** — 分析擷取和轉換 MongoDB 索引的策略，以在 Amazon DocumentDB 中獲得最佳效能。 + **[使用者遷移](#mig-runbook-user)** — 詳細說明將資料庫使用者、角色和存取控制遷移至 Amazon DocumentDB 的方法。 + **[資料遷移](#mig-runbook-data)** — 涵蓋各種使用 進行資料遷移的方法 AWS DMS，包括完全載入和變更資料擷取 (CDC)。 + **[監控](#mig-runbook-monitoring)** — 詳細說明使用 DMS 或原生工具進行遷移時的各種監控方法。 + **[驗證](#mig-runbook-validation)** — 提供遷移後資料完整性檢查、功能驗證和效能比較的程序。 透過遵循此 Runbook 中的指引，團隊可以確保順利、安全且有效率地轉換至 Amazon DocumentDB，同時保留應用程式功能並將風險降至最低。 ## 相容性 **Topics** + [核心功能相容性](#w2aac15b9c13c13) + [Amazon DocumentDB 相容性評估工具](#w2aac15b9c13c15) 從 MongoDB 遷移到 Amazon DocumentDB 時，完整的初始評估和功能相容性檢查對於成功遷移至關重要。此程序從 MongoDB 功能的全面清查開始，包括彙總管道運算子、查詢模式、索引和資料模型。 由於 Amazon 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`、`$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、操作和資料類型](mongo-apis.md)和 [功能差異：Amazon DocumentDB 和 MongoDB](functional-differences.md)以最大化資料庫的潛力。 Amazon DocumentDB 不支援 MongoDB 提供的所有索引。我們在 GitHub 上提供免費[索引工具](https://github.com/awslabs/amazon-documentdb-tools/blob/master/index-tool/README.md)，以檢查相容性。執行索引工具來評估不相容並相應地規劃解決方法。 ### Amazon DocumentDB 相容性評估工具 GitHub 上的 [Amazon DocumentDB 相容性工具](https://github.com/awslabs/amazon-documentdb-tools/blob/master/compat-tool/README.md)會分析您的MongoDB工作負載，並報告不支援或需要在 Amazon DocumentDB 中變更的運算子、命令和功能。它支援從 3.6 到 8.0.1 的目標版本 （預設值：8.0.1)。 **建議：URI 模式 (MongoDB 5.0\+)** URI 模式會直接連線至 MongoDB 執行個體、即時取樣操作，而且不需要分析或日誌存取。 **替代方法** + **日誌型分析** — 剖析MongoDB分析器日誌。擷取實際執行時間行為，但需要啟用分析，且僅涵蓋記錄期間。 + **原始程式碼分析** — 掃描應用程式原始程式碼以取得 MongoDB API 用量。提供全面的涵蓋範圍，但可能會標記未使用的程式碼路徑，並且無法偵測動態建構的查詢。 **先決條件** + Python 3.7\+ + 複製工具： `git clone https://github.com/awslabs/amazon-documentdb-tools.git` + 安裝相依性： `pip install -r compat-tool/requirements.txt` 如需完整用量詳細資訊和所有可用選項，請參閱 GitHub 上的 [README](https://github.com/awslabs/amazon-documentdb-tools/blob/master/compat-tool/README.md)。 ## 工作負載探索 從 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 相容，但支援的功能存在差異，例如： + **交易** — 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 支援的身分驗證機制。 + **權限差異** — 識別沒有直接 Amazon DocumentDB 對等項目的 MongoDB 權限 （例如叢集管理角色）。 Amazon DocumentDB + **應用程式身分驗證** — 更新 Amazon DocumentDB 密碼政策的連線字串和憑證管理。您可以使用秘密管理員來存放您的登入資料並輪換密碼。 + **服務帳戶管理** — 建立管理服務帳戶登入資料的程序 AWS Secrets Manager。 + **最低權限實作** — 檢閱和精簡存取控制，以在新環境中實作最低權限原則。 **加密** 確保靜態加密和傳輸中加密符合合規要求。 **網路組態** 規劃 [Virtual Private Cloud (VPC)](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html) 設定和安全群組規則。 ### 操作和監控考量 為了維護系統可靠性，工作負載探索也應該包含： + **備份和還原策略** — 評估現有的備份方法和 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 秒的間隔對精細作業系統層級指標啟用增強型監控。 ## 建立新的目標叢集 依照中的步驟建立 Amazon DocumentDB 叢集[建立 Amazon DocumentDB 叢集](db-cluster-create.md)。設定叢集進行遷移時，請套用下列建議： + **執行個體類別：**選擇 R8G 以獲得最佳效能。如果您的目標區域無法使用 R8G，請使用 R6G。盡可能選擇大型執行個體，以獲得最佳完全載入輸送量。遷移完成後縮減規模。 + **引擎版本：**最新 (8.0.1) + **執行個體數量：**選擇 1 個執行個體，將遷移期間的成本降至最低。完整載入遷移完成後，將 擴展至 3 個執行個體以獲得高可用性。 + **網路設定：**確保您的 Amazon DocumentDB 安全群組允許來自 DMS 複寫執行個體安全群組 （用於線上遷移） 或從 EC2 遷移主機 （用於使用 mongorestore 的離線遷移） 的傳入連線。 ## 索引遷移 從 MongoDB 遷移到 Amazon DocumentDB 不僅需要傳輸資料，還包含索引，以維持查詢效能並最佳化資料庫操作。本節概述將索引從 MongoDB 遷移至 Amazon DocumentDB 的詳細step-by-step程序，同時確保相容性和效率。 ### 使用 Amazon DocumentDB 索引工具 **在 GitHub 上複製[索引工具](https://github.com/awslabs/amazon-documentdb-tools/blob/master/index-tool/README.md) ** ``` 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 ``` **重要說明** + 基於安全考量，密碼不會匯出，且必須手動新增至 user.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 複寫執行個體子網路的路由。 **內部部署 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 私有連線 (Enterprise 層）。 + 建立具有適當讀取/寫入許可的專用使用者。 + 使用將 SSL 模式設定為 "verify-full" 的 MongoDB Atlas 連線字串。 + 確保遷移持續時間有足夠的 oplog 大小。 **Amazon DocumentDB 來源** 設定來源 Amazon DocumentDB 安全群組，以允許來自 DMS 複寫執行個體安全群組的傳入流量。 #### 建立 DMS 複寫執行個體 在 GitHub 上使用 [DMS Buddy](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/dms_buddy) 來建立具有最佳 DMS 設定和執行個體大小的最佳遷移基礎設施。如果您想要手動設定 ，請依照下列步驟進行： 1. 在 AWS DMS 主控台的導覽窗格中，選擇**遷移或複寫**，然後選擇**佈建執行個體**。 1. 輸入複寫執行個體詳細資訊： + **執行個體名稱**：選擇唯一的名稱。 + **執行個體類別**：根據工作負載選取 。範例：dms.r7i.large （小型工作負載）、dms.r7i.4xlarge （大型工作負載）。 + **引擎版本**：3.5.4 + **配置的儲存空間**：預設值為 50 GB （視需要增加）。這取決於文件大小、更新/秒和完全載入持續時間。 + **異地同步備份部署**：視需要啟用 以獲得高可用性。 + 選擇與 Amazon DocumentDB 相同的 VPC。 + 確保**安全群組**允許來自來源和 Amazon DocumentDB 的傳入流量。 1. 選擇**建立複寫執行個體**，並等待狀態可用。 #### 建立 DMS 端點 ##### 建立來源端點 **對於 MongoDB 來源** 1. 在 DMS 主控台的導覽窗格中，選擇**遷移或複寫**，然後選擇**端點**。 1. 選擇**建立端點**。 1. 在**建立端點**頁面上，選擇**來源端點**。 1. 在**端點組態**區段中： + 輸入唯一且有意義的**端點識別符** （例如，「mongodb-source」)。 + 選擇 **MongoDB** 做為**來源引擎**。 + 對於**端點資料庫的存取**，選擇**手動提供存取資訊**。 + 在**伺服器名稱**中，輸入您的 {{MongoDB 伺服器 DNS 名稱/IP 地址}}。 + 針對**連接埠**，輸入 **27017** （預設 MongoDB 連接埠）。 + 對於**身分驗證模式**，為您的應用程式選擇適當的模式 （密碼/SSL) （預設為 Secrets Manager)。 + 如果**身分驗證模式**是**密碼**，請提供： + **使用者名稱和密碼******：輸入 MongoDB 登入資料。 + **資料庫名稱**：您的來源資料庫名稱。 + **身分驗證機制**：SCRAM-SHA-1 （預設） 或適當的機制 1. 對於**中繼資料模式**，請保留 **文件**的預設設定。 1. 其他連線屬性： + authSource=admin （如果身分驗證資料庫不同） + replicaSet= (CDC 需要） **對於 Amazon DocumentDB 來源** 1. 在 DMS 主控台的導覽窗格中，選擇**遷移或複寫**，然後選擇**端點**。 1. 選擇**建立端點**。 1. 在**建立端點**頁面上，選擇**來源端點**。 1. 在**端點組態**區段中： + 輸入唯一且有意義的**端點識別符** （例如 "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 （預設） 或適當的機制 1. 對於**中繼資料模式**，請保留 **文件**的預設設定。 ##### 建立目標端點 (Amazon DocumentDB) 1. 在 DMS 主控台的導覽窗格中，選擇**遷移或複寫**，然後選擇**端點**。 1. 選擇**建立端點**。 1. 在**建立端點**頁面上，選擇**目標端點**。 1. 在**端點組態**區段中： + 輸入唯一且有意義的**端點識別符** （例如 "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 （預設） 或適當的機制 1. 對於**中繼資料模式**，請保留 **文件**的預設設定。 #### 建立複寫任務 1. 在 DMS 主控台的導覽窗格中，選擇**遷移或複寫**，然後選擇**任務**。 1. 選擇 **Create task (建立任務)**。 1. 在**建立任務**頁面上的任務**組態**區段中： + 輸入唯一且有意義的**任務識別符** （例如「mongodb-docdb-replication」)。 + 在來源**資料庫端點下拉式功能表中選擇您先前建立的來源端點**。 + 選擇您先前在目標**資料庫端點下拉式功能表中建立的目標端點**。 + 選擇您先前在**佈建執行個體下拉式功能表中建立的複寫執行個體**。 + 針對**任務類型**，選擇**遷移和複寫**。 + 對於**您希望繼續從來源複寫到目標的時間長度？**，請選擇**在有限時間內**。 1. 在**設定**區段中： + 針對**目標資料表準備模式**，選擇**不執行任何動作**。否則，將會刪除已建立的集合和索引。 + 對於**任務日誌**，勾選**開啟 CloudWatch** 日誌方塊。 + 保留所有其他設定的預設值。 1. 回到**設定**區段頂端，針對**編輯模式**，選擇 **JSON 編輯器**並設定下列屬性： ``` { "TargetMetadata": { "ParallelApplyThreads": 5 }, "FullLoadSettings": { "MaxFullLoadSubTasks": 16 } } ``` `MaxFullLoadSubTasks` 根據您的集合計數和執行個體容量進行設定。對於較少或較小的集合，請使用較低的值 (2–4)，對於許多大型集合，請使用較高的值 (8–16)。如需自動調整大小，請參閱 GitHub 上的 [DMS Buddy](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/dms_buddy)。 1. 在**資料表映射**區段中，新增新的選取規則： + 針對**結構描述名稱**，新增要遷移的來源資料庫。使用 % 指定多個資料庫。 + 針對**結構描述資料表**名稱，新增要遷移的來源集合。使用 % 指定多個集合。 + 對於**動作**，保留 **Include** 的預設設定 1. 對於大型集合 （超過 100GB)，新增**資料表設定規則**： + 針對**結構描述名稱**，新增要遷移的來源資料庫。使用 % 指定多個資料庫。 + 針對**結構描述資料表**名稱，新增要遷移的來源集合。使用 % 指定多個集合。 + 對於**分割區數量**，請根據您的工作負載設定 。對於少量大型集合，請將分割區設為 ≥`MaxFullLoadSubTasks`，讓所有工作者保持忙碌。對於許多平行載入的集合，請設定 ≤ 的分割區，`MaxFullLoadSubTasks`因為集合計數本身提供足夠的平行處理。 1. 在**預遷移評估**區段中，確定已關閉。Amazon DocumentDB 不支援預遷移評估做為目標，且必須停用。 ### 離線移轉 本節概述使用原生 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 叢集 請參閱 [建立新的目標叢集](#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/秒） + **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 主控台。 1. 在您的日誌群組上尋找並選擇 。它看起來類似於「dms-tasks –」。 1. 尋找可能包含錯誤資訊的日誌串流： + 名稱中有「錯誤」的串流 + 具有任務 IDs串流 + 遷移期間的最新日誌串流 1. 在這些串流中，搜尋關鍵字，例如： + 「錯誤」 + 「例外狀況」 + 「失敗」 + 「警告」 #### DMS 任務狀態 （使用 AWS CLI) ``` aws dms describe-replication-tasks \ --filters Name=replication-task-id,Values={{}} \ --query "ReplicationTasks[0].Status" ``` 預期的狀態流程： 建立 → ready → 執行中 → 停止 → 已停止 （或失敗） #### 使用 監控 `docdb-dashboarder` 該`docdb-dashboarder`工具透過自動產生具有基本效能指標的 CloudWatch 儀表板，為 Amazon DocumentDB 叢集提供全面的監控。這些儀表板會顯示關鍵叢集層級指標 （複本延遲、操作計數器）、執行個體層級指標 (CPU、記憶體、連線） 和儲存指標 （磁碟區使用量、備份儲存）。對於遷移案例，該工具提供專門的儀表板，使用 CDC 複寫延遲和操作速率等指標來追蹤遷移進度。儀表板可以同時監控多個叢集，並包含對 NVMe 後端執行個體的支援。透過視覺化這些指標，團隊可以主動識別效能瓶頸、最佳化資源配置，並確保其 Amazon DocumentDB 部署的順暢操作。該工具無需手動建立儀表板，同時在所有環境中提供一致的監控。如需設定說明和進階組態選項，請參閱 [Amazon DocumentDB Dashboarder Tool](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 } }])" ``` 擷取相同的文件 IDs（目標）： ``` 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 工具進行驗證 GitHub 上的 [DataDiffer 工具](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/data-differ)提供可靠的方法來比較來源和目標資料庫之間的資料。 #### 先決條件 安裝 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://:@: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 工具時的最佳實務： + **分階段執行** — 首先驗證文件計數，然後範例金鑰文件，並視需要執行完整比較。 + **檢查結構描述差異** — Amazon DocumentDB 與 MongoDB 相比有一些限制。工具會反白顯示不相容的資料類型或結構。 + 在**靜止期間驗證** — 在寫入操作最少時執行驗證，以確保一致性。 + **監控資源用量** — 比較程序可能會耗費大量資源。相應地調整批次大小和執行緒計數。 + **驗證索引** — 驗證資料之後，請確定已在目標 Amazon DocumentDB 叢集上建立所有必要的索引。 + **文件驗證結果** — 將每個集合的驗證結果記錄為遷移文件的一部分。