状态存储组件说明

• 1: Aerospike
• 2: AWS DynamoDB
• 3: Azure Blob 存储
• 4: Azure Cosmos DB（SQL API）
• 5: Azure 表存储
• 6: Cassandra
• 7: Cloudflare Workers KV
• 8: CockroachDB
• 9: Couchbase
• 10: Etcd
• 11: GCP Firestore（Datastore 模式）
• 12: HashiCorp Consul
• 13: Hazelcast
• 14: JetStream KV
• 15: Memcached
• 16: Microsoft SQL Server & Azure SQL
• 17: MongoDB
• 18: MySQL & MariaDB
• 19: OCI 对象存储
• 20: Oracle 数据库
• 21: PostgreSQL
• 22: PostgreSQL v1
• 23: Redis
• 24: RethinkDB
• 25: SQLite
• 26: Zookeeper
• 27: 内存

下表列出了Dapr状态管理模块在不同层次上支持的状态存储。了解如何为Dapr状态管理配置不同的状态存储。

Table headers to note:

Header	Description	Example
Status	Component certification status	Alpha Beta Stable
Component version	The version of the component	v1
Since runtime version	The version of the Dapr runtime when the component status was set or updated	1.11

提示

如果状态存储支持事务操作和ETag，则可以用于Dapr的actor模型。

Generic

Component	CRUD	Transactional	ETag	TTL	Actors	Query	Status	Component version	Since runtime version
Aerospike	✅		✅				Alpha	v1	1.0
Apache Cassandra	✅			✅			Stable	v1	1.9
CockroachDB	✅	✅	✅	✅	✅	✅	Stable	v1	1.10
Couchbase	✅		✅				Alpha	v1	1.0
etcd	✅	✅	✅	✅	✅		Beta	v2	1.12
Hashicorp Consul	✅						Alpha	v1	1.0
Hazelcast	✅						Alpha	v1	1.0
In-memory	✅	✅	✅	✅	✅		Stable	v1	1.9
JetStream KV	✅						Alpha	v1	1.7
Memcached	✅			✅			Stable	v1	1.9
MongoDB	✅	✅	✅	✅	✅	✅	Stable	v1	1.0
MySQL & MariaDB	✅	✅	✅	✅	✅		Stable	v1	1.10
Oracle Database	✅	✅	✅	✅	✅		Beta	v1	1.7
PostgreSQL v1	✅	✅	✅	✅	✅	✅	Stable	v1	1.0
PostgreSQL v2	✅	✅	✅	✅	✅		Stable	v2	1.13
Redis	✅	✅	✅	✅	✅	✅	Stable	v1	1.0
RethinkDB	✅						Beta	v1	1.9
SQLite	✅	✅	✅	✅	✅		Stable	v1	1.11
Zookeeper	✅		✅				Alpha	v1	1.0

Amazon Web Services (AWS)

Component	CRUD	Transactional	ETag	TTL	Actors	Query	Status	Component version	Since runtime version
AWS DynamoDB	✅	✅	✅	✅	✅		Stable	v1	1.10

Cloudflare

Component	CRUD	Transactional	ETag	TTL	Actors	Query	Status	Component version	Since runtime version
Cloudflare Workers KV	✅			✅			Beta	v1	1.10

Google Cloud Platform (GCP)

Component	CRUD	Transactional	ETag	TTL	Actors	Query	Status	Component version	Since runtime version
GCP Firestore	✅						Stable	v1	1.11

Microsoft Azure

Component	CRUD	Transactional	ETag	TTL	Actors	Query	Status	Component version	Since runtime version
Azure Blob Storage	✅		✅				Stable	v2	1.13
Azure Cosmos DB	✅	✅	✅	✅	✅	✅	Stable	v1	1.0
Azure Table Storage	✅		✅				Stable	v1	1.9
Microsoft SQL Server	✅	✅	✅	✅	✅		Stable	v1	1.5

Oracle Cloud

Component	CRUD	Transactional	ETag	TTL	Actors	Query	Status	Component version	Since runtime version
Autonomous Database (ATP and ADW)	✅	✅	✅	✅	✅		Alpha	v1	1.7
Coherence	✅			✅			Alpha	v1	1.16
Object Storage	✅		✅	✅			Alpha	v1	1.6

1 - Aerospike

组件格式

要配置 Aerospike 状态存储，请创建一个类型为 state.Aerospike 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.Aerospike
  version: v1
  metadata:
  - name: hosts
    value: <REPLACE-WITH-HOSTS> # 必需。以逗号分隔的主机字符串。例如："aerospike:3000,aerospike2:3000"
  - name: namespace
    value: <REPLACE-WITH-NAMESPACE> # 必需。Aerospike 命名空间。
  - name: set
    value: <REPLACE-WITH-SET> # 可选

配置元数据字段

设置 Aerospike

• Self-Hosted
• Kubernetes

docker run -d --name aerospike -p 3000:3000 -p 3001:3001 -p 3002:3002 -p 3003:3003 aerospike

helm repo add incubator http://storage.googleapis.com/kubernetes-charts-incubator
helm install --name my-aerospike --namespace aerospike stable/aerospike

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取配置状态存储组件的说明
• 状态管理构建块

2 - AWS DynamoDB

组件格式

要设置 DynamoDB 状态存储，需要创建一个类型为 state.aws.dynamodb 的组件。请参考本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.aws.dynamodb
  version: v1
  metadata:
  - name: table
    value: "Contracts"
  - name: accessKey
    value: "AKIAIOSFODNN7EXAMPLE" # 可选
  - name: secretKey
    value: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" # 可选
  - name: endpoint
    value: "http://localhost:8080" # 可选
  - name: region
    value: "eu-west-1" # 可选
  - name: sessionToken
    value: "myTOKEN" # 可选
  - name: ttlAttributeName
    value: "expiresAt" # 可选
  - name: partitionKey
    value: "ContractID" # 可选
  # 如果希望将 AWS DynamoDB 用作 actor 的状态存储，请取消注释此行（可选）
  #- name: actorStateStore
  #  value: "true"

主键

要将 DynamoDB 用作 Dapr 状态存储，表必须有一个名为 key 的主键。请参考分区键部分以了解如何更改此设置。

规格元数据字段

设置 AWS DynamoDB

有关身份验证相关属性的信息，请参阅身份验证到 AWS

生存时间（TTL）

要使用 DynamoDB 的 TTL 功能，必须在表上启用 TTL 并定义属性名称。 属性名称需要在 ttlAttributeName 字段中指定。 请参阅官方AWS 文档。

分区键

默认情况下，DynamoDB 状态存储组件使用表属性名称 key 作为 DynamoDB 表中的主键/分区键。 可以通过在组件配置中指定一个元数据字段，键为 partitionKey，值为所需的属性名称来覆盖此设置。

要了解有关 DynamoDB 主键/分区键的更多信息，请阅读AWS DynamoDB 开发者指南。

以下 statestore.yaml 文件展示了如何配置 DynamoDB 状态存储组件以使用 ContractID 作为分区键属性名称：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: statestore
spec:
  type: state.aws.dynamodb
  version: v1
  metadata:
  - name: table
    value: "Contracts"
  - name: partitionKey
    value: "ContractID"

上述组件规格假设以下 DynamoDB 表布局：

{
    "Table": {
        "AttributeDefinitions": [
            {
                "AttributeName": "ContractID",
                "AttributeType": "S"
            }
        ],
        "TableName": "Contracts",
        "KeySchema": [
            {
                "AttributeName": "ContractID",
                "KeyType": "HASH"
            }
        ],
}

以下操作将 "A12345" 作为 key 的值传递，根据上述组件规格，Dapr 运行时将 key 属性名称替换为 ContractID，作为发送到 DynamoDB 的分区/主键：

$ dapr run --app-id contractsprocessing --app-port ...

$ curl -X POST http://localhost:3500/v1.0/state/<store_name> \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "A12345",
          "value": "Dapr Contract"
        }
      ]'

以下 AWS CLI 命令显示 DynamoDB Contracts 表的内容：

$ aws dynamodb get-item \
    --table-name Contracts \
    --key '{"ContractID":{"S":"contractsprocessing||A12345"}}' 
{
    "Item": {
        "value": {
            "S": "Dapr Contract"
        },
        "etag": {
            "S": "....."
        },
        "ContractID": {
            "S": "contractsprocessing||A12345"
        }
    }
}

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取配置状态存储组件的说明
• 状态管理构建块
• 身份验证到 AWS

