針對 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
診斷連線問題
如果您收到「服務無法使用」訊息,模擬器可能不會初始化網路堆疊。 檢查您是否已安裝 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 設定為預設值。例如:
在 IIS 管理員中,移至 [網站>默認網站]。
找出埠 8081 的網站系結,並加以編輯以停用 TLS 1.3。 您也可以使用 [設定] 選項來更新網頁瀏覽器的設定。
注意
如果您的電腦進入睡眠模式或在模擬器執行時執行任何 OS 更新,您可能會看到「服務目前無法使用」錯誤訊息。
若要重設模擬器數據,請以滑鼠右鍵按兩下出現在 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 證書存儲中,或將其用於其他地方,則必須使用目前的憑證重新匯入這些憑證。 在您更新憑證之前,您的應用程式無法連線到本機模擬器。