jamesgoulddev/azure-keyvault-emulator

Azure Key Vault模拟器Docker镜像文档

镜像概述

该Docker镜像是一个轻量级、全功能的Azure Key Vault模拟器，专为开发和测试场景设计。它允许开发人员在本地环境中模拟Azure Key Vault的核心功能，无需依赖真实的Azure云资源或账户。通过支持Azure官方SDK客户端库，可直接复用现有代码连接模拟器，大幅降低开发环境配置复杂度，提高Azure Key Vault相关应用的开发测试效率。

核心功能和特性

• 完整功能模拟：支持Azure Key Vault核心操作，包括密钥（Keys）、机密（Secrets）、证书（Certificates）的创建、读取、更新、删除（CRUD）及权限管理
• SDK兼容性：全面兼容Azure SDK客户端库（如.NET、Java、Python、JavaScript等），无需修改现有SDK代码即可连接
• 本地数据管理：数据存储于本地文件系统，支持临时存储（容器生命周期内）和持久化存储（挂载主机目录）两种模式
• 离线运行：完全本地运行，无需网络连接或Azure订阅，保障开发环境独立性
• 灵活配置：支持自定义服务端口、数据存储路径、日志级别等参数，适应不同开发场景需求

使用场景和适用范围

适用场景

• 本地开发调试：开发人员在本地机器上调试依赖Azure Key Vault的应用程序，验证密钥/机密访问逻辑
• CI/CD流水线集成：作为测试环境组件，集成到持续集成/部署流程，自动化验证Key Vault相关功能
• 单元测试与集成测试：为应用单元测试、集成测试提供隔离的模拟Key Vault环境，确保测试稳定性
• 培训与演示：在无Azure账户条件下，演示Azure Key Vault的功能特性和使用方法

限制说明

• 不支持Azure Key Vault高级特性（如软删除、备份恢复、HSM密钥等）
• 不提供生产级数据安全保障，禁止用于生产环境
• 性能和并发处理能力低于真实Azure Key Vault服务

使用方法和配置说明

基本部署（Docker Run）

标准启动命令

bash
docker run -d -p 8200:8200 --name keyvault-emulator [镜像名称]

• -d：后台运行容器
• -p 8200:8200：端口映射（主机端口:容器端口），默认使用8200端口
• --name keyvault-emulator：指定容器名称，便于后续管理

自定义端口配置

如需使用非默认端口（如8300）：

bash
docker run -d -p 8300:8300 --name keyvault-emulator [镜像名称] --port 8300

数据持久化配置

通过挂载主机目录实现数据持久化：

bash
docker run -d -p 8200:8200 -v /host/data/path:/emulator/data --name keyvault-emulator [镜像名称] --storage /emulator/data

• -v /host/data/path:/emulator/data：将主机目录/host/data/path挂载到容器内/emulator/data
• --storage /emulator/data：指定模拟器数据存储路径为容器内挂载目录

Docker Compose配置

创建docker-compose.yml文件：

yaml
version: '3.8'
services:
  keyvault-emulator:
    image: [镜像名称]
    container_name: keyvault-emulator
    ports:
      - "8200:8200"  # 端口映射
    volumes:
      - ./kv-data:/emulator/data  # 持久化数据到当前目录下kv-data文件夹
    command: --storage /emulator/data --port 8200  # 启动参数
    environment:
      - LOG_LEVEL=INFO  # 日志级别：DEBUG/INFO/WARN/ERROR
    restart: unless-stopped  # 容器退出时自动重启（除非手动停止）

启动服务：

bash
docker-compose up -d

SDK客户端连接示例

.NET SDK连接

csharp
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

// 创建模拟器客户端（使用DefaultAzureCredential，禁用共享令牌缓存）
var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions 
{ 
    ExcludeSharedTokenCacheCredential = true 
});
var client = new SecretClient(new Uri("http://localhost:8200"), credential);

// 示例：添加并读取机密
await client.SetSecretAsync("test-secret", "secret-value");
var secret = await client.GetSecretAsync("test-secret");
Console.WriteLine($"机密值：{secret.Value.Value}");

Python SDK连接

python
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

# 创建模拟器客户端
credential = DefaultAzureCredential(exclude_shared_token_cache_credential=True)
client = SecretClient(vault_url="http://localhost:8200", credential=credential)

# 示例：添加并读取机密
client.set_secret("test-secret", "secret-value")
secret = client.get_secret("test-secret")
print(f"机密值：{secret.value}")

配置参数说明

注意：所有启动命令参数需放在镜像名称之后，如docker run [镜像名称] --port 8300 --storage /data