共用方式為


針對 Azure Cosmos DB 模擬器進行疑難解答

Azure Cosmos DB 模擬器提供模擬雲端服務以進行開發的環境。 使用本文中的秘訣,協助您針對安裝或使用模擬器時可能會遇到的問題進行疑難解答。

疑難排解檢查清單

以下是 Azure Cosmos DB 模擬器未如預期般運作時所要遵循的常見疑難解答步驟清單。

重設數據

如果您已安裝新版本的模擬器,而且您遇到錯誤,請確定您重設數據。 若要重設數據,請從系統匣開啟 Azure Cosmos DB 模擬器操作功能表,然後選取 [ 重設數據]。

如果重設資料未修正錯誤,您可以:

  • 卸載模擬器。
  • 卸載舊版的模擬器(如果有的話)。
  • %ProgramFiles%\Azure Cosmos DB Emulator拿掉資料夾。
  • 重新安裝模擬器。

或者,如果重設數據無法運作,請移至 %LOCALAPPDATA%\CosmosDBEmulator 位置,然後刪除資料夾。

檢閱損毀的 Windows 性能計數器

  • 如果 Azure Cosmos DB 模擬器停止回應,請從 %LOCALAPPDATA%\CrashDumps 資料夾收集傾印檔案、壓縮檔案,然後在 Azure 入口網站開啟支援票證。

  • 如果 Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe 停止回應,此損毀可能表示性能計數器已損毀。 若要檢查計數器狀態,請執行下列命令:

    lodctr /R
    

診斷連線問題

  • 如果您遇到連線問題,請收集追蹤檔案、壓縮檔案,然後在 Azure 入口網站開啟支援票證。

  • 如果您收到「服務無法使用」訊息,模擬器可能不會初始化網路堆疊。 檢查您是否已安裝 Pulse Secure ClientJuniper Networks Client ,因為其網路篩選驅動程式可能會導致問題。 您也可以嘗試卸載其他網路篩選驅動程式來修正問題。 或者,使用 /DisableRIO 將模擬器網路通訊切換至一般 Winsock 來啟動模擬器。

  • 如果您收到連線錯誤訊息,例如 "Forbidden", "message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting...",此錯誤訊息可能會指出操作系統中的全域變更(例如 Insider Preview 組建 20170),或啟用 TLS 1.3 做為預設通訊協定的瀏覽器設定中的變更。 類似的錯誤訊息,例如「Microsoft.Azure.Documents.DocumentClientException:要求是在傳輸通訊協定或加密中使用禁止加密進行。 如果您使用 SDK 對 Azure Cosmos DB 模擬器執行要求,可能會產生 [檢查帳戶 SSL/TLS 最小允許的通訊協定設定]。 也可能會發生此錯誤,因為 Azure Cosmos DB 模擬器只支援 TLS 1.2 通訊協定。 建議的因應措施是將 TLS 1.2 設定為預設值。

    例如:

    1. IIS 管理員中,移至 [網站>默認網站]。

    2. 找出埠 8081 的網站系結,並加以編輯以停用 TLS 1.3。 您也可以使用 [設定] 選項來更新網頁瀏覽器的設定。

      注意

      如果您的電腦進入睡眠模式或在模擬器執行時執行任何 OS 更新,您可能會看到「服務目前無法使用」錯誤訊息。

    3. 若要重設模擬器數據,請以滑鼠右鍵按兩下出現在 Windows 通知匣中的圖示,然後選取 [ 重設數據]。

收集追蹤檔案

若要收集偵錯追蹤,請在命令提示字元視窗中以系統管理員身分執行下列命令:

  1. 瀏覽至模擬器安裝所在的路徑:

    cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
    
  2. 關閉模擬器,並監看系統匣,以確定程式已關閉:

    Microsoft.Azure.Cosmos.Emulator.exe /shutdown
    

    注意

    程式可能需要一分鐘的時間才能完成。 您也可以在 Azure Cosmos DB 模擬器使用者介面中選取 [結束 ]。

  3. 執行下列命令來啟動記錄:

    Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces
    
  4. 啟動模擬器:

    Microsoft.Azure.Cosmos.Emulator.exe
    
  5. 重現問題。 如果數據總管無法運作,您只需要等待幾秒鐘的時間,瀏覽器才能偵測到錯誤。

  6. 停止記錄:

    Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces
    
  7. 流覽至 %ProgramFiles%\Azure Cosmos DB Emulator 路徑,並找出 docdbemulator_000001.etl 檔案。

  8. 在 Azure 入口網站開啟支援票證,並包含 .etl 檔案以及重現問題所需的任何步驟。

