基于 Linux 的模拟器 - vNext

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

先决条件

• Docker

安装

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

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

正在运行

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

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

docker ps

CONTAINER ID   IMAGE                                                             COMMAND                  CREATED         STATUS         PORTS                                                                                  NAMES
c1bb8cf53f8a   mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest  "/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>

模拟器包括两个组件：

• 数据资源管理器 - 以交互方式浏览模拟器中的数据。 默认情况下，此组件在端口 1234上运行。
• Azure Cosmos DB模拟器 - Azure Cosmos DB数据库服务的本地版本。 默认情况下，此组件在端口 8081上运行。

模拟器网关终结点使用8081地址上的http://localhost:8081端口。 若要导航到数据资源管理器，请在 Web 浏览器中使用地址 http://localhost:1234。 网关终结点通常立即可用，但数据资源管理器可能需要几秒钟才能启动。

健康探测器

模拟器在端口 8080上公开健康探测端点。 使用此终结点可以确定模拟器何时完全初始化并准备好接受请求。

以下终结点可用：

• http://localhost:8080/alive — 生存度探测。
• http://localhost:8080/ready — 就绪情况探测。
• http://localhost:8080/status — 详细状态。

HTTPS 模式

.NET 和 Java SDK 在模拟器中不支持 HTTP 模式。 由于此版本的模拟器默认以 HTTP 开头，因此在启动容器时需要显式启用 HTTPS（见下文）。 对于 Java SDK，还需要安装证书。

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

将 HTTPS 与持久化数据卷配合使用时，模拟器会在启动时自动重新生成 SSL 证书，因此无需管理证书续订。

Docker 命令

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

功能支持

并非所有Azure Cosmos DB功能都受模拟器支持，有些功能未计划用于将来的支持。 下表包括各种功能的状态及其支持级别。

安装用于 Java SDK 的证书

在使用此版本的模拟器与Java SDK for Azure Cosmos DB结合进行 https 模式下应用时，必须将其证书安装到本地 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

将 Azure Cosmos DB Shell 与模拟器配合使用

Azure Cosmos DB Shell 是一个开源命令行接口（CLI），可用于使用类似于 bash 的命令与Azure Cosmos DB数据库进行交互。 shell 包含在模拟器容器映像中，因此无需单独安装它。

若要针对正在运行的模拟器启动交互式会话，请使用 docker exec：

docker exec -it <container-name> cosmoshell.sh

当容器首次启动时，shell 还可以运行脚本，因此在应用程序连接之前，数据库、容器、种子文档和任何其他状态都已准备就绪。 若要选择加入、设置 ENABLE_INIT_DATA=true 或传递 --enable-init-data=true。 默认值为 false。 启用后，模拟器会按字母顺序处理位于 /init 顶层的所有 .csh 文件。 若要使用其他目录，请将 INIT_PATH（或 --init-path）指向该目录。

使用包含的示例数据

该镜像附带位于 /scripts/init_examples/ 下的示例种子脚本，这些脚本会在构建时复制到 /init。 若要加载它们，请使用以下命令启动容器 ENABLE_INIT_DATA=true：

docker run --name emulator --rm -e ENABLE_INIT_DATA=true -p 8081:8081 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

然后，可以连接到 shell 并浏览数据：

docker exec emulator cosmoshell.sh -c 'ls; cd SampleDB; ls'

使用您自己的数据进行初始化

可以设定自己的数据种子。 例如，在本地文件夹中创建三个文件（01-create-db.csh和02-load-movies.csh03-verify.csh）。movies

mkdir movies && cd movies

01-create-db.csh：

mkdb MovieDB
mkcon Movies /genre --database=MovieDB

02-load-movies.csh：

mkitem -container Movies --database=MovieDB '{"id":"m1","genre":"scifi","title":"Inception","year":2010}'
mkitem -container Movies --database=MovieDB '{"id":"m2","genre":"scifi","title":"The Matrix","year":1999}'
mkitem -container Movies --database=MovieDB '{"id":"m3","genre":"drama","title":"The Godfather","year":1972}'

03-verify.csh：

query "SELECT VALUE COUNT(1) FROM c" --database=MovieDB --container=Movies

然后运行装载在该目录处 /init的模拟器：

docker run --name emulator --rm -e ENABLE_INIT_DATA=true -v "$(pwd):/init" -p 8081:8081 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

可以通过连接到 shell 并运行查询来验证数据是否已加载：

docker exec emulator cosmoshell.sh -c 'ls; query "SELECT VALUE COUNT(1) FROM c" --database=MovieDB --container=Movies'

跨初始化脚本共享状态

每个 .csh 文件 /init 在同一 shell 会话中运行，因此一个文件中的状态集在下一个文件中仍然有效。 这包括由 cd 设置的当前路径、使用 def 定义的自定义命令，以及 for 循环变量。

可以使用此方法避免在上一示例中的每一行重复 --database=MovieDB 。 将 cd MovieDB 添加到 01-create-db.csh 的末尾：

01-create-db.csh：

mkdb MovieDB
mkcon Movies /genre --database=MovieDB
cd MovieDB

然后，以后的文件可以省略 --database=MovieDB：

02-load-movies.csh：

mkitem -container Movies '{"id":"m1","genre":"scifi","title":"Inception","year":2010}'
mkitem -container Movies '{"id":"m2","genre":"scifi","title":"The Matrix","year":1999}'
mkitem -container Movies '{"id":"m3","genre":"drama","title":"The Godfather","year":1972}'

03-verify.csh：

query "SELECT VALUE COUNT(1) FROM c" --container=Movies

在重启后持续保留数据

默认情况下，每次 docker run --rm 在容器停止时擦除模拟器的数据，因此初始化脚本在下一个启动时从头开始重新运行。 若要保留预置数据（并在后续运行时跳过初始化），请在 /data 处绑定挂载主机文件夹：

mkdir -p ./cosmos-data

docker run --rm -p 8081:8081 -e ENABLE_INIT_DATA=true -v "$(pwd):/init" -v "$(pwd)/cosmos-data:/data" mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

之后每次使用同一个 -v "$(pwd)/cosmos-data:/data" 标志启动时，仿真器都会检测到现有数据并跳过初始化过程，因此会保留你之前预置的状态。 若要从头重新播种，请删除主机文件夹（rm -rf ./cosmos-data）并重新开始。

通过本地 shell 连接

还可以从本地安装的 Azure Cosmos DB Shell 版本连接到正在运行的模拟器。 将其指向模拟器的端点和密钥：

cosmosdbshell --connect "AccountEndpoint=http://localhost:8081/;AccountKey=<emulator-account-key>"

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-latest
        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-latest Docker 映像作为服务容器。 它使用环境变量来配置连接字符串、数据库名称和容器名称。 由于在这种情况下，作业直接在 GitHub Actions 运行程序计算机上运行，因此作业中的运行测试步骤可以访问模拟器，并且可以使用localhost:8081端口进行访问（8081是模拟器公开的端口）。

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

限制

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

• 适用于 Azure Cosmos DB 的 .NET SDK 不支持在模拟器中进行批量执行。
• 如果在大型查询结果中收到 HTTP 500 错误，请使用--query-buffer-size标志或QUERY_BUFFER_SIZE_KB环境变量来增加查询缓冲区大小。 默认值为 4096 KB（4 MB），最大值为 65536 KB（64 MB）。

报告问题

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