3 - Azure Blob 存储

组件格式

要设置 Azure Blob 存储状态存储，请创建一个类型为 state.azure.blobstorage 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.azure.blobstorage
  # 支持 v1 和 v2。用户应始终默认使用 v2。没有从 v1 到 v2 的迁移路径，请参见下文的 `versioning`。
  version: v2
  metadata:
  - name: accountName
    value: "[your_account_name]"
  - name: accountKey
    value: "[your_account_key]"
  - name: containerName
    value: "[your_container_name]"

版本控制

Dapr 提供了两个版本的 Azure Blob 存储状态存储组件：v1 和 v2。建议所有新应用程序使用 v2。v1 被视为遗留版本，仅为与现有应用程序的兼容性而保留。

在 v1 中，存在一个长期的实现问题，即组件错误地忽略了键前缀，导致 keyPrefix 始终被设置为 none。
更新后的 v2 组件修复了此问题，使状态存储能够正确地使用 keyPrefix 属性。

虽然 v1 和 v2 具有相同的元数据字段，但它们在其他方面不兼容，v1 到 v2 没有自动数据迁移路径。

如果您正在使用此组件的 v1，建议继续使用 v1，直到创建新的状态存储。

规格元数据字段

设置 Azure Blob 存储

按照 Azure 文档中的说明创建 Azure 存储帐户。

如果您希望为 Dapr 创建一个容器，可以事先进行。然而，如果不存在，Blob 存储状态提供者会自动为您创建。

为了将 Azure Blob 存储设置为状态存储，您将需要以下属性：

• accountName: 存储帐户名称。例如：mystorageaccount。
• accountKey: 主存储或辅助存储帐户密钥。
• containerName: 用于 Dapr 状态的容器名称。如果不存在，Blob 存储状态提供者会自动为您创建。

使用 Microsoft Entra ID 进行身份验证

此组件支持使用 Microsoft Entra ID 进行身份验证，作为使用帐户密钥的替代方案。无论何时可能，建议您在生产系统中使用 Microsoft Entra ID 进行身份验证，以利用更好的安全性、精细的访问控制以及在 Azure 上运行的应用程序中使用托管身份的能力。

以下脚本针对 bash 或 zsh shell 进行了优化，并需要安装以下应用程序：

• Azure CLI
• jq

您还必须在 Azure CLI 中通过 Azure 进行身份验证。

1. 要开始使用 Microsoft Entra ID 进行 Blob 存储状态存储组件的身份验证，请确保您已创建 Microsoft Entra ID 应用程序和服务主体，如身份验证到 Azure文档中所述。
   完成后，设置一个变量以存储您创建的服务主体的 ID：

SERVICE_PRINCIPAL_ID="[your_service_principal_object_id]"

2. 使用您的 Azure 存储帐户名称和其所在资源组的名称设置以下变量：

STORAGE_ACCOUNT_NAME="[your_storage_account_name]"
RG_NAME="[your_resource_group_name]"

3. 使用 RBAC，为我们的服务主体分配一个角色，以便它可以访问存储帐户内的数据。
   在这种情况下，您正在分配“存储 Blob 数据贡献者”角色，该角色具有广泛的访问权限；根据您的应用程序，也可以使用其他更具限制性的角色。

RG_ID=$(az group show --resource-group ${RG_NAME} | jq -r ".id")
az role assignment create \
  --assignee "${SERVICE_PRINCIPAL_ID}" \
  --role "Storage blob Data Contributor" \
  --scope "${RG_ID}/providers/Microsoft.Storage/storageAccounts/${STORAGE_ACCOUNT_NAME}"

当使用 Microsoft Entra ID 对您的组件进行身份验证时，不需要 accountKey 字段。请根据身份验证到 Azure文档，在组件的元数据中指定所需的凭据（如果有）。

例如：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.azure.blobstorage
  version: v1
  metadata:
  - name: accountName
    value: "[your_account_name]"
  - name: containerName
    value: "[your_container_name]"
  - name: azureTenantId
    value: "[your_tenant_id]"
  - name: azureClientId
    value: "[your_client_id]"
  - name: azureClientSecret
    value : "[your_client_secret]"

应用配置

在 Kubernetes 中

要将 Azure Blob 存储状态存储应用于 Kubernetes，请使用 kubectl CLI：

kubectl apply -f azureblob.yaml

本地运行

要在本地运行，请创建一个包含 YAML 文件的 components 目录，并使用 --resources-path 标志将路径提供给 dapr run 命令。

此状态存储在容器中创建一个 Blob 文件，并将原始状态放入其中。

例如，以下操作来自名为 myservice 的服务：

curl -X POST http://localhost:3500/v1.0/state \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "nihilus",
          "value": "darth"
        }
      ]'

这将在容器中创建一个以 key 为文件名、value 为文件内容的 Blob 文件。

并发

Azure Blob 存储状态并发是通过使用 ETag 实现的，具体请参见 Azure Blob 存储文档。

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取配置状态存储组件的说明
• 状态管理构建块

4 - Azure Cosmos DB（SQL API）

组件格式

要设置 Azure Cosmos DB 状态存储，请创建一个类型为 state.azure.cosmosdb 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.azure.cosmosdb
  version: v1
  metadata:
  - name: url
    value: <REPLACE-WITH-URL>
  - name: masterKey
    value: <REPLACE-WITH-MASTER-KEY>
  - name: database
    value: <REPLACE-WITH-DATABASE>
  - name: collection
    value: <REPLACE-WITH-COLLECTION>
  # 如果希望将 Azure Cosmos DB 用作 actor 的状态存储，请取消注释此行（可选）
  #- name: actorStateStore
  #  value: "true"

如果希望将 Cosmos DB 用作 actor 存储，请在 yaml 中添加以下内容。

  - name: actorStateStore
    value: "true"

规格元数据字段

Microsoft Entra ID 认证

Azure Cosmos DB 状态存储组件支持使用所有 Microsoft Entra ID 机制进行认证。有关更多信息以及根据选择的 Microsoft Entra ID 认证机制提供的相关组件元数据字段，请参阅Azure 认证文档。

您可以在下面的部分中阅读有关使用 Azure AD 认证设置 Cosmos DB 的更多信息。

设置 Azure Cosmos DB

按照说明从 Azure 文档中了解如何创建 Azure Cosmos DB 帐户。在 Dapr 使用之前，必须在 Cosmos DB 中创建数据库和集合。

重要：集合的分区键必须命名为 /partitionKey（注意：这是区分大小写的）。

为了将 Cosmos DB 设置为状态存储，您需要以下属性：

• URL：Cosmos DB 的 URL。例如：https://******.documents.azure.com:443/
• 主密钥：用于认证 Cosmos DB 帐户的密钥。如果使用 Microsoft Entra ID 认证，请跳过此步骤。
• 数据库：数据库名称
• 集合：集合（或容器）名称

TTL 和清理

此状态存储支持 Dapr 存储记录的生存时间 (TTL)。使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性以覆盖 CosmodDB 容器上的默认 TTL，指示何时应将数据视为“过期”。请注意，此值仅在容器的 DefaultTimeToLive 字段具有非 NULL 值时生效。有关更多信息，请参阅 CosmosDB 文档。

生产使用的最佳实践

Azure Cosmos DB 在单个 Azure Cosmos DB 帐户中的所有数据库之间共享严格的元数据请求速率限制。与 Azure Cosmos DB 的新连接假定占用允许请求速率限制的大部分百分比。（请参阅 Cosmos DB 文档）

因此，必须应用几种策略以避免同时与 Azure Cosmos DB 建立新连接：

• 确保应用程序的 sidecar 仅在需要时加载 Azure Cosmos DB 组件，以避免不必要的数据库连接。这可以通过将组件限定到特定应用程序来实现。
• 选择按顺序部署或启动应用程序的部署策略，以最大限度地减少对 Azure Cosmos DB 帐户的新连接突发。
• 避免为不相关的数据库或系统（即使在 Dapr 之外）重用同一个 Azure Cosmos DB 帐户。不同的 Azure Cosmos DB 帐户具有不同的速率限制。
• 增加 initTimeout 值，以允许组件在 sidecar 初始化期间重试连接到 Azure Cosmos DB，最长可达 5 分钟。默认值为 5s，应增加。当使用 Kubernetes 时，增加此值可能还需要更新您的就绪性和存活性探针。

