全部產品
Search

搜尋本產品

    ApsaraDB for MongoDB：串連訪問與網路

    文件中心

    ApsaraDB for MongoDB：串連訪問與網路

    更新時間：Jun 06, 2026

    本文旨在協助您解決串連 MongoDB 執行個體時遇到的問題。建議優先查閱常見報錯章節，以快速定位並解決問題；如果未找到匹配的錯誤資訊，可參考排查步驟，自主診斷和解決串連問題。

    串連問題排查步驟

    步驟一：網路連接

    排查方法

    通過以下命令測試到達MongoDB執行個體的網路是否通暢。

    • ping <網域名稱>，例如ping dds-xxxx.mongodb.rds.aliyuncs.com

      ping dds-xxx.mongodb.rds.aliyuncs.com
PING dds-xxx.mongodb.rds.aliyuncs.com (xxx): 56 data bytes
64 bytes from xxx: icmp_seq=0 ttl=90 time=7.698 ms
64 bytes from xxx: icmp_seq=1 ttl=90 time=7.085 ms
64 bytes from xxx: icmp_seq=2 ttl=90 time=11.006 ms
64 bytes from xxx: icmp_seq=3 ttl=90 time=12.154 ms
64 bytes from xxx: icmp_seq=4 ttl=90 time=9.149 ms

      圖中樣本表示用戶端與MongoDB執行個體之間網路連通。

    • telnet <網域名稱> <連接埠號碼>，例如telnet dds-xxxx.mongodb.rds.aliyuncs.com 3717

      root@mongotest:~# telnet xxx.mongodb.rds.aliyuncs.com 3717
