使用 Azurite 模拟器进行本地 Azure 存储开发

Azurite 开源模拟器提供一个免费的本地环境,用于测试 Azure Blob 和队列存储应用程序。 如果你对应用程序在本地的工作状况感到满意,可以改用云中的 Azure 存储帐户。 该仿真器在 Windows、Linux 和 macOS 上提供跨平台支持。

Azurite 是未来的存储仿真器平台。 Azurite 取代了 Azure 存储仿真器。 Azurite 将持续更新,以支持最新版本的 Azure 存储 API。

可通过多种不同的方法在本地系统上安装并运行 Azurite:

  1. 安装并运行 Azurite Visual Studio Code 扩展
  2. 使用 NPM 安装并运行 Azurite
  3. 安装并运行 Azurite Docker 映像
  4. 从 GitHub 存储库克隆、生成并运行 Azurite

安装并运行 Azurite Visual Studio Code 扩展

在 Visual Studio Code 中选择“扩展”窗格,然后在“扩展: 市场”中搜索 Azurite

Visual Studio Code 扩展市场

也可在浏览器中导航到 Visual Studio Code 扩展市场。 选择“安装”按钮打开 Visual Studio Code,并直接转到 Azurite 扩展页。

该扩展支持以下 Visual Studio Code 命令。 若要打开命令面板,请在 Visual Studio Code 中按 F1。

  • Azurite:Clean - 重置所有 Azurite 服务永久性数据
  • Azurite:Clean Blob Service - 清理 Blob 服务
  • Azurite:Clean Queue Service - 清理队列服务
  • Azurite:Close - 关闭所有 Azurite 服务
  • Azurite:Close Blob Service - 关闭 Blob 服务
  • Azurite:Close Queue Service - 关闭队列服务
  • Azurite:Start - 启动所有 Azurite 服务
  • Azurite:Start Blob Service - 启动 Blob 服务
  • Azurite:Start Queue Service - 启动队列服务

若要在 Visual Studio Code 中配置 Azurite,请选择“扩展”窗格。 选择 Azurite 所对应的“管理”(齿轮)图标。 选择“扩展设置”。

Azurite 的“配置扩展设置”

支持以下设置:

  • Azurite:Blob 主机 - Blob 服务的侦听终结点。 默认设置为 127.0.0.1。
  • Azurite:Blob 端口 - Blob 服务的侦听端口。 默认端口为 10000。
  • Azurite:证书 - 本地受信任 PEM 的路径或 PFX 证书文件路径,用于启用 HTTPS 模式。
  • Azurite:调试 - 将调试日志输出到 Azurite 通道。 默认值是 false 秒。
  • Azurite:密钥 - 本地受信任 PEM 密钥文件的路径,在“Azurite:证书”指向 PEM 文件文件时是必需的。
  • Azurite:位置 - 工作区位置路径。 默认值为 Visual Studio Code 的工作文件夹。
  • Azurite:松散 - 启用松散模式,将会忽略不受支持的标头和参数。
  • Azurite:Oauth - 可选 OAuth 级别。
  • Azurite:Pwd - PFX 文件的密码。 在“Azurite:证书”指向 PFX 文件时是必需的。
  • Azurite:队列主机 - 队列服务的侦听终结点。 默认设置为 127.0.0.1。
  • Azurite:队列端口 - 队列服务的侦听端口。 默认端口为 10001。
  • Azurite:无提示 - 无提示模式会禁用访问日志。 默认值是 false 秒。
  • Azurite:跳过 API 版本检查 - 跳过请求 API 版本检查。 默认值是 false 秒。

使用 NPM 安装并运行 Azurite

此安装方法需要安装 Node.js 8.0 或更高版本。 Node 包管理器 (npm) 是每个 Node.js 安装随附的包管理工具。 安装 Node.js 后,请执行以下 npm 命令以安装 Azurite。

npm install -g azurite

安装 Azurite 后,请参阅从命令行运行 Azurite

安装并运行 Azurite Docker 映像