spec:
  type: state.azure.cosmosdb
  version: v1
  initTimeout: 5m
  metadata:

数据格式

要使用 Cosmos DB 状态存储，您的数据必须以 JSON 序列化格式发送到 Dapr。仅仅是 JSON 可序列化 是不够的。

如果您使用 Dapr SDK（例如 .NET SDK），SDK 会自动将您的数据序列化为 JSON。

如果您想直接调用 Dapr 的 HTTP 端点，请查看下面分区键部分中的示例（使用 curl）。

分区键

对于非 actor 状态操作，Azure Cosmos DB 状态存储将使用请求中提供给 Dapr API 的 key 属性来确定 Cosmos DB 分区键。可以通过在请求中指定一个元数据字段，键为 partitionKey，值为所需的分区来覆盖此设置。

以下操作使用 nihilus 作为发送到 Cosmos DB 的分区键值：

curl -X POST http://localhost:3500/v1.0/state/<store_name> \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "nihilus",
          "value": "darth"
        }
      ]'

对于非 actor状态操作，如果您想控制 Cosmos DB 分区，可以在元数据中指定它。重用上面的示例，以下是如何将其放在 mypartition 分区下：

curl -X POST http://localhost:3500/v1.0/state/<store_name> \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "nihilus",
          "value": "darth",
          "metadata": {
            "partitionKey": "mypartition"
          }
        }
      ]'

对于actor状态操作，分区键由 Dapr 使用 appId、actor 类型和 actor id 生成，以便同一 actor 的数据始终位于同一分区下（您无需指定它）。这是因为 actor 状态操作必须使用事务，而在 Cosmos DB 中，事务中的项目必须位于同一分区。

使用 Microsoft Entra ID 认证设置 Cosmos DB

当使用 Dapr Cosmos DB 状态存储并使用 Microsoft Entra ID 进行认证时，您需要执行一些额外步骤来设置您的环境。

前提条件：

• 您需要根据Azure 认证页面中的说明创建一个服务主体。您需要服务主体的 ID 以用于下面的命令（请注意，这与您的应用程序的客户端 ID 不同，或您在元数据中用于 azureClientId 的值）。
• Azure CLI
• jq
• 以下脚本针对 bash 或 zsh shell 进行了优化

授予您的 Microsoft Entra ID 应用程序访问 Cosmos DB 的权限

您可以在官方文档中找到更多信息，包括分配更细粒度权限的说明。

为了授予您的应用程序访问 Cosmos DB 中存储数据的权限，您需要为 Cosmos DB 数据平面分配一个自定义角色。在此示例中，您将使用内置角色“Cosmos DB 内置数据贡献者”，该角色授予您的应用程序对数据的完全读写访问权限；您可以选择按照官方文档中的说明创建自定义的、精细调整的角色。

# 包含您的 Cosmos DB 的资源组名称
RESOURCE_GROUP="..."
# 您的 Cosmos DB 帐户名称
ACCOUNT_NAME="..."
# 您的服务主体对象的 ID
PRINCIPAL_ID="..."
# "Cosmos DB 内置数据贡献者" 角色的 ID
# 您也可以使用自定义角色的 ID
ROLE_ID="00000000-0000-0000-0000-000000000002"

az cosmosdb sql role assignment create \
  --account-name "$ACCOUNT_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --scope "/" \
  --principal-id "$PRINCIPAL_ID" \
  --role-definition-id "$ROLE_ID"

优化

优化 Cosmos DB 以提高批量操作写入性能

如果您正在构建一个仅通过键（id）从 Cosmos DB 读取数据的系统，这是使用状态管理 API 或 actor 时 Dapr 的默认行为，您可以通过排除所有路径的索引来优化 Cosmos DB 以提高写入速度。默认情况下，Cosmos DB 会索引文档内的所有字段。在写入密集型且对文档内的值运行很少或没有查询的系统中，此索引策略会减慢在 Cosmos DB 中写入或更新文档的时间。这在高容量系统中尤为严重。

例如，Cosmos SQL 容器索引的默认 Terraform 定义如下所示：

indexing_policy {
  indexing_mode = "consistent"

  included_path {
    path = "/*"
  }
}

可以通过排除所有其他字段的索引来强制 Cosmos DB 仅索引 id 和 partitionKey 字段。这可以通过将上述内容更新为如下所示来实现：

indexing_policy {
  # 如果您纯粹将容器用作键值存储，也可以将其设置为 "none"。如果您的容器仅用作分布式缓存，这可能适用。
  indexing_mode = "consistent" 

  # 请注意，included_path 已被 excluded_path 替换
  excluded_path {
    path = "/*"
  }
}

优化 Cosmos DB 以节省成本

如果您打算仅将 Cosmos DB 用作键值对，您可能会考虑在将状态对象持久化到状态之前将其转换为 JSON 并压缩，然后在从状态读取时解压缩。这是因为 Cosmos DB 根据给定时间段内（通常为每小时）使用的最大 RU/s 数量来计费。此外，RU 使用量是根据您读取或写入的每 1 KB 数据计算为 1 RU。压缩有助于减少存储在 Cosmos DB 中的数据大小，从而减少 RU 使用量。

这种节省对于 Dapr actor 尤为显著。虽然 Dapr 状态管理 API 在保存之前对您的对象进行 base64 编码，但 Dapr actor 状态以原始格式化 JSON 保存。这意味着多行带有缩进的格式。压缩可以显著减少 actor 状态对象的大小。例如，如果您的 actor 状态对象在 actor 被加载时为 75KB，您将使用 75 RU/s 从状态中读取该对象。如果您随后修改状态对象并使其增长到 100KB，您将使用 100 RU/s 将该对象写入 Cosmos DB，总计 175 RU/s 的 I/O 操作。假设您的 actor 同时处理 1000 个请求每秒，您将需要至少 175,000 RU/s 来满足该负载。通过有效的压缩，大小减少可以达到 90% 的范围，这意味着您只需要大约 17,500 RU/s 来满足负载。

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取有关配置状态存储组件的说明
• 状态管理构建块

5 - Azure 表存储

组件格式

要配置 Azure 表存储状态组件，请创建一个类型为 state.azure.tablestorage 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.azure.tablestorage
  version: v1
  metadata:
  - name: accountName
    value: <REPLACE-WITH-ACCOUNT-NAME>
  - name: accountKey
    value: <REPLACE-WITH-ACCOUNT-KEY>
  - name: tableName
    value: <REPLACE-WITH-TABLE-NAME>
# - name: cosmosDbMode
#   value: false

元数据字段说明

Microsoft Entra ID 认证

Azure Cosmos DB 状态组件支持所有 Microsoft Entra ID 认证机制。有关更多信息以及如何选择适合的组件元数据字段，请参阅Azure 认证文档。

您可以在下面的部分了解更多关于使用 Microsoft Entra ID 认证设置 Cosmos DB 的信息。

选项 1：设置 Azure 表存储

按照说明从 Azure 文档中了解如何创建 Azure 存储帐户。

如果您希望为 Dapr 创建一个表，可以提前进行。然而，表存储状态组件会自动为您创建一个表（如果它不存在），除非启用了 skipCreateTable 选项。

要将 Azure 表存储设置为状态存储，您需要以下属性：

• AccountName：存储帐户名称，例如：mystorageaccount。
• AccountKey：主存储或辅助存储密钥。如果使用 Microsoft Entra ID 认证，请跳过此步骤。
• TableName：用于 Dapr 状态的表名。如果不存在，将自动创建，除非启用了 skipCreateTable 选项。
• cosmosDbMode：设置为 false 以连接到 Azure 表。

选项 2：设置 Azure Cosmos DB 表 API

按照说明从 Azure 文档中了解如何使用表 API 创建 Cosmos DB 帐户。

如果您希望为 Dapr 创建一个表，可以提前进行。然而，表存储状态组件会自动为您创建一个表（如果它不存在），除非启用了 skipCreateTable 选项。

要将 Azure Cosmos DB 表 API 设置为状态存储，您需要以下属性：

• AccountName：Cosmos DB 帐户名称，例如：mycosmosaccount。
• AccountKey：Cosmos DB 主密钥。如果使用 Microsoft Entra ID 认证，请跳过此步骤。
• TableName：用于 Dapr 状态的表名。如果不存在，将自动创建，除非启用了 skipCreateTable 选项。
• cosmosDbMode：设置为 true 以连接到 Cosmos DB 表 API。

分区

