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

發行項
11/20/2024

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 Client 或 Juniper 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 通知匣中的圖示，然後選取 [ 重設數據]。

收集追蹤檔案

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

瀏覽至模擬器安裝所在的路徑：

cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"

關閉模擬器，並監看系統匣，以確定程式已關閉：
```
Microsoft.Azure.Cosmos.Emulator.exe /shutdown
```
注意

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

執行下列命令來啟動記錄：

Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces

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

停止記錄：

Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces

流覽至 %ProgramFiles%\Azure Cosmos DB Emulator 路徑，並找出 docdbemulator_000001.etl 檔案。
在 Azure 入口網站中開啟支援票證，並包含 .etl 檔案以及重現問題所需的任何步驟。

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

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

匯出 TLS/SLL 憑證

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

使用易記名稱 DocumentDbEmulatorCertificate 擷取憑證，並將憑證儲存在名為 $cert的殼層變數中。
```
$cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}
```
使用 Export-Certificate 將憑證匯出至主資料夾中的臨時檔。
```
$params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params
```
注意

在 Windows 中，主資料夾通常是 C:\Users\[username]\，假設主磁碟驅動器是 C:。
使用 certutil 將憑證 轉換成 Base-64 編碼的 X.509 憑證檔案。
```
certutil -encode $home/tmp-cert.cer $home/cosmosdbcert.cer
```
拿掉暫存盤。
```
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 證書存儲中，或將其用於其他地方，則必須使用目前的憑證重新匯入這些憑證。在您更新憑證之前，您的應用程式無法連線到本機模擬器。

共用方式為