基于 Linux 的模拟器 - vNext （预览版）

下一代 Azure Cosmos DB 模拟器完全基于 Linux，且可用作 Docker 容器。 它支持在各种处理器和操作系统上运行。

先决条件

• Docker

安装

使用 docker pull 获取 Docker 容器映像。 该容器映像将作为 发布到 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview。

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

正在运行

若要运行容器，请使用 docker run。 之后，使用 docker ps 来验证容器是否正常运行。

docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

docker ps

CONTAINER ID   IMAGE                                                             COMMAND                  CREATED         STATUS         PORTS                                                                                  NAMES
c1bb8cf53f8a   mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview  "/bin/bash -c /home/…"   5 seconds ago   Up 5 seconds   0.0.0.0:1234->1234/tcp, :::1234->1234/tcp, 0.0.0.0:8081->8081/tcp, :::8081->8081/tcp   <container-name>

docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol https

Docker 命令

下表总结了可用于配置模拟器的 Docker 命令。 此表详细列出了每个命令的相应参数、环境变量、允许的值、默认设置和说明。

功能支持

此模拟器处于积极开发阶段，现为预览版。 因此，并非所有 Azure Cosmos DB 功能都受支持。 而且，某些功能将来也无法获得支持。 下表包括各种功能的状态及其支持级别。

限制

除了尚不支持或未规划的功能外，以下列表还包括模拟器的当前限制。

• 适用于 Azure Cosmos DB 的 .NET SDK 不支持在模拟器中进行批量执行。

安装用于 Java SDK 的证书

在 HTTPS 模式下将适用于 Azure Cosmos DB 的 Java SDK 与此版本的模拟器配合使用时，必须将其证书安装到本地 Java 信任存储。

获取证书

在 bash 窗口中，运行以下命令：

# If the emulator was started with /AllowNetworkAccess, replace localhost 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

安装证书

导航到 cacerts 文件所在的 Java 安装目录（将下面的目录替换为正确的目录）：

cd "C:/Program Files/Eclipse Adoptium/jdk-17.0.10.7-hotspot/bin"

导入证书（系统可能会要求输入密码，默认值为“changeit”）：

keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

如果由于别名已存在而出现错误，请将其删除，然后再次运行上述命令：

keytool -cacerts -delete -alias cosmos_emulator

OpenTelemetry 支持

OpenTelemetry 是一个开源可观测性框架，它提供工具、API 和 SDK 集合，用于检测、生成、收集和导出遥测数据。 OpenTelemetry 协议（OTLP）是 OpenTelemetry 用来在组件之间传输遥测数据的协议。

可以将 OpenTelemetry 与模拟器配合使用来监视和跟踪应用程序。 模拟器支持遥测选项，可以在运行 Docker 容器时通过环境变量或命令行标志进行配置。

模拟器导出以下指标。 可通过支持 OTLP 的任何指标后端获取这些指标，并提供有关数据库性能和运行状况的宝贵见解：

• 请求速率：显示不同作类型的流量模式
• 查询执行时间：测量执行不同查询所花费的时间
• 资源利用率：CPU、内存使用情况和连接池指标
• 错误率：按类型和终结点跟踪错误

GitHub 存储库中提供了包含示例的详细说明。

在持续集成工作流中使用

在 CI/CD 管道中使用 Docker 容器有很多好处，尤其是对于数据库等有状态系统。 这可能在测试套件的成本效益、性能、可靠性和一致性方面。

模拟器可以合并为 CI/CD 管道的一部分。 可以参考此 GitHub 存储库，其中提供了如何在 x64 和 ARM64 体系结构（针对使用 ubuntu 的 Linux 运行程序进行了演示）上为 .NET、Python、Java 和 Go 应用程序将模拟器用作 GitHub Actions CI 工作流的一部分的示例。

下面是 GitHub Actions CI 工作流的示例，演示如何将模拟器配置为 GitHub Actions 服务容器 作为工作流中作业的一部分。 GitHub 负责启动 Docker 容器并在作业完成时销毁它，而无需手动干预（例如使用 docker run 命令）。

name: CI demo app

on:
  push:
    branches: [main]
    paths:
      - 'java-app/**'
  pull_request:
    branches: [main]
    paths:
      - 'java-app/**'

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    services:
      cosmosdb:
        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
        ports:
          - 8081:8081
        env:
          PROTOCOL: https
        
    env:
      COSMOSDB_CONNECTION_STRING: ${{ secrets.COSMOSDB_CONNECTION_STRING }}
      COSMOSDB_DATABASE_NAME: ${{ vars.COSMOSDB_DATABASE_NAME }}
      COSMOSDB_CONTAINER_NAME: ${{ vars.COSMOSDB_CONTAINER_NAME }}

    steps:

      - name: Set up Java
        uses: actions/setup-java@v3
        with:
          distribution: 'microsoft'
          java-version: '21.0.0'

      - name: Export Cosmos DB Emulator Certificate
        run: |

          sudo apt update && sudo apt install -y openssl

          openssl s_client -connect localhost:8081 </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cosmos_emulator.cert

          cat cosmos_emulator.cert

          $JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file cosmos_emulator.cert -storepass changeit -noprompt
      
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run tests
        run: cd java-app && mvn test

此作业在 Ubuntu 运行程序上运行，并使用 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview Docker 映像作为服务容器。 它使用环境变量来配置连接字符串、数据库名称和容器名称。 由于在这种情况下，作业直接在 GitHub Actions 运行程序计算机上运行，因此作业中的运行测试步骤可以访问模拟器，并且可以使用localhost:8081端口进行访问（8081是模拟器公开的端口）。

导出 Cosmos DB 模拟器证书步骤特定于 Java 应用程序，因为 Azure Cosmos DB Java SDK 当前不支持HTTP模拟器中的模式。 环境变量PROTOCOL在部分中设置为httpsservices，此步骤将导出模拟器证书并将其导入 Java 密钥存储。 这同样适用于 .NET。

报告问题

如果在使用此版本的模拟器时遇到问题，请在 GitHub 存储库 (https://github.com/Azure/azure-cosmos-db-emulator-docker) 中开启一个问题，并使用标签 cosmosEmulatorVnextPreview 对其进行标记。