在适用于 Linux 的 Docker 上运行 Azure Cosmos DB 仿真器

您所在的位置：网站首页 › docker模拟器 › 在适用于 Linux 的 Docker 上运行 Azure Cosmos DB 仿真器

在适用于 Linux 的 Docker 上运行 Azure Cosmos DB 仿真器

2023-03-20 04:22| 来源: 网络整理| 查看: 265

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

在用于 Linux 的 Docker（预览版）上运行仿真器项目 03/18/2023

适用于： NoSQL MongoDB

为方便进行开发，Azure Cosmos DB Linux 仿真器提供了一个模拟 Azure Cosmos DB 服务的本地环境。目前，Linux 模拟器仅支持 API for NoSQL 和 MongoDB。使用 Azure Cosmos DB 模拟器可在本地开发和测试应用程序，无需创建 Azure 订阅且不会产生任何费用。如果对应用程序在 Azure Cosmos DB Linux 仿真器中的工作情况感到满意，可以转为在云中切换到使用 Azure Cosmos DB 帐户。本文介绍了如何在 macOS 和 Linux 环境中安装和使用仿真器。

注意

Azure Cosmos DB Linux 模拟器目前处于预览模式，仅支持 API for NoSQL 和 MongoDB。与 Windows 版本相比，在仿真器每秒处理的请求数方面，性能可能会略微降低。物理分区的默认数量为 10，此默认数量直接影响可预配的容器数量。

不建议在生产环境中使用仿真器（预览版）。对于更大的工作负载，请使用 Windows 仿真器。

重要

Linux 模拟器目前对于采用 M1 和 M2 芯片的开发者计算机的支持有限。临时解决方法是安装 Windows 虚拟机并在该平台上运行模拟器。

模拟器如何工作？

Azure Cosmos DB Linux 仿真器提供对 Azure Cosmos DB 服务的高保真仿真。模拟器支持与 Azure Cosmos DB 等效的功能。功能包括创建数据、查询数据、预配和缩放容器，以及执行存储过程和触发器。可以使用 Azure Cosmos DB Linux 仿真器来开发和测试应用程序。还可以通过将 Azure Cosmos DB 连接终结点从仿真器更新到一个实时帐户，在全局规模将应用程序部署到 Azure。

使用仿真器时，依赖于 Azure 基础结构的功能（例如全局复制、读/写的个位数毫秒延迟，以及可调整的一致性级别）不适用。

Linux 仿真器和云服务之间的差异

由于 Azure Cosmos DB 仿真器提供一个在本地开发人员工作站上运行的模拟环境，因此该仿真器在功能上与云中的 Azure Cosmos DB 帐户之间存在一些差异：

目前，模拟器中的“数据资源管理器”窗格仅完全支持 API for NoSQL 和 MongoDB 客户端。

使用 Linux 仿真器时，只能在预配吞吐量模式下创建 Azure Cosmos DB 帐户；目前它不支持无服务器模式。

Linux 仿真器不是一项可缩放的服务，它不支持大量容器。使用 Azure Cosmos DB 仿真器时，默认情况下，最多可创建 10 个 400 RU/s 的固定大小容器（仅支持使用 Azure Cosmos DB SDK 进行创建），或 5 个不受限容器。有关如何更改此值的详细信息，请参阅设置 PartitionCount 值一文。

虽然一致性级别可以仅针对测试场景使用命令行参数进行调整（默认设置为“会话”），但用户可能不希望看到与云服务中的行为相同的行为。例如，除了向 Azure Cosmos DB SDK 发送帐户的默认一致性信号外，强和有限过期的一致性不会对仿真器产生任何影响。

Linux 仿真器未提供多区域复制功能。

你的 Azure Cosmos DB Linux 仿真器可能并非始终保持最新状态，即并非始终包含 Azure Cosmos DB 服务中的最新更改。你应当始终参考 Azure Cosmos DB 容量规划器来准确估算应用程序的吞吐量 (RU) 需求。

Linux 仿真器支持的最大 ID 属性大小为 254 个字符。

Linux 仿真器支持每个查询上限为五个 JOIN 语句。

在 macOS 上运行 Linux 仿真器

注意