安裝用戶端應用程式的憑證

有時候,您可能需要取得導出的模擬器憑證,並將其與用戶端應用程式搭配使用。 確切的程式會依 SDK 而有所不同。

匯出 TLS/SLL 憑證

匯出模擬器憑證,以從未與 Windows 證書存儲整合的語言和運行時間環境成功使用模擬器端點。 第一次執行模擬器之後,您可以使用 Windows 憑證管理員或 PowerShell 導出憑證。

  1. 使用易記名稱 DocumentDbEmulatorCertificate 擷取憑證,並將憑證儲存在名為 $cert的殼層變數中。

    $cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}
    
  2. 使用 Export-Certificate 將憑證匯出至主資料夾中的臨時檔。

    $params = @{
        Cert = $cert
        Type = "CERT"
        FilePath = "$home/tmp-cert.cer"
        NoClobber = $true
    }
    Export-Certificate @params
    

    注意

    在 Windows 中,主資料夾通常是 C:\Users\[username]\,假設主磁碟驅動器是 C:

  3. 使用 certutil 將憑證 轉換成 Base-64 編碼的 X.509 憑證檔案。

    certutil -encode $home/tmp-cert.cer $home/cosmosdbcert.cer
    
  4. 拿掉暫存盤。

    Remove-Item $home/tmp-cert.cer
    

匯入 Java 應用程式的憑證

當您執行使用 Java 型用戶端的 Java 應用程式或 MongoDB 應用程式時,將憑證安裝到 Java 預設證書儲存會比傳遞 -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" 參數更容易。 例如包含的 Java 示範應用程式 (https://localhost:8081/_explorer/index.html) 取決於預設的憑證存放區。

依照建立、導出和匯入 TLS/SSL 憑證中的指示,將 X.509 憑證匯入預設 Java 證書存儲。 請記住,在執行 keytool 時,您正在 %JAVA_HOME% 目錄中工作。 將憑證匯入證書存儲之後,SQL 和適用於 MongoDB 的 Azure Cosmos DB API 用戶端可以連線到 Azure Cosmos DB 模擬器。

或者,您可以執行下列 bash 腳本來匯入憑證:

#!/bin/bash

# If the emulator was started with /AllowNetworkAccess, replace the following with the actual IP address of it:
EMULATOR_HOST=localhost
EMULATOR_PORT=8081
EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert
openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > $EMULATOR_CERT_PATH
# Delete the cert if it already exists
sudo $JAVA_HOME/bin/keytool -cacerts -delete -alias cosmos_emulator
# Import the cert
sudo $JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

CosmosDBEmulatorCertificate安裝 TLS/SSL 憑證之後,您的應用程式應該能夠連線並使用本機 Azure Cosmos DB 模擬器。

如果您有任何問題,請參閱偵錯 SSL/TLS 連線。 在大多數情況下,憑證可能不會安裝到 %JAVA_HOME%/jre/lib/security/cacerts 存放區。 例如,如果有多個已安裝的 Java 版本,您的應用程式可能會使用與您更新的證書存儲不同。

匯入 Python 應用程式的憑證

當您從 Python 應用程式連線到模擬器時,TLS 驗證會停用。 預設情況下,適用於 Azure Cosmos DB for NoSQL 的 Python SDK 在連線到本機模擬器時不會嘗試使用 TLS/SSL 憑證。 如需詳細資訊,請參閱適用於 Python 的 Azure Cosmos DB for NoSQL 用戶端程式庫

如果您想要使用 TLS 驗證,請遵循套接字物件的 TLS/SSL 包裝函式中的範例。

匯入Node.js應用程式的憑證

從 Node.js SDK 連線到模擬器時,會停用 TLS 驗證。 根據預設, 適用於 NoSQL 的 API Node.js SDK(1.10.1 版或更新版本) 不會在連線到本機模擬器時嘗試使用 TLS/SSL 憑證。

若要使用 TLS 驗證,請依照 Node.js 文件中的範例操作。

輪換憑證

您可以使用 自變數開啟模擬器,強制重新產生模擬器 /ResetDataPath 憑證。 此動作會抹除模擬器本機儲存的所有數據。 如需命令行自變數的詳細資訊,請參閱 Windows 模擬器命令行自變數。

提示

或者,從 Windows 系統匣中的 Azure Cosmos DB 模擬器操作功能選取 [重設數據 ]。

如果您將憑證安裝到 Java 證書存儲中,或將其用於其他地方,則必須使用目前的憑證重新匯入這些憑證。 在您更新憑證之前,您的應用程式無法連線到本機模擬器。