使用以下命令通过 DockerHub 提取最新的 Azurite 映像

docker pull mcr.microsoft.com/azure-storage/azurite

运行 Azurite Docker 映像

以下命令运行 Azurite Docker 映像。 -p 10000:10000 参数将来自主机端口 10000 的请求重定向到 Docker 实例。

docker run -p 10000:10000 -p 10001:10001 \
    mcr.microsoft.com/azure-storage/azurite

指定工作区位置

在以下示例中,-v c:/azurite:/data 参数指定“c:/azurite”作为 Azurite 永久性数据的位置。 必须在运行 Docker 命令之前创建目录“c:/azurite”。

docker run -p 10000:10000 -p 10001:10001 \
    -v c:/azurite:/data mcr.microsoft.com/azure-storage/azurite

仅运行 blob 服务

docker run -p 10000:10000 mcr.microsoft.com/azure-storage/azurite \
    azurite-blob --blobHost 0.0.0.0 --blobPort 10000

若要详细了解如何在启动时配置 Azurite,请参阅命令行选项

从 GitHub 存储库克隆、生成并运行 Azurite

此安装方法需要安装 Git。 使用以下控制台命令克隆 Azurite 项目的 GitHub 存储库

git clone https://github.com/Azure/Azurite.git

克隆源代码后,从克隆的存储库的根目录执行以下命令,以生成并安装 Azurite。

npm install
npm run build
npm install -g

安装并生成 Azurite 后,请参阅从命令行运行 Azurite

从命令行运行 Azurite

备注

如果只是安装了 Visual Studio Code 扩展,则无法从命令行运行 Azurite。 请改用 Visual Studio Code 命令面板。 有关详细信息,请参阅安装并运行 Azurite Visual Studio Code 扩展

若要立即开始使用命令行,请创建名为 c:\azurite 的目录,然后发出以下命令以启动 Azurite:

azurite --silent --location c:\azurite --debug c:\azurite\debug.log

此命令告知 Azurite 要将所有数据存储在特定目录 c:\azurite 中。 如果省略 --location 选项,此命令将使用当前工作目录。

命令行选项

本部分详细说明启动 Azurite 时可用的命令行开关。

帮助

可选 - 通过使用 -h--help 开关获取命令行帮助。

azurite -h
azurite --help

Blob 侦听主机

可选 - 默认情况下,Azurite 将侦听本地服务器 127.0.0.1。 可根据需要使用 --blobHost 开关设置地址。

仅接受本地计算机上的请求:

azurite --blobHost 127.0.0.1

允许远程请求:

azurite --blobHost 0.0.0.0

注意

允许远程请求可能会导致系统容易受到外部攻击。

Blob 侦听端口配置

可选 - 默认情况下,Azurite 将在端口 10000 上侦听 Blob 服务。 使用 --blobPort 开关可指定所需的侦听端口。

备注

使用自定义端口后,需要在 Azure 存储工具或 SDK 中更新连接字符串或相应的配置。

自定义 Blob 服务侦听端口:

azurite --blobPort 8888

让系统自动选择可用端口:

azurite --blobPort 0

Azurite 启动期间,会显示正在使用的端口。

队列侦听主机

可选 - 默认情况下,Azurite 将侦听本地服务器 127.0.0.1。 可根据需要使用 --queueHost 开关设置地址。

仅接受本地计算机上的请求:

azurite --queueHost 127.0.0.1

允许远程请求:

azurite --queueHost 0.0.0.0

注意

允许远程请求可能会导致系统容易受到外部攻击。

队列侦听端口配置

可选 - 默认情况下,Azurite 将在端口 10001 上侦听队列服务。 使用 --queuePort 开关可指定所需的侦听端口。

备注

使用自定义端口后,需要在 Azure 存储工具或 SDK 中更新连接字符串或相应的配置。

自定义队列服务侦听端口:

azurite --queuePort 8888

让系统自动选择可用端口:

azurite --queuePort 0

Azurite 启动期间,会显示正在使用的端口。

工作区路径