仿真器仅支持 Macbook 与 Intel 处理器。

若要开始操作，请访问 Docker Hub 并安装适用于 macOS 的 Docker Desktop。使用以下步骤在 macOS 上运行仿真器：

检索本地计算机的 IP 地址。如果直接模式设置是使用 Azure Cosmos DB SDK（.NET、Java）配置的，则需要此步骤。

ipaddr="`ifconfig | grep "inet " | grep -Fv 127.0.0.1 | awk '{print $2}' | head -n 1`"

从注册表中拉取 Docker 映像。

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator

运行具有以下配置的 Docker 映像：

API for NoSQL 适用于 MongoDB 的 API docker run \ --publish 8081:8081 \ --publish 10250-10255:10250-10255 \ --memory 3g --cpus=2.0 \ --name=test-linux-emulator \ --env AZURE_COSMOS_EMULATOR_PARTITION_COUNT=10 \ --env AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE=true \ --env AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=$ipaddr \ --interactive \ --tty \ mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator docker run \ --publish 8081:8081 \ --publish 10250-10255:10250-10255 \ --name=test-linux-emulator-mongo \ --env AZURE_COSMOS_EMULATOR_PARTITION_COUNT=10 \ --env AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE=true \ --env AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=$ipaddr \ --env AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0 \ --interactive \ --tty \ mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb 安装证书

运行仿真器后，使用其他终端将本地计算机的 IP 地址加载到变量中。

ipaddr="`ifconfig | grep "inet " | grep -Fv 127.0.0.1 | awk '{print $2}' | head -n 1`"

接下来，下载仿真器的证书。

curl -k https://$ipaddr:8081/_explorer/emulator.pem > emulatorcert.crt 通过 UI 使用终结点

仿真器使用自签名证书来确保到其终结点的连接安全，并且需要手动信任。使用以下步骤通过 UI 使用所需的 Web 浏览器来使用终结点：

请确保已下载仿真器自签名证书

curl -k https://$ipaddr:8081/_explorer/emulator.pem > emulatorcert.crt

在 Mac 上打开 Keychain Access 应用以导入仿真器证书。

选择“文件”和“导入项”，然后导入 emulatorcert.crt 。

将 emulatorcert.crt 加载到 KeyChain 后，双击 localhost 名称，将信任设置更改为“始终信任” 。

现可浏览到 https://localhost:8081/_explorer/index.html 或 https://{your_local_ip}:8081/_explorer/index.html，并检索仿真器的连接字符串。

还可以选择对应用程序禁用 TLS/SSL 验证。建议仅在开发用途中禁用验证，在生产环境中运行时不应这样做。

在 Linux OS 上运行 Linux 仿真器

若要开始操作，请使用 apt 包并安装最新版本的 Docker。

sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io

如果使用适用于 Linux 的 Windows 子系统 (WSL)，请运行以下命令来获取 ifconfig：

sudo apt-get install net-tools

使用以下步骤在 Linux 上运行仿真器：

检索本地计算机的 IP 地址。如果直接模式设置是使用 Azure Cosmos DB SDK（.NET、Java）配置的，则需要此步骤。

ipaddr="`ifconfig | grep "inet " | grep -Fv 127.0.0.1 | awk '{print $2}' | head -n 1`"

从注册表中拉取 Docker 映像。

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator

运行具有以下配置的 Docker 映像：

运行仿真器后，使用其他终端将本地计算机的 IP 地址加载到变量中。

ipaddr="`ifconfig | grep "inet " | grep -Fv 127.0.0.1 | awk '{print $2}' | head -n 1`"

接下来，下载仿真器的证书。或者，在仿真器终结点准备好接收来自其他应用程序的请求时，还可以使用下面下载自签名仿真器证书的终结点来发送信号。

curl -k https://$ipaddr:8081/_explorer/emulator.pem > ~/emulatorcert.crt

将 CRT 文件复制到你的 Linux 分发版中包含自定义证书的文件夹。在 Debian 分发版中，它通常位于 /usr/local/share/ca-certificates/ 中。

cp ~/emulatorcert.crt /usr/local/share/ca-certificates/

更新 TLS/SSL 证书，这将更新 /etc/ssl/certs/ 文件夹。