Azure 表存储状态组件使用请求中提供的 key 属性来确定 row key，而服务名称用于 partition key。这提供了最佳性能，因为每种服务类型在其自己的表分区中存储状态。

此状态存储在表存储中创建一个名为 Value 的列，并将原始状态放入其中。

例如，来自名为 myservice 的服务的以下操作

curl -X POST http://localhost:3500/v1.0/state \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "nihilus",
          "value": "darth"
        }
      ]'

将在表中创建以下记录：

并发

Azure 表存储状态的并发通过使用 ETag 实现，具体请参阅官方文档。

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取有关配置状态存储组件的说明
• 状态管理构建块

6 - Cassandra

组件格式

要配置 Cassandra 状态存储组件，请创建一个类型为 state.cassandra 的组件。请参阅本指南以了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.cassandra
  version: v1
  metadata:
  - name: hosts
    value: <用逗号分隔的主机列表> # 必需。示例：cassandra.cassandra.svc.cluster.local
  - name: username
    value: <用户名> # 可选。默认值：""
  - name: password
    value: <密码> # 可选。默认值：""
  - name: consistency
    value: <一致性级别> # 可选。默认值："All"
  - name: table
    value: <表名> # 可选。默认值："items"
  - name: keyspace
    value: <键空间> # 可选。默认值："dapr"
  - name: protoVersion
    value: <协议版本> # 可选。默认值："4"
  - name: replicationFactor
    value: <复制因子> # 可选。默认值："1"

规格元数据字段

设置 Cassandra

• 自托管
• Kubernetes

docker run -e DS_LICENSE=accept --memory 4g --name my-dse -d datastax/dse-server -g -s -k

kubectl create namespace cassandra
helm install cassandra incubator/cassandra --namespace cassandra

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取配置状态存储组件的说明
• 状态管理构建块

7 - Cloudflare Workers KV

创建 Dapr 组件

要配置 Cloudflare Workers KV 状态存储，您需要创建一个类型为 state.cloudflare.workerskv 的组件。请参考本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.cloudflare.workerskv
  version: v1
  # 如果 Dapr 为您管理 Worker，请增加 initTimeout
  initTimeout: "120s"
  metadata:
    # Workers KV 命名空间的 ID（必需）
    - name: kvNamespaceID
      value: ""
    # Worker 的名称（必需）
    - name: workerName
      value: ""
    # PEM 编码的私有 Ed25519 密钥（必需）
    - name: key
      value: |
        -----BEGIN PRIVATE KEY-----
        MC4CAQ...
        -----END PRIVATE KEY-----
    # Cloudflare 账户 ID（需要 Dapr 管理 Worker 时必需）
    - name: cfAccountID
      value: ""
    # Cloudflare 的 API 令牌（需要 Dapr 管理 Worker 时必需）
    - name: cfAPIToken
      value: ""
    # Worker 的 URL（如果 Worker 已在 Dapr 外部预创建，则必需）
    - name: workerUrl
      value: ""

规格元数据字段

如果您配置 Dapr 为您创建 Worker，可能需要为组件的 initTimeout 属性设置更长的值，以便为 Worker 脚本的部署留出足够的时间。例如：initTimeout: "120s"

创建 Workers KV 命名空间

要使用此组件，您必须在 Cloudflare 账户中创建一个 Workers KV 命名空间。

您可以通过以下两种方式之一创建新的 Workers KV 命名空间：

• 使用 Cloudflare 仪表板
  记下您在仪表板中看到的 Workers KV 命名空间的 “ID”。这是一个十六进制字符串（例如 123456789abcdef8b5588f3d134f74ac）–而不是您创建它时使用的名称！

• 使用 Wrangler CLI:

  # 如果需要，首先使用 `npx wrangler login` 进行身份验证
  wrangler kv:namespace create <NAME>
  

  输出包含命名空间的 ID，例如：

  { binding = "<NAME>", id = "123456789abcdef8b5588f3d134f74ac" }
  

配置 Worker

由于 Cloudflare Workers KV 命名空间只能由在 Workers 上运行的脚本访问，Dapr 需要维护一个 Worker 来与 Workers KV 存储进行通信。

Dapr 可以自动为您管理 Worker，或者您可以自行预配置一个 Worker。在 workerd 上运行时，预配置 Worker 是唯一支持的选项。

• 让 Dapr 管理 Worker
• 手动预配置 Worker 脚本

# 您的 Worker 的名称，例如 "mydaprkv"
name = ""

# 不要更改这些选项
main = "worker.js"
compatibility_date = "2022-12-09"
usage_model = "bundled"

[vars]
# 将此设置为 Ed25519 密钥的 **公共** 部分，PEM 编码（用 `\n` 替换换行符）。
# 示例：
# PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\nMCowB...=\n-----END PUBLIC KEY-----
PUBLIC_KEY = ""
# 将此设置为您的 Worker 的名称（与上面 "name" 属性的值相同），例如 "mydaprkv"。
TOKEN_AUDIENCE = ""

[[kv_namespaces]]
# 将以下两个值设置为您的 KV 命名空间的 ID（而不是名称），例如 "123456789abcdef8b5588f3d134f74ac"。
# 请注意，它们都将设置为相同的值。
binding = ""
id = ""

# 将此设置为您正在使用的 Dapr 版本
DAPR_VERSION="release-1.15"
curl -LfO "https://raw.githubusercontent.com/dapr/components-contrib/${DAPR_VERSION}/internal/component/cloudflare/workers/code/worker.js"

npx wrangler publish

生成 Ed25519 密钥对

所有 Cloudflare Workers 都在公共互联网监听，因此 Dapr 需要使用额外的身份验证和数据保护措施，以确保没有其他人或应用程序可以与您的 Worker（以及您的 Worker KV 命名空间）通信。这些措施包括行业标准措施，例如：

• Dapr 向 Worker 发出的所有请求都通过一个持有者令牌（技术上是一个 JWT）进行身份验证，该令牌由 Ed25519 密钥签名。
• Dapr 和您的 Worker 之间的所有通信都通过加密连接进行，使用 TLS（HTTPS）。
• 持有者令牌在每次请求时生成，并且仅在短时间内有效（目前为一分钟）。

为了让 Dapr 发出持有者令牌，并让您的 Worker 验证它们，您需要生成一个新的 Ed25519 密钥对。以下是使用 OpenSSL 或 step CLI 生成密钥对的示例。

• 使用 OpenSSL 生成
• 使用 step CLI 生成

openssl genpkey -algorithm ed25519 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem

step crypto keypair \
  public.pem private.pem \
  --kty OKP --curve Ed25519 \
  --insecure --no-password

无论您如何生成密钥对，按照上述说明，您将拥有两个文件：

• private.pem 包含密钥的私有部分；使用此文件的内容作为组件元数据的 key 属性。
• public.pem 包含密钥的公共部分，您仅在手动部署 Worker 时需要它（如上一节中的说明）。

附加说明

• 请注意，Cloudflare Workers KV 不保证强数据一致性。虽然更改通常会立即对同一 Cloudflare 数据中心的请求可见，但更改在所有 Cloudflare 区域之间复制可能需要一定时间（通常最多一分钟）。
• 此状态存储支持 Dapr 的 TTL，但 TTL 的最小值为 1 分钟。

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取有关配置状态存储组件的说明
• 状态管理构建块
• Cloudflare Workers KV 的文档

8 - CockroachDB

创建一个 Dapr 组件

创建一个名为 cockroachdb.yaml 的文件，粘贴以下内容并将 <CONNECTION STRING> 值替换为您的连接字符串。CockroachDB 的连接字符串与 PostgreSQL 的连接字符串标准相同。例如，"host=localhost user=root port=26257 connect_timeout=10 database=dapr_test"。有关如何定义连接字符串的信息，请参阅 CockroachDB 数据库连接文档。

如果您还想配置 CockroachDB 来存储 actor 状态，请添加 actorStateStore 选项，如下面的示例所示。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.cockroachdb
  version: v1
  metadata:
  # 连接字符串
  - name: connectionString
    value: "<CONNECTION STRING>"
  # 数据库操作的超时时间，以秒为单位（可选）
  #- name: timeoutInSeconds
  #  value: 20
  # 存储状态的表名（可选）
  #- name: tableName
  #  value: "state"
  # Dapr 使用的元数据存储表名（可选）
  #- name: metadataTableName
  #  value: "dapr_metadata"
  # 清理过期行的间隔时间，以秒为单位（可选）
  #- name: cleanupIntervalInSeconds
  #  value: 3600
  # 连接关闭前的最大空闲时间（可选）
  #- name: connectionMaxIdleTime
  #  value: 0
  # 如果希望使用 CockroachDB 作为 actor 的状态存储，请取消注释此行（可选）
  #- name: actorStateStore
  #  value: "true"