可选 - 在执行过程中,Azurite 会将数据存储到本地磁盘。 使用 -l--location 开关可将某个路径指定为工作区位置。 默认将使用当前进程的工作目录。 请注意小写的“l”。

azurite -l c:\azurite
azurite --location c:\azurite

访问日志

可选 - 默认情况下,访问日志会显示在控制台窗口中。 使用 -s--silent 开关可以禁止显示访问日志。

azurite -s
azurite --silent

调试日志

可选 - 调试日志包括有关每个请求和异常堆栈跟踪的详细信息。 在 -d--debug 开关中提供有效的本地文件路径可以启用调试日志。

azurite -d path/debug.log
azurite --debug path/debug.log

松散模式

可选 - 默认情况下,Azurite 应用严格模式来阻止不受支持的请求标头和参数。 使用 -L--loose 开关禁用严格模式。 请注意大写的“L”。

azurite -L
azurite --loose

版本

可选 - 通过使用 -v--version 开关显示已安装 Azurite 的版本号。

azurite -v
azurite --version

证书配置 (HTTPS)

可选 - 默认情况下,Azurite 使用 HTTP 协议。 启用 HTTPS 模式的方法是:向隐私增强邮件 (.pem) 提供路径,或者向 --cert 开关提供个人信息交换 (.pfx) 证书文件。

为 PEM 文件提供 --cert 时,必须提供相应的 --key 开关。

azurite --cert path/server.pem --key path/key.pem

为 PFX 文件提供 --cert 时,必须提供相应的 --pwd 开关。

azurite --cert path/server.pfx --pwd pfxpassword

若要详细了解如何创建 PEM 和 PFX 文件,请参阅 HTTPS 设置

OAuth 配置

可选 - 通过使用 --oauth 开关为 Azurite 启用 OAuth 身份验证。

azurite --oauth basic --cert path/server.pem --key path/key.pem

备注

OAuth 需要 HTTPS 终结点。 请确保通过提供 --cert 开关和 --oauth 开关来启用 HTTPS。

Azurite 通过为 --oauth 开关指定 basic 参数来支持基本身份验证。 Azurite 会执行基本身份验证,例如验证传入的持有者令牌;检查颁发者、受众和到期时间。 Azurite 不会检查令牌签名或权限。

跳过 API 版本检查

可选 - 启动时,Azurite 会检查请求的 API 版本是否有效。 以下命令会跳过 API 版本检查:

azurite --skipApiVersionCheck

工具和 SDK 的授权

使用任何身份验证策略从 Azure 存储 SDK 或工具(例如 Azure 存储资源管理器)连接到 Azurite。 需要身份验证。 Azurite 支持使用 OAuth、共享密钥和共享访问签名 (SAS) 进行授权。 Azurite 还支持匿名访问公共容器。

如果使用的是 Azure SDK,请使用 --oauth basic and --cert --key/--pwd 选项启动 Azurite。

已知的存储帐户和密钥

Azurite 接受旧式 Azure 存储模拟器使用的同一个众所周知的帐户和密钥。

  • 帐户名称:devstoreaccount1
  • 帐户密钥:Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==

自定义存储帐户和密钥

Azurite 支持自定义存储帐户名称和密钥,但需将 AZURITE_ACCOUNTS 环境变量设置为以下格式:account1:key1[:key2];account2:key1[:key2];...

例如,使用包含一个密钥的自定义存储帐户:

set AZURITE_ACCOUNTS="account1:key1"
export AZURITE_ACCOUNTS="account1:key1"

也可使用多个存储帐户,每个存储帐户有两个密钥:

set AZURITE_ACCOUNTS="account1:key1:key2;account2:key1:key2"
export AZURITE_ACCOUNTS="account1:key1:key2;account2:key1:key2"

默认情况下,Azurite 每分钟刷新环境变量中的自定义帐户名和密钥。 利用此功能,可以动态轮换帐户密钥,或添加新的存储帐户,而无需重启 Azurite。

备注