Trying xxx...
Connected to xxx.mongodb.rds.aliyuncs.com.
Escape character is '^]'.

      圖中樣本表示可以正常解析該網域名稱地址，且3717連接埠可正常通訊。

    核查清單

    如果網路測試不通，請通過以下方式排查問題及解決。

    檢查執行個體狀態。執行個體的狀態需為運行中。

    檢查白名單設定。需要將用戶端IP地址添加到ApsaraDB for MongoDB執行個體的白名單中。

    • 排查方法：

      請在資料庫的白名單中臨時添加0.0.0.0/0，如果設定後可以正常訪問，說明是白名單設定存在問題。

      重要

      0.0.0.0/0表示允許任何裝置訪問ApsaraDB for MongoDB執行個體，請謹慎使用，測試完成後請及時修改。

    • 解決方案：

      將正確的用戶端IP地址添加到ApsaraDB for MongoDB執行個體的白名單中。擷取本地公網IP地址的方法，請參見常見問題。

    檢查網路環境與執行個體串連地址。ApsaraDB for MongoDB支援私網和公網兩種串連方式，不同網路環境需使用不同的串連地址。

    您可以登入MongoDB管理主控台，在数据库连接頁面查看ApsaraDB for MongoDB執行個體的串連地址。

    步驟二：授權與身分識別驗證

    確認賬戶名與密碼，並檢查密碼中是否包含特殊字元。

    • 確認提供的賬戶名與密碼資訊正確。

    • 修改密碼。如果您需要修改密碼，請參見重設密碼。

      如果您通過DMS串連ApsaraDB for MongoDB執行個體後，修改了密碼，請在Data Management服務頁面，右擊目標執行個體，編輯執行個體重新登入。

    • 特殊字元。通過Mongo Shell或程式碼串連ApsaraDB for MongoDB執行個體時，如果串連串中的帳號密碼包含特殊字元!@#$%^&*()_+=，需要轉義處理。解決方案，請參見如何解決串連串中帳號密碼包含特殊字元導致失敗的問題？。

    檢查鑒權資料庫。資料庫帳號必須在所屬的資料庫下驗證，才能鑒權成功。

    請參見如何在串連中指定鑒權資料庫？。

    檢查執行個體串連地址。複本集執行個體，並且需要執行寫操作，推薦使用ConnectionStringURI地址串連執行個體。

    • 現象：沒有改變串連地址，執行個體突然無法串連。

    • 原因：僅主節點可以執行寫操作。如果您的業務之前通過主節點（Primary節點）的地址串連，複本集執行個體主備切換後，實際串連的節點角色變成了從節點（Secondary節點），寫入會失敗。

    • 解決方案：

      請為業務設計重連機制和異常處理能力，串連閃斷後可自動重連，保障業務穩定運行。

    步驟三：其他問題核查

    檢查執行個體效能是否滿足業務需求。

    檢查第三方工具。

    當第三方工具（如Navicat、Compass等工具）無法串連ApsaraDB for MongoDB執行個體時，可能是執行個體設定或者第三方工具設定不正確導致。建議您通過以下步驟排查：

    1. 使用Mongo Shell測試。

      建議通過Mongo Shell工具串連執行個體的高可用串連串（ConnectionStringURI地址）串連執行個體測試。

    2. 根據測試結果排查問題。

      • 串連成功：表示執行個體本身可訪問，可能是第三方工具設定不正確。請根據您實際使用的工具，具體排查工具的各種設定。

      • 串連失敗：若Mongo Shell無法串連，可能是執行個體設定不正確。請參照本文排查網路連接、授權及身分識別驗證等其他設定。

    常見報錯

    錯誤資訊

    報錯原因及解決方案

    network error while attempting to run command 'isMaster' on host 'dds-xxxx.mongodb.rds.aliyuncs.com:3717' :exception: connect failed

    • Timed out after 3000ms while waiting for a server that matches ReadPreferenceServerSelector{readPreference=primary}. exception=(com.mongodb.MongoSocketReadException: Prematurely reached end of stream)

    • Socket recv() errno:54 Connection reset by peer x.x.x.x:27017

    可能該執行個體的串連數已經達到上限，無法為新的串連請求建立串連。

    解決方案：

    1. 檢查串連數是否耗盡：如何查詢串連數？。

    2. 最佳化串連使用：如何解決執行個體串連數滿的問題？。

    MongoDB.Driver.MongoWaitQueueFullException: The wait queue for acquiring a connection to server xxx is full.

    MongoDB 驅動程式的等待隊列已滿，可能由於串連池設定較小或出現高並發請求等原因導致，從而無法提供可用串連。

    解決方案：

    1. 建議您優先檢查對應報錯程式的串連池配置，例如確保設定了合理的串連池大小，詳情請參見如何限制終端串連數？。

    2. 若程式側調整後問題依然存在，您可檢查MongoDB執行個體側的串連數是否耗盡，請參見：

      1. 如何查詢串連數？

      2. 如何解決執行個體串連數滿的問題？

    (TooManyLogicalSessions) Unable to add session into the cache because the number of active sessions is too high.

    並發串連過多時，可能會耗盡可用會話。

    解決方案：

    1. 排查因串連數耗盡導致串連失敗的問題。

      1. 如何查詢串連數？

      2. 如何解決執行個體串連數滿的問題？

    2. 如果串連數未發現異常，排查執行個體其他效能是否無法滿足業務需求。

      1. 通過節點監控查看常用資源（例如CPU使用率和記憶體使用量率）的運行情況，確認執行個體規格大小是否滿足業務需求。

      2. 如果執行個體規格過小，但負載較高，可在業務低峰期變更執行個體配置。

    • getaddrinfo failed.

    • No suitable servers found (`serverSelectionTryOnce` set).

    請檢查執行個體串連地址是否正確，串連地址說明，請參見：

    • Failed to connect to 10.*.*.8:3717 after 5000 milliseconds, giving up.Error: couldn't connect to server 10.*.*.8:3717 (10.*.*.8), connection attempt failed

    • pymongo.errors.ServerSelectionTimeoutError: dds-xxxx.mongodb.rds.aliyuncs.com:3717: [Errno 113] No route to host,dds-xxxx.mongodb.rds.aliyuncs.com:3717

    • InvalidInstanceId.NotFound: The instance not in current vpc.

    Elastic Compute Service執行個體通過私網串連ApsaraDB for MongoDB失敗。

    解決方案：

    1. 檢查白名單設定。確保Elastic Compute Service執行個體的私網IP地址添加到ApsaraDB for MongoDB執行個體的白名單。

    2. 確保ECS執行個體與MongoDB執行個體網路互連。

      ECS與MongoDB執行個體在同一個專用網路中（VPC ID相同），可直接通過私網串連。跨VPC時，可參考以下方式調整。

    org.springframework.data.mongodb.UncategorizedMongoDbException: Timeout while receiving message; nested exception is com.mongodb.MongoSocketReadTimeoutException: Timeout while receiving message

    • "errmsg": "not master", "code": 10107, "codeName": "NotMaster"

    • "errmsg": "not master", "code": 10107, "codeName": "NotWritablePrimary"

    • Time out after 30000ms while waiting for a server that matches writableServerSelector.

    • Command failed with error 10107 (NotWritablePrimary): 'not primary' on server xxx.

    • Explain's child command cannot run on this node. Are you explaining a write command on a secondary?

    • not master and slaveOk=false.

    • MongoNotPrimaryException: Command failed with error 10107 (NotMaster): 'not master' on server xxx.

    • reason: TopologyDescription { type: 'ReplicaSetNoPrimary',...}

    當前寫入資料的節點不是主節點（Primary節點）。

    原因：僅主節點可以執行寫操作。如果您的業務之前通過主節點（Primary節點）的地址串連，複本集執行個體主備切換後，實際串連的節點角色變成了從節點（Secondary節點），寫入會失敗。

    解決方案：

    請為業務設計重連機制和異常處理能力，串連閃斷後可自動重連，保障業務穩定運行。

    [Unauthorized] cloud instance error, disk locked, plz check and upgrade your disk quota,

    磁碟滿導致執行個體鎖定。

    解決方案：解決因磁碟空間耗盡導致的鎖定或無法寫入問題。

    (AuthenticationFailed) Authentication failed.

    • !xxx@dds-xxx.mongodb.rds.aliyuncs.com: event not found

    資料庫帳號的密碼中包含特殊字元!@#$%^&*()_+=。

    解決方案：如何解決串連串中帳號密碼包含特殊字元導致失敗的問題？。

    error getting cluster ID: (CommandNotFound) replSetGetConfig is forbidden by cloud provider for security reason

    ApsaraDB for MongoDB不支援replSetGetConfig命令。更多資訊，請參見ApsaraDB for MongoDB支援及限制哪些命令？

    常見問題

    如何查詢串連數？

    根據您購買的MongoDB執行個體規格不同，最大串連數也不同，詳情請參見執行個體規格。

    說明

    最大串連數是指執行個體中每個節點的最大串連數，例如您購買了1核2G規格的三節點複本集執行個體，那麼該執行個體的Primary節點和Secondary節點的最大串連數均為500，Hidden節點由於其架構特殊性，不對外提供服務。

    控制台查看

    1. 訪問MongoDB複本集執行個體列表或MongoDB分區叢集執行個體列表，在上方選擇地區，然後單擊目標執行個體ID。

    2. 在目標執行個體頁面的左側導覽列，單擊监控信息。

    3. 在监控信息頁面，查看執行個體當前的連接數資訊。

      執行個體為分區叢集執行個體時，您需要在頁面右上方選擇業務當前使用的Mongos節點。

    命令查看

    1. 通過Mongo Shell串連執行個體。

    2. 查看串連數。

      執行命令db.serverStatus().connections。

      mgset-123456:PRIMARY> db.serverStatus().connections
{
        "current" : 1,
        "available" : 999,
        "internal_current" : 10,
        "internal_available" : 990,
        "totalCreated" : 632
}

      參數說明：

      • "current" ：當前已經建立的串連數。

      • "available" ：當前可用的串連數。

    3. 查詢當前串連來源。

      1. 切換至admin資料庫。 

        use admin

      2. 執行命令db.runCommand({currentOp: 1, $all: true})。

        mgset-123456:PRIMARY> db.runCommand({currentOp: 1, $all:[{"active" : true}]})

      通過分析命令的輸出結果，您可以查詢每個串連對應的來源IP地址，從而得出各終端與MongoDB執行個體分別建立了多少串連。更多詳情請參見官方文檔。

    如何限制終端串連數？

    通過Connection String URI串連資料庫時，在URI末尾加上&maxPoolSize=<integer>即可設定串連池的串連數。Mongo Shell串連樣本（設定串連數為10），資料庫帳號為test，所屬資料庫為admin：

    mongo "mongodb://test:****@dds-bp19f409d7512****-pub.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****-pub.mongodb.rds.aliyuncs.com:3717/admin?replicaSet=mgset-6108****&maxPoolSize=10"
    說明

    關於不同語言的用戶端如何限制串連池的數量，請參見MongoDB官網的API文檔。

    如何解決執行個體串連數滿的問題？

    您可以通過重啟執行個體、組件或節點來臨時釋放所有的串連。

    重要

    重啟執行個體的操作會將執行個體的節點進行輪轉重啟，每個節點會有30秒左右的閃斷，如果集合的數量較多（超過1萬），閃斷時間也會隨之變長，重啟前請做好業務安排並確保應用有重連機制。

    為避免再次出現該問題，重啟後建議您參考下述方法進行調整：

    如何解決串連串中帳號密碼包含特殊字元導致失敗的問題？

    通過Mongo Shell或程式碼串連ApsaraDB for MongoDB執行個體時，串連串中的帳號密碼包含特殊字元!@#$%^&*()_+=，這些特殊字元在串連時無法被識別，導致執行個體串連失敗。

    解決方案：您需要在串連串中對特殊字元進行轉義處理，轉義規則如下：

    ! : %21