规格元数据字段

设置 CockroachDB

• Self-Hosted
• Kubernetes

高级

TTL 和清理

此状态存储支持 Dapr 存储记录的生存时间 (TTL)。使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性，以指示数据在多少秒后应被视为“过期”。

由于 CockroachDB 没有内置的 TTL 支持，您可以通过在状态表中添加一列来实现这一点，该列指示数据何时应被视为“过期”。即使“过期”记录仍然物理存储在数据库中，也不会返回给调用者。后台“垃圾收集器”定期扫描状态表以删除过期的行。

您可以使用 cleanupIntervalInSeconds 元数据属性设置删除过期记录的间隔时间，默认为 3600 秒（即 1 小时）。

• 较长的间隔需要较少频繁地扫描过期行，但可能需要更长时间存储过期记录，可能需要更多的存储空间。如果您计划在状态表中存储许多记录，并且 TTL 较短，请考虑将 cleanupIntervalInSeconds 设置为较小的值，例如 300（300 秒或 5 分钟）。
• 如果您不打算在 Dapr 和 CockroachDB 状态存储中使用 TTL，您应考虑将 cleanupIntervalInSeconds 设置为 <= 0（例如 0 或 -1）以禁用定期清理并减少数据库的负载。

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取有关配置状态存储组件的说明
• 状态管理构建块

9 - Couchbase

组件格式

要设置 Couchbase 状态存储，需要创建一个类型为 state.couchbase 的组件。请参阅本指南以了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.couchbase
  version: v1
  metadata:
  - name: couchbaseURL
    value: <REPLACE-WITH-URL> # 必填。示例: "http://localhost:8091"
  - name: username
    value: <REPLACE-WITH-USERNAME> # 必填。
  - name: password
    value: <REPLACE-WITH-PASSWORD> # 必填。
  - name: bucketName
    value: <REPLACE-WITH-BUCKET> # 必填。

配置元数据字段

设置 Couchbase

• Self-Hosted
• Kubernetes

docker run -d --name db -p 8091-8094:8091-8094 -p 11210:11210 couchbase

helm repo add couchbase https://couchbase-partners.github.io/helm-charts/
helm install couchbase/couchbase-operator
helm install couchbase/couchbase-cluster

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取配置状态存储组件的说明
• 状态管理构建块

10 - Etcd

组件格式

要配置 Etcd 状态存储，需创建一个类型为 state.etcd 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.etcd
  # 支持 v1 和 v2。建议默认使用 v2。请注意，v1 和 v2 之间没有直接的迁移路径，详情请参见下文的 `版本控制`。
  version: v2
  metadata:
  - name: endpoints
    value: <CONNECTION STRING> # 必需。示例：192.168.0.1:2379,192.168.0.2:2379,192.168.0.3:2379
  - name: keyPrefixPath
    value: <KEY PREFIX STRING> # 可选。默认值：""。示例："dapr"
  - name: tlsEnable
    value: <ENABLE TLS> # 可选。示例："false"
  - name: ca
    value: <CA> # 可选。如果 tlsEnable 为 `true`，则必需。
  - name: cert
    value: <CERT> # 可选。如果 tlsEnable 为 `true`，则必需。
  - name: key
    value: <KEY> # 可选。如果 tlsEnable 为 `true`，则必需。
  # 如果希望将 Etcd 用作 actor 的状态存储，请取消注释此行（可选）
  #- name: actorStateStore
  #  value: "true"

版本控制

Dapr 提供了两个版本的 Etcd 状态存储组件：v1 和 v2。建议使用 v2，因为 v1 已被弃用。

虽然 v1 和 v2 使用相同的元数据字段，但在使用 Dapr v1.12 的 actor TTLs 时，v1 可能会导致应用程序中的数据不一致。 v1 和 v2 之间不兼容，且在现有的 Etcd 集群和 keyPrefixPath 上没有从 v1 到 v2 的数据迁移路径。 如果您当前使用的是 v1，建议继续使用，直到您创建一个新的 Etcd 集群或使用不同的 keyPrefixPath。

规格元数据字段

设置 Etcd

• Self-Hosted
• Kubernetes

version: '2'
services:
  etcd:
    image: gcr.io/etcd-development/etcd:v3.4.20
    ports:
      - "2379:2379"
    command: etcd --listen-client-urls http://0.0.0.0:2379 --advertise-client-urls http://0.0.0.0:2379```

docker-compose up -d

etcdctl --endpoints=localhost:2379 put mykey myvalue

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取有关配置状态存储组件的说明
• 状态管理构建块

11 - GCP Firestore（Datastore 模式）

组件格式

要设置 GCP Firestore 状态存储组件，请创建一个类型为 state.gcp.firestore 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.gcp.firestore
  version: v1
  metadata:
  - name: project_id
    value: <REPLACE-WITH-PROJECT-ID> # 必填。
  - name: endpoint # 可选。
    value: "http://localhost:8432"
  - name: private_key_id
    value: <REPLACE-WITH-PRIVATE-KEY-ID> # 可选。
  - name: private_key
    value: <REPLACE-WITH-PRIVATE-KEY> # 可选，但如果指定了 `private_key_id` 则必填。
  - name: client_email
    value: <REPLACE-WITH-CLIENT-EMAIL> # 可选，但如果指定了 `private_key_id` 则必填。
  - name: client_id
    value: <REPLACE-WITH-CLIENT-ID> # 可选，但如果指定了 `private_key_id` 则必填。
  - name: auth_uri
    value: <REPLACE-WITH-AUTH-URI> # 可选。
  - name: token_uri
    value: <REPLACE-WITH-TOKEN-URI> # 可选。
  - name: auth_provider_x509_cert_url
    value: <REPLACE-WITH-AUTH-X509-CERT-URL> # 可选。
  - name: client_x509_cert_url
    value: <REPLACE-WITH-CLIENT-x509-CERT-URL> # 可选。
  - name: entity_kind
    value: <REPLACE-WITH-ENTITY-KIND> # 可选。默认值："DaprState"
  - name: noindex
    value: <REPLACE-WITH-BOOLEAN> # 可选。默认值："false"
  - name: type 
    value: <REPLACE-WITH-CREDENTIALS-TYPE> # 已弃用。

规格元数据字段

GCP 凭据

由于 GCP Firestore 组件使用 GCP Go 客户端库，默认情况下会使用 应用程序默认凭据 进行身份验证。详细信息请参阅使用客户端库对 GCP 云服务进行身份验证指南。

设置 GCP Firestore

• Self-Hosted
• Google Cloud

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取有关配置状态存储组件的说明
• 状态管理构建块

12 - HashiCorp Consul

组件格式

要配置 HashiCorp Consul 状态存储，创建一个类型为 state.consul 的组件。请参考本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.consul
  version: v1
  metadata:
  - name: datacenter
    value: <REPLACE-WITH-DATA-CENTER> # 必需。示例: dc1
  - name: httpAddr
    value: <REPLACE-WITH-CONSUL-HTTP-ADDRESS> # 必需。示例: "consul.default.svc.cluster.local:8500"
  - name: aclToken
    value: <REPLACE-WITH-ACL-TOKEN> # 可选。默认: ""
  - name: scheme
    value: <REPLACE-WITH-SCHEME> # 可选。默认: "http"
  - name: keyPrefixPath
    value: <REPLACE-WITH-TABLE> # 可选。默认: ""

规范元数据字段

设置 HashiCorp Consul

• Self-Hosted
• Kubernetes

docker run -d --name=dev-consul -e CONSUL_BIND_INTERFACE=eth0 consul

helm install consul stable/consul

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取配置状态存储组件的说明
• 状态管理构建块

13 - Hazelcast

创建一个 Dapr 组件

要配置 Hazelcast 状态存储，请创建一个类型为 state.hazelcast 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.hazelcast
  version: v1
  metadata:
  - name: hazelcastServers
    value: <REPLACE-WITH-HOSTS> # 必需。服务器地址的逗号分隔字符串。例如："hazelcast:3000,hazelcast2:3000"
  - name: hazelcastMap
    value: <REPLACE-WITH-MAP> # 必需。Hazelcast map 的配置。