设置自定义存储帐户时,将禁用默认的 devstoreaccount1 存储帐户。

连接字符串

从应用程序连接到 Azurite 的最简单方法是在应用程序的配置文件中配置一个引用快捷方式 UseDevelopmentStorage=true 的连接字符串。 下面是 app.config 文件中的连接字符串示例:

<appSettings>
  <add key="StorageConnectionString" value="UseDevelopmentStorage=true" />
</appSettings>

HTTP 连接字符串

可将以下连接字符串传递到 Azure SDK 或者 Azure CLI 2.0 或存储资源管理器等工具。

完整的连接字符串为:

DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;QueueEndpoint=http://127.0.0.1:10001/devstoreaccount1;

若只连接到 blob 服务,则连接字符串为:

DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;

若只连接到队列服务,则连接字符串为:

DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;QueueEndpoint=http://127.0.0.1:10001/devstoreaccount1;

HTTPS 连接字符串

完整的 HTTPS 连接字符串为:

DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://127.0.0.1:10000/devstoreaccount1;QueueEndpoint=https://127.0.0.1:10001/devstoreaccount1;

若只使用 blob 服务,则 HTTPS 连接字符串为:

DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://127.0.0.1:10000/devstoreaccount1;

若只使用队列服务,则 HTTPS 连接字符串为:

DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;QueueEndpoint=https://127.0.0.1:10001/devstoreaccount1;

如果使用了 dotnet dev-certs 生成自签名证书,请使用以下连接字符串。

DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://localhost:10000/devstoreaccount1;QueueEndpoint=https://localhost:10001/devstoreaccount1;

使用自定义存储帐户和密钥时,请更新连接字符串。

有关详细信息,请参阅配置 Azure 存储连接字符串

Azure SDK

若要将 Azurite 与 Azure SDK 配合使用,请使用 OAuth 和 HTTPS 选项:

azurite --oauth basic --cert certname.pem --key certname-key.pem

Azure Blob 存储

然后,可以实例化 BlobContainerClient、Blobserviceclient 或 BlobClient。

// With container URL and DefaultAzureCredential
var client = new BlobContainerClient(
    new Uri("https://127.0.0.1:10000/devstoreaccount1/container-name"), new DefaultAzureCredential()
  );

// With connection string
var client = new BlobContainerClient(
    "DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://127.0.0.1:10000/devstoreaccount1;QueueEndpoint=https://127.0.0.1:10001/devstoreaccount1;", "container-name"
  );

// With account name and key
var client = new BlobContainerClient(
    new Uri("https://127.0.0.1:10000/devstoreaccount1/container-name"),
    new StorageSharedKeyCredential("devstoreaccount1", "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==")
  );

Azure Queue Storage

还可以实例化 QueueClient 或 QueueServiceClient。

// With queue URL and DefaultAzureCredential
var client = new QueueClient(
    new Uri("https://127.0.0.1:10001/devstoreaccount1/queue-name"), new DefaultAzureCredential()
  );

// With connection string
var client = new QueueClient(
    "DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=https://127.0.0.1:10000/devstoreaccount1;QueueEndpoint=https://127.0.0.1:10001/devstoreaccount1;", "queue-name"
  );

// With account name and key
var client = new QueueClient(
    new Uri("https://127.0.0.1:10001/devstoreaccount1/queue-name"),
    new StorageSharedKeyCredential("devstoreaccount1", "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==")
  );

Microsoft Azure 存储资源管理器

可以使用存储资源管理器查看存储在 Azurite 中的数据。

使用 HTTP 连接到 Azurite

在存储资源管理器中,按照以下步骤连接到 Azurite:

  1. 选择“管理帐户”图标
  2. 选择“添加帐户”
  3. 选择“附加到本地仿真器”
  4. 选择“下一步”
  5. 将“显示名称”字段编辑为所选名称
  6. 再次选择“下一步”
  7. 选择“连接”

使用 HTTPS 连接到 Azurite

