排查 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 客户端 ,因为其网络筛选器驱动程序可能会导致问题。 还可以尝试卸载其他网络筛选器驱动程序来解决此问题。 或者,通过使用
/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..."
),此错误消息可能指示 OS (例如 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。 还可以使用 “设置” 选项更新 Web 浏览器的设置。
注意
如果计算机在模拟器运行时进入睡眠模式或运行任何 OS 更新,你可能会看到“服务当前不可用”错误消息。
若要重置仿真器数据,请右键单击 Windows 通知栏中显示的图标,然后选择“ 重置数据”。
收集跟踪文件
若要收集调试跟踪,请在命令提示符窗口中以管理员身份运行以下命令:
导航到安装仿真器的路径:
cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
关闭仿真器,并watch系统托盘,以确保程序已关闭:
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
shell 变量中。$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 和 Azure Cosmos DB API for MongoDB 的客户端可以连接到 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 验证处于禁用状态。 默认情况下, Node.js SDK (版本 1.10.1 或更高版本的 API for NoSQL) 在连接到本地模拟器时不会尝试使用 TLS/SSL 证书。
若要使用 TLS 验证,请按照 Node.js 文档中的示例进行操作。
轮换证书
可以通过使用 参数打开模拟器来强制重新生成仿真器 /ResetDataPath
证书。 此操作将清除模拟器在本地存储的所有数据。 有关命令行参数的详细信息,请参阅 Windows 模拟器命令行参数。
提示
或者,从 Windows 系统托盘中的 Azure Cosmos DB 模拟器上下文菜单中选择“ 重置数据 ”。
如果将证书安装到 Java 证书存储中或在其他地方使用,则必须使用当前证书重新导入它们。 在更新证书之前,应用程序无法连接到本地模拟器。