规格元数据字段

设置 Hazelcast

• 自托管
• Kubernetes

docker run -e JAVA_OPTS="-Dhazelcast.local.publicAddress=127.0.0.1:5701" -p 5701:5701 hazelcast/hazelcast

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取配置状态存储组件的说明
• 状态管理构建块

14 - JetStream KV

组件格式

要设置 JetStream KV 状态存储，请创建一个类型为 state.jetstream 的组件。有关如何创建和应用状态存储配置的详细步骤，请参阅本指南。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.jetstream
  version: v1
  metadata:
  - name: natsURL
    value: "nats://localhost:4222"
  - name: jwt
    value: "eyJhbGciOiJ...6yJV_adQssw5c" # 可选。用于分布式 JWT 认证
  - name: seedKey
    value: "SUACS34K232O...5Z3POU7BNIL4Y" # 可选。用于分布式 JWT 认证
  - name: bucket
    value: "<bucketName>"

规格元数据字段说明

创建 NATS 服务器

• Self-Hosted
• Kubernetes

docker run -d -p 4222:4222 nats:latest -js

helm repo add nats https://nats-io.github.io/k8s/helm/charts/
helm install my-nats nats/nats

创建 JetStream KV 桶

需要创建一个键值桶，这可以通过 NATS CLI 轻松完成。

nats kv add <bucketName>

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取配置状态存储组件的说明
• 状态管理构建块
• JetStream 文档
• 键值存储文档
• NATS CLI

15 - Memcached

组件格式

要配置 Memcached 状态存储，需创建一个类型为 state.memcached 的组件。请参阅本指南以了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.memcached
  version: v1
  metadata:
  - name: hosts
    value: <REPLACE-WITH-COMMA-DELIMITED-ENDPOINTS> # 必需。示例: "memcached.default.svc.cluster.local:11211"
  - name: maxIdleConnections
    value: <REPLACE-WITH-MAX-IDLE-CONNECTIONS> # 可选。默认值: "2"
  - name: timeout
    value: <REPLACE-WITH-TIMEOUT> # 可选。默认值: "1000"

规格元数据字段

设置 Memcached

• Self-Hosted
• Kubernetes

docker run --name my-memcache -d memcached

helm install memcached stable/memcached

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取配置状态存储组件的说明
• 状态管理构建块

16 - Microsoft SQL Server & Azure SQL

组件格式

该状态存储组件适用于 Microsoft SQL Server 和 Azure SQL。

要配置此状态存储，请创建一个类型为 state.sqlserver 的组件。请参考本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.sqlserver
  version: v1
  metadata:
    # 使用 SQL Server 凭据进行身份验证
    - name: connectionString
      value: |
        Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;

    # 使用 Microsoft Entra ID 进行身份验证（仅限 Azure SQL）
    # "useAzureAD" 设置为 "true"
    - name: useAzureAD
      value: true
    # Azure SQL 数据库的连接字符串或 URL，可选包含数据库
    - name: connectionString
      value: |
        sqlserver://myServerName.database.windows.net:1433?database=myDataBase

    # 其他可选字段（列出默认值）
    - name: tableName
      value: "state"
    - name: metadataTableName
      value: "dapr_metadata"
    - name: schema
      value: "dbo"
    - name: keyType
      value: "string"
    - name: keyLength
      value: "200"
    - name: indexedProperties
      value: ""
    - name: cleanupIntervalInSeconds
      value: "3600"
   # 如果希望使用 Microsoft SQL Server 作为 actor 的状态存储，请取消注释此行（可选）
   #- name: actorStateStore
   #  value: "true"

如果希望将 SQL Server 用作 actor 状态存储，请在元数据中添加以下内容：

  - name: actorStateStore
    value: "true"

规格元数据字段

使用 SQL Server 凭据进行身份验证

以下元数据选项是使用 SQL Server 凭据进行身份验证所必需的。这在 SQL Server 和 Azure SQL 上均受支持。

使用 Microsoft Entra ID 进行身份验证

使用 Microsoft Entra ID 进行身份验证仅在 Azure SQL 上受支持。Dapr 支持的所有身份验证方法均可使用，包括客户端凭据（“服务主体”）和托管身份。

其他元数据选项

创建 Microsoft SQL Server/Azure SQL 实例

按照说明从 Azure 文档中了解如何创建 SQL 数据库。数据库必须在 Dapr 使用之前创建。

为了将 SQL Server 设置为状态存储，您需要以下属性：

• 连接字符串：SQL Server 连接字符串。例如：server=localhost;user id=sa;password=your-password;port=1433;database=mydatabase;
• 模式：要使用的数据库模式（默认=dbo）。如果不存在，将被创建
• 表名：数据库表名。如果不存在，将被创建
• 索引属性：来自 json 数据的可选属性，将被索引并作为单独的列持久化

创建专用用户

当使用专用用户（非 sa）连接时，即使用户是所需数据库模式的所有者，也需要为用户提供以下授权：

• CREATE TABLE
• CREATE TYPE

TTL 和清理

此状态存储支持 Dapr 存储的记录的 生存时间 (TTL)。使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性，以指示数据在多少秒后应被视为“过期”。

由于 SQL Server 没有内置的 TTL 支持，Dapr 通过在状态表中添加一列来实现这一点，该列指示数据何时应被视为“过期”。即使“过期”记录仍然物理存储在数据库中，也不会返回给调用者。后台“垃圾收集器”定期扫描状态表以查找过期的行并删除它们。

您可以使用 cleanupIntervalInSeconds 元数据属性设置过期记录删除的间隔，默认为 3600 秒（即 1 小时）。

• 较长的间隔需要较少频繁地扫描过期行，但可能需要更长时间存储过期记录，可能需要更多的存储空间。如果您计划在状态表中存储许多记录，并且 TTL 较短，请考虑将 cleanupIntervalInSeconds 设置为较小的值 - 例如，300（300 秒，或 5 分钟）。
• 如果您不打算在 Dapr 和 SQL Server 状态存储中使用 TTL，您应该考虑将 cleanupIntervalInSeconds 设置为 <= 0 的值（例如 0 或 -1）以禁用定期清理并减少数据库的负载。

状态存储在 ExpireDate 列上没有索引，这意味着每次清理操作都必须执行全表扫描。如果您打算在表中写入大量使用 TTL 的记录，您应该考虑在 ExpireDate 列上创建索引。索引使查询更快，但使用更多的存储空间并略微减慢写入速度。

CREATE CLUSTERED INDEX expiredate_idx ON state(ExpireDate ASC)

相关链接

• Dapr 组件的基本模式
• 阅读本指南以获取有关配置状态存储组件的说明
• 状态管理构建块

17 - MongoDB

组件格式

为了设置MongoDB状态存储，您需要创建一个类型为state.mongodb的组件。请参考本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.mongodb
  version: v1
  metadata:
  - name: server
    value: <REPLACE-WITH-SERVER> # 必填，除非设置了"host"字段。例如："server.example.com"
  - name: host
    value: <REPLACE-WITH-HOST> # 必填，除非设置了"server"字段。例如："mongo-mongodb.default.svc.cluster.local:27017"
  - name: username
    value: <REPLACE-WITH-USERNAME> # 可选。例如："admin"
  - name: password
    value: <REPLACE-WITH-PASSWORD> # 可选。
  - name: databaseName
    value: <REPLACE-WITH-DATABASE-NAME> # 可选。默认值："daprStore"
  - name: collectionName
    value: <REPLACE-WITH-COLLECTION-NAME> # 可选。默认值："daprCollection"
  - name: writeConcern
    value: <REPLACE-WITH-WRITE-CONCERN> # 可选。
  - name: readConcern
    value: <REPLACE-WITH-READ-CONCERN> # 可选。
  - name: operationTimeout
    value: <REPLACE-WITH-OPERATION-TIMEOUT> # 可选。默认值："5s"
  - name: params
    value: <REPLACE-WITH-ADDITIONAL-PARAMETERS> # 可选。例如："?authSource=daprStore&ssl=true"
  # 如果希望将MongoDB用作actor的状态存储，请取消注释此行（可选）
  #- name: actorStateStore
  #  value: "true"

actor状态存储和事务支持

当MongoDB用作actor状态存储或需要事务支持时，必须在副本集中运行。