@ : %40
# : %23
$ : %24
% : %25
^ : %5e
& : %26
* : %2a
( : %28
) : %29
_ : %5f
+ : %2b
= : %3d

    樣本：密碼為ab@#c時，在串連串中對特殊字元進行轉義處理，密碼對應為ab%40%23c。

    如何在串連中指定鑒權資料庫？

    鑒權資料庫用於儲存資料庫帳號和密碼，資料庫帳號必須在所屬的資料庫下驗證，才能鑒權成功。

    假設帳號和密碼都是test，test帳號屬於testdb資料庫。

    高可用地址

    當您使用ConnectionStringURI地址、ReadOnly ConnectionStringURI高可用地址串連資料庫時，需要設定authSource參數指定資料庫帳號所屬的資料庫，如果不配置該參數，<database>會作為鑒權資料庫。

    樣本如下：

    • test帳號在testdb資料庫鑒權成功後，執行個體進入<database>資料庫。

    mongo "mongodb://test:test@<host1>:<port1>,<host2>:<port2>,...,<hostN>:<portN>/<database>?replicaSet=<replicaSet_value>&authSource=testdb"

    • test帳號在testdb資料庫鑒權成功後，執行個體進入testdb資料庫。

    mongo "mongodb://test:test@<host1>:<port1>,<host2>:<port2>,...,<hostN>:<portN>/testdb?replicaSet=<replicaSet_value>"

    單節點地址

    可使用如下命令登入：

    mongo --host $myhost --port $myport -u test -p test --authenticationDatabase testdb

    或者

        mongo --host $myhost --port $myport
    mongo> use testdb
    mongo> db.auth("test", "test")

    關於串連地址的參數說明，請參見複本集執行個體串連說明、分區叢集執行個體串連說明。

    如何通過DMS登入MongoDB資料庫？

    各執行個體類型串連方法，請參見：

    ApsaraDB for MongoDB支援哪些語言的用戶端進行串連？

    ApsaraDB for MongoDB完全相容官方MongoDB。即官方MongoDB支援的用戶端，ApsaraDB for MongoDB全部支援。

    例如：C、C++、C#、Java、Node.js、Python、PHP、Perl等語言，詳情請參見官方連結。

    程式碼樣本，請參見：

    說明

    為確保串連ApsaraDB for MongoDB時能夠正常鑒權，請使用MongoDB 3.0以上版本的Driver。

    ApsaraDB for MongoDB是否支援公網訪問？

    支援。具體操作，請參見本地用戶端通過公網串連MongoDB。

    ApsaraDB for MongoDB是否支援免密訪問？

    ApsaraDB for MongoDB已不支援開啟VPC網路下的免密訪問。

    已開啟免密訪問的執行個體可以關閉該功能，關閉後無法重新開啟。關閉免密訪問的具體操作，請參見關閉私網免密訪問。

    Windows系統安裝和使用Mongo Shell

    • 安裝Mongo Shell。訪問MongoDB Shell 下載頁面，按照頁面提示下載並安裝。

    • 使用Mongo Shell。

      • 開啟cmd命令視窗。

      • 串連MongoDB執行個體。

        樣本：

        mongosh "mongodb://test:****@dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717,dds-bp19f409d7512****.mongodb.rds.aliyuncs.com:3717/admin?replicaSet=mgset-6108****"

        關於串連地址的參數說明，請參見複本集執行個體串連說明、分區叢集執行個體串連說明。

    常見串連情境