默认情况下,存储资源管理器不会打开使用自签名证书的 HTTPS 终结点。 如果你是使用 HTTPS 来运行 Azurite,则可能使用的是自签名证书。 在存储资源管理器中,通过“编辑” -> “SSL 证书” -> “导入证书”对话框导入 SSL 证书。

将证书导入到存储资源管理器
  1. 在本地计算机上找到证书。
  2. 在存储资源管理器中转到“编辑” -> “SSL 证书” -> “导入证书”,然后导入你的证书。

如果不导入证书,则会出现错误:

unable to verify the first certificateself signed certificate in chain

通过 HTTPS 连接字符串添加 Azurite

按照以下步骤将 Azurite HTTPS 添加到存储资源管理器:

  1. 选择“切换资源管理器”
  2. 选择“本地和附加”
  3. 右键单击“存储帐户”,然后选择“连接到 Azure 存储”。
  4. 选择“使用连接字符串”
  5. 选择“下一步”。
  6. 在“显示名称”字段中输入值。
  7. 输入本文档上一部分中的 HTTPS 连接字符串
  8. 选择“下一步”
  9. 选择“连接”

工作区结构

初始化 Azurite 时,可以在工作区位置创建以下文件和文件夹。

  • __blobstorage__ - 目录,其中包含 Azurite blob 服务持久化二进制数据
  • __queuestorage__ - 目录,其中包含 Azurite 队列服务持久化二进制数据
  • __azurite_db_blob__.json - Azurite blob 服务元数据文件
  • __azurite_db_blob_extent__.json - Azurite blob 服务盘区元数据文件
  • __azurite_db_queue__.json - Azurite 队列服务元数据文件
  • __azurite_db_queue_extent__.json - Azurite 队列服务盘区元数据文件

若要清理 Azurite,请删除以上文件和文件夹,然后重启仿真器。

Azurite 与 Azure 存储之间的差别

Azurite 本地实例与云中的 Azure 存储帐户在功能上有差别。

终结点和连接 URL

Azurite 的服务终结点不同于 Azure 存储帐户的终结点。 本地计算机不执行域名解析,要求 Azurite 终结点是本地地址。

对 Azure 存储帐户中的资源寻址时,帐户名称是 URI 主机名的一部分。 要寻址的资源是 URI 路径的一部分:

<http|https>://<account-name>.<service-name>.core.chinacloudapi.cn/<resource-path>

以下 URI 是 Azure 存储帐户中某个 Blob 的有效地址:

https://myaccount.blob.core.chinacloudapi.cn/mycontainer/myblob.txt

由于本地计算机不执行域名解析,帐户名称是 URI 路径的一部分,而不是主机名的一部分。 对 Azurite 中的资源使用以下 URI 格式:

http://<local-machine-address>:<port>/<account-name>/<resource-path>

可使用以下地址访问 Azurite 中的 Blob:

http://127.0.0.1:10000/myaccount/mycontainer/myblob.txt

缩放和性能

Azurite 不支持大量连接的客户端。 它不提供性能方面的保证。 Azurite 用于开发和测试目的。

错误处理。

Azurite 的错误处理逻辑与 Azure 存储相符,但存在一些差别。 例如,错误消息可能不同,而错误状态代码是一致的。

RA-GRS

Azurite 支持读取访问异地冗余复制 (RA-GRS)。 对于存储资源,可以通过在帐户名称后面追加 -secondary 来访问次要位置。 例如,以下地址可用于访问 Azurite 中使用只读辅助副本的 Blob:

http://127.0.0.1:10000/devstoreaccount1-secondary/mycontainer/myblob.txt

表支持

对 Azurite 中表的支持目前正在开发中,欢迎为此做出贡献! 有关最新进度,请查看 Azurite V3 表项目。

支持持久函数需要表。

Azurite 是开源的

欢迎为 Azurite 贡献作品和提出建议。 请访问 Azurite GitHub 项目页或 GitHub 问题了解产品里程碑,以及我们针对即将推出的功能和 bug 修复正在跟进的工作项。 GitHub 中也列出了详细的工作项。

后续步骤