如果希望将MongoDB用作actor存储，请在组件YAML中添加以下元数据选项：

  - name: actorStateStore
    value: "true"

规格元数据字段

^[1] server和host字段是互斥的。如果两者都未设置或都设置，Dapr将返回错误。

^[2] params字段接受一个查询字符串，该字符串指定连接特定选项为<name>=<value>对，以&分隔并以?为前缀。例如，要使用"daprStore"数据库作为身份验证数据库并在连接中启用SSL/TLS，请将参数指定为?authSource=daprStore&ssl=true。有关可用选项及其用例的列表，请参阅MongoDB手册。

设置MongoDB

• Self-Hosted
• Kubernetes

docker run --name some-mongo -d -p 27017:27017 mongo

TTL和清理

此状态存储支持Dapr存储记录的生存时间（TTL）。使用Dapr存储数据时，您可以设置ttlInSeconds元数据属性以指示数据何时应被视为“过期”。

相关链接

• Dapr组件的基本架构
• 阅读本指南以获取配置状态存储组件的说明
• 状态管理构建块

18 - MySQL & MariaDB

组件格式

MySQL 状态存储组件允许连接到 MySQL 和 MariaDB 数据库。在本文档中，“MySQL” 代表这两个数据库。

要设置 MySQL 状态存储，请创建一个类型为 state.mysql 的组件。请参考本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.mysql
  version: v1
  metadata:
  - name: connectionString
    value: "<CONNECTION STRING>"
  - name: schemaName
    value: "<SCHEMA NAME>"
  - name: tableName
    value: "<TABLE NAME>"
  - name: timeoutInSeconds
    value: "30"
  - name: pemPath # 如果未提供 pemContents，则为必需。pem 文件的路径。
    value: "<PEM PATH>"
  - name: pemContents # 如果未提供 pemPath，则为必需。pem 值。
    value: "<PEM CONTENTS>"    
# 如果希望将 MySQL & MariaDB 用作 actor 的状态存储，请取消注释此行（可选）
  #- name: actorStateStore
  #  value: "true"

如果希望将 MySQL 用作 actor 存储，请在 yaml 中添加以下配置。

  - name: actorStateStore
    value: "true"

规格元数据字段

设置 MySQL

Dapr 可以使用任何 MySQL 实例 - 无论是容器化的 MySQL 实例、在本地开发机器上运行的，还是云服务提供的 MySQL 实例。

• Self-Hosted
• Kubernetes
• Azure
• AWS
• GCP

docker run --name dapr-mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:latest

非 SSL 连接

将 <CONNECTION STRING> 值替换为您的连接字符串。连接字符串是标准的 MySQL 连接字符串。例如，"<user>:<password>@tcp(<server>:3306)/?allowNativePasswords=true"。

强制 SSL 连接

如果您的服务器需要 SSL，您的连接字符串必须以 &tls=custom 结尾，例如，"<user>:<password>@tcp(<server>:3306)/?allowNativePasswords=true&tls=custom"。您必须将 <PEM PATH> 替换为 PEM 文件的完整路径。连接到 MySQL 将需要最低 TLS 版本为 1.2。

TTL 和清理

此状态存储支持 Dapr 存储的记录的生存时间 (TTL)。使用 Dapr 存储数据时，您可以设置 ttlInSeconds 元数据属性以指示数据何时应被视为 “过期”。

由于 MySQL 没有内置的 TTL 支持，这在 Dapr 中通过在状态表中添加一列来实现，指示数据何时应被视为 “过期”。即使数据仍然物理存储在数据库中，“过期” 的记录也不会返回给调用者。后台 “垃圾收集器” 定期扫描状态表以删除过期的行。

删除过期记录的间隔时间由 cleanupIntervalInSeconds 元数据属性设置，默认为 3600 秒（即 1 小时）。

• 较长的间隔需要较少频繁地扫描过期行，但可能需要更长时间存储过期记录，可能需要更多的存储空间。如果您计划在状态表中存储许多记录，并且 TTL 较短，请考虑将 cleanupIntervalInSeconds 设置为较小的值，例如 300（300 秒或 5 分钟）。
• 如果您不打算在 Dapr 和 MySQL 状态存储中使用 TTL，您应考虑将 cleanupIntervalInSeconds 设置为 <= 0（例如 0 或 -1）以禁用定期清理并减少数据库的负载。

相关链接

• Dapr 组件的基本 schema
• 阅读本指南以获取配置状态存储组件的说明
• 状态管理构建块

19 - OCI 对象存储

组件格式

要配置 OCI 对象存储状态存储，请创建一个类型为 state.oci.objectstorage 的组件。请参阅本指南了解如何创建和应用状态存储配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.oci.objectstorage
  version: v1
  metadata:
 - name: instancePrincipalAuthentication
   value: <"true" 或 "false">  # 可选。默认值："false"
 - name: configFileAuthentication
   value: <"true" 或 "false">  # 可选。默认值："false"。当 instancePrincipalAuthentication 为 "true" 时不使用
 - name: configFilePath
   value: <配置文件的完整路径>  # 可选。无默认值。仅在 configFileAuthentication 为 "true" 时使用
 - name: configFileProfile
   value: <配置文件中的配置名称>  # 可选。默认值："DEFAULT"。仅在 configFileAuthentication 为 "true" 时使用
 - name: tenancyOCID
   value: <租户的 OCID>  # 当 configFileAuthentication 为 "true" 或 instancePrincipalAuthentication 为 "true" 时不使用
 - name: userOCID
   value: <用户的 OCID>  # 当 configFileAuthentication 为 "true" 或 instancePrincipalAuthentication 为 "true" 时不使用
 - name: fingerPrint
   value: <公钥的指纹>  # 当 configFileAuthentication 为 "true" 或 instancePrincipalAuthentication 为 "true" 时不使用
 - name: privateKey  # 当 configFileAuthentication 为 "true" 或 instancePrincipalAuthentication 为 "true" 时不使用
   value: |
          -----BEGIN RSA PRIVATE KEY-----
          私钥内容
          -----END RSA PRIVATE KEY-----
 - name: region
   value: <OCI 区域>  # 当 configFileAuthentication 为 "true" 或 instancePrincipalAuthentication 为 "true" 时不使用
 - name: bucketName
   value: <桶的名称>
 - name: compartmentOCID
   value: <隔间的 OCID>

规格元数据字段

设置 OCI 对象存储

OCI 对象存储状态存储需要与 Oracle 云基础设施交互。状态存储支持两种认证方法：基于身份（用户或服务账户）的认证和实例主体认证。请注意，资源主体认证（用于非实例的资源，如无服务器函数）目前不支持。

在 Oracle 云基础设施上运行的 Dapr 应用程序（无论是在计算实例中还是作为 Kubernetes 上的容器）可以使用实例主体认证。有关更多信息，请参阅 OCI 文档关于从实例调用 OCI 服务。简而言之：实例需要是动态组的成员，并且该动态组需要通过 IAM 策略获得与对象存储服务交互的权限。在这种情况下，设置 instancePrincipalAuthentication 为 "true"。您无需配置 tenancyOCID、userOCID、region、fingerPrint 和 privateKey 属性——如果您为它们定义了值，这些将被忽略。

基于身份的认证通过具有权限的 OCI 账户与 OCI 交互，以在指定的桶中创建、读取和删除对象，并允许在指定的隔间中创建桶（如果桶未事先创建）。OCI 文档描述了如何创建 OCI 账户。状态存储通过使用为 OCI 账户生成的 RSA 密钥对的公钥指纹和私钥进行交互。OCI 文档中提供了生成密钥对和获取所需信息的说明。

身份和身份凭证的详细信息可以直接在 Dapr 组件属性文件中提供——使用属性 tenancyOCID、userOCID、fingerPrint、privateKey 和 region——或者可以从配置文件中提供，这在许多 OCI 相关工具（如 CLI 和 Terraform）和 SDK 中很常见。在后一种情况下，必须通过属性 configFilePath 提供确切的文件名和完整路径。请注意：路径中不支持 ~/ 前缀。配置文件可以包含多个配置；可以通过属性 configFileProfile 指定所需的配置。如果未提供值，则使用 DEFAULT 作为要使用的配置名称。请注意：如果未找到指定的配置，则使用 DEFAULT 配置（如果存在）。OCI SDK 文档提供了关于配置文件定义的详细信息。

如果您希望为 Dapr 使用创建桶，可以事先进行。然而，如果不存在，对象存储状态提供者将在指定的隔间中自动为您创建一个。