update-ca-certificates

对于基于 Java 的应用程序，必须将证书导入到 Java 受信任存储。

keytool -keystore ~/cacerts -importcert -alias emulator_cert -file ~/emulatorcert.crt java -ea -Djavax.net.ssl.trustStore=~/cacerts -Djavax.net.ssl.trustStorePassword="changeit" $APPLICATION_ARGUMENTS 配置选项名称默认说明端口：-p 目前，仿真器终结点仅需要端口 8081 和 10250-10255。 AZURE_COSMOS_EMULATOR_PARTITION_COUNT 10 控制物理分区的总数，而物理分区又控制在给定时间点可以创建和存在的容器数。建议从小规模开始，以改进仿真器的启动时间，即 3。内存：-m 对于内存，需要 3 GB 或更多。核心：--cpus 确保分配足够的内存和 CPU 核心数。建议至少四个核心。 AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE false 此设置本身有助于在容器重启之间保存数据。 AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT 此设置为模拟器启用 API for MongoDB 终结点，并配置 MongoDB 服务器版本。（有效的服务器版本值包括 3.2、3.6、4.0 和 4.2）排查问题

本部分提供有关使用 Linux 仿真器时排查错误的提示。

连接问题我的应用无法连接到仿真器终结点（“无法建立 TLS/SSL 连接”）或无法启动数据资源管理器

请确保仿真器正在运行以下命令：

docker ps --all

验证具体的仿真器容器是否处于运行状态。

验证是否没有其他应用程序正在使用仿真器端口：8081 和 10250-10255。

验证容器端口 8081 是否已正确映射，并且是否可从容器之外的环境中进行访问。

netstat -lt

尝试使用 Docker 容器的 IP 地址而不非“localhost”访问仿真器的终结点和端口。

请确保已将仿真器自签名证书正确添加到 KeyChain。

对于 Java 应用程序，请确保已将证书导入到 Java 证书存储部分。

对于 .NET 应用程序，你可以禁用 TLS/SSL 验证：

.NET Standard 2.1+ .NET Standard 2.0

对于在与 .NET Standard 2.1 或更高版本兼容的框架中运行的任何应用程序，我们可以使用 CosmosClientOptions.HttpClientFactory：

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions() { HttpClientFactory = () => { HttpMessageHandler httpMessageHandler = new HttpClientHandler() { ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator }; return new HttpClient(httpMessageHandler); }, ConnectionMode = ConnectionMode.Gateway }; CosmosClient client = new CosmosClient(endpoint, authKey, cosmosClientOptions);

对于在与 .NET Standard 2.0 兼容的框架中运行的任何应用程序，我们可以使用 CosmosClientOptions.HttpClientFactory：

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions() { HttpClientFactory = () => { HttpMessageHandler httpMessageHandler = new HttpClientHandler() { ServerCertificateCustomValidationCallback = (req, cert, chain, errors) => true }; return new HttpClient(httpMessageHandler); }, ConnectionMode = ConnectionMode.Gateway }; CosmosClient client = new CosmosClient(endpoint, authKey, cosmosClientOptions); 我的 Node.js 应用正在报告自签名证书错误

如果尝试通过 localhost 以外的地址（例如容器 IP 地址）连接到仿真器，Node.js 将引发有关证书自签名的错误，即使已安装了证书也是如此。

可通过将环境变量 NODE_TLS_REJECT_UNAUTHORIZED 设置为 0 来禁用 TLS 验证：

NODE_TLS_REJECT_UNAUTHORIZED=0

建议仅将此标志用于本地开发，因为它禁用 Node.js 的 TLS。有关详细信息，请参阅 Node.js 文档和 Azure Cosmos DB 仿真器证书文档。

Docker 容器无法启动

仿真器出错，并出现以下消息：

/palrun: ERROR: Invalid mapping of address 0x40037d9000 in reserved address space below 0x400000000000. Possible causes: 1. The process (itself, or via a wrapper) starts up its own running environment sets the stack size limit to unlimited via syscall setrlimit(2); 2. The process (itself, or via a wrapper) adjusts its own execution domain and flag the system its legacy personality via syscall personality(2); 3. Sysadmin deliberately sets the system to run on legacy VA layout mode by adjusting a sysctl knob vm.legacy_va_layout.

