排查 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..."，此错误消息可能指示 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 设置为默认值。

例如：
1. 在 IIS 管理器中，转到“网站>默认网站”。
2. 找到端口 8081 的站点绑定，然后编辑它们以禁用 TLS 1.3。还可以使用 “设置”选项更新 Web 浏览器的设置 。
  
  注意
  
  如果计算机进入睡眠模式或在模拟器运行时运行任何 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 的 shell 变量中。
```
$cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}
```
使用导出证书将证书导出到主文件夹中的临时文件。
```
$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 验证。默认情况下，适用于 NoSQL 的 API 的 Node.js SDK（版本 1.10.1 或更高版本）在连接到本地模拟器时不会尝试使用 TLS/SSL 证书。

如果要使用 TLS 验证，请按照 Node.js 文档中的示例进行操作。

轮换证书

可以通过使用 /ResetDataPath 参数打开模拟器来强制重新生成模拟器证书。此操作会擦除模拟器本地存储的所有数据。有关命令行参数的详细信息，请参阅 Windows 模拟器命令行参数。

提示

或者，从 Windows 系统托盘中的 Azure Cosmos DB 模拟器上下文菜单中选择“ 重置数据 ”。

如果将证书安装到 Java 证书存储中或在其他地方使用它们，则必须使用当前证书重新导入它们。在更新证书之前，应用程序无法连接到本地模拟器。

通过