为了将 OCI 对象存储设置为状态存储，您需要以下属性：

• instancePrincipalAuthentication：指示是否应使用基于实例主体的认证的标志。
• configFileAuthentication：指示是否通过配置文件提供 OCI 身份凭证的标志。当 instancePrincipalAuthentication 为 true 时不使用。
• configFilePath：OCI 配置文件的完整路径。当 instancePrincipalAuthentication 为 true 或 configFileAuthentication 不为 true 时不使用。
• configFileProfile：配置文件中的配置名称。默认值：“DEFAULT”。当 instancePrincipalAuthentication 为 true 或 configFileAuthentication 不为 true 时不使用。当在配置文件中找不到指定的配置时，使用 DEFAULT 配置（如果存在）。
• tenancyOCID：要存储状态的 OCI 云租户的标识符。当 instancePrincipalAuthentication 为 true 或 configFileAuthentication 为 true 时不使用。
• userOCID：状态存储组件用于连接到 OCI 的账户标识符；这必须是对指定隔间和桶上的 OCI 对象存储服务具有适当权限的账户。当 instancePrincipalAuthentication 为 true 或 configFileAuthentication 为 true 时不使用。
• fingerPrint：为 userOCID 指定的账户生成的 RSA 密钥对中公钥的指纹。当 instancePrincipalAuthentication 为 true 或 configFileAuthentication 为 true 时不使用。
• privateKey：为 userOCID 指定的账户生成的 RSA 密钥对中的私钥。当 instancePrincipalAuthentication 为 true 或 configFileAuthentication 为 true 时不使用。
• region：OCI 区域 - 例如 us-ashburn-1、eu-amsterdam-1、ap-mumbai-1。当 instancePrincipalAuthentication 为 true 时不使用。
• bucketName：OCI 对象存储中将创建状态的桶的名称。此桶可以在状态存储初始化时已经存在，也可以在状态存储初始化期间创建。请注意，桶的名称在命名空间内是唯一的。
• compartmentOCID：租户中桶存在或将被创建的隔间的标识符。

运行时会发生什么？

每个状态条目由 OCI 对象存储中的一个对象表示。OCI 对象存储状态存储使用请求中提供给 Dapr API 的 key 属性来确定对象的名称。value 作为对象的内容存储。每个对象在创建或更新时都会分配一个唯一的 ETag 值；这是 OCI 对象存储的本机行为。状态存储为它写入的每个对象分配一个元数据标签；标签是 category，其值是 dapr-state-store。这允许创建为 Dapr 应用程序状态的对象被识别。

例如，以下操作

curl -X POST http://localhost:3500/v1.0/state \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "nihilus",
          "value": "darth"
        }
      ]'

创建以下对象：

Dapr 使用固定的键方案与复合键来跨应用程序分区状态。对于一般状态，键格式为： App-ID||state key OCI 对象存储状态存储将第一个键段（用于 App-ID）映射到桶内的目录，使用 OCI 对象存储文档中描述的用于模拟目录结构的前缀和层次结构。

因此，以下操作（注意复合键）

curl -X POST http://localhost:3500/v1.0/state \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "myApplication||nihilus",
          "value": "darth"
        }
      ]'

将创建以下对象：

您将能够通过控制台、API、CLI 或 SDK 检查通过 OCI 对象存储状态存储存储的所有状态。通过直接访问桶，您可以准备在运行时可用作应用程序状态的状态。

生存时间和状态过期

OCI 对象存储状态存储支持 Dapr 的生存时间逻辑，确保状态在过期后无法检索。有关详细信息，请参阅此设置状态生存时间的操作指南。

OCI 对象存储不支持本机生存时间设置。此组件中的实现使用在每个指定了 TTL 的对象上放置的元数据标签。该标签称为 expiry-time-from-ttl，它包含一个 ISO 日期时间格式的字符串，表示基于 UTC 的过期时间。当通过调用 Get 检索状态时，此组件会检查它是否设置了 expiry-time-from-ttl，如果是，则检查它是否在过去。在这种情况下，不返回状态。

因此，以下操作（注意复合键）

curl -X POST http://localhost:3500/v1.0/state \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "temporary",
          "value": "ephemeral",
          "metadata": {"ttlInSeconds": "120"}}
        }
      ]'

创建以下对象：

当然，expiry-time-from-ttl 的确切值取决于创建状态的时间，并将在该时刻之后的 120 秒。

请注意，此组件不会从状态存储中删除过期的状态。应用程序操作员可以决定运行一个定期作业，以某种形式的垃圾收集来显式删除所有具有过去时间戳的 expiry-time-from-ttl 标签的状态。

并发

OCI 对象存储状态并发通过使用 ETag 实现。OCI 对象存储中的每个对象在创建或更新时都会分配一个唯一的 ETag。当此状态存储的 Set 和 Delete 请求指定 FirstWrite 并发策略时，请求需要提供要写入或删除的状态的实际 ETag 值，以便请求成功。

一致性

OCI 对象存储状态不支持事务。

查询

OCI 对象存储状态不支持查询 API。

相关链接

• Dapr 组件的基本架构
• 阅读本指南以获取有关配置状态存储组件的说明
• 状态管理构建块

20 - Oracle 数据库

组件格式

创建一个组件属性的 yaml 文件，例如 oracle.yaml（名称可以随意），然后粘贴以下内容，并将 <CONNECTION STRING> 替换为您的连接字符串。连接字符串是标准的 Oracle 数据库连接字符串，格式为："oracle://user/password@host:port/servicename"，例如 "oracle://demo:demo@localhost:1521/xe"。

如果您通过 Oracle Wallet 连接数据库，则应为 oracleWalletLocation 属性指定一个值，例如："/home/app/state/Wallet_daprDB/"；这应该指向本地文件系统目录，该目录包含从 Oracle Wallet 压缩文件中提取的 cwallet.sso 文件。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: state.oracledatabase
  version: v1
  metadata:
  - name: connectionString
    value: "<CONNECTION STRING>"
  - name: oracleWalletLocation
    value: "<FULL PATH TO DIRECTORY WITH ORACLE WALLET CONTENTS >"  # 可选，无默认值
  - name: tableName
    value: "<NAME OF DATABASE TABLE TO STORE STATE IN >" # 可选，默认为 STATE
  # 如果您希望使用 Oracle 数据库作为 actor 的状态存储，请取消注释此行（可选）
  #- name: actorStateStore
  #  value: "true"

规格元数据字段

运行时会发生什么？

当状态存储组件初始化时，它会连接到 Oracle 数据库并检查是否存在指定 tableName 的表。如果不存在，它会创建此表（包含列 Key, Value, Binary_YN, ETag, Creation_Time, Update_Time, Expiration_time）。

每个状态条目由数据库表中的一条记录表示。请求中提供的 key 属性用于确定存储在 KEY 列中的对象名称。value 作为对象的内容存储。二进制内容以 Base64 编码文本存储。每个对象在创建或更新时都会分配一个唯一的 ETag 值。

例如，以下操作

curl -X POST http://localhost:3500/v1.0/state \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "nihilus",
          "value": "darth"
        }
      ]'

在表 STATE 中创建以下记录：

Dapr 使用固定的键方案和复合键来跨应用程序分区状态。对于一般状态，键格式为：App-ID||state key。Oracle 数据库状态存储将此键完整映射到 KEY 列。

您可以通过对 tableName 表（例如 STATE 表）进行 SQL 查询轻松检查所有存储的状态。

生存时间和状态过期

Oracle 数据库状态存储组件支持 Dapr 的生存时间逻辑，确保状态在过期后无法检索。有关详细信息，请参阅此处关于设置状态生存时间的指南。

Oracle 数据库本身不支持生存时间设置。此组件的实现使用名为 EXPIRATION_TIME 的列来保存记录被视为过期的时间。仅当在 Set 请求中指定了 TTL 时，才会设置此列中的值。它被计算为当前 UTC 时间戳加上 TTL 时间段。当通过 Get 调用检索状态时，此组件会检查是否设置了 EXPIRATION_TIME，如果是，则检查它是否在过去。在这种情况下，不会返回状态。

以下操作：

curl -X POST http://localhost:3500/v1.0/state \
  -H "Content-Type: application/json"
  -d '[
        {
          "key": "temporary",
          "value": "ephemeral",
          "metadata": {"ttlInSeconds": "120"}}
        }
      ]'

创建以下对象：