以 Linux 為基礎的模擬器 - vNext （預覽）

適用於: ✅ NoSQL

新一代的 Azure Cosmos DB 模擬器完全是以 Linux 為基礎，可作為 Docker 容器使用。它支援在各種不同的處理器和作系統上執行。

重要事項

此版本的模擬器僅支援閘道模式下的 API for NoSQL，而且只提供部分功能。如需詳細資訊，請參閱功能支援。

先決條件

Docker

安裝

使用 docker pull 取得 Docker 容器映像。容器映像會發行至 Microsoft Artifact Registry 作為 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>

附註

模擬器是由兩個元件所組成：

資料總管 - 以互動方式探索模擬器中的資料。根據預設，這會在連接埠 1234 上執行
Azure Cosmos DB 模擬器 - Azure Cosmos DB 資料庫服務的本機版本。根據預設，這會在連接埠 8081 上執行。

模擬器閘道端點通常可在位址 8081 的連接埠 http://localhost:8081 上使用。若要瀏覽至資料總管，請在網頁瀏覽器中使用位址 http://localhost:1234。可能需要幾秒鐘的時間才能使用資料總管。閘道端點通常可立即使用。

重要事項

.NET 和 Java SDK 不支援模擬器中的 HTTP 模式。由於此版本的模擬器預設會以 HTTP 啟動，因此您需要在啟動容器時明確啟用 HTTPS (請參閱下方)。針對 Java SDK，您也需要安裝憑證。

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

Docker 命令

下表摘要說明可用於設定模擬器的 Docker 命令。此表詳細說明了每個命令的相對應引數、環境變數、允許值、預設設定和描述。

需求	引數	環境	允許的值	預設	描述
從容器將設定列印至 stdout	`--help`、`-h`	N/A	N/A	N/A	顯示可用設定的相關資訊
設定 Cosmos 端點的連接埠	`--port [INT]`	連接埠	INT	8081	容器上 Cosmos 端點的連接埠。您仍然需要發佈此連接埠 (例如 `-p 8081:8081`)。
指定 Cosmos 端點所使用的通訊協定	`--protocol`	通訊協定	`https`、`http`、`https-insecure`	`http`	容器上 Cosmos 端點的通訊協定。
啟用資料總管	`--enable-explorer`	ENABLE_EXPLORER	`true`、`false`	`true`	實現在相同容器上執行 Cosmos 資料總管。
設定資料總管所使用的連接埠	`--explorer-port`	EXPLORER_PORT	INT	1234	容器上 Cosmos 資料總管的連接埠。您仍然需要發佈此連接埠 (例如 `-p 1234:1234`)。
使用者應該要能指定總管所使用的通訊協定，否則預設為 Cosmos 端點所使用的通訊協定	`--explorer-protocol`	EXPLORER_PROTOCOL	`https`、`http`、`https-insecure`	`<the value of --protocol>`	容器上 Cosmos 資料總管的通訊協定。預設為 Cosmos 端點上的通訊協定設定。
自訂閘道的公開端點	`--gateway-endpoint`	GATEWAY_PUBLIC_ENDPOINT	N/A	`localhost`	公共網關端點。預設為 `localhost`。
透過以下檔案指定金鑰：	`--key-file [PATH]`	KEY_FILE	路徑	`<default secret>`	使用檔案中指定的金鑰覆寫預設金鑰。您需要將此檔案掛接至容器 (例如，如果 KEY_FILE=/mykey，您會將如下所示的選項新增至 docker run：`--mount type=bind,source=./myKey,target=/myKey`)
設定資料路徑	`--data-path [PATH]`	DATA_PATH	路徑	`/data`	指定資料的目錄。經常搭配 `docker run --mount` 選項使用 (例如，如果 DATA_PATH=/usr/cosmos/data，則您需要在 docker run 中新增類似下面的選項：`--mount type=bind,source=./.local/data,target=/usr/cosmos/data`)
指定要用於 https 的憑證路徑	`--cert-path [PATH]`	CERT_PATH	路徑	`<default cert>`	指定用於保護流量之憑證的路徑。您需要將此檔案掛接至容器中 (例如，如果 CERT_PATH=/mycert.pfx，則您需要在 docker run 中新增類似下面的選項：`--mount type=bind,source=./mycert.pfx,target=/mycert.pfx`)
指定要用於 https 的憑證祕密	N/A	CERT_SECRET	字串	`<default secret>`	CERT_PATH 上指定之憑證的秘密。
設定記錄層級	`--log-level [LEVEL]`	LOG_LEVEL	`quiet`、`error`、`warn`、`info`、`debug`、`trace`	`info`	模擬器和資料總管所發出之記錄的詳細程度。
啟用 OpenTelemetry OTLP 匯出器	`--enable-otlp`	ENABLE_OTLP_EXPORTER	`true`、`false`	`false`	啟用 OpenTelemetry 整合。
啟用主控台匯出器	`--enable-console`	啟用主控台匯出器	`true`、`false`	`false`	啟用遙測資料的主控台輸出（對除錯很有用）。
啟用傳送至 Microsoft 的診斷資訊	`--enable-telemetry`	ENABLE_TELEMETRY	`true`、`false`	`true`	啟用傳送使用資料給 Microsoft，幫助我們改進模擬器。

