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

適用於: ✅ NoSQL

下一代 Azure Cosmos DB 模擬器完全基於 Linux，並以 Docker 容器形式提供。它支援在各種不同的處理器和作系統上執行。

Important

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

Prerequisites

Docker

Installation

使用 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

Running

若要執行容器，請使用 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-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>

模擬器包含兩個組件：

Data Explorer - 互動式探索模擬器中的資料。預設情況下，此元件運行於埠 1234口。
Azure Cosmos DB 模擬器 - Azure Cosmos DB 資料庫服務的本地版本。預設情況下，此元件運行於埠 8081口。

模擬器閘道端點使用埠 8081 在位址 http://localhost:8081。要前往Data Explorer，請在瀏覽器中使用網址 http://localhost:1234。閘道端通常立即可用，但 Data Explorer 可能需要幾秒鐘才能啟動。

健康探測

模擬器會在埠 8080口暴露健康探針端點。利用此端點判斷模擬器何時已完全初始化並準備接受請求。

下列端點可供使用：

http://localhost:8080/alive — 活度探針。
http://localhost:8080/ready — 就緒探測器。
http://localhost:8080/status — 詳細狀態。

Note

舊有日誌訊息 System is now fully ready to accept requests 仍會為向下相容而發出，但未來版本可能會被移除。請改用健康探針進行就緒檢查。

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-preview --protocol https

當你使用 HTTPS 搭配持久化資料卷時，模擬器會在啟動時自動重新產生 SSL 憑證，因此你不需要管理憑證續期。

Docker 命令

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

需求	引數	環境	允許的值	預設值	Description
從容器將設定列印至 stdout	`--help`、`-h`	N/A	N/A	N/A	顯示可用設定的相關資訊
設定 Cosmos 端點的連接埠	`--port [INT]`	PORT	INT	8081	容器上 Cosmos 端點的連接埠。您仍然需要發佈此連接埠 (例如 `-p 8081:8081`)。
指定 Cosmos 端點所使用的通訊協定	`--protocol`	通訊協定	`https`、`http`、`https-insecure`	`http`	容器上 Cosmos 端點的通訊協定。
啟用資料總管	`--enable-explorer`	ENABLE_EXPLORER	`true`、`false`	`true`	啟用 Cosmos Data Explorer 在同一容器上運行。
設定資料總管所使用的連接埠	`--explorer-port`	EXPLORER_PORT	INT	1234	貨櫃上的 Cosmos Data Explorer 端口。您仍然需要發佈此連接埠 (例如 `-p 1234:1234`)。
指定資料探索器所使用的協定	`--explorer-protocol`	EXPLORER_PROTOCOL	`https`、`http`、`https-insecure`	`<the value of --protocol>`	容器上的 Cosmos Data Explorer 協定。預設為 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`	啟用遙測資料的主控台輸出（對除錯很有用）。
啟用冗長模式	`--verbose`	冗長	`true`、`false`	`false`	啟用 verbose 模式以將 PostgreSQL 日誌（pglog）列印到主控台。對除錯很有用。
設定查詢緩衝區大小	`--query-buffer-size`	QUERY_BUFFER_SIZE_KB	INT	4096（4 MB），最大 65536（64 MB）	查詢結果緩衝區的最大大小（KB）。如果在大型查詢中遇到 HTTP 500 錯誤，請增加這個比例。
啟用傳送給 Microsoft 的診斷資訊	`--enable-telemetry`	ENABLE_TELEMETRY	`true`、`false`	`true`	啟用傳送使用資料給 Microsoft，幫助我們改進模擬器。

功能支援

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

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

Note

標示 為 No-op 的功能會接受請求並回傳有效的 HTTP 狀態碼，但不會執行底層操作。你的程式碼不會壞掉，但不要依賴這些功能來維持功能性。為了相容性，我們接受自訂索引政策和集合更新，但查詢不會因自訂索引而優化。

局限性

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

Azure Cosmos DB 的 .NET SDK 在模擬器中不支援批量執行。
如果大型查詢結果出現 HTTP 500 錯誤，請用旗標或--query-buffer-size環境變數增加查詢緩衝區大小QUERY_BUFFER_SIZE_KB。預設值為 4096 KB4 （MB），最大值為 65536 KB64 （MB）。

安裝 Java SDK 憑證

當使用 Java SDK for Azure Cosmos DB 並以 https 模式進行此版本模擬器時，必須將其憑證安裝到本地的 Java trust store。

取得憑證

在 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、記憶體使用率與連線池指標
錯誤率：依類型與端點追蹤錯誤

Note

模擬器支援條件式 TLS 作為 OTLP 匯出器，因此你可以與需要安全連線的可觀測性平台整合。

詳細說明與範例可在 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是模擬器公開的端口）。

Export Cosmos DB 模擬器憑證步驟是針對Java應用程式的，因為 Azure Cosmos DB Java SDK 目前不支援模擬器中的 HTTP 模式。 PROTOCOL 環境變數在 https 區塊中設定為 services，此步驟會匯出模擬器憑證並匯入 Java 金鑰庫。同樣適用於 .NET。

報告問題

如果你在使用這個版本模擬器時遇到問題，可以在GitHub倉庫（https://github.com/Azure/azure-cosmos-db-emulator-docker）中開啟一個問題，並標註為 cosmosEmulatorVnextPreview。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-04-27

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

Prerequisites

Installation

Running

健康探測

HTTPS 模式

Docker 命令

功能支援

局限性

安裝 Java SDK 憑證

取得憑證

安裝憑證

OpenTelemetry 支援

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

報告問題

意見反應

其他資源