排查 Azure Cosmos DB 模拟器问题

项目
04/13/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 客户端 ，因为其网络筛选器驱动程序可能会导致问题。还可以尝试卸载其他网络筛选器驱动程序来解决此问题。或者，通过使用 /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"

关闭仿真器，并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 检索证书，并将证书存储在名为的 $certshell 变量中。
```
$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 证书存储中或在其他地方使用，则必须使用当前证书重新导入它们。在更新证书之前，应用程序无法连接到本地模拟器。

通过