功能支援

此模擬器處於作用中的開發和預覽狀態。因此，並非所有 Azure Cosmos DB 功能都受到支援。某些功能未來也將不受支援。此表包括各種功能的狀態及其支援層級。

功能	支援
批次 API	✅ 支援
大量 API	✅ 支援
變更摘要	✅ 支援
使用 utf 資料建立和讀取文件	✅ 支援
建立集合	✅ 支援
建立集合兩次衝突	✅ 支援
使用自訂索引原則建立集合	⚠️ 尚未實作
建立具有 ttl 到期的集合	✅ 支援
建立資料庫	✅ 支援
建立資料庫兩次衝突	✅ 支援
建立文件	✅ 支援
建立分割的集合	✅ 支援
刪除集合	✅ 支援
刪除資料庫	✅ 支援
刪除文件	✅ 支援
取得和變更集合效能	⚠️ 尚未實作
插入大型文件	✅ 支援
修補文件	✅ 支援
平行查詢分割集合	⚠️ 尚未實作
使用彙總進行查詢	✅ 支援
使用 AND 篩選條件進行查詢	✅ 支援
使用 AND 篩選條件和投影進行查詢	✅ 支援
使用相等進行查詢	✅ 支援
使用識別碼相等進行查詢	✅ 支援
使用聯結進行查詢	✅ 支援
使用排序依據進行查詢	✅ 支援
使用分割集合的排序依據進行查詢	✅ 支援
使用按數字排序進行查詢	✅ 支援
使用按字串排序進行查詢	✅ 支援
使用分頁進行查詢	✅ 支援
使用範圍運算子日期時間進行查詢	✅ 支援
使用針對數字的範圍運算子進行查詢	✅ 支援
使用針對字串的範圍運算子進行查詢	✅ 支援
使用單一聯結進行查詢	✅ 支援
使用字串、數學和陣列運算子進行查詢	✅ 支援
使用子文件進行查詢	✅ 支援
使用兩個聯結進行查詢	✅ 支援
使用兩個聯結 AND 篩選條件進行查詢	✅ 支援
讀取集合	✅ 支援
讀取集合摘要	⚠️ 尚未實作
讀取資料庫	✅ 支援
讀取資料庫摘要	⚠️ 尚未實作
讀取文件	✅ 支援
讀取文件摘要	✅ 支援
取代文件	✅ 支援
要求單位	⚠️ 尚未實作
預存程序	❌ 未規劃
觸發程序	❌ 未規劃
UDF	❌ 未規劃
更新集合	⚠️ 尚未實作
更新文件	✅ 支援

限制

除了尚未支援或尚未規劃的功能之外，下列清單還包含模擬器目前的限制。

適用於 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 容器中設定。

模擬器匯出以下指標。這些指標可以透過任何支援 OpenTelemetry 協議 (OTLP) 的後端取得，該後端提供有關資料庫效能和健康狀況的寶貴洞見：

請求速率：顯示不同操作類型的流量模式
查詢執行時間：衡量執行不同查詢所花費的時間
資源利用率：CPU、記憶體使用率與連線池指標
錯誤率：依類型與端點追蹤錯誤

詳細說明與範例可在 GitHub 倉庫中找到。

在持續整合工作流程中使用

在 CI/CD 管線中使用 Docker 容器有許多優點，尤其是適用於資料庫等具狀態系統。這可能就測試套件的成本效益、效能、可靠性和一致性而言。

模擬器可以併入為 CI/CD 管線的一部分。您可以參考此 GitHub 存放庫，其中提供範例，展示如何在 .NET、Python、Java 和 Go 應用程式的 GitHub Actions CI 工作流程中使用模擬器，適用於 x64 和 ARM64 架構（使用 ubuntu 的 Linux 執行器進行示範）。

以下是 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 進行標記。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-19