此错误很可能是因为当前 Docker 主机处理器类型与我们的 Docker 映像不兼容。例如，如果计算机使用的是独特的芯片集或处理器体系结构。

我的应用收到太多与连接相关的超时信息

没有为 Docker 容器预配足够的资源（核心或内存）。建议增加核心数，或者减少启动时预配的物理分区数。

确保 TCP 连接数不超过当前的操作系统设置。

尝试降低应用程序中文档的大小。

我的应用无法创建数据库或容器

仿真器上预配的物理分区数太低。删除未使用的数据库/集合，或者使用大量物理分区启动仿真器。

可靠性和故障

仿真程序启动失败：

请确保正在运行适用于 Linux 的 Azure Cosmos DB 仿真器的最新映像。否则，请参阅上述与连接相关的问题部分。

如果 Azure Cosmos DB 仿真器数据文件夹为“卷装载”，请确保卷具有足够的空间，并且可读/写。

确认使用建议的设置创建的容器是否有效。如果有效，则失败的原因很可能是启动容器时通过相应的 Docker 命令传递的额外设置。

如果仿真器启动失败并出现以下错误：

"Failed loading Emulator secrets certificate. Error: 0x8009000f or similar, a new policy might have been added to your host that prevents an application such as Azure Cosmos DB Emulator from creating and adding self signed certificate files into your certificate store."

即使在管理员上下文中运行也可能会发生此失败，因为通常由 IT 部门添加的特定策略优先于本地管理员。在这种情况下，改用仿真器的 Docker 映像可能会有所帮助。只要你还有权将自签名仿真器 TLS/SSL 证书添加到主机上下文中，该映像就会有所帮助。 Java 和 .NET Azure Cosmos DB SDK 客户端应用程序需要自签名证书。

仿真器出现故障：

确认使用建议的设置创建的容器是否有效。如果有效，则失败的原因很可能是启动容器时通过相应的 Docker 命令传递的额外设置。

在附加模式下启动仿真器的 Docker 容器（请参阅 docker start -it）。

收集与故障相关的转储/数据，并按照所述步骤报告问题。

数据资源管理器错误

我无法查看我的数据：

请参阅上述与连接相关的问题部分。

请确保正确导入并手动信任自签名仿真器证书，以便浏览器能够访问数据资源管理器页。

尝试创建数据库/容器并使用数据资源管理器插入项。如果成功，则问题的原因很可能就在应用程序中。如果失败，请联系 Azure Cosmos DB 团队。

性能问题

每秒的请求数较低，请求的延迟较高：

没有为 Docker 容器预配足够的资源（核心或内存）。建议增加核心数，或者减少启动时预配的物理分区数。刷新 Linux 容器

使用以下步骤刷新 Linux 容器：

运行以下命令查看所有 Docker 容器。

docker ps --all

使用从上面的命令中检索到的 ID 删除容器。

docker rm ID_OF_CONTAINER_FROM_ABOVE

接下来列出所有 Docker 映像。

docker images

使用从上一步中检索到的 ID 删除映像。

docker rmi ID_OF_IMAGE_FROM_ABOVE

拉取 Azure Cosmos DB Linux 仿真器的最新映像。

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator

若要启动已停止的容器，请运行以下命令：

docker start -ai ID_OF_CONTAINER 报告仿真器的问题

报告 Linux 仿真器的问题时，请提供尽可能多的有关问题的信息。这些详细信息包括：

遇到的错误/问题的说明环境（OS、主机配置）计算机和处理器类型用于创建和启动仿真器的命令（如果使用 Docker Compose，则使用 YML 文件）工作负载的说明使用的数据库/集合和项的示例包括在附加模式下启动仿真器的 Docker 容器的控制台输出请在我们的 Azure Cosmos DB 问答论坛上发布反馈。后续步骤

在本文中，你已了解如何使用 Azure Cosmos DB Linux 仿真器进行免费的本地开发。你现在可以继续学习下面的文章：

导出要用于 Java、Python 和 Node.js 应用的 Azure Cosmos DB 模拟器证书使用模拟器调试问题

【本文地址】

公司简介

联系我们