Dapr 文档库

AWS 认证

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 组件通过 AWS SDK 使用 AWS 服务（例如，DynamoDB、SQS、S3），并支持标准化的配置属性。了解更多关于 AWS SDK 如何处理凭证的信息。

您可以使用 AWS SDK 的默认提供者链，或者选择以下列出的预定义 AWS 认证配置文件之一来进行认证配置。通过测试和检查 Dapr 运行时日志来验证组件配置，确保正确初始化。

术语

ARN (Amazon Resource Name): 用于唯一标识 AWS 资源的标识符。格式为：arn:partition:service:region:account-id:resource。示例：arn:aws:iam::123456789012:role/example-role。
IAM (Identity and Access Management): AWS 提供的用于安全管理对 AWS 资源访问的服务。

认证配置文件

访问密钥 ID 和秘密访问密钥

使用静态访问密钥和秘密密钥凭证，可以通过组件元数据字段或通过默认 AWS 配置进行配置。

重要

在以下场景中，建议通过默认 AWS 配置加载凭证：

在 EKS（AWS Kubernetes）上运行 Dapr sidecar (daprd) 和您的应用程序。
使用附加了定义 AWS 资源访问的 IAM 策略的节点或 pod。

属性	必需	描述	示例
`region`	Y	要连接的 AWS 区域。	“us-east-1”
`accessKey`	N	AWS 访问密钥 ID。在 Dapr v1.17 中将是必需的。	“AKIAIOSFODNN7EXAMPLE”
`secretKey`	N	AWS 秘密访问密钥，与 `accessKey` 一起使用。在 Dapr v1.17 中将是必需的。	“wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY”
`sessionToken`	N	AWS 会话令牌，与 `accessKey` 和 `secretKey` 一起使用。对于 IAM 用户密钥通常不需要。

假设 IAM 角色

此配置文件允许 Dapr 假设特定的 IAM 角色。通常在 Dapr sidecar 在 EKS 或链接到 IAM 策略的节点/pod 上运行时使用。目前由 Kafka 和 PostgreSQL 组件支持。

安装 Dapr CLI

Mon, 01 Jan 0001 00:00:00 +0000

Dapr CLI 是执行各种 Dapr 相关任务的主要工具。您可以使用它来：

运行带有 Dapr 边车的应用程序。
查看边车日志。
列出正在运行的服务。
运行 Dapr 仪表板。

Dapr CLI 可在自托管和 Kubernetes 环境中使用。

开始之前

请在 Docker Desktop 的高级选项中确认已启用默认的 Docker socket。如果您在 Windows 上使用 WSL 集成，则此选项不可用。

步骤 1：安装 Dapr CLI

从终端安装

将最新的 Linux Dapr CLI 安装到 /usr/local/bin：

贡献概览

Mon, 01 Jan 0001 00:00:00 +0000

感谢您对Dapr项目的关注！本文档为您提供如何通过提交问题和拉取请求来为Dapr项目做出贡献的指南。您还可以通过其他方式参与，例如参加社区电话会议、对问题或拉取请求进行评论等。

有关社区参与和成员资格的更多信息，请参阅Dapr社区代码库。

Dapr代码库索引

以下是Dapr组织下的代码库列表，您可以在这些代码库中进行贡献：

文档：此代码库包含Dapr的文档。您可以通过更新现有文档、修复错误或添加新内容来改善用户体验和清晰度。请参阅文档贡献指南。
快速入门：快速入门代码库提供简单的分步指南，帮助用户快速上手Dapr。您可以通过创建新的快速入门、改进现有的快速入门或确保它们与最新功能保持同步来贡献。查看贡献指南。
运行时：Dapr运行时代码库包含核心运行时组件。您可以通过修复错误、优化性能、实现新功能或增强现有功能来贡献。
组件贡献：此代码库托管了Dapr的社区贡献组件集合。您可以通过添加新组件、改进现有组件或审查和测试社区的贡献来参与。
SDKs：Dapr SDKs为各种编程语言提供与Dapr交互的库。您可以通过改进SDK功能、修复错误或添加对新功能的支持来贡献。请参阅SDK贡献指南以获取特定SDK的详细信息。
CLI：Dapr CLI用于在本地开发机器或Kubernetes集群上设置Dapr以启动和管理Dapr实例。对CLI代码库的贡献包括添加新功能、修复错误、提高可用性，并确保与最新的Dapr版本兼容。请参阅开发指南以获取有关开发Dapr CLI的帮助。

问题

问题类型

在大多数Dapr代码库中，通常有4种类型的问题：

问题/错误：您发现了代码中的错误，并希望报告或创建一个问题来跟踪该错误。
问题/讨论：您有一些想法，需要在讨论中获得他人的意见，然后最终形成提案。
问题/提案：用于提出新想法或功能的项目。这允许在编写代码之前获得他人的反馈。
问题/问题：如果您需要帮助或有问题，请使用此问题类型。

提交之前

在提交问题之前，请确保您已检查以下内容：

这是正确的代码库吗？
- Dapr项目分布在多个代码库中。如果您不确定哪个代码库是正确的，请查看代码库列表。
检查现有问题
- 在创建新问题之前，请在开放问题中搜索，查看该问题或功能请求是否已被提交。
- 如果您发现您的问题已经存在，请进行相关评论并添加您的反应。使用反应：
  - 👍 赞成
  - 👎 反对
对于错误
- 检查这不是环境问题。例如，如果在Kubernetes上运行，请确保先决条件已到位。（state存储、bindings等）
- 您拥有尽可能多的数据。这通常以日志和/或堆栈跟踪的形式出现。如果在Kubernetes或其他环境中运行，请查看Dapr服务（运行时、operator、placement服务）的日志。有关如何获取日志的更多详细信息，请参阅此处。
对于提案
- 许多对Dapr运行时的更改可能需要对API进行更改。在这种情况下，讨论潜在功能的最佳地点是主要的Dapr代码库。
- 其他示例可能包括bindings、state存储或全新的组件。

拉取请求

所有贡献都通过拉取请求提交。要提交建议的更改，请遵循以下工作流程：

确保已提出问题（错误或提案），以设定您即将进行的贡献的期望。
分叉相关代码库并创建新分支
- 一些Dapr代码库支持Codespaces，为您提供即时环境以构建和测试您的更改。
- 有关设置Dapr开发环境的更多信息，请参阅开发Dapr文档。
创建您的更改
- 代码更改需要测试
更新相关文档以反映更改
使用DCO签署提交并打开PR
等待CI过程完成并确保所有检查通过
项目的维护者将被分配，您可以在几天内期待审查

使用草稿PR以获得早期反馈

在投入过多时间之前进行沟通的好方法是创建一个“草稿”PR并与您的审阅者分享。标准做法是在PR的标题中添加“[WIP]”前缀，并分配do-not-merge标签。这将让查看您PR的人知道它尚未成熟。

使用第三方代码

第三方代码必须包含许可证。

开发者来源证书：签署您的工作

每次提交都需要签署

开发者来源证书（DCO）是一种轻量级方式，供贡献者证明他们编写或以其他方式有权提交他们贡献给项目的代码。以下是DCO的完整文本，经过重新格式化以提高可读性：

通过对该项目进行贡献，我证明：
 (a) 该贡献完全或部分由我创建，并且我有权根据文件中指明的开源许可证提交它；或者
 (b) 该贡献基于我所知的适当开源许可证覆盖的先前工作，并且我有权根据该许可证提交该工作及其修改，无论是由我完全或部分创建的，均根据相同的开源许可证（除非我被允许根据不同的许可证提交），如文件中所示；或者
 (c) 该贡献是由其他人直接提供给我的，他们证明了(a)、(b)或(c)，而我没有修改它。
 (d) 我理解并同意该项目和贡献是公开的，并且贡献的记录（包括我提交的所有个人信息，包括我的签署）将被无限期地维护，并可能根据该项目或涉及的开源许可证进行再分发。

贡献者通过在提交消息中添加Signed-off-by行来签署他们遵守这些要求。

这是我的提交消息
Signed-off-by: Random J Developer <random@developer.example.org>

Git甚至有一个-s命令行选项，可以自动将其附加到您的提交消息中：

概念文章模板

Mon, 01 Jan 0001 00:00:00 +0000

贡献新的概念或概述文章

概念（或概述）文章旨在回答以下问题：

为什么这个功能对你很重要？
它能帮助你解决哪些问题？

尽管组件、API 或 SDK 规范可以帮助读者理解如何使用这些功能，概念文章则提供了更深入的背景和上下文。请链接到规范文章，但尽量避免简单重复规范内容。

在为你的概念文章命名时，确保其名称、参数和术语与规范保持一致。如有必要，请同时更新两者。

注意

此模板仅为建议。可以根据文档的目的进行调整。

了解更多关于为 Dapr 文档做贡献的信息，例如前置内容和短代码。

模板

---
type: #必填; docs
title: #必填; 简洁明了的标题
linkTitle: #必填; 简短标题
weight: #必填; 根据层级使用正确的权重
description: #必填; 对文章内容的简短描述
---

<!--
在打开 PR 之前，删除此模板中的所有注释。
-->

<!-- 
H1: Hugo 前置内容中的标题作为文章的 markdown H1。
-->

<!-- 简介段落 
必填。简要介绍文章将涵盖的概念。链接到适当的参考、规范或操作指南以提供上下文。 -->

<!-- 
如果可能，包含图表或图片。
-->

## <章节 1 H2>

<!-- 
在此添加你的内容。
-->

## <章节 2 H2>

<!-- 
每个 H2 步骤应以名词/描述性词语开头。
-->

## <章节 3 H2>

<!--
在此添加你的内容。
-->

<!--
在适用的地方，包含图表或图片。
-->

## 体验 <概念>

<!-- 
如果适用，包含一个部分，链接到相关的快速开始、操作指南或教程。
--> 

### 快速开始和教程

想要体验 Dapr <主题> API？通过以下快速开始和教程来了解 <主题> 的实际应用：

| 快速开始/教程 | 描述 |
| ------------------- | ----------- |
| [<主题> 快速开始](link) | 快速开始的描述。 |
| [<主题> 教程](link) | 教程的描述。 |

### 在你的应用中直接使用 <主题>

想跳过快速开始？没问题。你可以在你的应用中直接使用 <主题> 构建块。在[Dapr 安装完成](link)后，你可以开始使用 <主题> API，从[<主题> 操作指南](link)开始。

-->

## 下一步

<!--
链接到相关页面和示例。例如，相关的 API 规范，相关的构建块等。
-->

Actors 概述

Mon, 01 Jan 0001 00:00:00 +0000

Actor 模型将 actor 描述为“计算的基本单位”。换句话说，您可以将代码编写在一个自包含的单元中（称为 actor），该单元接收消息并一次处理一条消息，而无需任何形式的并发或线程。

当您的代码处理一条消息时，它可以向其他 actor 发送一条或多条消息，或创建新的 actor。底层运行时管理每个 actor 的运行方式、时间和位置，并在 actor 之间路由消息。

大量的 actor 可以同时执行，并且 actor 彼此独立执行。

Dapr 中的 Actor 模型

Dapr 包含一个专门实现虚拟 Actor 模型的运行时。通过 Dapr 的实现，您可以根据 Actor 模型编写 Dapr actor，Dapr 利用底层平台提供的可扩展性和可靠性保证。

每个 actor 都被定义为 actor 类型的一个实例，与对象是类的一个实例相同。例如，可能有一个实现计算器功能的 actor 类型，并且可能有许多此类型的 actor 分布在集群的各个节点上。每个这样的 actor 都由一个 actor ID 唯一标识。

以下概述视频和演示展示了 Dapr 中的 actor 如何工作。

Dapr Actors 与 Dapr Workflow

Dapr actors 基于状态管理和服务调用 API 创建具有身份的有状态、长时间运行的对象。Dapr Workflow 和 Dapr Actors 是相关的，workflow 基于 actor 提供更高层次的抽象来编排一组 actor，实现常见的 workflow 模式并代表您管理 actor 的生命周期。

服务调用概述

Mon, 01 Jan 0001 00:00:00 +0000

通过服务调用，您的应用程序可以使用标准的gRPC或HTTP协议可靠且安全地与其他应用程序进行通信。

在许多基于微服务的应用程序中，多个服务需要能够相互通信。这种服务间通信要求应用程序开发人员处理以下问题：

服务发现。 如何找到我的不同服务？
标准化服务间的API调用。 如何在服务之间调用方法？
安全的服务间通信。 如何通过加密安全地调用其他服务并对方法应用访问控制？
缓解请求超时或失败。 如何处理重试和瞬态错误？
实现可观测性和追踪。 如何使用追踪查看带有指标的调用图以诊断生产中的问题？

服务调用API

Dapr通过提供一个类似反向代理的服务调用API来解决这些挑战，该API内置了服务发现，并利用了分布式追踪、指标、错误处理、加密等功能。

Dapr采用sidecar架构。要使用Dapr调用应用程序：

您在Dapr实例上使用invoke API。
每个应用程序与其自己的Dapr实例通信。
Dapr实例相互发现并通信。

以下概述视频和演示展示了Dapr服务调用的工作原理。

下图概述了Dapr的服务调用在两个集成Dapr的应用程序之间的工作原理。

服务A发起一个HTTP或gRPC调用，目标是服务B。调用发送到本地Dapr sidecar。
Dapr使用正在运行的名称解析组件在给定的托管平台上发现服务B的位置。
Dapr将消息转发到服务B的Dapr sidecar
- 注意：所有Dapr sidecar之间的调用都通过gRPC进行以提高性能。只有服务与Dapr sidecar之间的调用可以是HTTP或gRPC。
服务B的Dapr sidecar将请求转发到服务B上的指定端点（或方法）。服务B然后运行其业务逻辑代码。
服务B向服务A发送响应。响应发送到服务B的sidecar。
Dapr将响应转发到服务A的Dapr sidecar。
服务A接收响应。

您还可以使用服务调用API调用非Dapr HTTP端点。例如，您可能只在整个应用程序的一部分中使用Dapr，可能无法访问代码以迁移现有应用程序以使用Dapr，或者只是需要调用外部HTTP服务。阅读“如何：使用HTTP调用非Dapr端点”以获取更多信息。

功能

服务调用提供了多种功能，使您可以轻松地在应用程序之间调用方法或调用外部HTTP端点。

HTTP和gRPC服务调用

HTTP：如果您已经在应用程序中使用HTTP协议，使用Dapr HTTP头可能是最简单的入门方式。您无需更改现有的端点URL；只需添加dapr-app-id头即可开始。有关更多信息，请参阅使用HTTP调用服务。
gRPC：Dapr允许用户保留自己的proto服务并以gRPC的方式工作。这意味着您可以使用服务调用来调用现有的gRPC应用程序，而无需包含任何Dapr SDK或自定义gRPC服务。有关更多信息，请参阅Dapr和gRPC的操作教程。

服务到服务的安全性

通过Dapr Sentry服务，所有Dapr应用程序之间的调用都可以通过托管平台上的相互（mTLS）认证来实现安全，包括自动证书轮换。

有关更多信息，请阅读服务到服务的安全性文章。

包括重试的弹性

在调用失败和瞬态错误的情况下，服务调用提供了一种弹性功能，可以在回退时间段内自动重试。要了解更多信息，请参阅弹性文章。

具有可观测性的追踪和指标

默认情况下，所有应用程序之间的调用都会被追踪，并收集指标以提供应用程序的洞察和诊断。这在生产场景中特别重要，提供了服务之间调用的调用图和指标。有关更多信息，请阅读可观测性。

访问控制

通过访问策略，应用程序可以控制：

哪些应用程序被允许调用它们。
应用程序被授权做什么。

例如，您可以限制包含人员信息的敏感应用程序不被未授权的应用程序访问。结合服务到服务的安全通信，您可以提供软多租户部署。

有关更多信息，请阅读服务调用的访问控制允许列表文章。

命名空间范围

您可以将应用程序限定到命名空间以进行部署和安全，并在部署到不同命名空间的服务之间进行调用。有关更多信息，请阅读跨命名空间的服务调用文章。

使用mDNS的轮询负载均衡

Dapr通过mDNS协议提供服务调用请求的轮询负载均衡，例如在单台机器或多台联网的物理机器上。

错误概述

Mon, 01 Jan 0001 00:00:00 +0000

错误代码是用于指示错误性质的数字或字母数字代码，并在可能的情况下，说明其发生的原因。

Dapr 错误代码是标准化的字符串，适用于 Dapr API 中 HTTP 和 gRPC 请求的 80 多种常见错误。这些代码会：

在请求的 JSON 响应体中返回。
启用后，会在运行时的调试级别日志中记录。
- 如果您在 Kubernetes 中运行，错误代码会记录在 sidecar 中。
- 如果您在自托管中运行，可以启用并查看调试日志。

错误格式

Dapr 错误代码由前缀、类别和错误本身的简写组成。例如：

前缀	类别	错误简写
ERR_	PUBSUB_	NOT_FOUND

一些最常见的返回错误包括：

ERR_ACTOR_TIMER_CREATE
ERR_PURGE_WORKFLOW
ERR_STATE_STORE_NOT_FOUND
ERR_HEALTH_NOT_READY

注意： 查看 Dapr 中错误代码的完整列表。

对于未找到的状态存储返回的错误可能如下所示：

{
 "error": "Bad Request",
 "error_msg": "{\"errorCode\":\"ERR_STATE_STORE_NOT_FOUND\",\"message\":\"state store <name> is not found\",\"details\":[{\"@type\":\"type.googleapis.com/google.rpc.ErrorInfo\",\"domain\":\"dapr.io\",\"metadata\":{\"appID\":\"nodeapp\"},\"reason\":\"DAPR_STATE_NOT_FOUND\"}]}",
 "status": 400
}

返回的错误包括：

错误代码：ERR_STATE_STORE_NOT_FOUND
描述问题的错误消息：state store <name> is not found
发生错误的应用程序 ID：nodeapp
错误的原因：DAPR_STATE_NOT_FOUND

Dapr 错误代码指标

指标帮助您查看错误在运行时发生的具体时间。错误代码指标通过 error_code_total 端点收集。此端点默认情况下是禁用的。您可以通过配置文件中的 recordErrorCodes 字段启用它。

分布式追踪概述

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 通过 Open Telemetry (OTEL) 和 Zipkin 协议来实现分布式追踪。OTEL 是行业标准，并且是推荐使用的追踪协议。

大多数可观测性工具支持 OTEL，包括：

下图展示了 Dapr（使用 OTEL 和 Zipkin 协议）如何与多个可观测性工具集成。

场景

追踪用于服务调用和发布/订阅（pubsub）API。您可以在使用这些 API 的服务之间传递追踪上下文。追踪的使用有两种场景：

Dapr 生成追踪上下文，您将追踪上下文传递到另一个服务。
您生成追踪上下文，Dapr 将追踪上下文传递到服务。

场景 1：Dapr 生成追踪上下文头

顺序服务调用的传递

Dapr 负责创建追踪头。然而，当有两个以上的服务时，您需要负责在它们之间传递追踪头。让我们通过示例来了解这些场景：

单一服务调用

例如，服务 A -> 服务 B。

Dapr 在 服务 A 中生成追踪头，然后从 服务 A 传递到 服务 B。不需要进一步的传递。

多个顺序服务调用

例如，服务 A -> 服务 B -> 传递追踪头到 -> 服务 C，以及其他启用 Dapr 的服务。

Dapr 命令行界面 (CLI) 参考

Mon, 01 Jan 0001 00:00:00 +0000

Dapr CLI 使您能够在本地开发环境或 Kubernetes 集群上配置 Dapr，提供调试支持，并启动和管理 Dapr 实例。


 __
 ____/ /___ _____ _____
 / __ / __ '/ __ \/ ___/
 / /_/ / /_/ / /_/ / /
 \__,_/\__,_/ .___/_/
 /_/

===============================
分布式应用运行时

用法:
 dapr [命令]

可用命令:
 annotate 为 Kubernetes 配置添加 Dapr 注释。适用平台：Kubernetes
 build-info 显示 Dapr CLI 和运行时的构建信息
 completion 生成 shell 自动补全脚本
 components 列出所有 Dapr 组件。适用平台：Kubernetes
 configurations 列出所有 Dapr 配置。适用平台：Kubernetes
 dashboard 启动 Dapr 仪表板。适用平台：Kubernetes 和 本地托管
 help 获取任何命令的帮助信息
 init 在支持的平台上安装 Dapr。适用平台：Kubernetes 和 本地托管
 invoke 调用指定 Dapr 应用程序上的方法。适用平台：本地托管
 list 列出所有 Dapr 实例。适用平台：Kubernetes 和 本地托管
 logs 获取应用程序的 Dapr sidecar 日志。适用平台：Kubernetes
 mtls 检查 mTLS 是否已启用。适用平台：Kubernetes
 publish 发布一个 pubsub 事件。适用平台：本地托管
 run 运行 Dapr 并可选择与您的应用程序一起运行。适用平台：本地托管
 status 显示 Dapr 服务的健康状态。适用平台：Kubernetes
 stop 停止 Dapr 实例及其关联的应用程序。适用平台：本地托管
 uninstall 卸载 Dapr 运行时。适用平台：Kubernetes 和 本地托管
 upgrade 升级集群中的 Dapr 控制平面安装。适用平台：Kubernetes
 version 显示 Dapr 运行时和 CLI 的版本信息

标志:
 -h, --help 获取 dapr 的帮助信息
 --log-as-json 以 JSON 格式记录输出
 -v, --version 获取 dapr 的版本信息

使用 "dapr [command] --help" 获取有关命令的更多信息。

命令参考

您可以通过以下链接了解每个 Dapr 命令的详细信息。

贡献者指南

Mon, 01 Jan 0001 00:00:00 +0000

在本指南中，您将学习如何为 Dapr 文档库做出贡献。由于 Dapr 文档发布在 docs.dapr.io，您需要确保您的贡献能够正确编译和发布。

先决条件

在为 Dapr 文档做贡献之前：

查看关于 Dapr 项目贡献的一般指导。
使用 Hugo 和 Docsy 主题安装并设置您的本地环境。请按照库中的 README.md 中的说明进行操作。
分叉并克隆文档库。

分支指导

Dapr 文档的分支管理与大多数代码库不同。没有主分支，每个分支都与运行时发布的主要和次要版本相匹配。完整列表请访问 Docs repo。

通常，您所有的文档更新都应提交到 Dapr 最新版本的文档分支。最新版本是默认分支 [https://github.com/dapr/docs]。例如，如果您正在修复拼写错误、添加注释或澄清某个点，请将您的更改提交到默认的 Dapr 分支。

对于适用于候选发布或预发布版本的文档更改，请将您的更改指向该特定分支。例如，如果您正在记录即将对组件或运行时的更改，请将您的更改提交到预发布分支。

风格和语气

在所有 Dapr 文档中应遵循风格和语气惯例，以确保所有文档的一致性：

风格/语气	指导
大小写	仅在以下情况下使用大写：句子或标题的开头专有名词，包括技术名称（Dapr、Redis、Kubernetes 等）
标题和标题	标题和标题必须简洁，但描述性和清晰。
使用简单句子	写出易于阅读、可扫描的句子。提示：跳过正式语气，像直接与读者交谈一样写作。
避免使用第一人称	代替第一人称 “I”、“we” 和 “our”，使用第二人称 “you” 和 “your”。
假设 “新开发者” 受众	对于经验丰富的开发者来说一些看似显而易见的步骤可能对新开发者并不那么明显。为读者提供更明确、详尽的说明。
使用现在时	避免使用诸如 “this command will install Redis” 的句子。相反，使用 “This command installs Redis”。

图表和图像

图表和图像是文档页面中无价的视觉辅助工具。使用 Dapr 图表模板套件中的图表样式和图标。

W3C 跟踪上下文概述

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 采用 Open Telemetry 协议，该协议利用 W3C 跟踪上下文来实现服务调用和发布/订阅消息的分布式跟踪。Dapr 生成并传播跟踪上下文信息，可以将其发送到可观测性工具进行可视化和查询。

背景

分布式跟踪是一种由跟踪工具实现的方法，用于跟踪、分析和调试跨多个软件组件的事务。

通常，分布式跟踪会跨越多个服务，因此需要一个唯一的标识符来标识每个事务。跟踪上下文传播就是传递这种唯一标识符的过程。

过去，不同的跟踪供应商各自实现自己的跟踪上下文传播方式。在多供应商环境中，这会导致互操作性的问题，例如：

不同供应商收集的跟踪数据无法关联，因为没有共享的唯一标识符。
跨越不同供应商边界的跟踪无法传播，因为没有统一的标识符集。
中间商可能会丢弃供应商特定的元数据。
云平台供应商、中间商和服务提供商无法保证支持跟踪上下文传播，因为没有标准可循。

以前，大多数应用程序由单一的跟踪供应商监控，并保持在单一平台提供商的边界内，因此这些问题没有显著影响。

如今，越来越多的应用程序是分布式的，并利用多个中间件服务和云平台。这种现代应用程序的转变需要一个分布式跟踪上下文传播标准。

W3C 跟踪上下文规范定义了一种通用格式，用于交换跟踪上下文数据（称为跟踪上下文）。通过提供以下内容，跟踪上下文解决了上述问题：

为单个跟踪和请求提供唯一标识符，允许将多个供应商的跟踪数据链接在一起。
提供一种机制来转发供应商特定的跟踪数据，避免在单个事务中多个跟踪工具参与时出现断裂的跟踪。
一个中间商、平台和硬件供应商可以支持的行业标准。

这种统一的跟踪数据传播方法提高了对分布式应用程序行为的可见性，促进了问题和性能分析。

W3C 跟踪上下文和头格式

W3C 跟踪上下文

Dapr 使用标准的 W3C 跟踪上下文头。

对于 HTTP 请求，Dapr 使用 traceparent 头。
对于 gRPC 请求，Dapr 使用 grpc-trace-bin 头。

当请求到达时没有跟踪 ID，Dapr 会创建一个新的。否则，它会沿调用链传递跟踪 ID。

W3C 跟踪头

这些是 Dapr 为 HTTP 和 gRPC 生成和传播的特定跟踪上下文头。

在从 HTTP 响应传播跟踪上下文头到 HTTP 请求时复制这些头：

在本地环境中配置 Dapr

Mon, 01 Jan 0001 00:00:00 +0000

现在您已经安装了 Dapr CLI，可以使用 CLI 在本地计算机上配置 Dapr。

Dapr 作为一个附属进程与您的应用程序一起运行。在自托管模式下，这意味着它在您的本地计算机上作为一个进程运行。通过配置 Dapr，您可以：

获取并在本地安装 Dapr sidecar 的二进制文件。
创建一个简化应用程序开发的环境。

Dapr 的配置过程包括：

启动一个 Redis 容器实例 作为本地状态存储和消息代理。
启动一个 Zipkin 容器实例 以实现可观测性。
创建一个包含上述组件定义的 默认组件文件夹。
启动一个 Dapr placement service 容器实例 以支持本地 actor。
启动一个 Dapr scheduler service 容器实例 以进行任务调度。

Kubernetes 开发环境

要在本地或远程 Kubernetes 集群中配置 Dapr 进行开发（包括上面列出的 Redis 和 Zipkin 容器），请参阅如何在 Kubernetes 上配置 Dapr 进行开发

Docker

推荐的开发环境需要 Docker。虽然您可以在没有 Docker 依赖的情况下配置 Dapr，但本指南的下一步假设您使用推荐的 Docker 开发环境。

您也可以安装 Podman 代替 Docker。阅读更多关于使用 Podman 配置 Dapr的信息。

步骤 1：打开具有管理员权限的终端

如果您在运行 Docker 命令时使用 sudo，或者安装路径是 /usr/local/bin（默认安装路径），则需要在此快速入门中使用 sudo。

错误代码参考指南

Mon, 01 Jan 0001 00:00:00 +0000

以下表格列出了 Dapr 运行时返回的错误代码。错误代码会在 HTTP 请求的响应体中或 gRPC 状态响应的 ErrorInfo 部分返回（如果存在）。我们正在努力根据更丰富的错误模型来改进所有 gRPC 错误响应。没有对应 gRPC 代码的错误代码表示这些错误尚未更新到此模型。

演员 API

HTTP 代码	gRPC 代码	描述
`ERR_ACTOR_INSTANCE_MISSING`		缺少演员实例
`ERR_ACTOR_INVOKE_METHOD`		调用演员方法时发生错误
`ERR_ACTOR_RUNTIME_NOT_FOUND`		找不到演员运行时
`ERR_ACTOR_STATE_GET`		获取演员状态时发生错误
`ERR_ACTOR_STATE_TRANSACTION_SAVE`		保存演员事务时发生错误
`ERR_ACTOR_REMINDER_CREATE`		创建演员提醒时发生错误
`ERR_ACTOR_REMINDER_DELETE`		删除演员提醒时发生错误
`ERR_ACTOR_REMINDER_GET`		获取演员提醒时发生错误
`ERR_ACTOR_REMINDER_NON_HOSTED`		非托管演员类型的提醒操作
`ERR_ACTOR_TIMER_CREATE`		创建演员计时器时发生错误
`ERR_ACTOR_NO_APP_CHANNEL`		应用通道未初始化
`ERR_ACTOR_STACK_DEPTH`		超过演员调用堆栈的最大深度
`ERR_ACTOR_NO_PLACEMENT`		未配置放置服务
`ERR_ACTOR_RUNTIME_CLOSED`		演员运行时已关闭
`ERR_ACTOR_NAMESPACE_REQUIRED`		在 Kubernetes 模式下运行时，演员必须配置命名空间
`ERR_ACTOR_NO_ADDRESS`		找不到演员的地址

工作流 API

HTTP 代码	gRPC 代码	描述
`ERR_GET_WORKFLOW`		获取工作流时发生错误
`ERR_START_WORKFLOW`		启动工作流时发生错误
`ERR_PAUSE_WORKFLOW`		暂停工作流时发生错误
`ERR_RESUME_WORKFLOW`		恢复工作流时发生错误
`ERR_TERMINATE_WORKFLOW`		终止工作流时发生错误
`ERR_PURGE_WORKFLOW`		清除工作流时发生错误
`ERR_RAISE_EVENT_WORKFLOW`		在工作流中引发事件时发生错误
`ERR_WORKFLOW_COMPONENT_MISSING`		缺少工作流组件
`ERR_WORKFLOW_COMPONENT_NOT_FOUND`		找不到工作流组件
`ERR_WORKFLOW_EVENT_NAME_MISSING`		缺少工作流事件名称
`ERR_WORKFLOW_NAME_MISSING`		未配置工作流名称
`ERR_INSTANCE_ID_INVALID`		无效的工作流实例 ID。（仅允许字母数字和下划线字符）
`ERR_INSTANCE_ID_NOT_FOUND`		找不到工作流实例 ID
`ERR_INSTANCE_ID_PROVIDED_MISSING`		缺少工作流实例 ID
`ERR_INSTANCE_ID_TOO_LONG`		工作流实例 ID 过长

状态管理 API

HTTP 代码	gRPC 代码	描述
`ERR_STATE_TRANSACTION`		状态事务出错
`ERR_STATE_SAVE`		保存状态时出错
`ERR_STATE_GET`		获取状态时出错
`ERR_STATE_DELETE`		删除状态时出错
`ERR_STATE_BULK_DELETE`		批量删除状态时出错
`ERR_STATE_BULK_GET`		批量获取状态时出错
`ERR_NOT_SUPPORTED_STATE_OPERATION`		事务中不支持的操作
`ERR_STATE_QUERY`	`DAPR_STATE_QUERY_FAILED`	查询状态时出错
`ERR_STATE_STORE_NOT_FOUND`	`DAPR_STATE_NOT_FOUND`	找不到状态存储
`ERR_STATE_STORE_NOT_CONFIGURED`	`DAPR_STATE_NOT_CONFIGURED`	未配置状态存储
`ERR_STATE_STORE_NOT_SUPPORTED`	`DAPR_STATE_TRANSACTIONS_NOT_SUPPORTED`	状态存储不支持事务
`ERR_STATE_STORE_NOT_SUPPORTED`	`DAPR_STATE_QUERYING_NOT_SUPPORTED`	状态存储不支持查询
`ERR_STATE_STORE_TOO_MANY_TRANSACTIONS`	`DAPR_STATE_TOO_MANY_TRANSACTIONS`	每个事务的操作过多
`ERR_MALFORMED_REQUEST`	`DAPR_STATE_ILLEGAL_KEY`	无效的键

配置 API

HTTP 代码	gRPC 代码	描述
`ERR_CONFIGURATION_GET`		获取配置时出错
`ERR_CONFIGURATION_STORE_NOT_CONFIGURED`		未配置配置存储
`ERR_CONFIGURATION_STORE_NOT_FOUND`		找不到配置存储
`ERR_CONFIGURATION_SUBSCRIBE`		订阅配置时出错
`ERR_CONFIGURATION_UNSUBSCRIBE`		取消订阅配置时出错

加密 API

HTTP 代码	gRPC 代码	描述
`ERR_CRYPTO`		加密操作出错
`ERR_CRYPTO_KEY`		检索加密密钥时出错
`ERR_CRYPTO_PROVIDER_NOT_FOUND`		找不到加密提供者
`ERR_CRYPTO_PROVIDERS_NOT_CONFIGURED`		未配置加密提供者

密钥管理 API

HTTP 代码	gRPC 代码	描述
`ERR_SECRET_GET`		获取密钥时出错
`ERR_SECRET_STORE_NOT_FOUND`		找不到密钥存储
`ERR_SECRET_STORES_NOT_CONFIGURED`		未配置密钥存储
`ERR_PERMISSION_DENIED`		策略拒绝权限

发布/订阅和消息传递错误

HTTP 代码	gRPC 代码	描述
`ERR_PUBSUB_EMPTY`	`DAPR_PUBSUB_NAME_EMPTY`	发布/订阅名称为空
`ERR_PUBSUB_NOT_FOUND`	`DAPR_PUBSUB_NOT_FOUND`	找不到发布/订阅
`ERR_PUBSUB_NOT_FOUND`	`DAPR_PUBSUB_TEST_NOT_FOUND`	找不到发布/订阅
`ERR_PUBSUB_NOT_CONFIGURED`	`DAPR_PUBSUB_NOT_CONFIGURED`	未配置发布/订阅
`ERR_TOPIC_NAME_EMPTY`	`DAPR_PUBSUB_TOPIC_NAME_EMPTY`	主题名称为空
`ERR_PUBSUB_FORBIDDEN`	`DAPR_PUBSUB_FORBIDDEN`	禁止访问主题的应用 ID
`ERR_PUBSUB_PUBLISH_MESSAGE`	`DAPR_PUBSUB_PUBLISH_MESSAGE`	发布消息时出错
`ERR_PUBSUB_REQUEST_METADATA`	`DAPR_PUBSUB_METADATA_DESERIALIZATION`	反序列化元数据时出错
`ERR_PUBSUB_CLOUD_EVENTS_SER`	`DAPR_PUBSUB_CLOUD_EVENT_CREATION`	创建 CloudEvent 时出错
`ERR_PUBSUB_EVENTS_SER`	`DAPR_PUBSUB_MARSHAL_ENVELOPE`	编组 Cloud Event 信封时出错
`ERR_PUBSUB_EVENTS_SER`	`DAPR_PUBSUB_MARSHAL_EVENTS`	将事件编组为字节时出错
`ERR_PUBSUB_EVENTS_SER`	`DAPR_PUBSUB_UNMARSHAL_EVENTS`	解组事件时出错
`ERR_PUBLISH_OUTBOX`		将消息发布到 outbox 时出错

对话 API

HTTP 代码	gRPC 代码	描述
`ERR_CONVERSATION_INVALID_PARMS`		对话组件的参数无效
`ERR_CONVERSATION_INVOKE`		调用对话时出错
`ERR_CONVERSATION_MISSING_INPUTS`		对话缺少输入
`ERR_CONVERSATION_NOT_FOUND`		找不到对话

服务调用 / 直接消息传递 API

HTTP 代码	gRPC 代码	描述
`ERR_DIRECT_INVOKE`		调用服务时出错

绑定 API

HTTP 代码	gRPC 代码	描述
`ERR_INVOKE_OUTPUT_BINDING`		调用输出绑定时出错

分布式锁 API

HTTP 代码	gRPC 代码	描述
`ERR_LOCK_STORE_NOT_CONFIGURED`		未配置锁存储
`ERR_LOCK_STORE_NOT_FOUND`		找不到锁存储
`ERR_TRY_LOCK`		获取锁时出错
`ERR_UNLOCK`		释放锁时出错

健康检查

HTTP 代码	gRPC 代码	描述
`ERR_HEALTH_NOT_READY`		Dapr 未准备好
`ERR_HEALTH_APPID_NOT_MATCH`		Dapr 应用 ID 不匹配
`ERR_OUTBOUND_HEALTH_NOT_READY`		Dapr 出站未准备好

通用

HTTP 代码	gRPC 代码	描述
`ERR_API_UNIMPLEMENTED`		API 未实现
`ERR_APP_CHANNEL_NIL`		应用通道为 nil
`ERR_BAD_REQUEST`		错误请求
`ERR_BODY_READ`		读取请求体时出错
`ERR_INTERNAL`		内部错误
`ERR_MALFORMED_REQUEST`		请求格式错误
`ERR_MALFORMED_REQUEST_DATA`		请求数据格式错误
`ERR_MALFORMED_RESPONSE`		响应格式错误

调度/作业 API

HTTP 代码	gRPC 代码	描述
`DAPR_SCHEDULER_SCHEDULE_JOB`	`DAPR_SCHEDULER_SCHEDULE_JOB`	调度作业时出错
`DAPR_SCHEDULER_JOB_NAME`	`DAPR_SCHEDULER_JOB_NAME`	作业名称应仅在 URL 中设置
`DAPR_SCHEDULER_JOB_NAME_EMPTY`	`DAPR_SCHEDULER_JOB_NAME_EMPTY`	作业名称为空
`DAPR_SCHEDULER_GET_JOB`	`DAPR_SCHEDULER_GET_JOB`	获取作业时出错
`DAPR_SCHEDULER_LIST_JOBS`	`DAPR_SCHEDULER_LIST_JOBS`	列出作业时出错
`DAPR_SCHEDULER_DELETE_JOB`	`DAPR_SCHEDULER_DELETE_JOB`	删除作业时出错
`DAPR_SCHEDULER_EMPTY`	`DAPR_SCHEDULER_EMPTY`	必需的参数为空
`DAPR_SCHEDULER_SCHEDULE_EMPTY`	`DAPR_SCHEDULER_SCHEDULE_EMPTY`	未提供作业的调度

通用

HTTP 代码	gRPC 代码	描述
`ERROR`	`ERROR`	通用错误

下一步

操作指南：使用HTTP调用服务

Mon, 01 Jan 0001 00:00:00 +0000

本文演示了如何部署服务，每个服务都有一个唯一的应用程序ID，以便其他服务可以通过HTTP进行服务调用来发现并调用它们的端点。

注意

如果您还没有尝试过，请先查看服务调用快速入门，以快速了解如何使用服务调用API。

为服务选择一个ID

Dapr允许您为应用程序分配一个全局唯一的ID。无论应用程序有多少实例，该ID都代表应用程序的状态。

dapr run --app-id checkout --app-protocol http --dapr-http-port 3500 -- python3 checkout/app.py

dapr run --app-id order-processor --app-port 8001 --app-protocol http --dapr-http-port 3501 -- python3 order-processor/app.py

如果您的应用程序使用TLS，您可以通过设置--app-protocol https来告诉Dapr通过TLS连接调用您的应用程序：

快速入门指南模板

Mon, 01 Jan 0001 00:00:00 +0000

贡献新的快速入门指南

Dapr 快速入门指南包含一些简明的指令，帮助读者完成一个预先准备好的快速入门项目，这些项目保存在 dapr/quickstarts 仓库中。这些快速入门将整个功能或构建块集中在一起，使读者能够轻松体验其工作原理，而不影响他们自己的项目。

快速入门指令应当简洁明了。快速入门指南的唯一目的是简单地指导读者完成准备好的快速入门。如果您想解释快速入门背后的概念，请将读者引导到相关的概念文章以获取更多背景信息。

注意

此模板仅为建议。可以根据文档的具体需求进行调整。

了解更多关于如何贡献 Dapr 文档的信息，例如前置内容和短代码。

模板

---
type: #必填; docs
title: #必填; "快速入门：简洁明了的标题"
linkTitle: #必填; 这将在文档目录中显示
weight: #必填; 根据层级使用正确的权重
description: #必填; 一句话描述文章的预期内容
---

<!--
在提交 PR 之前，删除此模板中的所有注释。
-->

<!-- 
H1：Hugo 前置内容中的标题作为文章的 markdown H1。
-->

<!-- 引言段落 
必填。简要介绍快速入门将涵盖的内容。链接到适当的概念或概述文档以提供背景。 -->

<!-- 
如果可能，包含一个图表或图像。
-->

<!-- 
确保快速入门包含多个编程语言的示例。
-->

## 前置条件

<!--
列出读者在开始快速入门之前可能需要准备的内容，以确保顺利完成。
-->

## 步骤 1：设置环境

<!-- 
提供快速入门示例的链接，供读者克隆。
-->

## 步骤 2：<操作或任务>

<!-- 
每个 H2 步骤应以动词/动作词开头。
-->

<!--
尽可能包含代码片段。
-->

## 告诉我们您的想法！

我们正在不断努力改进我们的快速入门示例，并重视您的反馈。您觉得这个快速入门有帮助吗？您有改进建议吗？

欢迎加入我们的 [discord 频道](https://discord.gg/22ZtJrNe)进行讨论。

<!-- 由于 Dapr 是一个开放的贡献者社区，请确保提供 discord 讨论的链接以欢迎反馈。
-->

## 下一步

<!--
链接到相关页面和示例。例如，构建块概述，SDK 快速入门示例的 HTTP 版本等。
-->

<!--
使用按钮短代码将读者引导到更深入的相关场景，例如 Dapr 教程。
-->

维护者指南

Mon, 01 Jan 0001 00:00:00 +0000

在本指南中，您将学习如何履行 Dapr 文档维护者和审批者的日常职责。要成功完成这些任务，您需要在 dapr/docs 仓库中拥有审批者或维护者的权限。

如果您想了解如何为 Dapr 文档做出贡献，请查看贡献者指南。

分支管理指南

Dapr 文档的分支管理与大多数代码仓库不同。没有 main 分支，每个分支都与运行时发布的主要和次要版本相对应。

完整的分支列表请访问文档仓库。

阅读贡献者指南以获取有关发布分支的更多信息。

从当前发布分支合并到预发布分支

作为文档审批者或维护者，您需要定期进行合并操作，以确保预发布分支与当前发布分支保持同步。建议每周将当前分支的更新合并到预发布分支。

以下步骤中，将 v1.0 视为当前发布版本，将 v1.1 视为即将发布版本。

在 Visual Studio Code 中打开 Dapr 文档仓库。
在本地仓库中，切换到最新分支 (v1.0) 并同步更改：
```
git pull upstream v1.0
git push origin v1.0
```
切换到即将发布的分支 (v1.1) 并同步更改：
```
git pull upstream v1.1
git push origin v1.1
```
基于即将发布的版本创建一个新分支：
```
git checkout -b upmerge_MM-DD
```
在终端中，从最新发布分支合并到新建的合并分支：
```
git merge --no-ff --no-commit v1.0
```
在终端中，确保合并的文件准确无误。在 VS Code 中检查是否有合并冲突。删除不需要合并的配置更改或版本信息。

Dapr 演讲指南

Mon, 01 Jan 0001 00:00:00 +0000

我们欢迎社区成员分享关于 Dapr 的演讲，并推广 Dapr 的各种强大功能！我们提供了一个 PowerPoint 模板文件，帮助您快速开始。

下载 Dapr 演示文稿

如果您在 MacOS 上使用 PowerPoint 模板，请安装 Space Grotesk 字体以确保文本正确显示：

brew install --cask font-space-grotesk

如何进行 Dapr 演讲

首先下载 Dapr 演示文稿，其中包含您进行 Dapr 演讲所需的幻灯片和图表。
接下来，查看文档以确保您理解概念。
使用 Dapr 快速入门和示例仓库，展示如何使用 Dapr。

过往的 Dapr 演讲

演讲	录音	幻灯片
在 Kubernetes 中运行事件驱动的 Pub/Sub 微服务与 Dapr	链接	N/A
Ignite 2019: Mark Russinovich 展示云原生应用的未来	链接	链接
Azure Community Live: 使用 DAPR 构建微服务应用与 Mark Fussell	链接	N/A
Ready 2020: Mark Russinovich 展示云原生应用	链接	链接
Ignite 2021: Mark Russinovich 发布 Dapr v1.0	链接	N/A

其他资源

在社区仓库中可以找到更多 Dapr 资源。

Actor 的运行时特性

Mon, 01 Jan 0001 00:00:00 +0000

在您已经从高层次上了解了 Actor 构建块之后，让我们深入探讨 Dapr 中 Actor 的特性和概念。

Actor 的生命周期

Dapr 中的 Actor 是虚拟的，这意味着它们的生命周期与内存中的表示无关。因此，不需要显式地创建或销毁它们。Dapr 的 Actor 运行时会在首次收到某个 Actor ID 的请求时自动激活该 Actor。如果某个 Actor 在一段时间内未被使用，Dapr 的 Actor 运行时会对其进行垃圾回收，但会保留其存在的信息，以便在需要时重新激活。

调用 Actor 方法、定时器和提醒会重置 Actor 的空闲时间。例如，提醒的触发会保持 Actor 的活跃状态。

Actor 的提醒会在无论其活跃与否的情况下触发。如果提醒触发了一个不活跃的 Actor，它会先激活该 Actor。
Actor 的定时器触发会重置空闲时间；然而，定时器仅在 Actor 活跃时触发。

Dapr 运行时用于判断 Actor 是否可以被垃圾回收的空闲超时和扫描间隔是可配置的。当 Dapr 运行时调用 Actor 服务以获取支持的 Actor 类型时，可以传递此信息。

这种虚拟 Actor 生命周期的抽象带来了一些注意事项，尽管 Dapr 的 Actor 实现有时会偏离这种模型。

Actor 在首次向其 Actor ID 发送消息时会自动激活（即构建 Actor 对象）。经过一段时间后，Actor 对象会被垃圾回收。将来再次使用该 Actor ID 会导致构建新的 Actor 对象。Actor 的状态超越对象的生命周期，因为状态存储在为 Dapr 运行时配置的状态提供者中。

处理 HTTP 错误代码

Mon, 01 Jan 0001 00:00:00 +0000

在向 Dapr 运行时发出的 HTTP 调用中，如果发生错误，响应体会返回一个错误的 JSON。该 JSON 包含错误代码和描述性错误信息。

{
 "errorCode": "ERR_STATE_GET",
 "message": "请求的状态键在状态存储中不存在。"
}

操作指南模板

Mon, 01 Jan 0001 00:00:00 +0000

贡献新的操作指南

操作指南为读者提供逐步的实用指导，帮助他们实现以下目标：

启用某个功能
集成某项技术
在特定场景中使用 Dapr

操作指南相较于快速入门，是更高级别的自助文档。操作场景通常需要更长的时间，并且更容易应用于读者的个人项目或环境。

命名操作文档时，应在文件名中包含子目录名称。如果需要创建新的子目录，请确保其具有描述性，并包含相关组件或概念名称。例如，pubsub-namespaces。

注意

此模板仅为建议。可以根据文档的目的进行调整。

了解更多关于贡献 Dapr 文档的信息，例如前置内容和短代码。

模板

---
type: #必填; docs
title: #必填; "如何：简洁明了的标题"
linkTitle: #必填; "如何：比常规标题更短，以便在目录中显示"
weight: #必填; 根据层级使用正确的权重
description: #必填; 对文章内容的期望进行一句话描述
---

<!--
在提交 PR 之前，请删除此模板中的所有注释。
-->

<!-- 
H1：Hugo 前置内容中的标题作为文章的 markdown H1。
-->

<!-- 引言段落 
必填。简要介绍将涵盖的内容以及任何默认的 Dapr 特性。链接到适当的概念或概述文档以提供背景。 -->

<!-- 
如果可能，包含一个图表或图像。
-->

<!--
如果适用，请在短代码注释或警报中链接到相关的快速入门，文本如：

 如果您还没有，请[尝试 <topic> 快速入门](link)，以快速了解如何使用 <topic>。

-->

<!-- 
确保操作指南包含多个编程语言、操作系统或部署目标的示例（如果适用）。
-->

## <操作或任务>

<!-- 
与快速入门不同，不要使用“步骤 1”、“步骤 2”等。
-->

## <操作或任务>

<!-- 
每个 H2 步骤应以动词/动作词开头。
-->

<!--
尽可能包含代码片段。
-->

## 后续步骤

<!--
链接到相关页面和示例。例如，构建块概述、相关教程、API 参考等。
-->

Dapr 发展规划

Mon, 01 Jan 0001 00:00:00 +0000

请访问此文档以了解 Dapr 项目的发展规划。

配置 Dapr 发送分布式追踪数据

Mon, 01 Jan 0001 00:00:00 +0000

注意

建议在任何生产环境中启用 Dapr 的追踪功能。您可以根据运行环境配置 Dapr，将追踪和遥测数据发送到多种可观测性工具，无论是在云端还是本地。

配置

在 Configuration 规范中的 tracing 部分包含以下属性：

spec:
 tracing:
 samplingRate: "1"
 otel: 
 endpointAddress: "myendpoint.cluster.local:4317"
 zipkin:
 endpointAddress: "https://..."

下表列出了追踪的属性：

属性	类型	描述
`samplingRate`	string	设置追踪的采样率来启用或禁用追踪。
`stdout`	bool	如果为真，则会将更详细的信息写入追踪。
`otel.endpointAddress`	string	设置 Open Telemetry (OTEL) 目标主机名和可选端口。如果使用此项，则无需指定 ‘zipkin’ 部分。
`otel.isSecure`	bool	指定连接到端点地址的连接是否加密。
`otel.protocol`	string	设置为 `http` 或 `grpc` 协议。
`zipkin.endpointAddress`	string	设置 Zipkin 服务器 URL。如果使用此项，则无需指定 `otel` 部分。

要启用追踪，请使用配置文件（在 selfhost 模式下）或 Kubernetes 配置对象（在 Kubernetes 模式下）。例如，以下配置对象将采样率设置为 1（每个 span 都被采样），并使用 OTEL 协议将追踪发送到本地的 OTEL 服务器 localhost:4317。

使用 Dapr API

Mon, 01 Jan 0001 00:00:00 +0000

在本指南中，您将通过运行 sidecar 并直接调用状态管理 API 来模拟应用程序的操作。在使用 Dapr CLI 运行 Dapr 之后，您将：

保存一个状态对象。
读取/获取状态对象。
删除状态对象。

了解更多关于状态构建块及其工作原理的概念文档。

前置条件

安装 Dapr CLI。
运行 dapr init。

步骤 1: 运行 Dapr sidecar

dapr run 命令通常会运行您的应用程序和一个 Dapr sidecar。在这种情况下，由于您直接与状态管理 API 交互，它只运行 sidecar。

启动一个 Dapr sidecar，它将在端口 3500 上监听一个名为 myapp 的空白应用程序：

dapr run --app-id myapp --dapr-http-port 3500

由于上述命令没有定义自定义组件文件夹，Dapr 使用在 dapr init 流程中创建的默认组件定义。

步骤 2: 保存状态

使用一个对象更新状态。新的状态将如下所示：

[
 {
 "key": "name",
 "value": "Bruce Wayne"
 }
]

注意，状态中包含的每个对象都有一个 key，其值为 name。您将在下一步中使用该 key。

使用以下命令保存一个新的状态对象：

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

Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '[{ "key": "name", "value": "Bruce Wayne"}]' -Uri 'http://localhost:3500/v1.0/state/statestore'

步骤 3: 获取状态

使用状态管理 API 和 key name 检索您刚刚存储在状态中的对象。在同一个终端窗口中，运行以下命令：

如何使用 gRPC 调用服务

Mon, 01 Jan 0001 00:00:00 +0000

本文介绍如何通过 Dapr 使用 gRPC 进行服务间通信。

通过 Dapr 的 gRPC 代理功能，您可以使用现有的基于 proto 的 gRPC 服务，并让流量通过 Dapr sidecar。这为开发人员带来了以下 Dapr 服务调用的优势：

双向认证
跟踪
指标
访问控制列表
网络级别的弹性
基于 API 令牌的认证

Dapr 支持代理所有类型的 gRPC 调用，包括一元和流式调用。

第一步：运行 gRPC 服务器

以下示例来自 “hello world” grpc-go 示例。虽然此示例使用 Go 语言，但相同的概念适用于所有支持 gRPC 的编程语言。

package main

import (
	"context"
	"log"
	"net"

	"google.golang.org/grpc"
	pb "google.golang.org/grpc/examples/helloworld/helloworld"
)

const (
	port = ":50051"
)

// server 用于实现 helloworld.GreeterServer。
type server struct {
	pb.UnimplementedGreeterServer
}

// SayHello 实现 helloworld.GreeterServer
func (s *server) SayHello(ctx context.Context, in *pb.HelloRequest) (*pb.HelloReply, error) {
	log.Printf("Received: %v", in.GetName())
	return &pb.HelloReply{Message: "Hello " + in.GetName()}, nil
}

func main() {
	lis, err := net.Listen("tcp", port)
	if err != nil {
		log.Fatalf("failed to listen: %v", err)
	}
	s := grpc.NewServer()
	pb.RegisterGreeterServer(s, &server{})
	log.Printf("server listening at %v", lis.Addr())
	if err := s.Serve(lis); err != nil {
		log.Fatalf("failed to serve: %v", err)
	}
}

这个 Go 应用实现了 Greeter proto 服务并提供了一个 SayHello 方法。

actor 运行时配置参数

Mon, 01 Jan 0001 00:00:00 +0000

您可以使用以下配置参数来调整 Dapr actor 的默认运行时行为。

参数	描述	默认值
`entities`	此主机支持的 actor 类型。	N/A
`actorIdleTimeout`	空闲 actor 的停用超时时间。每隔 `actorScanInterval` 时间间隔检查一次。	60 分钟
`actorScanInterval`	指定扫描空闲 actor 的时间间隔。超过 `actorIdleTimeout` 的 actor 将被停用。	30 秒
`drainOngoingCallTimeout`	在重新平衡 actor 时，指定当前活动 actor 方法的完成超时时间。如果没有正在进行的方法调用，则忽略此项。	60 秒
`drainRebalancedActors`	如果设置为 true，Dapr 将在 `drainOngoingCallTimeout` 时间内等待当前 actor 调用完成，然后再尝试停用 actor。	true
`reentrancy` (`ActorReentrancyConfig`)	配置 actor 的重入行为。如果未提供，则重入功能被禁用。	禁用，false
`remindersStoragePartitions`	配置 actor 的提醒分区数量。如果未提供，所有提醒将作为 actor 状态存储中的单个记录保存。	0
`entitiesConfig`	使用配置数组单独配置每个 actor 类型。任何在单个实体配置中指定的实体也必须在顶级 `entities` 字段中列出。	N/A

示例

// 在 Startup.cs 中
public void ConfigureServices(IServiceCollection services)
{
 // 使用 DI 注册 actor 运行时
 services.AddActors(options =>
 {
 // 注册 actor 类型并配置 actor 设置
 options.Actors.RegisterActor<MyActor>();

 // 配置默认设置
 options.ActorIdleTimeout = TimeSpan.FromMinutes(60);
 options.ActorScanInterval = TimeSpan.FromSeconds(30);
 options.DrainOngoingCallTimeout = TimeSpan.FromSeconds(60);
 options.DrainRebalancedActors = true;
 options.RemindersStoragePartitions = 7;
 options.ReentrancyConfig = new() { Enabled = false };

 // 为特定 actor 类型添加配置。
 // 此 actor 类型必须在基础级别的 'entities' 字段中有匹配值。如果没有，配置将被忽略。
 // 如果有匹配的实体，这里的值将用于覆盖根配置中指定的任何值。
 // 在此示例中，`ReentrantActor` 启用了重入；然而，'MyActor' 将不启用重入。
 options.Actors.RegisterActor<ReentrantActor>(typeOptions: new()
 {
 ReentrancyConfig = new()
 {
 Enabled = true,
 }
 });
 });

 // 注册用于 actor 的其他服务
 services.AddSingleton<BankService>();
}

查看 .NET SDK 文档以注册 actor。

处理 gRPC 错误代码

Mon, 01 Jan 0001 00:00:00 +0000

最初，错误是按照标准 gRPC 错误模型进行处理的。然而，为了提供更详细且信息丰富的错误消息，定义了一个增强的错误模型，与 gRPC 的更丰富的错误模型保持一致。

注意

并不是所有的 Dapr 错误都已转换为更丰富的 gRPC 错误模型。

标准 gRPC 错误模型

标准 gRPC 错误模型是 gRPC 中的一种错误报告方法。每个错误响应都包含一个错误代码和一条错误消息。错误代码是标准化的，反映了常见的错误情况。

标准 gRPC 错误响应示例：

ERROR:
 Code: InvalidArgument
 Message: 输入键/键前缀 'bad||keyname' 不能包含 '||'

更丰富的 gRPC 错误模型

更丰富的 gRPC 错误模型通过提供关于错误的额外上下文和详细信息来扩展标准错误模型。此模型包括标准错误 code 和 message，以及一个 details 部分，可以包含各种类型的信息，如 ErrorInfo、ResourceInfo 和 BadRequest 详细信息。

更丰富的 gRPC 错误响应示例：

ERROR:
 Code: InvalidArgument
 Message: 输入键/键前缀 'bad||keyname' 不能包含 '||'
 Details:
 1)	{
 	 "@type": "type.googleapis.com/google.rpc.ErrorInfo",
 	 "domain": "dapr.io",
 	 "reason": "DAPR_STATE_ILLEGAL_KEY"
 	}
 2)	{
 	 "@type": "type.googleapis.com/google.rpc.ResourceInfo",
 	 "resourceName": "statestore",
 	 "resourceType": "state"
 	}
 3)	{
 	 "@type": "type.googleapis.com/google.rpc.BadRequest",
 	 "fieldViolations": [
 	 {
 	 "field": "bad||keyname",
 	 "description": "输入键/键前缀 'bad||keyname' 不能包含 '||'"
 	 }
 	 ]
 	}

对于 HTTP 客户端，Dapr 会将 gRPC 错误模型转换为类似的 JSON 格式结构。响应包括一个 errorCode、一个 message 和一个 details 数组，反映了更丰富的 gRPC 模型中的结构。

命名空间中的actor

Mon, 01 Jan 0001 00:00:00 +0000

在Dapr中，命名空间用于提供隔离，从而支持多租户。通过为actor添加命名空间，相同的actor类型可以部署在不同的命名空间中。您可以在同一命名空间中使用这些actor的实例。

注意

每个命名空间中的actor部署必须使用独立的状态存储，特别是在相同的actor类型跨多个命名空间使用时。换句话说，actor记录中不包含任何命名空间信息，因此每个命名空间需要单独的状态存储。请参阅为命名空间配置actor状态存储部分以获取示例。

创建和配置命名空间

您可以在自托管模式或Kubernetes上使用命名空间。

在自托管模式下，您可以通过设置NAMESPACE环境变量为Dapr实例指定命名空间。

在Kubernetes上，您可以在部署actor应用程序时创建和配置命名空间。例如，使用以下kubectl命令开始：

kubectl create namespace namespace-actorA
kubectl config set-context --current --namespace=namespace-actorA

然后，将您的actor应用程序部署到此命名空间中（在示例中为namespace-actorA）。

为命名空间配置actor状态存储

每个命名空间中的actor部署必须使用独立的状态存储。虽然您可以为每个actor命名空间使用不同的物理数据库，但某些状态存储组件提供了一种通过表、前缀、集合等逻辑分隔数据的方法。这允许您在多个命名空间中使用相同的物理数据库，只要您在Dapr组件定义中提供逻辑分隔即可。

以下是一些示例。

示例1：通过etcd中的前缀

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
spec:
 type: state.etcd
 version: v2
 metadata:
 - name: endpoints
 value: localhost:2379
 - name: keyPrefixPath
 value: namespace-actorA
 - name: actorStateStore
 value: "true"

示例2：通过SQLite中的表名

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
spec:
 type: state.sqlite
 version: v1
 metadata:
 - name: connectionString
 value: "data.db"
 - name: tableName
 value: "namespace-actorA"
 - name: actorStateStore
 value: "true"

示例3：通过Redis中的逻辑数据库编号

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
spec:
 type: state.redis
 version: v1
 metadata:
 - name: redisHost
 value: localhost:6379
 - name: redisPassword
 value: ""
 - name: actorStateStore
 value: "true"
 - name: redisDB
 value: "1"
 - name: redisPassword
 secretKeyRef:
 name: redis-secret
 key: redis-password
 - name: actorStateStore
 value: "true"
 - name: redisDB
 value: "1"
auth:
 secretStore: <SECRET_STORE_NAME>

查看您的状态存储组件规格以了解其提供的功能。

如何：使用HTTP调用非Dapr端点

Mon, 01 Jan 0001 00:00:00 +0000

本文介绍如何通过Dapr使用HTTP调用非Dapr端点。

通过Dapr的服务调用API，您可以与使用或不使用Dapr的端点进行通信。使用Dapr调用非Dapr端点不仅提供了一致的API，还带来了以下Dapr服务调用的优势：

应用弹性策略
通过跟踪和指标实现调用的可观测性
通过访问控制实现安全性
利用中间件管道组件
服务发现
使用请求头进行身份验证

通过HTTP调用外部服务或非Dapr端点

有时您可能需要调用非Dapr的HTTP端点，例如：

您可能只在应用程序的一部分中使用Dapr，尤其是在涉及旧系统时
您可能无法访问代码以将现有应用程序迁移到Dapr
您需要调用外部的HTTP服务

通过定义HTTPEndpoint资源，您可以声明性地配置与非Dapr端点的交互方式。然后，您可以使用服务调用URL来访问非Dapr端点。或者，您可以直接在服务调用URL中使用非Dapr的完全限定域名（FQDN）端点URL。

HttpEndpoint、FQDN URL和appId的优先级

在进行服务调用时，Dapr运行时遵循以下优先级顺序：

是否为命名的HTTPEndpoint资源？
是否为带有http://或https://前缀的FQDN URL？
是否为appID？

服务调用与非Dapr HTTP端点

下图概述了Dapr在调用非Dapr端点时的工作流程。

服务A发起一个HTTP调用，目标是服务B（一个非Dapr端点）。调用被发送到本地的Dapr sidecar。
Dapr通过HTTPEndpoint或FQDN URL定位服务B的位置，然后将消息转发给服务B。
服务B向服务A的Dapr sidecar发送响应。
服务A接收响应。

使用HTTPEndpoint资源或FQDN URL调用非Dapr端点

在与Dapr应用程序或非Dapr应用程序通信时，有两种方法可以调用非Dapr端点。Dapr应用程序可以通过以下方式之一调用非Dapr端点：

使用命名的HTTPEndpoint资源，定义一个HTTPEndpoint资源类型。请参阅HTTPEndpoint参考中的示例。
```
localhost:3500/v1.0/invoke/<HTTPEndpoint-name>/method/<my-method>
```
例如，使用名为"palpatine"的HTTPEndpoint资源和名为"Order66"的方法：
```
curl http://localhost:3500/v1.0/invoke/palpatine/method/order66
```

使用指向非Dapr端点的FQDN URL。

localhost:3500/v1.0/invoke/<URL>/method/<my-method>

例如，使用名为https://darthsidious.starwars的FQDN资源：

curl http://localhost:3500/v1.0/invoke/https://darthsidious.starwars/method/order66

使用appId调用启用Dapr的应用程序

AppID用于通过appID和my-method调用Dapr应用程序。阅读如何：使用HTTP调用服务指南以获取更多信息。例如：

localhost:3500/v1.0/invoke/<appID>/method/<my-method>

curl http://localhost:3602/v1.0/invoke/orderprocessor/method/checkout

TLS认证

使用HTTPEndpoint资源允许您根据远程端点的认证要求使用根证书、客户端证书和私钥的任意组合。

使用根证书的示例

apiVersion: dapr.io/v1alpha1
kind: HTTPEndpoint
metadata:
 name: "external-http-endpoint-tls"
spec:
 baseUrl: https://service-invocation-external:443
 headers:
 - name: "Accept-Language"
 value: "en-US"
 clientTLS:
 rootCA:
 secretKeyRef:
 name: dapr-tls-client
 key: ca.crt

使用客户端证书和私钥的示例

apiVersion: dapr.io/v1alpha1
kind: HTTPEndpoint
metadata:
 name: "external-http-endpoint-tls"
spec:
 baseUrl: https://service-invocation-external:443
 headers:
 - name: "Accept-Language"
 value: "en-US"
 clientTLS:
 certificate:
 secretKeyRef:
 name: dapr-tls-client
 key: tls.crt
 privateKey:
 secretKeyRef:
 name: dapr-tls-key
 key: tls.key

社区电话演示

观看此视频以了解如何使用服务调用来调用非Dapr端点。

actor 定时器和提醒

Mon, 01 Jan 0001 00:00:00 +0000

actor 可以通过注册定时器或提醒来安排周期性工作。

定时器和提醒的功能非常相似。主要区别在于 Dapr actor 运行时在停用后不会保留任何关于定时器的信息，而是使用 Dapr actor 状态提供程序持久化提醒的信息。

这种区别允许用户在轻量但无状态的定时器与更资源密集但有状态的提醒之间进行选择。

定时器和提醒的调度配置是相同的，概述如下：

dueTime 是一个可选参数，用于设置第一次调用回调的时间或时间间隔。如果省略 dueTime，则在定时器/提醒注册后立即调用回调。

支持的格式：

RFC3339 日期格式，例如 2020-10-02T15:00:00Z
time.Duration 格式，例如 2h30m
ISO 8601 持续时间格式，例如 PT2H30M

period 是一个可选参数，用于设置两次连续回调调用之间的时间间隔。当以 ISO 8601-1 持续时间 格式指定时，您还可以配置重复次数以限制回调调用的总次数。如果省略 period，则回调只会被调用一次。

支持的格式：

time.Duration 格式，例如 2h30m
ISO 8601 持续时间格式，例如 PT2H30M, R5/PT1M30S

ttl 是一个可选参数，用于设置定时器/提醒将过期和删除的时间或时间间隔。如果省略 ttl，则不应用任何限制。

支持的格式：

RFC3339 日期格式，例如 2020-10-02T15:00:00Z
time.Duration 格式，例如 2h30m
ISO 8601 持续时间格式。示例：PT2H30M

actor 运行时验证调度配置的正确性，并在输入无效时返回错误。

当您同时指定 period 中的重复次数和 ttl 时，定时器/提醒将在任一条件满足时停止。

actor 定时器

您可以在 actor 上注册一个基于定时器执行的回调。

指南：跨命名空间进行服务调用

Mon, 01 Jan 0001 00:00:00 +0000

在本文中，您将学习如何在不同命名空间之间进行服务调用。默认情况下，service-invocation支持通过简单引用应用程序ID（如nodeapp）来调用同一命名空间内的服务：

localhost:3500/v1.0/invoke/nodeapp/method/neworder

service-invocation也支持跨命名空间的调用。在所有支持的平台上，Dapr应用程序ID遵循包含目标命名空间的有效FQDN格式。您可以同时指定：

应用程序ID（如nodeapp），以及
应用程序所在的命名空间（如production）。

示例 1

调用位于production命名空间中nodeapp的neworder方法：

localhost:3500/v1.0/invoke/nodeapp.production/method/neworder

在使用service-invocation调用不同命名空间中的应用程序时，您需要使用命名空间来限定它。这在Kubernetes集群中的跨命名空间调用中非常有用。

示例 2

调用位于production命名空间中myapp的ping方法：

https://localhost:3500/v1.0/invoke/myapp.production/method/ping

示例 3

使用curl命令从外部DNS地址（例如api.demo.dapr.team）调用与示例2相同的ping方法，并提供Dapr API令牌进行身份验证：

MacOS/Linux:

curl -i -d '{ "message": "hello" }' \
 -H "Content-type: application/json" \
 -H "dapr-api-token: ${API_TOKEN}" \
 https://api.demo.dapr.team/v1.0/invoke/myapp.production/method/ping

使用 GitHub Codespaces 进行贡献

Mon, 01 Jan 0001 00:00:00 +0000

GitHub Codespaces 是为 Dapr 仓库做出贡献的最简单方式。只需点击一下，您就可以在浏览器中获得一个已准备好的环境，包含所有必要的前置条件。

功能

一键运行：获取一个专用且沙盒化的环境，所有必需的框架和包都已准备就绪。
按使用计费：只需为您在 Codespaces 中开发的时间付费。当不使用时，环境会自动关闭。
便携性：可以在浏览器中运行，也可以在 Visual Studio Code 中运行，或使用 SSH 连接。

在 Codespace 中打开 Dapr 仓库

要在 Codespace 中打开 Dapr 仓库，请从仓库主页选择“Code”并选择“Open with Codespaces”：

如果您还没有 fork 该仓库，创建 Codespace 时会自动为您创建一个 fork，并在 Codespace 中使用它。

支持的仓库

在 Codespace 中开发 Dapr 组件

开发新的 Dapr 组件需要同时处理 dapr/components-contrib 和 dapr/dapr 仓库。建议将这两个文件夹并排放置在 /workspaces 目录中。

如果您从 `dapr/dapr` 创建了 Codespace

如果您的 Codespaces 是从 dapr/dapr 仓库或其 fork 启动的，您需要在 /workspaces/components-contrib 中克隆 dapr/components-contrib 仓库（或其 fork）。

如何启用actor提醒分区

Mon, 01 Jan 0001 00:00:00 +0000

actor提醒在sidecar重启后仍然持久化并继续触发。注册了多个提醒的应用程序可能会遇到以下问题：

提醒注册和注销的吞吐量低
基于state存储单个记录大小限制的提醒注册数量有限

为了解决这些问题，应用程序可以通过在state存储中将数据分布在多个键中来启用actor提醒分区。

在actors\|\|<actor type>\|\|metadata中使用一个元数据记录来存储给定actor类型的持久化配置。
多个记录存储同一actor类型的提醒子集。

键	值
`actors\|\|<actor type>\|\|metadata`	`{ "id": <actor metadata identifier>, "actorRemindersMetadata": { "partitionCount": <number of partitions for reminders> } }`
`actors\|\|<actor type>\|\|<actor metadata identifier>\|\|reminders\|\|1`	`[ <reminder 1-1>, <reminder 1-2>, ... , <reminder 1-n> ]`
`actors\|\|<actor type>\|\|<actor metadata identifier>\|\|reminders\|\|2`	`[ <reminder 1-1>, <reminder 1-2>, ... , <reminder 1-m> ]`

如果您需要更改分区数量，Dapr的sidecar将自动重新分配提醒集。

配置actor运行时以分区actor提醒

与其他actor配置元素类似，actor运行时通过actor的GET /dapr/config端点提供适当的配置来分区actor提醒。选择您偏好的语言以获取actor运行时配置示例。

// 在Startup.cs中
public void ConfigureServices(IServiceCollection services)
{
 // 使用DI注册actor运行时
 services.AddActors(options =>
 {
 // 注册actor类型并配置actor设置
 options.Actors.RegisterActor<MyActor>();

 // 配置默认设置
 options.ActorIdleTimeout = TimeSpan.FromMinutes(60);
 options.ActorScanInterval = TimeSpan.FromSeconds(30);
 options.RemindersStoragePartitions = 7;
 });

 // 注册用于actor的其他服务
 services.AddSingleton<BankService>();
}

查看.NET SDK中注册actor的文档。

Dapr 机器人参考

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 机器人通过一系列命令来帮助处理 Dapr 组织中的常见任务。它可以为每个代码库单独配置（示例），并能够在特定事件发生时运行。以下是命令列表及其在各个代码库中的实现。

命令参考

命令	目标	描述	谁可以使用	代码库
`/assign`	Issue	将一个 issue 分配给一个或多个用户	任何人	`dapr`, `docs`, `quickstarts`, `cli`, `components-contrib`, `go-sdk`, `js-sdk`, `java-sdk`, `python-sdk`, `dotnet-sdk`, `rust-sdk`
`/ok-to-test`	Pull request	`dapr`: 触发端到端测试 `components-contrib`: 触发一致性和认证测试	在 bot 中授权的用户	`dapr`, `components-contrib`
`/ok-to-perf`	Pull request	触发性能测试。	在 bot 中授权的用户	`dapr`
`/make-me-laugh`	Issue 或 pull request	发布一个随机笑话，增添趣味	在 bot 中授权的用户	`dapr`, `components-contrib`

标签参考

您可以通过使用 created-by/dapr-bot 标签查询由 Dapr 机器人创建的 issue（查询）。

标签	目标	作用说明	代码库
`docs-needed`	Issue	在 `dapr/docs` 中创建一个新的 issue 以跟踪文档工作	`dapr`
`sdk-needed`	Issue	在 SDK 仓库中创建新的 issue 以跟踪 SDK 工作	`dapr`
`documentation required`	Issue 或 pull request	在 `dapr/docs` 中创建一个新的 issue 以跟踪文档工作	`components-contrib`
`new component`	Issue 或 pull request	在 `dapr/dapr` 中创建一个新的 issue 以注册新组件	`components-contrib`

操作指南：使用脚本与虚拟actor交互

Mon, 01 Jan 0001 00:00:00 +0000

了解如何通过HTTP/gRPC端点来使用虚拟actor。

调用actor方法

您可以通过调用HTTP/gRPC端点与Dapr交互，以调用actor方法。

POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/method/<method>

在请求体中提供actor方法所需的数据。请求的响应，即actor方法调用返回的数据，将在响应体中。

有关更多详细信息，请参阅Actors API规范。

注意

您也可以使用Dapr SDKs来操作actors。

使用actors保存状态

您可以通过HTTP/gRPC端点与Dapr交互，利用Dapr的actor状态管理功能来可靠地保存状态。

要使用actors，您的状态存储必须支持多项事务。这意味着您的状态存储组件需要实现TransactionalStore接口。

查看支持事务/actors的组件列表。所有actors只能使用一个状态存储组件来保存状态。

下一步

actor重入 >>

定义一个组件

Mon, 01 Jan 0001 00:00:00 +0000

在构建应用程序时，通常需要根据所需的构建块和特定组件创建组件文件定义。

在本教程中，您将创建一个组件定义文件以与secrets构建块API交互：

创建一个本地JSON密钥存储。
使用组件定义文件向Dapr注册密钥存储。
使用Dapr HTTP API获取密钥。

步骤1：创建一个JSON密钥存储

创建一个名为my-components的新目录以保存新的密钥和组件文件：
```
mkdir my-components
```
进入此目录。
```
cd my-components
```
Dapr支持多种类型的密钥存储，但在本教程中，创建一个名为mysecrets.json的本地JSON文件，其中包含以下密钥：

{
 "my-secret" : "I'm Batman"
}

步骤2：创建一个密钥存储Dapr组件

创建一个新文件localSecretStore.yaml，内容如下：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: my-secret-store
 namespace: default
spec:
 type: secretstores.local.file
 version: v1
 metadata:
 - name: secretsFile
 value: ./mysecrets.json
 - name: nestedSeparator
 value: ":"

在上述文件定义中：

type: secretstores.local.file 指定Dapr使用本地文件组件作为密钥存储。
元数据字段提供了与此组件一起使用所需的特定信息。在这种情况下，密钥存储JSON路径是相对于您执行dapr run命令的位置。

步骤3：运行Dapr sidecar

启动一个Dapr sidecar，它将在端口3500上监听一个名为myapp的空应用程序：

对于PowerShell环境：

dapr run --app-id myapp --dapr-http-port 3500 --resources-path ../

对于非PowerShell环境：

快速入门：服务调用

Mon, 01 Jan 0001 00:00:00 +0000

通过 Dapr 的服务调用模块，您的应用程序可以稳定且安全地与其他应用程序进行通信。

Dapr 提供了多种服务调用的方法，您可以根据具体需求进行选择。在本教程中，您将启用结账服务，通过 HTTP 代理调用订单处理服务中的方法，具体步骤如下：

在概述文章中了解更多关于 Dapr 服务调用方法的信息。

使用多应用程序运行

在继续本教程之前，请选择您偏好的编程语言。

步骤 1：准备工作

在此示例中，您需要：

快速入门：发布和订阅

Mon, 01 Jan 0001 00:00:00 +0000

我们来了解一下 Dapr 的发布和订阅 (Pub/sub) 构建块。在这个快速入门中，您将运行发布者和订阅者微服务，以演示 Dapr 如何实现 Pub/sub 模式。

使用发布者服务，开发者可以不断地将消息发布到某个主题。
Pub/sub 组件会对这些消息进行排队或代理。我们下面的示例使用 Redis，您也可以使用 RabbitMQ、Kafka 等。
订阅该主题的订阅者会从队列中获取消息并进行处理。

您可以通过以下两种方式尝试此 Pub/sub 快速入门：

使用多应用运行

在继续快速入门之前，请选择您偏好的 Dapr SDK 语言。

步骤 1：先决条件

对于此示例，您将需要：

快速入门：工作流

Mon, 01 Jan 0001 00:00:00 +0000

注意

在快速入门中，Redis 目前用作工作流的状态存储组件。然而，Redis 不支持事务回滚，因此不建议在生产环境中用作 actor 状态存储。

让我们来了解一下 Dapr 的工作流构建块。在这个快速入门中，您将创建一个简单的控制台应用程序，演示 Dapr 的工作流编程模型和管理 API。

在本指南中，您将：

运行 order-processor 应用程序。
启动工作流并观察工作流活动/任务的执行。
查看工作流逻辑和工作流活动，以及它们在代码中的表示。

在继续快速入门之前，请选择您偏好的 Dapr SDK 语言版本。

order-processor 控制台应用程序启动并管理 order_processing_workflow，该工作流模拟从商店购买商品。工作流由五个独特的工作流活动或任务组成：

快速入门：状态管理

Mon, 01 Jan 0001 00:00:00 +0000

本文将介绍 Dapr 的状态管理模块。在本快速入门指南中，您将学习如何使用 Redis 状态存储来保存、获取和删除状态。您可以选择以下两种方式之一：

虽然本示例使用了 Redis，您也可以替换为其他支持的状态存储。

使用多应用运行

在开始之前，请选择您偏好的编程语言对应的 Dapr SDK。

先决条件

您需要准备以下环境：

快速入门：输入和输出绑定

Mon, 01 Jan 0001 00:00:00 +0000

我们来了解一下 Dapr 的绑定构建块。通过使用绑定，您可以：

让您的应用程序响应来自外部系统的事件。
与外部系统进行交互。

在本快速入门中，您将使用输入 Cron 绑定每 10 秒调度一次批处理脚本。该脚本处理一个 JSON 文件，并使用 PostgreSQL Dapr 绑定将数据输出到 SQL 数据库。

在继续快速入门之前，请选择您偏好的 Dapr SDK 语言版本。

先决条件

您需要准备以下环境：

快速入门：Actors

Mon, 01 Jan 0001 00:00:00 +0000

我们来了解一下 Dapr 的 Actors 构建模块。在这个快速入门中，您将运行一个智能设备微服务和一个简单的控制台客户端，以演示 Dapr Actors 中的有状态对象模式。

目前，您可以通过 .NET SDK 体验这个 actors 快速入门。

以下是 .NET actors 快速入门的简要概述：

使用 SmartDevice.Service 微服务，您将托管：
- 两个 SmokeDetectorActor 烟雾报警对象
- 一个 ControllerActor 对象，用于指挥和控制智能设备
使用 SmartDevice.Client 控制台应用程序，客户端应用程序与每个 actor 或控制器交互，以执行聚合操作。
SmartDevice.Interfaces 包含服务和客户端应用程序使用的共享接口和数据类型。

先决条件

对于这个示例，您将需要：

Dapr CLI 和已初始化的环境。

Docker Desktop

安装 .NET 6、.NET 8 或 .NET 9

注意： .NET 6 是此版本中 Dapr .NET SDK 包的最低支持版本。只有 .NET 8 和 .NET 9 将在 Dapr v1.16 及更高版本中得到支持。

快速入门：机密管理

Mon, 01 Jan 0001 00:00:00 +0000

Dapr提供了一个专用的机密API，允许开发者从机密存储中检索机密。在本快速入门中，您将：

运行一个带有机密存储组件的微服务。
在应用程序代码中使用Dapr机密API检索机密。

在继续快速入门之前，请选择您偏好的编程语言对应的Dapr SDK。

前置条件

您需要准备以下环境：

Docker Desktop

步骤1：设置环境

克隆快速入门仓库中的示例。

快速入门：配置

Mon, 01 Jan 0001 00:00:00 +0000

接下来，我们将介绍 Dapr 的配置模块。配置项通常具有动态特性，并且与应用程序的需求紧密相关。配置项是包含配置信息的键/值对，例如：

应用程序 ID
分区键
数据库名称等

在本快速入门中，您将运行一个使用配置 API 的 order-processor 微服务。该服务将：

从配置存储中获取配置项。
订阅配置更新。

在继续快速入门之前，请选择您偏好的 Dapr SDK 语言版本。

前提条件

您需要准备以下环境：

快速入门：加密技术

Mon, 01 Jan 0001 00:00:00 +0000

Alpha

加密构建块目前处于初始阶段。

我们来了解一下 Dapr 的加密构建块。在这个快速入门中，您将创建一个应用程序，使用 Dapr 加密 API 来加密和解密数据。您将：

加密并解密一个短字符串（使用 RSA 密钥），在内存中读取结果，使用 Go 的字节切片格式。
加密并解密一个大文件（使用 AES 密钥），通过流的方式将加密和解密的数据存储到文件中。

注意

此示例使用 Dapr SDK，该 SDK 利用 gRPC，并在使用加密 API 加密和解密消息时强烈推荐使用。

目前，您可以使用 Go SDK 体验加密 API。

此快速入门包括一个名为 crypto-quickstart 的 JavaScript 应用程序。

前置条件

对于此示例，您将需要：

Docker Desktop

系统上可用的 OpenSSL

步骤 1：设置环境

克隆快速入门仓库中提供的示例

教程：配置状态存储和发布/订阅消息代理

Mon, 01 Jan 0001 00:00:00 +0000

要使用状态和发布/订阅功能，您需要配置两个组件：

用于数据持久化和恢复的状态存储组件。
用于异步消息传递的发布/订阅消息代理组件。

您可以在以下链接找到支持的组件列表：

本教程将介绍如何使用 Redis 进行配置。

步骤 1：创建 Redis 存储

Dapr 可以使用任何 Redis 实例，无论是：

在本地开发环境中运行的容器化实例，还是
托管在云服务上的实例。

如果您已经有一个 Redis 实例，请直接跳到配置部分。

在自托管环境中，Dapr CLI 会在初始化过程中自动安装 Redis。您可以直接进行下一步。

您可以使用 Helm 在 Kubernetes 集群中创建 Redis 实例。在开始之前，请确保已安装 Helm v3。

如何：在Dapr中启用和使用actor重入

Mon, 01 Jan 0001 00:00:00 +0000

虚拟actor模式的一个核心原则是actor的单线程执行特性。没有重入时，Dapr运行时会锁定所有actor请求。第二个请求必须等到第一个请求完成后才能启动。这意味着actor不能调用自身，也不能被另一个actor调用，即使它们属于同一调用链。

重入通过允许同一链或上下文的请求重新进入已锁定的actor来解决这个问题。这在以下场景中非常有用：

一个actor想要调用自身的方法
actor在工作流中用于执行任务，然后回调到协调actor。

重入允许的调用链示例如下：

Actor A -> Actor A
Actor A -> Actor B -> Actor A

通过重入，您可以执行更复杂的actor调用，而不影响虚拟actor的单线程特性。

maxStackDepth参数用于设置一个值，以控制对同一actor可以进行多少次重入调用。默认情况下，这个值为32，通常已经足够。

配置actor运行时以启用重入

要启用actor重入，必须提供适当的配置。这是通过actor的GET /dapr/config端点完成的，类似于其他actor配置元素。

public class Startup
{
	public void ConfigureServices(IServiceCollection services)
	{
		services.AddSingleton<BankService>();
		services.AddActors(options =>
		{
		options.Actors.RegisterActor<DemoActor>();
		options.ReentrancyConfig = new Dapr.Actors.ActorReentrancyConfig()
			{
			Enabled = true,
			MaxStackDepth = 32,
			};
		});
	}
}

import { CommunicationProtocolEnum, DaprClient, DaprServer } from "@dapr/dapr";

// 使用DaprClientOptions配置actor运行时。
const clientOptions = {
 actor: {
 reentrancy: {
 enabled: true,
 maxStackDepth: 32,
 },
 },
};

from fastapi import FastAPI
from dapr.ext.fastapi import DaprActor
from dapr.actor.runtime.config import ActorRuntimeConfig, ActorReentrancyConfig
from dapr.actor.runtime.runtime import ActorRuntime
from demo_actor import DemoActor

reentrancyConfig = ActorReentrancyConfig(enabled=True)
config = ActorRuntimeConfig(reentrancy=reentrancyConfig)
ActorRuntime.set_actor_config(config)
app = FastAPI(title=f'{DemoActor.__name__}Service')
actor = DaprActor(app)

@app.on_event("startup")
async def startup_event():
	# 注册DemoActor
	await actor.register_actor(DemoActor)

@app.get("/MakeExampleReentrantCall")
def do_something_reentrant():
	# 在这里调用另一个actor，重入将自动处理
	return

以下是一个用Golang编写的actor代码片段，通过HTTP API提供重入配置。重入尚未包含在Go SDK中。

快速入门：作业

Mon, 01 Jan 0001 00:00:00 +0000

Alpha

作业构建块目前处于 alpha 阶段。

Dapr 作业构建块允许您在特定时间或间隔调度和运行作业。在本快速入门中，您将学习如何使用 Dapr 的作业 API 来调度、获取和删除作业。

您可以通过以下两种方式来体验此作业快速入门：

同时运行多个应用

在开始之前，请选择您偏好的 Dapr SDK 语言。目前，您可以使用 Go SDK 来试验作业 API。

本快速入门包含两个应用程序：

job-scheduler.go： 负责调度、检索和删除作业。
job-service.go： 负责处理已调度的作业。

步骤 1：准备工作

您需要以下工具：

Docker Desktop

步骤 2：设置环境

克隆快速入门仓库中的示例。

git clone https://github.com/dapr/quickstarts.git

cd jobs/go/sdk

步骤 3：调度作业

运行应用程序并调度作业：

Dapr sidecar (daprd) 概述

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 采用 sidecar 模式，这意味着 Dapr API 运行在一个独立的进程中，即 Dapr sidecar，并与您的应用程序一起运行。Dapr sidecar 进程命名为 daprd，并根据托管环境以不同的方式启动。

Dapr sidecar 提供以下功能：

应用程序业务逻辑使用的构建块 API
用于发现功能和设置属性的元数据 API
用于检查健康状态和 sidecar 准备及存活状态的健康 API

当应用程序在其配置的端口上可访问时，Dapr sidecar 即达到准备状态。在应用程序启动或初始化期间，应用程序暂时无法访问 Dapr 组件。

应用程序通过本地 http 或 gRPC 端点调用 sidecar API。

使用 `dapr run` 的自托管

在自托管模式下安装 Dapr 时，daprd 二进制文件会被下载并放置在用户主目录下（Linux/macOS 为 $HOME/.dapr/bin，Windows 为 %USERPROFILE%\.dapr\bin\）。

在自托管模式下，使用 Dapr CLI 的 run 命令会启动 daprd 可执行文件，并运行您提供的应用程序可执行文件。这是在本地进行开发和测试等场景中运行 Dapr sidecar 的推荐方式。

您可以在 Dapr run 命令参考中找到 CLI 提供的用于配置 sidecar 的各种参数。

在 Kubernetes 中使用 `dapr-sidecar-injector`

在 Kubernetes 上，Dapr 控制平面包括 dapr-sidecar-injector 服务，它监视带有 dapr.io/enabled 注释的新 pod，并在 pod 内注入一个包含 daprd 进程的容器。在这种情况下，可以通过注释传递 sidecar 参数，如此表中的 Kubernetes 注释 列所述。

Dapr 常见问题解答

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 与 Istio、Linkerd 或 OSM 等服务网格有何不同？

Dapr 并非服务网格。服务网格主要关注细粒度的网络控制，而 Dapr 则致力于帮助开发人员构建分布式应用程序。Dapr 和服务网格都采用 sidecar 模式，与应用程序共同运行。虽然它们有一些功能重叠，但各自也提供了独特的优势。有关更多信息，请阅读 Dapr & 服务网格概念页面。

性能基准

由于 Dapr 作为应用程序的 sidecar，Dapr 项目对性能非常重视。请参阅此处以获取最新的性能数据。

actors

Dapr、Orleans 和 Service Fabric Reliable Actors 之间有什么关系？

Dapr 中的 actors 源于 Orleans 的虚拟 actor 概念，这意味着它们在被调用时会激活，并在一段时间后自动停用。如果您熟悉 Orleans，Dapr 的 C# actors 会让您感到熟悉。Dapr 的 C# actors 基于 Service Fabric Reliable Actors（同样源于 Orleans），这使得您可以将 Service Fabric 中的 Reliable Actors 迁移到其他托管平台，如 Kubernetes 或其他本地环境。此外，Dapr 不仅仅局限于 actors。它为您提供了一套最佳实践的构建模块，可以集成到任何微服务应用程序中。请参阅 Dapr 概述。

Dapr 与其他 actor 框架有何区别？

虚拟 actor 功能是 Dapr 运行时提供的众多构建模块之一。由于 Dapr 是编程语言无关的，并提供 http/gRPC API，因此可以从任何语言调用 actors。这允许用一种语言编写的 actors 调用用不同语言编写的 actors。

服务调用API参考

Mon, 01 Jan 0001 00:00:00 +0000

Dapr为用户提供了使用唯一命名标识符（appId）来调用其他使用Dapr的应用程序的功能，或者调用不使用Dapr的HTTP端点。这使得应用程序可以通过命名标识符相互交互，并将服务发现的责任交给Dapr运行时。

调用远程Dapr应用上的方法

这个端点允许您在另一个启用了Dapr的应用中调用方法。

HTTP请求

PATCH/POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/invoke/<appID>/method/<method-name>

调用非Dapr端点上的方法

这个端点允许您使用HTTPEndpoint资源名称或完全限定域名（FQDN）URL在非Dapr端点上调用方法。

HTTP请求

PATCH/POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/invoke/<HTTPEndpoint name>/method/<method-name>

PATCH/POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/invoke/<FQDN URL>/method/<method-name>

HTTP响应代码

当一个服务通过Dapr调用另一个服务时，被调用服务的状态码将返回给调用者。如果存在网络错误或其他瞬态错误，Dapr将返回一个500错误，并附带详细的错误信息。

如果用户通过HTTP调用Dapr与启用gRPC的服务通信，来自被调用gRPC服务的错误将返回为500，而成功的响应将返回为200 OK。

代码	描述
XXX	上游状态返回
400	未提供方法名称
403	访问控制禁止调用
500	请求失败

URL参数

参数	描述
daprPort	Dapr端口
appID	与远程应用关联的应用ID
HTTPEndpoint name	与外部端点关联的HTTPEndpoint资源
FQDN URL	在外部端点上调用的完全限定域名URL
method-name	要在远程应用上调用的方法或URL的名称

注意，所有URL参数区分大小写。

请求内容

在请求中，您可以传递头信息：

{
 "Content-Type": "application/json"
}

在请求体中放置您想要发送给服务的数据：

{
 "arg1": 10,
 "arg2": 23,
 "operator": "+"
}

被调用服务接收到的请求

一旦您的服务代码在另一个启用了Dapr的应用或非Dapr端点中调用了方法，Dapr会在<method-name>端点上发送请求，并附带头信息和请求体。

被调用的Dapr应用或非Dapr端点需要监听并响应该端点上的请求。

跨命名空间调用

在支持命名空间的托管平台上，Dapr应用ID符合包含目标命名空间的有效FQDN格式。例如，以下字符串包含应用ID（myApp）以及应用运行的命名空间（production）。

myApp.production

支持命名空间的平台

Kubernetes

示例

您可以通过发送以下内容来调用mathService服务上的add方法：

curl http://localhost:3500/v1.0/invoke/mathService/method/add \
 -H "Content-Type: application/json"
 -d '{ "arg1": 10, "arg2": 23}'

mathService服务需要在/add端点上监听以接收和处理请求。

概述

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 是一个便于移植的事件驱动运行时，帮助开发者轻松构建在云和边缘环境中运行的弹性应用，无论是无状态还是有状态的，并支持多种编程语言和开发框架。

支持任何语言、框架和环境

随着云技术的普及，传统的 Web + 数据库应用架构（如经典的三层设计）正逐渐向微服务架构转变，这些架构本质上是分布式的。开发微服务应用不应要求您成为分布式系统的专家。

这正是 Dapr 的优势所在。Dapr 将构建微服务应用的最佳实践转化为开放且独立的 API，称为构建块。Dapr 的构建块：

允许您使用任意语言和框架构建可移植的应用。
完全独立
在应用中使用的数量没有限制

通过 Dapr，您可以逐步将现有应用迁移到微服务架构，采用云原生模式，如扩展/缩减、弹性和独立部署。

Dapr 是平台无关的，这意味着您可以在以下环境中运行您的应用：

本地
任何 Kubernetes 集群
虚拟或物理机器
Dapr 集成的其他托管环境

这使您能够构建可以在云和边缘运行的微服务应用。

云和边缘的微服务构建块

Dapr 提供分布式系统构建块，使您能够以标准方式构建微服务应用并部署到任何环境。

每个构建块 API 都是独立的，这意味着您可以在应用中使用任意数量的它们。

构建块	描述
服务间调用	提供弹性的服务间调用功能，无论远程服务位于何处，都可以进行方法调用，包括重试。
发布和订阅	在服务之间发布事件和订阅主题，简化事件驱动架构的水平扩展并增强其故障弹性。Dapr 提供至少一次消息传递保证、消息 TTL、消费者组和其他高级功能。
工作流	工作流 API 可以与其他 Dapr 构建块结合使用，定义跨多个微服务的长时间运行、持久化的流程或数据流，使用 Dapr 工作流或工作流组件。
状态管理	通过状态管理存储和查询键/值对，您可以轻松地在应用中编写长时间运行、高可用的有状态服务和无状态服务。状态存储是可插拔的，示例包括 AWS DynamoDB、Azure Cosmos DB、Azure SQL Server、GCP Firebase、PostgreSQL 或 Redis 等。
资源绑定	资源绑定与触发器在事件驱动架构上进一步构建，以通过接收和发送事件到任何外部源（如数据库、队列、文件系统等）来实现扩展和弹性。
Actors	一种用于有状态和无状态对象的模式，使并发变得简单，具有方法和状态封装。Dapr 在其 actor 运行时中提供许多功能，包括并发、状态和生命周期管理，用于 actor 激活/停用，以及定时器和提醒以唤醒 actor。
Secrets	秘密管理 API 与公共云和本地秘密存储集成，以检索用于应用代码的秘密。
Configuration	配置 API 使您能够从配置存储中检索和订阅应用配置项。
分布式锁	分布式锁 API 使您的应用能够获取任何资源的锁，从而在锁被应用释放或租约超时发生之前，给予其独占访问权限。
Cryptography	加密 API 提供了一个在安全基础设施（如密钥库）之上的抽象层。它包含允许您执行加密操作的 API，如加密和解密消息，而不将密钥暴露给您的应用。
Jobs	作业 API 使您能够在特定时间或间隔安排作业。
Conversation	对话 API 使您能够抽象与大型语言模型（LLM）交互的复杂性，并包括提示缓存和个人身份信息（PII）模糊化等功能。使用对话组件，您可以提供提示与不同的 LLM 进行对话。

跨领域 API

除了其构建块，Dapr 还提供适用于您使用的所有构建块的跨领域 API。

bindings 概述

Mon, 01 Jan 0001 00:00:00 +0000

通过 Dapr 的 bindings API，您可以利用外部系统的事件来触发应用程序，并与外部系统交互。使用 bindings API，您可以：

避免连接到消息系统并进行轮询的复杂性（如队列和消息总线）。
专注于业务逻辑，而不是系统交互的实现细节。
使您的代码不依赖于特定的 SDK 或库。
处理重试和故障恢复。
在运行时可以切换不同的 bindings。
构建具有特定环境 bindings 设置的可移植应用程序，而无需更改代码。

例如，通过 bindings，您的应用程序可以响应传入的 Twilio/SMS 消息，而无需：

添加或配置第三方 Twilio SDK
担心从 Twilio 轮询（或使用 WebSockets 等）

在上图中：

输入 binding 触发您应用程序上的一个方法。
在组件上执行输出 binding 操作，例如 "create"。

bindings 的开发独立于 Dapr 运行时。您可以查看并贡献 bindings。

注意

如果您正在使用 HTTP Binding，建议使用service-invocation 代替。阅读如何：使用 HTTP 调用非 Dapr 端点以获取更多信息。

输入 bindings

通过输入 bindings，您可以在外部资源发生事件时触发您的应用程序。请求中可以发送可选的负载和元数据。

以下概述视频和演示展示了 Dapr 输入 binding 的工作原理。

要接收来自输入 binding 的事件：

状态管理概述

Mon, 01 Jan 0001 00:00:00 +0000

您的应用程序可以利用Dapr的状态管理API在支持的状态存储中保存、读取和查询键/值对。通过状态存储组件，您可以构建有状态且长时间运行的应用程序，例如购物车或游戏的会话状态。如下图所示：

使用HTTP POST来保存或查询键/值对。
使用HTTP GET来读取特定键并返回其值。

以下视频和演示概述了Dapr状态管理的工作原理。

功能

通过状态管理API模块，您的应用程序可以利用一些通常复杂且容易出错的功能，包括：

设置并发控制和数据一致性的选项。
执行批量更新操作CRUD，包括多个事务操作。
查询和过滤键/值数据。

以下是状态管理API的一些功能：

可插拔的状态存储

Dapr的数据存储被设计为组件，可以在不更改服务代码的情况下进行替换。查看支持的状态存储以获取更多信息。

可配置的状态存储行为

使用Dapr，您可以在状态操作请求中附加元数据，描述您期望请求如何被处理。您可以附加：

并发性要求
一致性要求

默认情况下，您的应用程序应假设数据存储是最终一致的，并使用最后写入胜出并发模式。

并非所有存储都是平等的。为了确保您的应用程序的可移植性，您可以查询存储的元数据能力，并使您的代码适应不同的存储能力。

并发

Dapr支持使用ETags的乐观并发控制（OCC）。当请求状态值时，Dapr总是将ETag属性附加到返回的状态中。当用户代码：

更新状态时，期望通过请求体附加ETag。
删除状态时，期望通过If-Match头附加ETag。

当提供的ETag与状态存储中的ETag匹配时，写入操作成功。

为什么Dapr选择乐观并发控制（OCC）

在许多应用程序中，数据更新冲突很少见，因为客户端通常根据业务上下文分区以操作不同的数据。然而，如果您的应用程序选择使用ETags，不匹配的ETags可能导致请求被拒绝。建议您在代码中使用重试策略，以在使用ETags时补偿冲突。

如果您的应用程序在写入请求中省略ETags，Dapr在处理请求时会跳过ETag检查。这使得最后写入胜出模式成为可能，与使用ETags的首次写入胜出模式相比。

关于ETags的注意事项

对于不原生支持ETags的存储，相应的Dapr状态存储实现应模拟ETags，并在处理状态时遵循Dapr状态管理API规范。由于Dapr状态存储实现技术上是底层数据存储的客户端，模拟应该是直接的，使用存储提供的并发控制机制。

阅读API参考以了解如何设置并发选项。

一致性

Dapr支持强一致性和最终一致性，最终一致性是默认行为。

强一致性：Dapr在确认写入请求之前等待所有副本（或指定的法定人数）确认。
最终一致性：Dapr在底层数据存储接受写入请求后立即返回，即使这只是一个副本。

阅读API参考以了解如何设置一致性选项。

设置内容类型

状态存储组件可能会根据内容类型不同地维护和操作数据。Dapr支持在状态管理API中作为请求元数据的一部分传递内容类型。

设置内容类型是_可选的_，组件决定是否使用它。Dapr仅提供将此信息传递给组件的手段。

使用HTTP API：通过URL查询参数metadata.contentType设置内容类型。例如，http://localhost:3500/v1.0/state/store?metadata.contentType=application/json。
使用gRPC API：通过在请求元数据中添加键/值对"contentType" : <content type>来设置内容类型。

多重操作

Dapr支持两种类型的多读或多写操作：批量或事务性。阅读API参考以了解如何使用批量和多选项。

批量读取操作

您可以将多个读取请求分组为批量（或批次）操作。在批量操作中，Dapr将读取请求作为单独的请求提交到底层数据存储，并将它们作为单个结果返回。

事务性操作

您可以将写入、更新和删除操作分组为一个请求，然后作为一个原子事务处理。请求将作为一组事务性操作成功或失败。

actor状态

事务性状态存储可用于存储actor状态。要指定用于actor的状态存储，请在状态存储组件的元数据部分中将属性actorStateStore的值指定为true。actor状态以特定方案存储在事务性状态存储中，允许进行一致的查询。所有actor只能使用一个状态存储组件作为状态存储。阅读state API参考和actors API参考以了解有关actor状态存储的更多信息。

actor状态的生存时间（TTL）

在保存actor状态时，您应始终设置TTL元数据字段（ttlInSeconds）或在您选择的SDK中使用等效的API调用，以确保状态最终被移除。阅读actors概述以获取更多信息。

状态加密

Dapr支持应用程序状态的自动客户端加密，并支持密钥轮换。这在所有Dapr状态存储上都支持。有关更多信息，请阅读如何：加密应用程序状态主题。

Dapr 配置

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 配置通过一系列设置和策略，允许您调整单个 Dapr 应用程序的行为，或控制平面系统服务的整体行为。

欲了解更多信息，请阅读配置概念。

应用程序配置

设置应用程序配置

您可以在自托管模式或 Kubernetes 模式下设置应用程序配置。

在自托管模式下，Dapr 配置是一个配置文件，例如 config.yaml。默认情况下，Dapr sidecar 会在默认的 Dapr 文件夹中查找运行时配置：

Linux/MacOs: $HOME/.dapr/config.yaml
Windows: %USERPROFILE%\.dapr\config.yaml

您还可以在 dapr run CLI 命令中使用 --config 标志指定文件路径来应用配置。

在 Kubernetes 模式下，Dapr 配置是一个应用于集群的配置资源。例如：

kubectl apply -f myappconfig.yaml

您可以使用 Dapr CLI 列出应用程序的配置资源。

dapr configurations -k

Dapr sidecar 可以通过 dapr.io/config 注解来应用特定配置。例如：

概述

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 提供了一种通过弹性规范来定义和应用容错策略的功能。弹性规范与组件规范存放在同一位置，并在 Dapr sidecar 启动时生效。sidecar 决定如何将这些策略应用于您的 Dapr API 调用。在自托管模式下，弹性规范文件必须命名为 resiliency.yaml。在 Kubernetes 中，Dapr 会找到您的应用程序使用的命名弹性规范。在弹性规范中，您可以定义常见的弹性模式策略，例如：

这些策略可以应用于目标，包括：

通过服务调用的应用程序
组件
actor

此外，弹性策略还可以限定到特定应用程序。

演示视频

了解更多关于如何使用 Dapr 编写弹性微服务。

弹性策略结构

以下是弹性策略的一般结构：

apiVersion: dapr.io/v1alpha1
kind: Resiliency
metadata:
 name: myresiliency
scopes:
 # 可选地将策略限定到特定应用程序
spec:
 policies:
 timeouts:
 # 超时策略定义

 retries:
 # 重试策略定义

 circuitBreakers:
 # 断路器策略定义

 targets:
 apps:
 # 应用程序及其应用的策略

 actors:
 # actor 类型及其应用的策略

 components:
 # 组件及其应用的策略

完整示例策略

apiVersion: dapr.io/v1alpha1
kind: Resiliency
metadata:
 name: myresiliency
# 类似于订阅和配置规范，scopes 列出了可以使用此弹性规范的 Dapr 应用程序 ID。
scopes:
 - app1
 - app2
spec:
 # policies 是定义超时、重试和断路器策略的地方。
 # 每个策略都有一个名称，以便可以在弹性规范的 targets 部分引用。
 policies:
 # 超时是简单的命名持续时间。
 timeouts:
 general: 5s
 important: 60s
 largeResponse: 10s

 # 重试是重试配置的命名模板，并在操作的生命周期内实例化。
 retries:
 pubsubRetry:
 policy: constant
 duration: 5s
 maxRetries: 10

 retryForever:
 policy: exponential
 maxInterval: 15s
 maxRetries: -1 # 无限重试

 important:
 policy: constant
 duration: 5s
 maxRetries: 30

 someOperation:
 policy: exponential
 maxInterval: 15s

 largeResponse:
 policy: constant
 duration: 5s
 maxRetries: 3

 # 断路器会自动为每个组件和应用实例创建。
 # 断路器维护的计数器在 Dapr sidecar 运行期间存在。它们不会被持久化。
 circuitBreakers:
 simpleCB:
 maxRequests: 1
 timeout: 30s 
 trip: consecutiveFailures >= 5

 pubsubCB:
 maxRequests: 1
 interval: 8s
 timeout: 45s
 trip: consecutiveFailures > 8

 # targets 是应用命名策略的对象。Dapr 支持 3 种目标类型 - 应用程序、组件和 actor
 targets:
 apps:
 appB:
 timeout: general
 retry: important
 # 服务的断路器是按应用实例限定的。
 # 当断路器被触发时，该路由将从负载均衡中移除，持续配置的 `timeout` 时间。
 circuitBreaker: simpleCB

 actors:
 myActorType: # 自定义 actor 类型名称
 timeout: general
 retry: important
 # actor 的断路器可以按类型、ID 或两者限定。
 # 当断路器被触发时，该类型或 ID 将从配置表中移除，持续配置的 `timeout` 时间。
 circuitBreaker: simpleCB
 circuitBreakerScope: both ## 
 circuitBreakerCacheSize: 5000

 components:
 # 对于状态存储，策略适用于保存和检索状态。
 statestore1: # 任何组件名称 -- 这里是一个状态存储
 outbound:
 timeout: general
 retry: retryForever
 # 组件的断路器是按组件配置/实例限定的。例如 myRediscomponent。
 # 当此断路器被触发时，所有与该组件的交互将在配置的 `timeout` 时间内被阻止。
 circuitBreaker: simpleCB

 pubsub1: # 任何组件名称 -- 这里是一个 pubsub broker
 outbound:
 retry: pubsubRetry
 circuitBreaker: pubsubCB

 pubsub2: # 任何组件名称 -- 这里是另一个 pubsub broker
 outbound:
 retry: pubsubRetry
 circuitBreaker: pubsubCB
 inbound: # inbound 仅适用于从 sidecar 到应用程序的传递
 timeout: general
 retry: important
 circuitBreaker: pubsubCB

应用健康检查

Mon, 01 Jan 0001 00:00:00 +0000

应用健康检查功能可以检测应用程序的健康状况，并对状态变化做出反应。

应用程序可能由于多种原因变得无响应。例如，您的应用程序：

可能太忙而无法接受新工作；
可能已崩溃；或
可能处于死锁状态。

有时这种情况可能是暂时的，例如：

如果应用程序只是忙碌，最终会恢复接受新工作
如果应用程序因某种原因正在重启并处于初始化阶段

应用健康检查默认情况下是禁用的。一旦启用，Dapr 运行时（sidecar）会通过 HTTP 或 gRPC 调用定期轮询您的应用程序。当检测到应用程序的健康状况出现问题时，Dapr 会通过以下方式暂停接受新工作：

取消所有 pub/sub 订阅
停止所有输入绑定
短路所有服务调用请求，这些请求在 Dapr 运行时终止，不会转发到应用程序

这些变化是暂时的，一旦 Dapr 检测到应用程序恢复响应，它将恢复正常操作。

应用健康检查与平台级健康检查

Dapr 的应用健康检查旨在补充而不是替代任何平台级健康检查，例如在 Kubernetes 上运行时的存活探针。

平台级健康检查（或存活探针）通常确保应用程序正在运行，并在出现故障时导致平台重启应用程序。

与平台级健康检查不同，Dapr 的应用健康检查专注于暂停当前无法接受工作的应用程序，但预计最终能够恢复接受工作。目标包括：

不给已经超载的应用程序带来更多负担。
当 Dapr 知道应用程序无法处理消息时，不从队列、绑定或 pub/sub 代理中获取消息。

在这方面，Dapr 的应用健康检查是“较软”的，等待应用程序能够处理工作，而不是以“硬”方式终止正在运行的进程。

注意

对于 Kubernetes，失败的应用健康检查不会将 pod 从服务发现中移除：这仍然是 Kubernetes 存活探针的责任，而不是 Dapr。

配置应用健康检查

应用健康检查默认情况下是禁用的，但可以通过以下方式启用：

--enable-app-health-check CLI 标志；或
在 Kubernetes 上运行时使用 dapr.io/enable-app-health-check: true 注释。

添加此标志是启用应用健康检查的必要且充分条件，使用默认选项。

完整的选项列表如下表所示：

CLI 标志	Kubernetes 部署注释	描述	默认值
`--enable-app-health-check`	`dapr.io/enable-app-health-check`	启用健康检查的布尔值	禁用
`--app-health-check-path`	`dapr.io/app-health-check-path`	当应用通道为 HTTP 时，Dapr 用于健康探测的路径（如果应用通道使用 gRPC，则忽略此值）	`/healthz`
`--app-health-probe-interval`	`dapr.io/app-health-probe-interval`	每次健康探测之间的秒数	`5`
`--app-health-probe-timeout`	`dapr.io/app-health-probe-timeout`	健康探测请求的超时时间（以毫秒为单位）	`500`
`--app-health-threshold`	`dapr.io/app-health-threshold`	在应用被视为不健康之前的最大连续失败次数	`3`

请参阅完整的 Dapr 参数和注释参考以获取所有选项及其启用方法。

快速入门：从服务到组件的弹性

Mon, 01 Jan 0001 00:00:00 +0000

通过模拟系统故障来了解Dapr的弹性功能。在本快速入门中，您将：

运行一个微服务应用程序，该应用程序通过Dapr的状态管理API持续保存和检索状态。
通过模拟系统故障来触发弹性策略。
解决故障后，微服务应用程序将恢复。

在继续快速入门之前，请选择您偏好的Dapr SDK语言。

前提条件

对于此示例，您将需要：

Docker Desktop

步骤1：设置环境

克隆快速入门仓库中提供的示例。

入门指南：服务间的弹性

Mon, 01 Jan 0001 00:00:00 +0000

通过模拟系统故障来测试Dapr的弹性功能。在本入门指南中，您将会：

运行两个微服务应用程序：checkout和order-processor。checkout将持续向order-processor发起Dapr服务调用请求。
通过模拟系统故障来触发弹性机制。
移除故障以让微服务应用程序恢复。

在继续入门指南之前，选择您偏好的Dapr SDK语言版本。

前提条件

对于此示例，您将需要：

Sidecar 健康检查

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 提供了一种方法，通过 HTTP /healthz 端点来确定其健康状态。通过这个端点，daprd 进程或 sidecar 可以：

检查整体健康状况
在初始化期间确认 Dapr sidecar 的就绪状态
在 Kubernetes 中确定就绪和存活状态

在本指南中，您将了解 Dapr /healthz 端点如何与应用托管平台（如 Kubernetes）以及 Dapr SDK 的健康检查功能集成。

注意

Dapr actor 也有一个健康 API 端点，Dapr 会探测应用程序以响应 Dapr 发出的信号，确认 actor 应用程序是健康且正在运行的。请参阅 actor 健康 API。

下图展示了 Dapr sidecar 启动时，healthz 端点和应用通道初始化的步骤。

出站健康端点

如上图中的红色边界线所示，v1.0/healthz/ 端点用于等待以下情况：

所有组件已初始化；
Dapr HTTP 端口可用；并且，
应用通道已初始化。

这用于确认 Dapr sidecar 的完整初始化及其健康状况。

您可以通过设置 DAPR_HEALTH_TIMEOUT 环境变量来控制健康检查的超时时间，这在高延迟环境中可能很重要。

另一方面，如上图中的绿色边界线所示，当 v1.0/healthz/outbound 端点返回成功时：

所有组件已初始化；
Dapr HTTP 端口可用；但，
应用通道尚未建立。

在 Dapr SDK 中，waitForSidecar/wait_until_ready 方法（取决于您使用的 SDK）用于通过 v1.0/healthz/outbound 端点进行此特定检查。使用这种方法，您的应用程序可以在应用通道初始化之前调用 Dapr sidecar API，例如，通过 secret API 读取 secret。

操作指南：保存和获取状态

Mon, 01 Jan 0001 00:00:00 +0000

状态管理是新应用程序、遗留应用程序、单体应用程序或微服务应用程序的常见需求之一。处理和测试不同的数据库库，以及处理重试和故障，可能既困难又耗时。

在本指南中，您将学习如何使用键/值状态API来保存、获取和删除应用程序的状态。

下面的代码示例描述了一个处理订单的应用程序，该应用程序使用Dapr sidecar。订单处理服务通过Dapr将状态存储在Redis状态存储中。

设置状态存储

状态存储组件是Dapr用于与数据库通信的资源。

在本指南中，我们将使用Redis状态存储，但您也可以选择支持列表中的其他状态存储。

当您在selfhost模式下运行dapr init时，Dapr会在您的本地机器上创建一个默认的Redis statestore.yaml并运行一个Redis状态存储，位置如下：

在Windows上，位于%UserProfile%\.dapr\components\statestore.yaml
在Linux/MacOS上，位于~/.dapr/components/statestore.yaml

通过使用statestore.yaml组件，您可以在不更改应用程序代码的情况下轻松更换底层组件。

要将其部署到Kubernetes集群中，请在下面的YAML中填写您的状态存储组件的metadata连接详细信息，保存为statestore.yaml，然后运行kubectl apply -f statestore.yaml。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
spec:
 type: state.redis
 version: v1
 metadata:
 - name: redisHost
 value: localhost:6379
 - name: redisPassword
 value: ""

请参阅如何在Kubernetes上设置不同的状态存储以获取更多信息。

操作指南：使用输入绑定触发应用程序

Mon, 01 Jan 0001 00:00:00 +0000

当外部资源发生事件时，您可以通过输入绑定来触发您的应用程序。外部资源可以是队列、消息管道、云服务、文件系统等。请求中可以发送可选的负载和元数据。

输入绑定非常适合用于事件驱动的处理、数据管道或一般的事件响应和后续处理。Dapr输入绑定允许您：

在不需要特定SDK或库的情况下接收事件
在不更改代码的情况下替换绑定
专注于业务逻辑而不是事件资源的实现

本指南使用Kafka绑定作为示例。您可以从绑定组件列表中找到您偏好的绑定规范。在本指南中：

示例调用/binding端点，使用checkout作为要调用的绑定名称。
负载需要放在data字段中，可以是任何可序列化为JSON的值。
operation字段指定绑定需要执行的操作。例如，Kafka绑定支持create操作。
- 您可以查看每个输出绑定支持的操作（特定于每个组件）。

注意

如果您还没有尝试过，试试绑定快速入门，快速了解如何使用绑定API。

创建绑定

创建一个binding.yaml文件，并保存到应用程序目录中的components子文件夹中。

创建一个名为checkout的新绑定组件。在metadata部分中，配置以下与Kafka相关的属性：

您将发布消息的主题
代理

在创建绑定组件时，指定绑定的支持direction。

使用dapr run命令的--resources-path标志指向您的自定义资源目录。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: checkout
spec:
 type: bindings.kafka
 version: v1
 metadata:
 # Kafka代理连接设置
 - name: brokers
 value: localhost:9092
 # 消费者配置：主题和消费者组
 - name: topics
 value: sample
 - name: consumerGroup
 value: group1
 # 发布者配置：主题
 - name: publishTopic
 value: sample
 - name: authRequired
 value: false
 - name: direction
 value: input

要部署到Kubernetes集群中，运行kubectl apply -f binding.yaml。

弹性策略

Mon, 01 Jan 0001 00:00:00 +0000

在 policies 下定义超时、重试和断路器策略。每个策略都有一个名称，以便您可以在弹性规范的 targets 部分中引用它们。

注意：Dapr 为某些 API 提供默认的重试机制。请参阅此处了解如何使用用户定义的重试策略覆盖默认重试逻辑。

超时

超时是可选策略，用于提前终止长时间运行的操作。如果超过了超时时间：

正在进行的操作将被终止（如果可能）。
返回错误。

有效值是 Go 的 time.ParseDuration 接受的格式，例如：15s、2m、1h30m。超时没有设置最大值。

示例：

spec:
 policies:
 # 超时是简单的命名持续时间。
 timeouts:
 general: 5s
 important: 60s
 largeResponse: 10s

如果未指定超时值，则策略不会强制执行时间限制，默认使用请求客户端设置的任何值。

重试

通过 retries，您可以为失败的操作定义重试策略，包括由于触发定义的超时或断路器策略而失败的请求。

Pub/sub 组件重试与入站弹性

每个 pub/sub 组件都有其内置的重试行为。显式应用 Dapr 弹性策略不会覆盖这些内置重试机制。相反，重试策略补充了内置重试机制，这可能导致消息的重复聚集。

以下重试选项是可配置的：

重试选项	描述
`policy`	确定退避和重试间隔策略。有效值为 `constant` 和 `exponential`。默认为 `constant`。
`duration`	确定重试之间的时间间隔。仅适用于 `constant` 策略。有效值为 `200ms`、`15s`、`2m` 等格式。默认为 `5s`。
`maxInterval`	确定 `exponential` 退避策略可以增长到的最大间隔。额外的重试总是在 `maxInterval` 的持续时间之后发生。默认为 `60s`。有效值为 `5s`、`1m`、`1m30s` 等格式。
`maxRetries`	尝试的最大重试次数。 `-1` 表示无限次重试，而 `0` 表示请求不会被重试（本质上表现为未设置重试策略）。默认为 `-1`。
`matching.httpStatusCodes`	可选：要重试的 HTTP 状态代码或代码范围的逗号分隔字符串。未列出的状态代码不重试。有效值：100-599，参考格式：`<code>` 或范围 `<start>-<end>` 示例：“429,501-503” 默认：空字符串 `""` 或字段未设置。重试所有 HTTP 错误。
`matching.gRPCStatusCodes`	可选：要重试的 gRPC 状态代码或代码范围的逗号分隔字符串。未列出的状态代码不重试。有效值：0-16，参考格式：`<code>` 或范围 `<start>-<end>` 示例：“1,501-503” 默认：空字符串 `""` 或字段未设置。重试所有 gRPC 错误。

httpStatusCodes 和 gRPCStatusCodes 格式

字段值应遵循字段描述中指定的格式或下面的“示例 2”中的格式。格式不正确的值将产生错误日志（“无法读取弹性策略”），并且 daprd 启动序列将继续。

指数退避窗口使用以下公式：

发布/订阅 API 参考

Mon, 01 Jan 0001 00:00:00 +0000

向指定主题发布消息

此端点允许您将数据发布到多个正在监听某个 topic 的消费者。Dapr 保证此端点至少会被调用一次。

HTTP 请求

POST http://localhost:<daprPort>/v1.0/publish/<pubsubname>/<topic>[?<metadata>]

HTTP 响应代码

代码	描述
204	消息已送达
403	访问控制禁止消息
404	未提供 pubsub 名称或主题
500	传递失败

URL 参数

参数	描述
`daprPort`	Dapr 端口
`pubsubname`	pubsub 组件的名称
`topic`	主题的名称
`metadata`	查询参数，用于元数据，如下所述

注意，所有 URL 参数区分大小写。

curl -X POST http://localhost:3500/v1.0/publish/pubsubName/deathStarStatus \
 -H "Content-Type: application/json" \
 -d '{
 "status": "completed"
 }'

头部

Content-Type 头部告知 Dapr 在构建 CloudEvent 信封时您的数据遵循哪种内容类型。Content-Type 头部的值填充 CloudEvent 中的 datacontenttype 字段。

除非指定，否则 Dapr 假定为 text/plain。如果您的内容类型是 JSON，请使用值为 application/json 的 Content-Type 头部。

Dapr与服务网格

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 采用 sidecar 架构，作为独立进程与应用程序并行运行，提供服务调用、网络安全和分布式追踪等功能。这常常引发一个问题：Dapr 与 Linkerd、Istio 和 Open Service Mesh 等服务网格解决方案相比如何？

Dapr与服务网格的比较

虽然 Dapr 和服务网格确实有一些功能重叠，但Dapr 不是一个服务网格。服务网格主要关注网络层面的问题，而 Dapr 则专注于为开发者提供构建微服务的工具。Dapr 是以开发者为中心的，而服务网格则是以基础设施为中心的。

通常情况下，开发者无需关心应用程序是否部署在包含服务网格的环境中，因为服务网格会自动处理网络流量。服务网格主要由系统运维人员管理和部署，而 Dapr 的构建块 API 则是供开发者在代码中直接使用的。

Dapr 与服务网格共享的一些常见功能包括：

使用 mTLS 加密进行安全的服务间通信
服务间的指标收集
服务间的分布式追踪
通过重试实现的弹性

值得注意的是，Dapr 提供基于名称的服务发现和调用，这对开发者来说非常友好。通过 Dapr 的 service-invocation API，开发者可以直接调用服务名称，而服务网格则处理 IP 地址和 DNS 地址等网络细节。然而，Dapr 不提供流量路由或流量拆分等功能，这些通常由应用程序的入口代理来解决。此外，Dapr 还提供其他应用程序级别的构建块，如状态管理、发布订阅消息传递、actor 模型等。

Dapr 与服务网格在可观测性（追踪和指标）方面也有所不同。服务网格在网络层面操作，追踪服务之间的网络调用，而 Dapr 则通过 service-invocation 实现这一点。此外，Dapr 通过将追踪 ID 写入 Cloud Events 信封，提供对发布订阅调用的可观测性。这意味着对于同时使用服务间调用和发布订阅进行通信的应用程序，Dapr 的指标和追踪范围更广。

下图展示了 Dapr 和服务网格提供的重叠功能和独特能力：

将Dapr与服务网格一起使用

Dapr 可以与服务网格协同工作。在两者同时部署的情况下，Dapr 和服务网格的 sidecar 都在应用程序环境中运行。在这种情况下，建议仅配置 Dapr 或服务网格来执行 mTLS 加密和分布式追踪。

构建模块

Mon, 01 Jan 0001 00:00:00 +0000

构建模块是一个 HTTP 或 gRPC API，可以从您的代码中调用，并使用一个或多个 Dapr 组件。Dapr 由一组 API 构建模块组成，并且可以扩展以添加新的构建模块。Dapr 的构建模块：

解决构建弹性微服务应用程序中的常见挑战
编码最佳实践和模式

下图展示了构建模块如何通过公共 API 暴露，并从您的代码中调用，使用组件来实现其功能。

Dapr 提供以下构建模块：

构建模块	端点	描述
服务间调用	`/v1.0/invoke`	服务调用使应用程序能够通过 HTTP 或 gRPC 消息形式的已知端点相互通信。Dapr 提供一个端点，结合内置服务发现的反向代理，同时利用分布式追踪和错误处理。
发布和订阅	`/v1.0/publish` `/v1.0/subscribe`	发布/订阅是一种松耦合的消息传递模式，发送者（或发布者）将消息发布到主题，订阅者订阅该主题。Dapr 支持应用程序之间的发布/订阅模式。
工作流	`/v1.0/workflow`	工作流 API 允许您定义长时间运行的、持久的流程或数据流，这些流程或数据流跨越多个微服务，使用 Dapr 工作流或工作流组件。工作流 API 可以与其他 Dapr API 构建模块结合使用。例如，工作流可以通过服务调用调用另一个服务或检索 secret，提供灵活性和可移植性。
状态管理	`/v1.0/state`	应用程序状态是应用程序希望在单个会话之外保留的任何内容。Dapr 提供基于键/值的状态和查询 API，具有可插拔的状态存储以实现持久性。
绑定	`/v1.0/bindings`	绑定提供与外部云/本地服务或系统的双向连接。Dapr 允许您通过 Dapr 绑定 API 调用外部服务，并允许您的应用程序被连接服务发送的事件触发。
Actors	`/v1.0/actors`	actor 是一个隔离的、独立的计算和状态单元，具有单线程执行。Dapr 提供基于虚拟 actor 模式的 actor 实现，提供单线程编程模型，并且当不使用时，actor 会被垃圾回收。
Secrets	`/v1.0/secrets`	Dapr 提供一个 secret 构建模块 API，并与 secret 存储集成，如公共云存储、本地存储和 Kubernetes 来存储 secret。服务可以调用 secret API 来检索 secret，例如获取数据库的连接字符串。
配置	`/v1.0/configuration`	配置 API 使您能够检索和订阅支持的配置存储的应用程序配置项。这使应用程序能够在启动时或在存储中进行配置更改时检索特定的配置信息。
分布式锁	`/v1.0-alpha1/lock`	分布式锁 API 使您能够对资源进行锁定，以便应用程序的多个实例可以在不发生冲突的情况下访问资源，并提供一致性保证。
加密	`/v1.0-alpha1/crypto`	加密 API 使您能够执行加密操作，例如加密和解密消息，而不将密钥暴露给您的应用程序。
作业	`/v1.0-alpha1/jobs`	作业 API 使您能够调度和编排作业。示例场景包括：安排批处理作业在每个工作日运行安排各种维护脚本进行清理安排 ETL 作业在特定时间（每小时、每天）运行以获取新数据，处理它，并使用最新信息更新数据仓库。
对话	`/v1.0-alpha1/conversation`	对话 API 使您能够提供提示与不同的大型语言模型（LLM）进行对话，并包括提示缓存和个人身份信息（PII）模糊化等功能。

认证流程

Mon, 01 Jan 0001 00:00:00 +0000

注意

认证流程仅适用于内置组件，不适用于可插拔组件。

概述

Dapr 采用模块化设计，功能以组件形式提供。每个组件都有一个接口定义，所有组件都是可互换的，因此理想情况下，您可以用具有相同接口的另一个组件替换一个组件。每个用于生产的组件都需要满足一定的技术要求，以确保功能兼容性和稳健性。

一般来说，一个组件需要：

符合定义的 Dapr 接口
功能正确且稳健
有良好的文档和维护

为了确保组件符合 Dapr 设定的标准，会在 Dapr 维护者管理的环境中对组件进行一系列测试。一旦测试持续通过，就可以确定组件的成熟度级别。

认证级别

级别如下：

Alpha

组件实现了所需的接口，并按规范描述工作
组件有文档
组件可能存在漏洞，或在集成时暴露出漏洞
组件可能无法通过所有一致性测试
组件可能没有一致性测试
由于后续版本中可能出现不兼容的更改，仅推荐用于非关键业务用途

所有组件都从 Alpha 阶段开始。

Beta

组件必须通过所有定义的组件一致性测试以满足组件规范
组件一致性测试已在 Dapr 维护者管理的环境中运行
组件包含由 Dapr 维护者审核和批准的特定 components-contrib 版本的一致性测试结果记录
由于后续版本中可能出现不兼容的更改，仅推荐用于非关键业务用途

注意

如果满足以下条件，组件可以跳过 Beta 阶段和一致性测试要求，由维护者决定：

组件是一个绑定
认证测试是全面的

Stable

组件必须有组件认证测试以验证功能和弹性
组件由 Dapr 维护者维护并由社区支持
组件有良好的文档和测试
组件在之前至少一个 Dapr 运行时的小版本发布中以 Alpha 或 Beta 形式存在
维护者将根据 Dapr 支持政策解决组件安全性、核心功能和测试问题，并发布包含修补的稳定组件的补丁版本

注意

稳定的 Dapr 组件基于 Dapr 认证和一致性测试，并不保证由任何特定供应商支持，其中供应商的 SDK 作为组件的一部分使用。

如何：编写中间件组件

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 允许通过将一系列中间件组件链接在一起来定义自定义处理管道。在本指南中，您将学习如何创建一个中间件组件。要了解如何配置已有的中间件组件，请参阅配置中间件组件

编写自定义 HTTP 中间件

Dapr 中的 HTTP 中间件是对标准 Go net/http 处理函数的封装。

您的中间件需要实现一个中间件接口，该接口定义了一个 GetHandler 方法，该方法返回一个 http.Handler 回调函数和一个 error：

type Middleware interface {
 GetHandler(metadata middleware.Metadata) (func(next http.Handler) http.Handler, error)
}

处理器接收一个 next 回调函数，该函数应被调用以继续处理请求。

您的处理器实现可以包括入站逻辑、出站逻辑，或同时包括两者：


func (m *customMiddleware) GetHandler(metadata middleware.Metadata) (func(next http.Handler) http.Handler, error) {
 var err error
 return func(next http.Handler) http.Handler {
 return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 // 入站逻辑
 // ...

 // 调用下一个处理器
 next.ServeHTTP(w, r)

 // 出站逻辑
 // ...
 }
 }, err
}

操作指南：查询状态

Mon, 01 Jan 0001 00:00:00 +0000

alpha

状态查询API目前处于alpha阶段。

通过状态查询API，您可以从状态存储组件中检索、过滤和排序键/值数据。查询API并不是完整查询语言的替代品。

尽管状态存储是键/值存储，value可能是一个包含自身层次结构、键和值的JSON文档。查询API允许您使用这些键/值来检索相应的文档。

查询状态

您可以通过HTTP POST/PUT或gRPC提交查询请求。请求的主体是一个包含以下三个部分的JSON对象：

filter
sort
page

`filter`

filter用于指定查询条件，结构类似于树形，每个节点表示一个操作，可能是单一或多个操作数。

支持以下操作：

操作符	操作数	描述
`EQ`	key:value	key 等于 value
`NEQ`	key:value	key 不等于 value
`GT`	key:value	key 大于 value
`GTE`	key:value	key 大于等于 value
`LT`	key:value	key 小于 value
`LTE`	key:value	key 小于等于 value
`IN`	key:[]value	key 等于 value[0] 或 value[1] 或 … 或 value[n]
`AND`	[]operation	operation[0] 且 operation[1] 且 … 且 operation[n]
`OR`	[]operation	operation[0] 或 operation[1] 或 … 或 operation[n]

操作数中的key类似于JSONPath表示法。键中的每个点表示嵌套的JSON结构。例如，考虑以下结构：

Bridge to Kubernetes 对 Dapr 服务的支持

Mon, 01 Jan 0001 00:00:00 +0000

Bridge to Kubernetes 允许您在开发计算机上运行和调试代码，同时保持与 Kubernetes 集群中其他应用程序或服务的连接。这种调试方式通常被称为本地隧道调试。

了解更多 Bridge to Kubernetes 信息

调试 Dapr 应用程序

Bridge to Kubernetes 支持在您的计算机上调试 Dapr 应用程序，同时与 Kubernetes 集群中的服务和应用程序进行交互。以下示例展示了 Bridge to Kubernetes 如何帮助开发人员调试分布式计算器快速入门：

隔离模式

隔离模式目前不支持 Dapr 应用程序。请确保启动 Bridge to Kubernetes 模式时不使用隔离模式。

进一步阅读

Dapr 参数和注解用于 daprd、CLI 和 Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

此表旨在帮助用户了解在不同环境中运行 Dapr sidecar 的对应选项：通过 CLI 直接运行，通过 daprd，或在 Kubernetes 上通过注解运行。

daprd	Dapr CLI	CLI 简写	Kubernetes 注解	描述
`--allowed-origins`	不支持		不支持	允许的 HTTP 来源（默认 “*"）
`--app-id`	`--app-id`	`-i`	`dapr.io/app-id`	应用程序的唯一 ID。用于服务发现、状态封装和 pub/sub 消费者 ID
`--app-port`	`--app-port`	`-p`	`dapr.io/app-port`	指定应用程序监听的端口
`--components-path`	`--components-path`	`-d`	不支持	已弃用，建议使用 `--resources-path`
`--resources-path`	`--resources-path`	`-d`	不支持	组件目录的路径。如果为空，则不会加载组件
`--config`	`--config`	`-c`	`dapr.io/config`	指定 Dapr 使用的配置资源
`--control-plane-address`	不支持		不支持	Dapr 控制平面的地址
`--dapr-grpc-port`	`--dapr-grpc-port`		`dapr.io/grpc-port`	设置 Dapr API gRPC 端口（默认 `50001`）；所有集群服务必须使用相同的端口进行通信
`--dapr-http-port`	`--dapr-http-port`		不支持	Dapr API 监听的 HTTP 端口（默认 `3500`）
`--dapr-http-max-request-size`	`--dapr-http-max-request-size`		`dapr.io/http-max-request-size`	已弃用，建议使用 `--max-body-size`。增加请求最大主体大小以处理使用 http 和 grpc 协议的大文件上传。默认是 `4` MB
`--max-body-size`	不支持		`dapr.io/max-body-size`	增加请求最大主体大小以处理使用 http 和 grpc 协议的大文件上传。使用大小单位设置值（例如，`16Mi` 表示 16MB）。默认是 `4Mi`
`--dapr-http-read-buffer-size`	`--dapr-http-read-buffer-size`		`dapr.io/http-read-buffer-size`	已弃用，建议使用 `--read-buffer-size`。增加 http 头读取缓冲区的最大大小（以 KB 为单位）以支持更大的头值，例如 `16` 支持最大 16KB 的头。默认是 `16` 表示 16KB
`--read-buffer-size`	不支持		`dapr.io/read-buffer-size`	增加 http 头读取缓冲区的最大大小（以 KB 为单位）以支持更大的头值。使用大小单位设置值，例如 `32Ki` 将支持最大 32KB 的头。默认是 `4` 表示 4KB
不支持	`--image`		`dapr.io/sidecar-image`	Dapr sidecar 镜像。默认是 daprio/daprd:latest。Dapr sidecar 使用此镜像而不是最新的默认镜像。当构建您自己的 Dapr 自定义镜像或使用替代的稳定 Dapr 镜像时使用此选项
`--internal-grpc-port`	不支持		`dapr.io/internal-grpc-port`	设置内部 Dapr gRPC 端口（默认 `50002`）；所有集群服务必须使用相同的端口进行通信
`--enable-metrics`	不支持		配置规范	启用 prometheus 指标（默认 true）
`--enable-mtls`	不支持		配置规范	启用 daprd 到 daprd 通信通道的自动 mTLS
`--enable-profiling`	`--enable-profiling`		`dapr.io/enable-profiling`	启用分析
`--unix-domain-socket`	`--unix-domain-socket`	`-u`	`dapr.io/unix-domain-socket-path`	套接字文件的父目录。在 Linux 上，与 Dapr sidecar 通信时，使用 unix 域套接字以获得比 TCP 端口更低的延迟和更高的吞吐量。在 Windows 操作系统上不可用。
`--log-as-json`	不支持		`dapr.io/log-as-json`	将此参数设置为 `true` 输出JSON 格式的日志。默认是 `false`
`--log-level`	`--log-level`		`dapr.io/log-level`	设置 Dapr sidecar 的日志级别。允许的值是 `debug`、`info`、`warn`、`error`。默认是 `info`
`--enable-api-logging`	`--enable-api-logging`		`dapr.io/enable-api-logging`	为 Dapr sidecar 启用 API 日志记录
`--app-max-concurrency`	`--app-max-concurrency`		`dapr.io/app-max-concurrency`	限制应用程序的并发性。有效值是大于 `0` 的任何数字。默认值：`-1`，表示无并发。
`--metrics-port`	`--metrics-port`		`dapr.io/metrics-port`	设置 sidecar 指标服务器的端口。默认是 `9090`
`--mode`	不支持		不支持	Dapr 的运行时托管选项模式，可以是 `"standalone"` 或 `"kubernetes"`（默认 `"standalone"`）。了解更多。
`--placement-host-address`	`--placement-host-address`		`dapr.io/placement-host-address`	Dapr actor 放置服务器的地址列表，以逗号分隔。当未设置注解时，默认值由 Sidecar Injector 设置。当注解设置且值为单个空格（`' '`）或 “empty” 时，sidecar 不连接到放置服务器。这可以在 sidecar 中没有运行 actor 时使用。当注解设置且值不为空时，sidecar 连接到配置的地址。例如：`127.0.0.1:50057,127.0.0.1:50058`
`--scheduler-host-address`	`--scheduler-host-address`		`dapr.io/scheduler-host-address`	Dapr 调度服务器的地址列表，以逗号分隔。当未设置注解时，默认值由 Sidecar Injector 设置。当注解设置且值为单个空格（`' '`）或 “empty” 时，sidecar 不连接到调度服务器。当注解设置且值不为空时，sidecar 连接到配置的地址。例如：`127.0.0.1:50055,127.0.0.1:50056`
`--actors-service`	不支持		不支持	提供 actor 放置信息的服务的配置。格式为 `<name>:<address>`。例如，将此值设置为 `placement:127.0.0.1:50057,127.0.0.1:50058` 是使用 `--placement-host-address` 标志的替代方法。
`--reminders-service`	不支持		不支持	启用 actor 提醒的服务的配置。格式为 `<name>[:<address>]`。目前，唯一支持的值是 `"default"`（这也是默认值），它使用 Dapr sidecar 中的内置提醒子系统。
`--profiling-port`	`--profiling-port`		不支持	配置文件服务器的端口（默认 `7777`）
`--app-protocol`	`--app-protocol`	`-P`	`dapr.io/app-protocol`	配置 Dapr 用于与您的应用程序通信的协议。有效选项是 `http`、`grpc`、`https`（带 TLS 的 HTTP）、`grpcs`（带 TLS 的 gRPC）、`h2c`（HTTP/2 明文）。请注意，Dapr 不验证应用程序提供的 TLS 证书。默认是 `http`
`--enable-app-health-check`	`--enable-app-health-check`		`dapr.io/enable-app-health-check`	启用健康检查的布尔值。默认是 `false`。
`--app-health-check-path`	`--app-health-check-path`		`dapr.io/app-health-check-path`	当应用程序通道为 HTTP 时，Dapr 调用的健康探测路径（如果应用程序通道使用 gRPC，则忽略此值）。需要启用应用程序健康检查。默认是 `/healthz`。
`--app-health-probe-interval`	`--app-health-probe-interval`		`dapr.io/app-health-probe-interval`	每次健康探测之间的秒数。需要启用应用程序健康检查。默认是 `5`
`--app-health-probe-timeout`	`--app-health-probe-timeout`		`dapr.io/app-health-probe-timeout`	健康探测请求的超时时间（以毫秒为单位）。需要启用应用程序健康检查。默认是 `500`
`--app-health-threshold`	`--app-health-threshold`		`dapr.io/app-health-threshold"`	在应用程序被认为不健康之前的最大连续失败次数。需要启用应用程序健康检查。默认是 `3`
`--sentry-address`	`--sentry-address`		不支持	Sentry CA 服务的地址
`--version`	`--version`	`-v`	不支持	打印运行时版本
`--dapr-graceful-shutdown-seconds`	不支持		`dapr.io/graceful-shutdown-seconds`	Dapr 的优雅关闭持续时间（以秒为单位），在等待所有进行中的请求完成时的最大持续时间，然后强制关闭。默认是 `5`。如果您在 Kubernetes 模式下运行，此值不应大于 Kubernetes 终止宽限期，其默认值为 `30`。
`--dapr-block-shutdown-duration`	不支持		`dapr.io/block-shutdown-duration`	阻止关闭的持续时间。如果设置了此参数，优雅关闭过程（如上所述）将被延迟，直到给定的持续时间已过或应用程序变得不健康（通过应用程序健康选项配置）。这对于需要在其自身终止过程中执行 Dapr API 的应用程序很有用。一旦阻止过期，应用程序将无法再调用任何 Dapr API。接受 Go 持续时间字符串。
不支持	不支持		`dapr.io/enabled`	将此参数设置为 true 将 Dapr sidecar 注入到 pod 中
不支持	不支持		`dapr.io/api-token-secret`	指定 Dapr 使用哪个 Kubernetes secret 进行基于令牌的 API 认证。默认情况下未设置
不支持	不支持		`dapr.io/app-token-secret`	指定 Dapr 使用哪个 Kubernetes secret 进行基于令牌的应用程序认证。默认情况下未设置
`--dapr-listen-addresses`	不支持		`dapr.io/sidecar-listen-addresses`	sidecar 将监听的 IP 地址列表，以逗号分隔。在 standalone 模式下默认为所有。在 Kubernetes 中默认为 `[::1],127.0.0.1`。要监听所有 IPv4 地址，请使用 `0.0.0.0`。要监听所有 IPv6 地址，请使用 `[::]`。
不支持	不支持		`dapr.io/sidecar-cpu-limit`	Dapr sidecar 可以使用的最大 CPU 量。查看有效值这里。默认情况下未设置
不支持	不支持		`dapr.io/sidecar-memory-limit`	Dapr sidecar 可以使用的最大内存量。查看有效值这里。默认情况下未设置
不支持	不支持		`dapr.io/sidecar-cpu-request`	Dapr sidecar 请求的 CPU 量。查看有效值这里。默认情况下未设置
不支持	不支持		`dapr.io/sidecar-memory-request`	Dapr sidecar 请求的内存量。查看有效值这里。默认情况下未设置
不支持	不支持		`dapr.io/sidecar-liveness-probe-delay-seconds`	sidecar 容器启动后启动活跃性探测之前的秒数。阅读更多这里。默认是 `3`
不支持	不支持		`dapr.io/sidecar-liveness-probe-timeout-seconds`	sidecar 活跃性探测超时后的秒数。阅读更多这里。默认是 `3`
不支持	不支持		`dapr.io/sidecar-liveness-probe-period-seconds`	执行 sidecar 活跃性探测的频率（以秒为单位）。阅读更多这里。默认是 `6`
不支持	不支持		`dapr.io/sidecar-liveness-probe-threshold`	当 sidecar 活跃性探测失败时，Kubernetes 将尝试 N 次后放弃。在这种情况下，Pod 将被标记为不健康。阅读更多关于 `failureThreshold` 的信息这里。默认是 `3`
不支持	不支持		`dapr.io/sidecar-readiness-probe-delay-seconds`	sidecar 容器启动后启动就绪探测之前的秒数。阅读更多这里。默认是 `3`
不支持	不支持		`dapr.io/sidecar-readiness-probe-timeout-seconds`	sidecar 就绪探测超时后的秒数。阅读更多这里。默认是 `3`
不支持	不支持		`dapr.io/sidecar-readiness-probe-period-seconds`	执行 sidecar 就绪探测的频率（以秒为单位）。阅读更多这里。默认是 `6`
不支持	不支持		`dapr.io/sidecar-readiness-probe-threshold`	当 sidecar 就绪探测失败时，Kubernetes 将尝试 N 次后放弃。在这种情况下，Pod 将被标记为未就绪。阅读更多关于 `failureThreshold` 的信息这里。默认是 `3`
不支持	不支持		`dapr.io/env`	要注入到 sidecar 中的环境变量列表。由以逗号分隔的键=值对组成的字符串。
不支持	不支持		`dapr.io/env-from-secret`	从 secret 注入到 sidecar 中的环境变量列表。由 `"key=secret-name:secret-key"` 对组成的字符串以逗号分隔。
不支持	不支持		`dapr.io/volume-mounts`	以只读模式挂载到 sidecar 容器的 pod 卷列表。由 `volume:path` 对组成的字符串以逗号分隔。例如，`"volume-1:/tmp/mount1,volume-2:/home/root/mount2"`。
不支持	不支持		`dapr.io/volume-mounts-rw`	以读写模式挂载到 sidecar 容器的 pod 卷列表。由 `volume:path` 对组成的字符串以逗号分隔。例如，`"volume-1:/tmp/mount1,volume-2:/home/root/mount2"`。
`--disable-builtin-k8s-secret-store`	不支持		`dapr.io/disable-builtin-k8s-secret-store`	禁用内置 Kubernetes secret 存储。默认值为 false。有关详细信息，请参阅 Kubernetes secret 存储组件。
不支持	不支持		`dapr.io/sidecar-seccomp-profile-type`	将 sidecar 容器的 `securityContext.seccompProfile.type` 设置为 `Unconfined`、`RuntimeDefault` 或 `Localhost`。默认情况下，此注解未在 Dapr sidecar 上设置，因此该字段从 sidecar 容器中省略。

操作指南：构建有状态服务

Mon, 01 Jan 0001 00:00:00 +0000

在本文中，您将学习如何创建一个可以水平扩展的有状态服务，选择性使用并发和一致性模型。状态管理API可以帮助开发者简化状态协调、冲突解决和故障处理的复杂性。

设置状态存储

状态存储组件是Dapr用来与数据库通信的资源。在本指南中，我们将使用默认的Redis状态存储。

使用Dapr CLI

当您在本地模式下运行dapr init时，Dapr会创建一个默认的Redis statestore.yaml并在您的本地机器上运行一个Redis状态存储，位置如下：

在Windows上，位于%UserProfile%\.dapr\components\statestore.yaml
在Linux/MacOS上，位于~/.dapr/components/statestore.yaml

通过statestore.yaml组件，您可以轻松替换底层组件而无需更改应用程序代码。

查看支持的状态存储列表。

Kubernetes

查看如何在Kubernetes上设置不同的状态存储。

强一致性和最终一致性

在强一致性模式下，Dapr确保底层状态存储：

在数据写入所有副本后才返回响应。
在写入或删除状态之前从法定人数接收确认。

对于读取请求，Dapr确保在副本之间一致地返回最新的数据。默认情况下是最终一致性，除非在请求状态API时另有指定。

以下示例展示了如何使用强一致性保存、获取和删除状态。示例用Python编写，但适用于任何编程语言。

保存状态

import requests
import json

store_name = "redis-store" # 在状态存储组件yaml文件中指定的状态存储名称
dapr_state_url = "http://localhost:3500/v1.0/state/{}".format(store_name)
stateReq = '[{ "key": "k1", "value": "Some Data", "options": { "consistency": "strong" }}]'
response = requests.post(dapr_state_url, json=stateReq)

获取状态

import requests
import json

store_name = "redis-store" # 在状态存储组件yaml文件中指定的状态存储名称
dapr_state_url = "http://localhost:3500/v1.0/state/{}".format(store_name)
response = requests.get(dapr_state_url + "/key1", headers={"consistency":"strong"})
print(response.headers['ETag'])

删除状态

import requests
import json

store_name = "redis-store" # 在状态存储组件yaml文件中指定的状态存储名称
dapr_state_url = "http://localhost:3500/v1.0/state/{}".format(store_name)
response = requests.delete(dapr_state_url + "/key1", headers={"consistency":"strong"})

如果没有指定concurrency选项，默认是后写胜出并发模式。

先写胜出和后写胜出

Dapr允许开发者在使用数据存储时选择两种常见的并发模式：

先写胜出：在应用程序的多个实例同时写入同一个键的情况下很有用。
后写胜出：Dapr的默认模式。

Dapr使用版本号来确定特定键是否已更新。您可以：

在读取键的数据时保留版本号。
在更新（如写入和删除）时使用版本号。

如果自从检索版本号以来版本信息已更改，将抛出错误，要求您执行另一次读取以获取最新的版本信息和状态。

Dapr利用ETags来确定状态的版本号。ETags从状态请求中以ETag头返回。使用ETags，您的应用程序知道自上次检查以来资源已更新，因为在ETag不匹配时会出错。

以下示例展示了如何：

获取ETag。
使用ETag保存状态。
删除状态。

以下示例用Python编写，但适用于任何编程语言。

操作指南：使用输出绑定与外部资源交互

Mon, 01 Jan 0001 00:00:00 +0000

使用输出绑定，您可以与外部资源进行交互。在调用请求中，您可以发送可选的负载和元数据。

本指南以Kafka绑定为例。您可以从绑定组件列表中选择您偏好的绑定规范。在本指南中：

示例中调用了/binding端点，使用checkout作为要调用的绑定名称。
负载放在必需的data字段中，可以是任何JSON可序列化的值。
operation字段指定绑定需要执行的操作。例如，Kafka绑定支持create操作。
- 您可以查看每个输出绑定支持的操作（特定于每个组件）。

注意

如果您还没有尝试过，请尝试绑定快速入门，以快速了解如何使用bindings API。

创建绑定

创建一个binding.yaml文件，并将其保存到应用程序目录中的components子文件夹中。

创建一个名为checkout的新绑定组件。在metadata部分中，配置以下与Kafka相关的属性：

您将发布消息的主题
代理

在创建绑定组件时，指定绑定的支持direction。

使用dapr run的--resources-path标志指向您的自定义资源目录。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: checkout
spec:
 type: bindings.kafka
 version: v1
 metadata:
 # Kafka代理连接设置
 - name: brokers
 value: localhost:9092
 # 消费者配置：主题和消费者组
 - name: topics
 value: sample
 - name: consumerGroup
 value: group1
 # 发布者配置：主题
 - name: publishTopic
 value: sample
 - name: authRequired
 value: false
 - name: direction
 value: output

要将以下binding.yaml文件部署到Kubernetes集群中，运行kubectl apply -f binding.yaml。

在 Docker Compose 中调试 Dapr 应用

Mon, 01 Jan 0001 00:00:00 +0000

本文旨在介绍一种方法，如何通过你的 IDE 在本地调试一个或多个使用 Dapr 的应用，同时保持与其他通过 Docker Compose 部署的应用的集成。

我们以一个包含两个服务的 Docker Compose 文件的简单示例为例：

nodeapp - 你的应用
nodeapp-dapr - 你的 nodeapp 服务的 Dapr sidecar 进程

compose.yml

services:
 nodeapp:
 build: ./node
 ports:
 - "50001:50001"
 networks:
 - hello-dapr
 nodeapp-dapr:
 image: "daprio/daprd:edge"
 command: [
 "./daprd",
 "--app-id", "nodeapp",
 "--app-port", "3000",
 "--resources-path", "./components"
 ]
 volumes:
 - "./components/:/components"
 depends_on:
 - nodeapp
 network_mode: "service:nodeapp"
networks:
 hello-dapr

当你使用 docker compose -f compose.yml up 运行这个 Docker 文件时，它将部署到 Docker 并正常运行。

更新组件

Mon, 01 Jan 0001 00:00:00 +0000

在更新应用程序使用的现有已部署组件时，除非启用了 HotReload 功能门控，否则 Dapr 不会自动更新组件。需要重启 Dapr sidecar 才能获取组件的最新版本。具体操作方式取决于托管环境。

Kubernetes

在 Kubernetes 中运行时，更新组件的过程包括以下两个步骤：

将新的组件 YAML 应用到所需的命名空间。
除非启用了 HotReload 功能门控，否则需要对部署执行滚动重启操作以获取最新组件。

自托管

除非启用了 HotReload 功能门控，更新组件的过程包括停止和重启 daprd 进程以获取最新组件的单个步骤。

热重载（预览功能）

此功能目前处于预览状态。热重载通过 HotReload 功能门控启用。

Dapr 可以实现“热重载”组件，从而在不需要重启 Dapr sidecar 进程或 Kubernetes pod 的情况下自动获取组件更新。这意味着创建、更新或删除组件清单将在运行时反映在 Dapr sidecar 中。

更新组件

当组件更新时，它首先被关闭，然后使用新配置重新初始化。这会导致组件在此过程中短时间内不可用。

初始化错误

如果通过热重载创建或更新组件时初始化过程出错，Dapr sidecar 会遵循组件字段 spec.ignoreErrors 的设置。也就是说，行为与 sidecar 在启动时加载组件时相同。

spec.ignoreErrors=false (默认): sidecar 优雅地关闭。
spec.ignoreErrors=true: sidecar 继续运行，既没有注册旧的也没有注册新的组件配置。

除以下类型外，所有组件均支持热重载。这些组件类型的任何创建、更新或删除都将被 sidecar 忽略，需要重启以获取更改。

进一步阅读

工作流 API 参考

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 提供了与工作流交互的功能，并自带一个内置的 dapr 组件。

启动工作流请求

使用指定名称启动一个工作流实例，并可选地指定一个实例 ID。

POST http://localhost:3500/v1.0/workflows/<workflowComponentName>/<workflowName>/start[?instanceID=<instanceID>]

请注意，工作流实例 ID 只能包含字母、数字、下划线和破折号。

URL 参数

参数	描述
`workflowComponentName`	对于 Dapr 工作流使用 `dapr`
`workflowName`	标识工作流类型
`instanceID`	（可选）为特定工作流的每次运行创建的唯一值

请求内容

任何请求内容都将作为输入传递给工作流。Dapr API 会原样传递内容，不会尝试解释。

HTTP 响应代码

代码	描述
`202`	已接受
`400`	请求格式错误
`500`	请求格式正确，但 Dapr 代码或底层组件出错

响应内容

API 调用将返回如下的响应：

{
 "instanceID": "12345678"
}

终止工作流请求

终止具有指定名称和实例 ID 的正在运行的工作流实例。

POST http://localhost:3500/v1.0/workflows/<workflowComponentName>/<instanceId>/terminate

注意

终止一个工作流将同时终止该实例创建的所有子工作流。

终止一个工作流不会影响由该实例启动的任何正在进行的活动。

URL 参数

参数	描述
`workflowComponentName`	对于 Dapr 工作流使用 `dapr`
`instanceId`	为特定工作流的每次运行创建的唯一值

HTTP 响应代码

代码	描述
`202`	已接受
`400`	请求格式错误
`500`	请求格式正确，但 Dapr 代码或底层组件出错

响应内容

此 API 不返回任何内容。

目标

Mon, 01 Jan 0001 00:00:00 +0000

目标

命名的策略被应用于目标。Dapr支持三种目标类型，这些类型适用于所有Dapr构建块的API：

apps
components
actors

应用程序

使用apps目标，您可以将retry、timeout和circuitBreaker策略应用于Dapr应用程序之间的服务调用。在targets/apps下，策略应用于每个目标服务的app-id。当sidecar之间的通信出现故障时，这些策略将被调用，如下图所示。

Dapr提供了内置的服务调用重试，因此任何应用的retry策略都是额外的。

应用于目标应用程序app-id为"appB"的策略示例：

specs:
 targets:
 apps:
 appB: # 目标服务的app-id
 timeout: general
 retry: general
 circuitBreaker: general

组件

使用components目标，您可以将retry、timeout和circuitBreaker策略应用于组件操作。

策略可以应用于outbound操作（从Dapr sidecar到组件的调用）和/或inbound（从sidecar到您的应用程序的调用）。

出站

outbound操作是从sidecar到组件的调用，例如：

持久化或检索状态。
在pubsub组件上发布消息。
调用输出绑定。

某些组件可能具有内置的重试功能，并且可以在每个组件的基础上进行配置。

spec:
 targets:
 components:
 myStateStore:
 outbound:
 retry: retryForever
 circuitBreaker: simpleCB

入站

inbound操作是从sidecar到您的应用程序的调用，例如：

pubsub订阅在传递消息时。
输入绑定。

某些组件可能具有内置的重试功能，并且可以在每个组件的基础上进行配置。

spec:
 targets:
 components:
 myInputBinding:
 inbound: 
 timeout: general
 retry: general
 circuitBreaker: general

PubSub

在pubsub target/component中，您可以同时指定inbound和outbound操作。

组件

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 采用模块化设计，功能以组件形式提供。每个组件都有一个接口定义。所有组件都是可互换的，因此您可以用具有相同接口的另一个组件替换掉一个组件。

您可以通过以下方式贡献实现并扩展 Dapr 的组件接口功能：

一个构建块可以使用任意组合的组件。例如，actors 和 state management 构建块都使用 state 组件。

另一个例子是，pub/sub 构建块使用 pub/sub 组件。

您可以使用 dapr components CLI 命令获取当前在托管环境中可用的组件列表。

注意

对于任何向应用程序返回数据的组件，建议相应地设置 Dapr sidecar 的内存容量（进程或容器）以避免潜在的内存不足崩溃。例如，在 Docker 中使用 --memory 选项。在 Kubernetes 中，使用 dapr.io/sidecar-memory-limit 注释。对于进程，这取决于操作系统和/或进程编排工具。

组件规范

每个组件都有一个规范（或称为 spec）。组件在设计时通过一个 YAML 文件进行配置，该文件存储在以下位置之一：

您解决方案中的 components/local 文件夹，或
在调用 dapr init 时创建的 .dapr 文件夹中全局存储。

这些 YAML 文件遵循通用的 Dapr 组件架构，但每个文件都特定于组件规范。

重要的是要理解组件规范值，特别是规范 metadata，在相同组件类型的不同组件之间可能会有所不同，例如在不同的 state 存储之间，并且某些设计时规范值可以在运行时通过向组件的 API 发出请求来覆盖。因此，强烈建议查看组件的规范，特别注意用于设置与组件交互的元数据的请求示例负载。

下图显示了每种组件类型的一些组件示例

内置和可插拔组件

Dapr 具有作为运行时一部分包含的内置组件。这些是由社区开发和捐赠的公共组件，并在每个版本中可用。

Dapr 还允许用户创建自己的私有组件，称为可插拔组件。这些组件是自托管的（进程或容器），不需要用 Go 编写，存在于 Dapr 运行时之外，并能够“插入”到 Dapr 中以利用构建块 API。

操作指南：启用事务性 Outbox 模式

Mon, 01 Jan 0001 00:00:00 +0000

事务性 Outbox 模式是一种广为人知的设计模式，用于发送应用程序状态变化的通知。它通过一个跨越数据库和消息代理的单一事务来传递通知。

开发人员在尝试自行实现此模式时会遇到许多技术难题，通常需要编写复杂且容易出错的中央协调管理器，这些管理器最多支持一种或两种数据库和消息代理的组合。

例如，您可以使用 Outbox 模式来：

向账户数据库写入新的用户记录。
发送账户成功创建的通知消息。

通过 Dapr 的 Outbox 支持，您可以在调用 Dapr 的事务 API时通知订阅者应用程序的状态何时被创建或更新。

下图概述了 Outbox 功能的工作原理：

服务 A 使用事务将状态保存/更新到状态存储。
在同一事务下将消息写入消息代理。当消息成功传递到消息代理时，事务完成，确保状态和消息一起被事务化。
消息代理将消息主题传递给任何订阅者 - 在此情况下为服务 B。

要求

Outbox 功能可以与 Dapr 支持的任何事务性状态存储一起使用。所有发布/订阅代理都支持 Outbox 功能。

了解更多关于您可以使用的事务方法。

注意

建议与竞争消费者模式（例如，Apache Kafka）一起使用的消息代理减少重复事件的可能性。

启用 Outbox 模式

要启用 Outbox 功能，请在状态存储组件上添加以下必需和可选字段：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: mysql-outbox
spec:
 type: state.mysql
 version: v1
 metadata:
 - name: connectionString
 value: "<CONNECTION STRING>"
 - name: outboxPublishPubsub # 必需
 value: "mypubsub"
 - name: outboxPublishTopic # 必需
 value: "newOrder"
 - name: outboxPubsub # 可选
 value: "myOutboxPubsub"
 - name: outboxDiscardWhenMissingState # 可选，默认为 false
 value: false

元数据字段

名称	必需	默认值	描述
outboxPublishPubsub	是	N/A	设置发布状态更改时传递通知的发布/订阅组件的名称
outboxPublishTopic	是	N/A	设置接收在配置了 `outboxPublishPubsub` 的发布/订阅上的状态更改的主题。消息体将是 `insert` 或 `update` 操作的状态事务项
outboxPubsub	否	`outboxPublishPubsub`	设置 Dapr 用于协调状态和发布/订阅事务的发布/订阅组件。如果未设置，则使用配置了 `outboxPublishPubsub` 的发布/订阅组件。如果您希望将用于发送通知状态更改的发布/订阅组件与用于协调事务的组件分开，这将很有用
outboxDiscardWhenMissingState	否	`false`	通过将 `outboxDiscardWhenMissingState` 设置为 `true`，如果 Dapr 无法在数据库中找到状态且不重试，则 Dapr 将丢弃事务。如果在 Dapr 能够传递消息之前，状态存储数据因任何原因被删除，并且您希望 Dapr 从发布/订阅中删除项目并停止重试获取状态，此设置可能会很有用

其他配置

在同一状态存储上组合 Outbox 和非 Outbox 消息

如果您希望使用相同的状态存储来发送 Outbox 和非 Outbox 消息，只需定义两个连接到相同状态存储的状态存储组件，其中一个具有 Outbox 功能，另一个没有。

操作指南：在应用程序之间共享状态

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 提供了多种在应用程序之间共享状态的方法。

不同的架构在共享状态时可能有不同的需求。在某些情况下，您可能会希望：

在特定应用程序中封装所有状态
让 Dapr 为您管理状态访问

在其他情况下，您可能需要两个应用程序在同一状态上进行操作，以便获取和保存相同的键。

为了实现状态共享，Dapr 支持以下键前缀策略：

键前缀	描述
`appid`	默认策略，允许您仅通过指定 `appid` 的应用程序管理状态。所有状态键将以 `appid` 为前缀，并限定于该应用程序。
`name`	使用状态存储组件的名称作为前缀。多个应用程序可以共享同一状态存储中的相同状态。
`namespace`	如果设置了命名空间，此策略会将 `appid` 键前缀替换为配置的命名空间，生成一个限定于该命名空间的键。这允许在不同命名空间中具有相同 `appid` 的应用程序重用相同的状态存储。如果未配置命名空间，则会回退到 `appid` 策略。有关 Dapr 中命名空间的更多信息，请参见操作指南：将组件限定到一个或多个应用程序
`none`	不使用任何前缀。多个应用程序可以在不同的状态存储中共享状态，而不受特定前缀的限制。

指定状态前缀策略

要指定前缀策略，请在状态组件上添加名为 keyPrefix 的元数据键：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
 namespace: production
spec:
 type: state.redis
 version: v1
 metadata:
 - name: keyPrefix
 value: <key-prefix-strategy>

示例

以下示例演示了使用每种支持的前缀策略进行状态检索的情况。

`appid`（默认）

在下面的示例中，具有应用程序 ID myApp 的 Dapr 应用程序正在将状态保存到名为 redis 的状态存储中：

弹性

Mon, 01 Jan 0001 00:00:00 +0000

分布式应用程序通常由许多微服务组成，这些微服务在底层基础设施上可以扩展到数十个甚至数百个实例。随着这些分布式解决方案的规模和复杂性增加，系统故障的可能性也随之增加。服务实例可能由于硬件故障、意外的吞吐量或应用程序生命周期事件（如扩展和重启）等多种问题而失败或无响应。因此，设计和实施能够检测、缓解和响应故障的自愈解决方案至关重要。

弹性策略

Dapr允许您为应用程序定义和应用容错的弹性策略。您可以为以下弹性模式设定策略：

超时
重试/退避
断路器

这些策略可以在调用具有弹性规范的组件时应用于任何Dapr API调用。

应用健康检查

应用程序可能由于多种原因变得无响应，例如过于繁忙无法接受新任务、崩溃或死锁。有时这些问题可能是暂时的，也可能是持久的。

Dapr提供了一种通过探测来检查应用程序健康状况并对状态变化做出反应的机制。当检测到应用不健康时，Dapr会停止为该应用分配新任务。

阅读更多关于如何将应用健康检查应用于您的应用程序。

Sidecar健康检查

Dapr提供了一种通过HTTP /healthz 端点来确定其健康状况的方法。通过此端点，daprd进程或sidecar可以：

检查其健康状况
确定其准备就绪状态和存活状态

阅读更多关于如何将dapr健康检查应用于您的应用程序。

下一步

了解更多关于弹性
尝试其中一个弹性快速入门：
- 弹性：服务到服务
- 弹性：状态管理

应用和控制平面配置

Mon, 01 Jan 0001 00:00:00 +0000

通过 Dapr 配置，您可以通过设置和策略来更改：

单个 Dapr 应用程序的行为
Dapr 控制平面系统服务的全局行为

例如，您可以在应用程序的 sidecar 配置中设置采样率策略，以指定哪些方法可以被其他应用程序调用。如果您在 Dapr 控制平面配置中设置策略，您可以调整部署到应用程序 sidecar 实例的所有证书的更新周期。

配置以 YAML 文件的形式定义并部署。以下是一个应用程序配置示例，其中设置了一个跟踪端点，用于发送指标信息，并捕获所有的跟踪样本。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: daprConfig
 namespace: default
spec:
 tracing:
 samplingRate: "1"
 zipkin:
 endpointAddress: "http://localhost:9411/api/v2/spans"

上述 YAML 配置用于记录指标的跟踪。您可以通过以下方式在本地自托管模式中加载它：

编辑 .dapr 目录中的默认配置文件 config.yaml，或
使用 kubectl/helm 将其应用到您的 Kubernetes 集群。

以下示例展示了在 dapr-system 命名空间中名为 daprsystem 的 Dapr 控制平面配置。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: daprsystem
 namespace: dapr-system
spec:
 mtls:
 enabled: true
 workloadCertTTL: "24h"
 allowedClockSkew: "15m"

默认情况下，安装 Dapr 控制平面系统服务时会有一个名为 daprsystem 的单一配置文件。此配置文件应用全局控制平面设置，并在 Dapr 部署到 Kubernetes 时设置。

操作指南：将组件限定于一个或多个应用程序

Mon, 01 Jan 0001 00:00:00 +0000

Dapr组件具有命名空间（这与Kubernetes的命名空间概念不同），这意味着一个Dapr运行时实例只能访问部署在相同命名空间中的组件。

Dapr运行时，会将其配置的命名空间与加载的组件的命名空间进行匹配，并仅初始化与其命名空间匹配的组件。其他命名空间中的组件将不会被加载。

命名空间

命名空间可以用来限制组件对特定Dapr实例的访问。

在自托管模式下，开发者可以通过设置NAMESPACE环境变量来为Dapr实例指定命名空间。如果设置了NAMESPACE环境变量，Dapr将不会加载任何在其元数据中未指定相同命名空间的组件。

例如，假设在production命名空间中有以下组件：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
 namespace: production
spec:
 type: state.redis
 version: v1
 metadata:
 - name: redisHost
 value: redis-master:6379

要告诉Dapr它被部署到哪个命名空间，设置环境变量：

MacOS/Linux:

export NAMESPACE=production
# 像往常一样运行Dapr

Windows:

setx NAMESPACE "production"
# 像往常一样运行Dapr

让我们考虑以下在Kubernetes中的组件：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
 namespace: production
spec:
 type: state.redis
 version: v1
 metadata:
 - name: redisHost
 value: redis-master:6379

在这个例子中，Redis组件仅对运行在production命名空间内的Dapr实例可访问。

状态管理API参考

Mon, 01 Jan 0001 00:00:00 +0000

组件文件

Dapr的statestore.yaml组件文件结构如下：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
 namespace: <NAMESPACE>
spec:
 type: state.<TYPE>
 version: v1
 metadata:
 - name:<KEY>
 value:<VALUE>
 - name: <KEY>
 value: <VALUE>

设置	描述
`metadata.name`	状态存储的名称。
`spec/metadata`	一个开放的键值对元数据，允许绑定定义连接属性。

键方案

Dapr状态存储是键/值存储。Dapr要求这些数据存储遵循固定的键方案，以确保数据兼容性。对于一般状态，键格式为：

<App ID>||<state key>

对于actor状态，键格式为：

<App ID>||<Actor type>||<Actor id>||<state key>

保存状态

通过该端点可以保存一组状态对象。

HTTP请求

POST http://localhost:<daprPort>/v1.0/state/<storename>

URL参数

参数	描述
`daprPort`	Dapr端口
`storename`	用户配置的`statestore.yaml`组件文件中的`metadata.name`字段。请参阅上面提到的Dapr状态存储配置结构。

可选的请求元数据通过URL查询参数传递。例如，

POST http://localhost:3500/v1.0/state/myStore?metadata.contentType=application/json

所有URL参数区分大小写。

由于||是用作键方案中的分隔符，因此不能在<state key>字段中使用。

请求体

状态对象的JSON数组，每个状态对象包含以下字段：

字段	描述
`key`	状态键
`value`	状态值，可以是任何字节数组
`etag`	（可选）状态ETag
`metadata`	（可选）要传递给状态存储的附加键值对
`options`	（可选）状态操作选项；请参阅状态操作选项

ETag格式： Dapr运行时将ETags视为不透明字符串。确切的ETag格式由相应的数据存储定义。

操作指南：加密应用程序状态

Mon, 01 Jan 0001 00:00:00 +0000

对静态应用程序状态进行加密，以在企业工作负载或受监管环境中提供更强的安全性。Dapr 提供基于 AES 的自动客户端加密，采用 Galois/Counter Mode (GCM)，支持 128、192 和 256 位的密钥。

除了自动加密，Dapr 还支持主加密密钥和次加密密钥，使开发人员和运维团队更容易启用密钥轮换策略。此功能由所有 Dapr 状态存储支持。

加密密钥始终从 secret 中获取，不能在 metadata 部分中以明文形式提供。

启用自动加密

将以下 metadata 部分添加到任何 Dapr 支持的状态存储中：

metadata:
- name: primaryEncryptionKey
 secretKeyRef:
 name: mysecret
 key: mykey # key 是可选的。

例如，这是一个 Redis 加密状态存储的完整 YAML：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
spec:
 type: state.redis
 version: v1
 metadata:
 - name: redisHost
 value: localhost:6379
 - name: redisPassword
 value: ""
 - name: primaryEncryptionKey
 secretKeyRef:
 name: mysecret
 key: mykey

现在，您已配置了一个 Dapr 状态存储，以从名为 mysecret 的 secret 中获取加密密钥，其中包含名为 mykey 的实际加密密钥。

Bindings API 参考

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 为应用程序提供了双向绑定的功能，提供了一种与不同云服务或本地系统交互的统一方法。开发人员可以通过 Dapr API 调用输出绑定，并让 Dapr 运行时通过输入绑定来触发应用程序。

bindings 的示例包括 Kafka、Rabbit MQ、Azure Event Hubs、AWS SQS、GCP Storage 等。

Bindings 结构

一个 Dapr Binding 的 yaml 文件结构如下：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
 namespace: <NAMESPACE>
spec:
 type: bindings.<TYPE>
 version: v1
 metadata:
 - name: <NAME>
 value: <VALUE>

metadata.name 是绑定的名称。

如果在本地自托管运行，请将此文件放在 components 文件夹中，与状态存储和消息队列 yml 配置相邻。

如果在 Kubernetes 上运行，请将组件应用到您的集群中。

注意： 在生产环境中，切勿在 Dapr 组件文件中放置密码或秘密。有关使用 secret 存储安全存储和检索秘密的信息，请参阅设置 Secret Store

绑定方向（可选）

在某些情况下，向 Dapr 提供额外的信息以指示绑定组件支持的方向是有帮助的。

可观测性

Mon, 01 Jan 0001 00:00:00 +0000

在构建应用程序时，理解系统行为是操作应用程序的重要且具有挑战性的部分，例如：

观察应用程序的内部调用
评估其性能
在问题发生时立即意识到

对于由多个微服务组成的分布式系统来说，这尤其具有挑战性，因为一个由多个调用组成的流程可能在一个微服务中开始并在另一个微服务中继续。

在生产环境中，应用程序的可观测性至关重要，并且在开发过程中也很有用，以便：

理解瓶颈
提高性能
在微服务范围内进行基本调试

虽然可以从底层基础设施（如内存消耗、CPU使用率）中收集一些关于应用程序的数据点，但其他有意义的信息必须从“应用程序感知层”收集——这个层可以显示重要调用系列如何在微服务之间执行。通常，您需要添加一些代码来对应用程序进行检测，这些代码将收集的数据（如追踪和指标）发送到可观测性工具或服务，这些工具或服务可以帮助存储、可视化和分析所有这些信息。

维护这些检测代码（它们不是应用程序核心逻辑的一部分）需要理解可观测性工具的API，使用额外的SDK等。这种检测也可能为您的应用程序带来可移植性挑战，要求根据应用程序的部署位置进行不同的检测。例如：

不同的云提供商提供不同的可观测性工具
本地部署可能需要自托管解决方案

使用Dapr实现应用程序的可观测性

当您利用Dapr API构建块进行服务间调用、发布/订阅消息传递和其他API时，Dapr在分布式追踪方面提供了优势。由于这种服务间通信通过Dapr运行时（或“sidecar”）流动，Dapr处于一个独特的位置，可以减轻应用程序级别检测的负担。

分布式追踪

Dapr可以使用广泛采用的Open Telemetry (OTEL)和Zipkin协议配置以发出追踪数据。这使得它可以轻松集成到多个可观测性工具中。

自动追踪上下文生成

Dapr使用W3C追踪规范作为追踪上下文的一部分，包含在Open Telemetry (OTEL)中，用于生成和传播应用程序的上下文头或传播用户提供的上下文头。这意味着您可以默认获得Dapr的追踪功能。

Dapr sidecar和控制平面的可观测性

您还可以通过以下方式观察Dapr本身：

生成由Dapr sidecar和Dapr控制平面服务发出的日志
收集性能、吞吐量和延迟的指标
使用健康端点探测来指示Dapr sidecar的健康状态

日志记录

Dapr生成日志以：

提供对sidecar操作的可见性
帮助用户识别问题并进行调试

日志事件包含由Dapr系统服务生成的警告、错误、信息和调试消息。您还可以配置Dapr将日志发送到收集器，如Open Telemetry Collector、Fluentd、New Relic、Azure Monitor和其他可观测性工具，以便可以搜索和分析日志以提供见解。

指标

指标是一系列测量值和计数，随着时间的推移被收集和存储。Dapr指标提供监控能力，以理解Dapr sidecar和控制平面的行为。例如，Dapr sidecar和用户应用程序之间的指标显示调用延迟、流量失败、请求错误率等。

Dapr 控制平面指标显示sidecar注入失败和控制平面服务的健康状况，包括CPU使用率、actor放置的数量等。

健康检查

Dapr sidecar公开了一个HTTP端点用于健康检查。通过这个API，用户代码或托管环境可以探测Dapr sidecar以确定其状态并识别sidecar准备就绪的问题。

相反，Dapr可以配置为探测您的应用程序的健康状况，并对应用程序健康状况的变化做出反应，包括停止pub/sub订阅和短路服务调用。

下一步

操作指南：在组件中引用secret

Mon, 01 Jan 0001 00:00:00 +0000

概述

在组件定义的spec.metadata部分中，可以引用secret。

要引用secret，你需要设置auth.secretStore字段来指定保存secret的secret存储的名称。

在Kubernetes中运行时，如果auth.secretStore为空，则默认使用Kubernetes secret存储。

支持的secret存储

访问此链接查看Dapr支持的所有secret存储，以及如何配置和使用它们的信息。

引用secret

虽然你可以选择使用纯文本secret（如MyPassword），如下面yaml中redisPassword的value所示，但这不建议用于生产环境：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
spec:
 type: state.redis
 version: v1
 metadata:
 - name: redisHost
 value: localhost:6379
 - name: redisPassword
 value: MyPassword

相反，建议在你的secret存储中创建secret并在组件定义中引用它。下面展示了两种情况——“secret包含嵌入的key”和“secret是一个字符串”。

“secret包含嵌入的key”适用于secret中嵌入了一个key的情况，即secret不是一个完整的连接字符串。这在以下组件定义yaml中展示。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
spec:
 type: state.redis
 version: v1
 metadata:
 - name: redisHost
 value: localhost:6379
 - name: redisPassword
 secretKeyRef:
 name: redis-secret
 key: redis-password
auth:
 secretStore: <SECRET_STORE_NAME>

SECRET_STORE_NAME是配置的secret存储组件的名称。在Kubernetes中运行并使用Kubernetes secret存储时，字段auth.SecretStore默认为kubernetes，可以留空。

状态生存时间 (TTL)

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 允许为每个状态设置生存时间 (TTL)。这意味着应用程序可以为存储的每个状态指定一个生存时间，过期后将无法检索这些状态。

对于支持的状态存储，只需在发布消息时设置 ttlInSeconds 元数据。其他状态存储将忽略此值。对于某些状态存储，您可以为每个表或容器指定默认的过期时间。

原生状态 TTL 支持

当状态存储组件原生支持状态 TTL 时，Dapr 会直接传递 TTL 配置，而不添加额外的逻辑，从而保持行为的一致性。这在组件以不同方式处理过期状态时尤为有用。

如果未指定 TTL，将保留状态存储的默认行为。

显式持久化绕过全局定义的 TTL

对于允许为所有数据指定默认 TTL 的状态存储，持久化状态的方式包括：

通过 Dapr 组件设置全局 TTL 值，或
在 Dapr 之外创建状态存储并设置全局 TTL 值。

如果未指定特定的 TTL，数据将在全局 TTL 时间段后过期，这不是由 Dapr 直接控制的。

此外，所有状态存储还支持显式持久化数据的选项。这意味着您可以忽略默认的数据库策略（可能是在 Dapr 之外或通过 Dapr 组件设置的），以无限期保留特定的数据库记录。您可以通过将 ttlInSeconds 设置为 -1 来实现，这表示忽略任何设置的 TTL 值。

支持的组件

请参阅状态存储组件指南中的 TTL 列。

示例

您可以在状态存储请求的元数据中设置状态 TTL：

# 依赖

from dapr.clients import DaprClient

# 代码

DAPR_STORE_NAME = "statestore"

with DaprClient() as client:
 client.save_state(DAPR_STORE_NAME, "order_1", str(orderId), state_metadata={
 'ttlInSeconds': '120'
 })

要启动 Dapr sidecar 并运行上述示例应用程序，您可以运行类似以下的命令：

Actors API 参考

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 提供了原生、跨平台和跨语言的虚拟 actor 功能。除了特定语言的 SDK，开发者还可以使用以下 API 端点来调用 actor。

用户服务代码调用 Dapr

调用 actor 方法

使用 Dapr 调用 actor 方法。

HTTP 请求

POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/method/<method>

HTTP 响应代码

代码	描述
200	请求成功
500	请求失败
XXX	上游调用的状态码

URL 参数

参数	描述
`daprPort`	Dapr 端口。
`actorType`	actor 类型。
`actorId`	actor ID。
`method`	要调用的方法名称。

注意，所有 URL 参数区分大小写。

示例

调用 actor 上的方法示例：

curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/method/shoot \
 -H "Content-Type: application/json"

您可以在请求体中提供方法参数和值，例如在 curl 中使用 -d "{\"param\":\"value\"}"。调用带参数的 actor 方法示例：

curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
 -H "Content-Type: application/json" \
 -d '{
 "destination": "Hoth"
 }'

或

安全性

Mon, 01 Jan 0001 00:00:00 +0000

安全性是Dapr的核心。本文介绍了在分布式应用中使用Dapr时的安全特性和功能。这些可以分为以下几类：

使用service-invocation和pubsub API进行安全通信。
通过配置应用于组件的安全策略。
操作安全实践。
状态安全，专注于静态数据。

一个示例应用程序用于说明Dapr中可用的多种安全特性。

安全通信

Dapr通过service-invocation API提供端到端的安全性，支持应用程序身份验证并设置访问策略。下图展示了这一点。

service-invocation范围访问策略

Dapr应用程序可以被限定在命名空间中进行部署和安全管理。您可以在不同命名空间的服务之间进行调用。阅读跨命名空间的service-invocation以获取更多信息。

Dapr应用程序可以限制哪些操作可以被调用，包括哪些应用程序被允许（或拒绝）调用它。阅读如何：为service-invocation应用访问控制列表配置以获取更多信息。

pubsub主题范围访问策略

对于pubsub组件，您可以限制哪些主题类型和应用程序被允许发布和订阅特定主题。阅读范围pubsub主题访问以获取更多信息。

使用mTLS加密数据

Dapr使用的一种加密传输中数据的安全机制是双向认证TLS或mTLS。mTLS为应用程序内部的网络流量提供了一些关键特性：

双向认证，客户端和服务器相互验证身份。
加密通道，用于所有在途通信，在建立双向认证后。

mTLS在几乎所有场景中都很有用，尤其是对于需要遵循法规的系统，如HIPAA和PCI。

Dapr之间的安全通信

在生产系统中，Dapr无需额外代码或复杂配置即可启用mTLS。此外，Dapr sidecar默认只允许localhost访问，阻止其他IP地址，除非明确配置。

Dapr包含一个“默认开启”的自动mTLS，为Dapr sidecar之间的流量提供在途加密。为实现这一点，Dapr利用一个名为Sentry的系统服务，该服务充当证书颁发机构（CA）/身份提供者，并签署来自Dapr sidecar的工作负载（应用程序）证书请求。

默认情况下，工作负载证书有效期为24小时，时钟偏差设置为15分钟。

除非您提供了现有的根证书，否则Sentry服务会自动创建并持久化有效期为一年的自签名根证书。Dapr管理工作负载证书的轮换；如果您自带证书，Dapr会在不影响应用程序正常运行的情况下进行。

当根证书被替换时（Kubernetes模式下为secret，自托管模式下为文件系统），Sentry会获取它们并重建信任链，无需重启且对Sentry无停机时间。

当一个新的Dapr sidecar初始化时，它会检查是否启用了mTLS。如果是，则生成一个ECDSA私钥和证书签名请求，并通过gRPC接口发送给Sentry。Dapr sidecar和Sentry之间的通信使用信任链证书进行认证，该证书由Dapr Sidecar Injector系统服务注入到每个Dapr实例中。

配置mTLS

可以通过编辑Dapr部署的默认配置中的spec.mtls.enabled字段来开启/关闭mTLS。

您可以在Kubernetes和自托管模式下进行此操作。

自托管模式下的mTLS

下图显示了Sentry系统服务如何根据操作员提供的或由Sentry服务生成并存储在文件中的根/颁发者证书为应用程序颁发证书。

Kubernetes模式下的mTLS

在Kubernetes集群中，保存根证书的secret是：

限定在部署Dapr组件的命名空间中。
仅由Dapr控制平面系统pod访问。

Dapr在Kubernetes上部署时还支持强身份验证，依赖于作为证书签名请求（CSR）一部分发送给Sentry的pod的服务账户令牌。

下图显示了Sentry系统服务如何根据操作员提供的或由Sentry服务生成并存储为Kubernetes secret的根/颁发者证书为应用程序颁发证书。

防止Dapr被IP地址访问

为了防止Dapr sidecar在任何IP地址上被调用（尤其是在Kubernetes等生产环境中），Dapr将其监听IP地址限制为localhost。如果您需要启用外部地址的访问，请使用dapr-listen-addresses设置。

安全的Dapr到应用程序通信

Dapr sidecar通过localhost运行在应用程序附近，建议在与应用程序相同的网络边界内运行。虽然许多现代云原生系统将pod级别（例如在Kubernetes上）视为可信的安全边界，但Dapr通过令牌为应用程序提供API级别的身份验证。此功能保证，即使在localhost上：

只有经过身份验证的应用程序可以调用Dapr
应用程序可以检查Dapr是否在回调它

有关配置API令牌安全性的更多详细信息，请阅读：

安全的Dapr到控制平面通信

除了Dapr sidecar之间的自动mTLS，Dapr还提供以下之间的强制mTLS：

Dapr sidecar
Dapr控制平面系统服务，即：
- Sentry服务（证书颁发机构）
- Placement服务（actor放置）
- Kubernetes Operator服务

当启用mTLS时，Sentry将根和颁发者证书写入限定在安装控制平面的命名空间的Kubernetes secret中。在自托管模式下，Sentry将证书写入可配置的文件系统路径。

状态存储组件

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 集成现有数据库，为应用提供 CRUD 操作、事务等状态管理功能。它还支持为每个应用配置多个独立的状态存储组件。

状态存储具有可扩展性，可以在 components-contrib 仓库中找到。

在 Dapr 中，状态存储通过 Component 文件进行描述：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
spec:
 type: state.<DATABASE>
 version: v1
 metadata:
 - name: <KEY>
 value: <VALUE>
 - name: <KEY>
 value: <VALUE>
...

数据库的类型由 type 字段决定，连接字符串和其他元数据信息放在 .metadata 部分。即使元数据值可以包含明文的密钥，仍建议使用密钥存储。

请参考本指南了解如何配置状态存储组件。

支持的状态存储

请访问此参考查看 Dapr 中支持的所有状态存储。

Secrets API 参考

Mon, 01 Jan 0001 00:00:00 +0000

获取 Secret

此接口允许您获取指定 secret 存储中的 secret 值。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/secrets/<secret-store-name>/<name>

URL 参数

参数	描述
daprPort	Dapr 端口
secret-store-name	要从中获取 secret 的 secret 存储名称
name	要获取的 secret 名称

请注意，所有 URL 参数区分大小写。

查询参数

某些 secret 存储支持可选的、每个请求的元数据属性。您可以通过查询参数来提供这些属性。例如：

GET http://localhost:<daprPort>/v1.0/secrets/<secret-store-name>/<name>?metadata.version_id=15

请注意，并非所有 secret 存储都支持相同的参数集。例如：

Hashicorp Vault、GCP Secret Manager 和 AWS Secret Manager 支持 version_id 参数
只有 AWS Secret Manager 支持 version_stage 参数
只有 Kubernetes Secrets 支持 namespace 参数请查阅每个 secret 存储的文档以获取支持的参数列表。

HTTP 响应

响应体

如果 secret 存储支持 secret 中的多个键值，将返回一个 JSON 负载，其中键名作为字段及其各自的值。

隔离

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 的命名空间功能提供了隔离和多租户支持，增强了安全性。通常，应用程序和组件会被部署到命名空间中，以便在特定环境中实现隔离，例如在 Kubernetes 中。

Dapr 支持在以下场景中使用命名空间：应用程序之间的服务调用、访问组件、在消费者组中发送 pubsub 消息以及 actor 类型的部署。无论是在自托管模式还是 Kubernetes 模式下，命名空间隔离都受到支持。

要开始使用，请先创建并配置您的命名空间。

在自托管模式下，通过设置 NAMESPACE 环境变量为 Dapr 实例指定命名空间。

在 Kubernetes 上，创建并配置命名空间：

kubectl create namespace namespaceA
kubectl config set-context --current --namespace=namespaceA

然后将您的应用程序部署到此命名空间中。

了解如何在 Dapr 中全面使用命名空间：

Secret 存储组件

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 集成了 Secret 存储，为应用程序和其他组件提供安全的 Secret 存储和访问，例如访问密钥和密码。每个 Secret 存储组件都有一个名称，用于访问 Secret 时使用。

与其他构建块组件类似，Secret 存储组件是可扩展的，相关代码可以在 components-contrib 仓库中找到。

在 Dapr 中，Secret 存储通过一个 Component 文件进行描述，包含以下字段：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: secretstore
spec:
 type: secretstores.<NAME>
 version: v1
 metadata:
 - name: <KEY>
 value: <VALUE>
 - name: <KEY>
 value: <VALUE>
...

Secret 存储的类型由 type 字段指定，连接字符串和其他元数据信息放在 .metadata 部分。

不同的支持的 Secret 存储会有不同的特定字段需要配置。例如，配置使用 AWS Secrets Manager 的 Secret 存储时，文件格式如下：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: awssecretmanager
spec:
 type: secretstores.aws.secretmanager
 version: v1
 metadata:
 - name: region
 value: "[aws_region]"
 - name: accessKey
 value: "[aws_access_key]"
 - name: secretKey
 value: "[aws_secret_key]"
 - name: sessionToken
 value: "[aws_session_token]"

重要

在 EKS (AWS Kubernetes) 上运行 Dapr sidecar (daprd) 时，如果节点/Pod 已附加了允许访问 AWS 资源的 IAM 策略，则不应在组件配置中提供 AWS access-key、secret-key 和 tokens。

应用配置

创建组件的 YAML 文件后，请根据您的托管环境按照以下说明应用它：

配置 API 参考

Mon, 01 Jan 0001 00:00:00 +0000

获取配置

该端点用于从存储中获取配置。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/configuration/<storename>

URL 参数

参数	描述
`daprPort`	Dapr 端口
`storename`	`metadata.name` 字段组件文件。请参阅组件规范

查询参数

如果不提供查询参数，将返回所有配置项。要指定需要获取的配置项的键，请使用一个或多个 key 查询参数。例如：

GET http://localhost:<daprPort>/v1.0/configuration/mystore?key=config1&key=config2

要检索所有配置项：

GET http://localhost:<daprPort>/v1.0/configuration/mystore

请求体

无

HTTP 响应

响应代码

代码	描述
`204`	获取操作成功
`400`	配置存储缺失或配置错误或请求格式错误
`500`	获取配置失败

响应体

每个配置项的键/值对的 JSON 编码值。

示例

curl -X GET 'http://localhost:3500/v1.0/configuration/mystore?key=myConfigKey'

上述命令返回以下 JSON：

{
 "myConfigKey": {
 "value":"myConfigValue"
 }
}

订阅配置

该端点用于订阅配置更改。当配置存储中的值被更新或删除时，会发送通知。这使应用程序能够对配置更改做出反应。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/configuration/<storename>/subscribe

URL 参数

参数	描述
`daprPort`	Dapr 端口
`storename`	`metadata.name` 字段组件文件。请参阅组件规范

查询参数

如果不提供查询参数，将订阅所有配置项。要指定需要订阅的配置项的键，请使用一个或多个 key 查询参数。例如：

Bindings 组件

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 可以与外部资源集成，使应用程序既能被外部事件触发，也能与资源进行交互。每个 bindings 组件都有一个名称，用于与资源进行交互时使用。

与其他构建块组件一样，bindings 组件是可扩展的，相关代码可以在 components-contrib 仓库中找到。

在 Dapr 中，bindings 使用一个 Component 文件描述，包含以下字段：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
 namespace: <NAMESPACE>
spec:
 type: bindings.<NAME>
 version: v1
 metadata:
 - name: <KEY>
 value: <VALUE>
 - name: <KEY>
 value: <VALUE>
...

bindings 的类型由 type 字段指定，连接字符串和其他元数据则在 .metadata 部分定义。

不同的支持的 bindings会有不同的特定字段需要配置。例如，当为 Azure Blob Storage 配置 bindings 时，文件看起来像这样：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.azure.blobstorage
 version: v1
 metadata:
 - name: storageAccount
 value: myStorageAccountName
 - name: storageAccessKey
 value: ***********
 - name: container
 value: container1
 - name: decodeBase64
 value: <bool>
 - name: getBlobRetryCount
 value: <integer>

应用配置

一旦创建了组件的 YAML 文件，请根据您的托管环境按照以下步骤进行配置：

分布式锁 API 参考

Mon, 01 Jan 0001 00:00:00 +0000

锁

通过此端点，您可以通过提供锁所有者的名称和要锁定的资源 ID 来获取锁。

HTTP 请求

POST http://localhost:<daprPort>/v1.0-alpha1/lock/<storename>

URL 参数

参数	描述
`daprPort`	Dapr 端口
`storename`	`metadata.name` 字段的组件文件。请参阅组件模式

查询参数

无

HTTP 响应代码

代码	描述
200	请求成功
204	空响应
400	请求格式错误
500	请求失败

HTTP 请求体

锁端点需要接收以下 JSON 负载：

{
 "resourceId": "",
 "lockOwner": "",
 "expiryInSeconds": 0
}

字段	描述
resourceId	要锁定的资源 ID。可以是任何值
lockOwner	锁所有者的名称。每次请求都应设置为唯一值
expiryInSeconds	锁定在过期前保持的时间（秒）

HTTP 响应体

锁端点会返回以下负载：

{
 "success": true
}

示例

curl -X POST http://localhost:3500/v1.0-alpha/lock/redisStore \
 -H "Content-Type: application/json" \
 -d '{
 "resourceId": "lock1",
 "lockOwner": "vader",
 "expiryInSeconds": 60
 }'

{
 "success": "true"
}

解锁

通过此端点，您可以根据锁所有者和资源 ID 解锁现有锁。

使用 OpenTelemetry Collector 收集追踪

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 推荐使用 OpenTelemetry (OTLP) 协议来写入追踪数据。对于直接支持 OTLP 的可观测性工具，建议使用 OpenTelemetry Collector，因为它可以快速卸载数据，并提供重试、批处理和加密等功能。更多信息请参阅 Open Telemetry Collector 的文档。

Dapr 也支持使用 Zipkin 协议来写入追踪数据。在 OTLP 协议支持之前，Zipkin 协议与 OpenTelemetry Collector 一起使用，以将追踪数据发送到 AWS X-Ray、Google Cloud Operations Suite 和 Azure Monitor 等可观测性工具。虽然两种协议都有效，但推荐使用 OpenTelemetry 协议。

先决条件

在 Kubernetes 上安装 Dapr
确保您的追踪后端已准备好接收追踪数据
查看 OTEL Collector 导出器所需的参数：
- opentelemetry-collector-contrib/exporter
- opentelemetry-collector/exporter

配置 OTEL Collector 推送追踪数据到您的后端

查看 open-telemetry-collector-generic.yaml。
将 <your-exporter-here> 替换为您的追踪导出器的实际配置。
- 请参考先决条件部分中的 OTEL Collector 链接以获取正确的配置。

使用以下命令应用配置：

kubectl apply -f open-telemetry-collector-generic.yaml

配置 Dapr 发送追踪数据到 OTEL Collector

创建一个 Dapr 配置文件以启用追踪，并部署一个使用 OpenTelemetry Collector 的追踪导出器组件。

Azure Cosmos DB

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 在保存和检索状态时不对状态值进行转换。Dapr 要求所有状态存储实现遵循特定的键格式规范（参见状态管理规范）。您可以直接与底层存储交互以操作状态数据，例如：

查询状态。
创建聚合视图。
进行备份。

注意

Azure Cosmos DB 是一个支持多种 API 的多模式数据库。默认的 Dapr Cosmos DB 状态存储实现使用 Azure Cosmos DB SQL API。

连接到 Azure Cosmos DB

要连接到您的 Cosmos DB 实例，您可以：

使用 Azure 管理门户上的数据资源管理器。
使用各种 SDK 和工具。

注意

当您为 Dapr 配置 Azure Cosmos DB 时，请指定要使用的具体数据库和集合。以下 Cosmos DB SQL API 示例假设您已连接到正确的数据库和名为 “states” 的集合。

按应用程序 ID 列出键

要获取与应用程序 “myapp” 关联的所有状态键，请使用查询：

SELECT * FROM states WHERE CONTAINS(states.id, 'myapp||')

上述查询返回所有 id 包含 “myapp||” 的文档，这是状态键的前缀。

获取特定状态数据

要通过键 “balance” 获取应用程序 “myapp” 的状态数据，请使用查询：

在 Kubernetes 上调试 Dapr 控制平面

Mon, 01 Jan 0001 00:00:00 +0000

概述

有时我们需要了解 Dapr 控制平面（即 Kubernetes 服务）的运行情况，包括 dapr-sidecar-injector、dapr-operator、dapr-placement 和 dapr-sentry，特别是在诊断 Dapr 应用程序时，想知道 Dapr 本身是否存在问题。此外，您可能正在为 Kubernetes 上的 Dapr 开发新功能，并希望调试您的代码。

本指南将介绍如何使用 Dapr 调试二进制文件来调试 Kubernetes 集群上的 Dapr 服务。

调试 Dapr Kubernetes 服务

前置条件

熟悉本指南以了解如何将 Dapr 部署到您的 Kubernetes 集群。
设置您的开发环境
Helm

1. 构建 Dapr 调试二进制文件

为了调试 Dapr Kubernetes 服务，需要重新构建所有 Dapr 二进制文件和 Docker 镜像以禁用编译器优化。为此，执行以下命令：

git clone https://github.com/dapr/dapr.git
cd dapr
make release GOOS=linux GOARCH=amd64 DEBUG=1

在 Windows 上下载 MingGW 并使用 ming32-make.exe 替代 make。

在上述命令中，通过将 ‘DEBUG’ 设置为 ‘1’ 来禁用编译器优化。‘GOOS=linux’ 和 ‘GOARCH=amd64’ 也是必要的，因为二进制文件将在下一步中打包到基于 Linux 的 Docker 镜像中。

设置 Minikube 集群

Mon, 01 Jan 0001 00:00:00 +0000

前提条件

安装：
- Docker
- kubectl
- Minikube
对于 Windows：
- 在 BIOS 中启用虚拟化
- 安装 Hyper-V

注意

查看 [Minikube 官方文档] 以了解有关驱动程序的详细信息和插件安装方法。

启动 Minikube 集群

如果您的项目需要，设置默认的虚拟机。
```
minikube config set vm-driver [driver_name]
```
启动集群。如果需要，使用 --kubernetes-version 指定 Kubernetes 1.13.x 或更新版本。
```
minikube start --cpus=4 --memory=4096
```

启用 Minikube 仪表板和 ingress 插件。

# 启用仪表板
minikube addons enable dashboard

# 启用 ingress
minikube addons enable ingress

安装 Helm v3（可选）

如果您使用 Helm，安装 Helm v3 客户端。

重要

最新的 Dapr Helm chart 不再支持 Helm v2。从 Helm v2 迁移到 Helm v3。

故障排除

负载均衡器的外部 IP 地址在 kubectl get svc 中未显示。

mtls export CLI 命令参考

Mon, 01 Jan 0001 00:00:00 +0000

描述

将根证书颁发机构（CA）、颁发者证书和密钥导出到本地文件中

适用平台

Kubernetes

用法

dapr mtls export [flags]

标志

名称	环境变量	默认值	描述
`--help`, `-h`			导出命令的帮助信息
`--out`, `-o`		当前目录	证书保存的输出目录路径

示例

# 检查 Kubernetes 证书的到期时间
dapr mtls export -o ./certs

警告信息

此命令可能会发出警告信息。

根证书更新警告

如果部署到 Kubernetes 集群的 mtls 根证书在 30 天内到期，将显示以下警告信息：

您的 Kubernetes 集群的 Dapr 根证书将在 <n> 天后到期。到期日期：<date:time> UTC。
请访问 docs.dapr.io 获取证书更新说明，以避免服务中断。

版本控制政策

Mon, 01 Jan 0001 00:00:00 +0000

介绍

Dapr 通过版本控制方案为未来的运行时、API 和组件的变化做好了设计。本主题描述了 API、组件和 Github 仓库的版本控制方案和策略。

版本控制

版本控制是为计算机软件的每个独特状态分配唯一版本名称或版本号的过程。

版本控制提供兼容性、明确的变更控制，并处理变更，尤其是重大变更。
Dapr 力求保持向后兼容性。如果需要重大变更，将会提前宣布。
废弃的功能将在多个版本中逐步淘汰，新旧功能将并行工作。

版本控制涉及以下 Dapr 仓库：dapr、CLI、稳定语言 SDK、dashboard、components-contrib、quickstarts、helm-charts 和文档。

Dapr 具有以下版本控制方案：

Dapr HTTP API 采用 MAJOR.MINOR 版本控制
Dapr GRPC API 采用 MAJOR 版本控制
发布版本（包括 GitHub 仓库中的 dapr、CLI、SDK 和 Helm Chart）采用 MAJOR.MINOR.PATCH 版本控制
文档和 Quickstarts 仓库与 Dapr 运行时仓库版本控制一致。
Dapr 组件 在 components-contrib GitHub 仓库中采用 MAJOR 版本控制。
Dapr 清单 采用 MAJOR.MINOR 版本控制。这些包括订阅和配置。

请注意，Dapr 的 API、二进制发布（运行时、CLI、SDK）和组件都是相互独立的。

Dapr HTTP API

Dapr HTTP API 根据这些REST API 指南进行版本控制。

运行 Dapr 时的常见问题

Mon, 01 Jan 0001 00:00:00 +0000

本指南涵盖了安装和运行 Dapr 时可能遇到的常见问题。

安装 Dapr CLI 时 Dapr 无法连接到 Docker

在安装和初始化 Dapr CLI 时，如果在运行 dapr init 后看到以下错误信息：

⌛ 正在进行初始化...
❌ 无法连接到 Docker。Docker 可能未安装或未运行

请通过以下步骤进行排查：

确保容器正确运行。
在 Docker Desktop 中，确认已选择 允许使用默认 Docker 套接字（需要密码） 选项。

我没有看到 Dapr sidecar 注入到我的 pod 中

sidecar 未注入到 pod 中可能有多种原因。首先，检查您的部署或 pod YAML 文件，确保在正确的位置有以下注释：

annotations:
 dapr.io/enabled: "true"
 dapr.io/app-id: "nodeapp"
 dapr.io/app-port: "3000"

示例部署：

apiVersion: apps/v1
kind: Deployment
metadata:
 name: nodeapp
 namespace: default
 labels:
 app: node
spec:
 replicas: 1
 selector:
 matchLabels:
 app: node
 template:
 metadata:
 labels:
 app: node
 annotations:
 dapr.io/enabled: "true"
 dapr.io/app-id: "nodeapp"
 dapr.io/app-port: "3000"
 spec:
 containers:
 - name: node
 image: dapriosamples/hello-k8s-node
 ports:
 - containerPort: 3000
 imagePullPolicy: Always

在某些情况下，这可能无法正常工作：

单元测试

Mon, 01 Jan 0001 00:00:00 +0000

在 PHP SDK 中，单元测试和集成测试是非常重要的组成部分。通过使用依赖注入容器、模拟、存根以及提供的 \Dapr\Mocks\TestClient，可以实现非常精细的测试。

测试 Actor

在测试 Actor 时，我们主要关注两个方面：

基于初始状态的返回结果
基于初始状态的结果状态

以下是一个简单的 Actor 测试示例，该 Actor 会更新其状态并返回特定值：

<?php

// TestState.php

class TestState extends \Dapr\Actors\ActorState
{
 public int $number;
}

// TestActor.php

#[\Dapr\Actors\Attributes\DaprType('TestActor')]
class TestActor extends \Dapr\Actors\Actor
{
 public function __construct(string $id, private TestState $state)
 {
 parent::__construct($id);
 }

 public function oddIncrement(): bool
 {
 if ($this->state->number % 2 === 0) {
 return false;
 }
 $this->state->number += 1;

 return true;
 }
}

// TheTest.php

class TheTest extends \PHPUnit\Framework\TestCase
{
 private \DI\Container $container;

 public function setUp(): void
 {
 parent::setUp();
 // 创建一个默认应用并从中获取 DI 容器
 $app = \Dapr\App::create(
 configure: fn(\DI\ContainerBuilder $builder) => $builder->addDefinitions(
 ['dapr.actors' => [TestActor::class]],
 [\Dapr\DaprClient::class => \DI\autowire(\Dapr\Mocks\TestClient::class)]
 ));
 $app->run(fn(\DI\Container $container) => $this->container = $container);
 }

 public function testIncrementsWhenOdd()
 {
 $id = uniqid();
 $runtime = $this->container->get(\Dapr\Actors\ActorRuntime::class);
 $client = $this->getClient();

 // 模拟从 http://localhost:1313/reference/api/actors_api/ 获取当前状态
 $client->register_get("/actors/TestActor/$id/state/number", code: 200, data: 3);

 // 模拟从 http://localhost:1313/reference/api/actors_api/ 进行状态递增
 $client->register_post(
 "/actors/TestActor/$id/state",
 code: 204,
 response_data: null,
 expected_request: [
 [
 'operation' => 'upsert',
 'request' => [
 'key' => 'number',
 'value' => 4,
 ],
 ],
 ]
 );

 $result = $runtime->resolve_actor(
 'TestActor',
 $id,
 fn($actor) => $runtime->do_method($actor, 'oddIncrement', null)
 );
 $this->assertTrue($result);
 }

 private function getClient(): \Dapr\Mocks\TestClient
 {
 return $this->container->get(\Dapr\DaprClient::class);
 }
}

<?php

// TestState.php

class TestState extends \Dapr\Actors\ActorState
{
 public int $number;
}

// TestActor.php

#[\Dapr\Actors\Attributes\DaprType('TestActor')]
class TestActor extends \Dapr\Actors\Actor
{
 public function __construct(string $id, private TestState $state)
 {
 parent::__construct($id);
 }

 public function oddIncrement(): bool
 {
 if ($this->state->number % 2 === 0) {
 return false;
 }
 $this->state->number += 1;

 return true;
 }
}

// TheTest.php

class TheTest extends \PHPUnit\Framework\TestCase
{
 public function testNotIncrementsWhenEven() {
 $container = new \DI\Container();
 $state = new TestState($container, $container);
 $state->number = 4;
 $id = uniqid();
 $actor = new TestActor($id, $state);
 $this->assertFalse($actor->oddIncrement());
 $this->assertSame(4, $state->number);
 }
}

测试事务

在构建事务时，您可能需要测试如何处理失败的事务。为此，您需要注入故障并确保事务按预期进行。

在 .NET Dapr 可插拔组件中使用多个服务

Mon, 01 Jan 0001 00:00:00 +0000

一个可插拔组件可以托管多种类型的组件。您可能会这样做：

以减少集群中运行的sidecar数量
以便将可能共享库和实现的相关组件进行分组，例如：
- 一个既作为通用状态存储又作为
- 允许更具体操作的输出绑定。

每个Unix域套接字可以管理对每种类型的一个组件的调用。要托管多个相同类型的组件，您可以将这些类型分布在多个套接字上。SDK将每个套接字绑定到一个“服务”，每个服务由一个或多个组件类型组成。

注册多个服务

每次调用RegisterService()都会将一个套接字绑定到一组注册的组件，其中每种类型的组件每个服务可以注册一个。

var app = DaprPluggableComponentsApplication.Create();

app.RegisterService(
 "service-a",
 serviceBuilder =>
 {
 serviceBuilder.RegisterStateStore<MyDatabaseStateStore>();
 serviceBuilder.RegisterBinding<MyDatabaseOutputBinding>();
 });

app.RegisterService(
 "service-b",
 serviceBuilder =>
 {
 serviceBuilder.RegisterStateStore<AnotherStateStore>();
 });

app.Run();

class MyDatabaseStateStore : IStateStore
{
 // ...
}

class MyDatabaseOutputBinding : IOutputBinding
{
 // ...
}

class AnotherStateStore : IStateStore
{
 // ...
}

配置多个组件

配置Dapr以使用托管组件与任何单个组件相同 - 组件YAML引用关联的套接字。

#
# 此组件使用与套接字 `state-store-a` 关联的状态存储
#
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: state-store-a
spec:
 type: state.service-a
 version: v1
 metadata: []

#
# 此组件使用与套接字 `state-store-b` 关联的状态存储
#
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: state-store-b
spec:
 type: state.service-b
 version: v1
 metadata: []

多应用运行概述

Mon, 01 Jan 0001 00:00:00 +0000

注意

Kubernetes 的多应用运行目前是一个预览功能。

如果您想在本地运行多个应用程序进行联合测试，类似于生产环境，多应用运行功能可以帮助您同时启动和停止一组应用程序。这些应用程序可以是：

本地/自托管的进程，或
通过构建容器镜像并部署到Kubernetes集群
- 您可以使用本地Kubernetes集群（如KiND）或将其部署到云（如AKS、EKS和GKE）。

多应用运行模板文件描述了如何启动多个应用程序，类似于您运行多个单独的CLI run命令。默认情况下，此模板文件名为dapr.yaml。

多应用运行模板文件

执行dapr run -f .时，它会启动当前目录中的多应用模板文件（名为dapr.yaml）以运行所有应用程序。

您可以使用自己喜欢的名称命名模板文件，而不是默认名称。例如dapr run -f ./<your-preferred-file-name>.yaml。

以下示例展示了一些您可以为应用程序自定义的模板属性。在示例中，您可以同时启动2个应用程序，应用程序ID分别为processor和emit-metrics。

version: 1
apps:
 - appID: processor
 appDirPath: ../apps/processor/
 appPort: 9081
 daprHTTPPort: 3510
 command: ["go","run", "app.go"]
 - appID: emit-metrics
 appDirPath: ../apps/emit-metrics/
 daprHTTPPort: 3511
 env:
 DAPR_HOST_ADD: localhost
 command: ["go","run", "app.go"]

有关模板属性的更深入示例和解释，请参见多应用模板。

配置概述

Mon, 01 Jan 0001 00:00:00 +0000

在开发应用程序时，配置是一个常见的任务。通常，我们会使用配置存储来管理这些配置数据。配置项通常具有动态特性，并且与应用程序的需求紧密相关。

例如，应用程序的配置可能包括：

密钥名称
各种标识符
分区或消费者ID
数据库名称等

通常，配置项以键/值对的形式存储在状态存储或数据库中。开发人员或运维人员可以在运行时更改配置存储中的应用程序配置。一旦进行了更改，服务会被通知以加载新的配置。

从应用程序API的角度来看，配置数据是只读的，配置存储的更新通过运维工具进行。使用Dapr的配置API，您可以：

获取以只读键/值对形式返回的配置项
订阅配置项的变更通知

注意

配置API不应与Dapr sidecar和控制平面配置混淆，后者用于在Dapr sidecar实例或已安装的Dapr控制平面上设置策略和参数。

试用配置

快速入门

想要测试Dapr配置API？通过以下快速入门来了解配置API的实际应用：

快速入门	描述
配置快速入门	使用配置API获取配置项或订阅配置更改。

直接在应用中开始使用配置API

想要跳过快速入门？没问题。您可以直接在应用程序中尝试配置构建模块以读取和管理配置数据。在Dapr安装完成后，您可以从配置操作指南开始使用配置API。

观看演示

观看使用Dapr配置构建模块的演示

下一步

请参阅以下指南：

操作指南：从配置存储读取应用程序配置

会话概述

Mon, 01 Jan 0001 00:00:00 +0000

Alpha

会话API目前处于alpha阶段。

Dapr的会话API简化了与大型语言模型（LLM）进行大规模、安全、可靠交互的复杂性。无论您是缺乏必要本地SDK的开发者，还是只想专注于LLM交互提示的多语言开发团队，会话API都提供了一个统一的API接口来与底层LLM提供商进行对话。

除了启用关键的性能和安全功能（如提示缓存和个人信息清理），您还可以将会话API与Dapr的其他功能结合使用，例如：

弹性断路器和重试机制，以应对限制和令牌错误，或
中间件，用于验证与LLM之间的请求

Dapr通过为您的LLM交互提供指标，增强了系统的可观测性。

功能

以下功能适用于所有支持的会话组件。

提示缓存

提示缓存通过存储和重用在多个API调用中经常重复的提示来优化性能。Dapr将这些频繁使用的提示存储在本地缓存中，从而显著减少延迟和成本，使您的集群、pod或其他组件可以重用，而无需为每个新请求重新处理信息。

个人信息清理

个人信息清理功能能够识别并删除会话响应中的任何形式的敏感用户信息。只需在输入和输出数据上启用此功能，即可保护您的隐私，清除可能用于识别个人的敏感细节。

演示

观看在Diagrid的Dapr v1.15庆祝活动中展示的演示，了解会话API如何使用.NET SDK工作。

试用会话

快速入门和教程

想要测试Dapr会话API？通过以下快速入门和教程来查看其实际应用：

快速入门/教程	描述
会话快速入门	TODO

直接在您的应用中开始使用会话API

想跳过快速入门？没问题。您可以直接在您的应用中试用会话模块。在Dapr安装完成后，您可以从操作指南开始使用会话API。

下一步

加密概述

Mon, 01 Jan 0001 00:00:00 +0000

使用加密构建块，您可以安全且一致地利用加密技术。Dapr 提供的 API 允许您在密钥库或 Dapr sidecar 中执行加密和解密操作，而无需将加密密钥暴露给您的应用程序。

为什么需要加密？

加密技术在应用程序中被广泛使用，正确实施可以在数据泄露时提高安全性。在某些情况下，您可能需要使用加密技术以符合行业法规（如金融领域）或法律要求（如 GDPR 等隐私法规）。

然而，正确使用加密技术可能很复杂。您需要：

选择合适的算法和选项
学习正确的密钥管理和保护方法
在希望限制对加密密钥材料的访问时，处理操作复杂性

安全的一个重要要求是限制对加密密钥的访问，这通常被称为“原始密钥材料”。Dapr 可以与密钥库集成，如 Azure Key Vault（未来将支持更多组件），这些密钥库将密钥存储在安全的环境中，并在库中执行加密操作，而不将密钥暴露给您的应用程序或 Dapr。

或者，您可以配置 Dapr 为您管理加密密钥，在 sidecar 中执行操作，同样不将原始密钥材料暴露给您的应用程序。

Dapr 中的加密

使用 Dapr，您可以在不将加密密钥暴露给应用程序的情况下执行加密操作。

通过使用加密构建块，您可以：

更轻松地以安全的方式执行加密操作。Dapr 提供了防止使用不安全算法或不安全选项的保护措施。
将密钥保存在应用程序之外。应用程序从未看到“原始密钥材料”，但可以请求库使用密钥执行操作。当使用 Dapr 的加密引擎时，操作在 Dapr sidecar 中安全地执行。
实现更好的关注点分离。通过使用外部库或加密组件，只有授权团队可以访问私钥材料。
更轻松地管理和轮换密钥。密钥在库中管理并在应用程序之外，它们可以在不需要开发人员参与（甚至不需要重启应用程序）的情况下轮换。
启用更好的审计日志记录，以监控何时在库中使用密钥执行操作。

注意

虽然在 alpha 版本中同时支持 HTTP 和 gRPC，但使用支持的 Dapr SDK 的 gRPC API 是加密的推荐方法。

功能

加密组件

Dapr 加密构建块包括两种组件：

允许与管理服务或库（“密钥库”）交互的组件。
类似于 Dapr 在各种 secret 存储或 state 存储之上的“抽象层”，这些组件允许与各种密钥库（如 Azure Key Vault）交互（未来 Dapr 版本中会有更多）。通过这些组件，对私钥的加密操作在库中执行，Dapr 从未看到您的私钥。

分布式锁概述

Mon, 01 Jan 0001 00:00:00 +0000

介绍

锁用于确保资源的互斥访问。例如，您可以使用锁来：

独占访问数据库的行、表或整个数据库
顺序锁定从队列中读取消息

任何需要更新的共享资源都可以被锁定。锁通常用于改变状态的操作，而不是读取操作。

每个锁都有一个名称。应用程序决定锁定哪些资源。通常，同一应用程序的多个实例使用这个命名锁来独占访问资源并进行更新。

例如，在竞争消费者模式中，应用程序的多个实例访问一个队列。您可以选择在应用程序执行其业务逻辑时锁定队列。

在下图中，同一应用程序的两个实例，App1，使用Redis锁组件来锁定共享资源。

第一个应用程序实例获取命名锁并获得独占访问权。
第二个应用程序实例无法获取锁，因此在锁被释放之前不允许访问资源，释放方式可以是：
- 通过应用程序显式调用解锁API，或
- 由于租约超时而在一段时间后自动释放。

*此API目前处于Alpha状态。

特性

资源的互斥访问

在任何给定时刻，只有一个应用程序实例可以持有命名锁。锁的范围限定在Dapr应用程序ID内。

使用租约防止死锁

Dapr分布式锁使用基于租约的锁定机制。如果应用程序获取锁后遇到异常，无法释放锁，则锁将在一段时间后通过租约自动释放。这防止了在应用程序故障时发生资源死锁。

演示

观看此视频以了解分布式锁API的概述：

下一步

请参阅以下指南：

如何在您的应用程序中使用分布式锁

作业概述

Mon, 01 Jan 0001 00:00:00 +0000

许多应用程序需要作业调度，或者需要在未来执行某些操作。作业API是一个用于管理和安排这些未来作业的工具，可以在特定时间或间隔执行。

作业API不仅帮助您安排作业，Dapr内部还利用调度服务来安排actor提醒。

在Dapr中，作业包括：

查看示例场景。

工作原理

作业API是一个作业调度器，而不是作业的执行者。设计上保证作业至少执行一次，注重可靠性和可扩展性，而非精确性。这意味着：

保证： 作业不会在计划时间之前被调用。
不保证： 作业在到期时间之后被调用的具体时间。

所有计划作业的详细信息和用户相关数据都存储在调度器服务的Etcd数据库中。您可以使用作业来：

延迟您的pubsub消息传递。 您可以在未来的特定时间发布消息（例如：一周后，或特定的UTC日期/时间）。
调度应用程序之间的服务调用方法。

场景

作业调度在以下场景中可能会有所帮助：

自动化数据库备份： 确保数据库每天备份以防止数据丢失。安排一个备份脚本在每晚2点运行，创建数据库备份并将其存储在安全位置。
定期数据处理和ETL（提取、转换、加载）： 处理和转换来自各种来源的原始数据并将其加载到数据仓库中。安排ETL作业在特定时间运行（例如：每小时、每天）以获取新数据、处理并更新数据仓库中的信息。
电子邮件通知和报告： 通过电子邮件接收每日销售报告和每周性能摘要。安排一个作业生成所需的报告并在每天早上6点通过电子邮件发送每日报告，每周一早上8点发送每周摘要。
维护任务和系统更新： 执行定期维护任务，如清理临时文件、更新软件和检查系统健康状况。安排各种维护脚本在非高峰时段运行，如周末或深夜，以尽量减少对用户的干扰。
金融交易的批处理： 处理需要在每个工作日结束时批处理和结算的大量交易。安排批处理作业在每个工作日下午5点运行，汇总当天的交易并执行必要的结算和对账。

Dapr的作业API确保这些场景中表示的任务在没有人工干预的情况下始终如一地执行，提高效率并减少错误风险。

特性

作业API提供了多种特性，使您可以轻松调度作业。

在多个副本之间调度作业

调度器服务支持在多个副本之间扩展作业调度，同时保证作业仅由一个调度器服务实例触发。

试用作业API

您可以在应用程序中试用作业API。在Dapr安装完成后，您可以开始使用作业API，从如何：调度作业指南开始。

下一步

发布-订阅模式概述

Mon, 01 Jan 0001 00:00:00 +0000

发布-订阅模式（pubsub）使微服务能够通过消息进行事件驱动的架构通信。

生产者或发布者将消息写入输入通道并发送到主题，而不关心哪个应用程序会接收它们。
消费者或订阅者订阅主题并从输出通道接收消息，而不关心哪个服务生成了这些消息。

消息代理会将每条消息从发布者的输入通道复制到所有对该消息感兴趣的订阅者的输出通道。这种模式在需要将微服务解耦时特别有用。

pubsub API

在 Dapr 中，pubsub API：

提供一个平台无关的 API 来发送和接收消息。
确保消息至少被传递一次。
与多种消息代理和队列系统集成。

您可以在运行时配置 Dapr pubsub 组件来使用特定的消息代理，这种可插拔性使您的服务更具可移植性和灵活性。

在 Dapr 中使用 pubsub 时：

您的服务通过网络调用 Dapr pubsub 构建块 API。
pubsub 构建块调用封装特定消息代理的 Dapr pubsub 组件。
为了接收主题上的消息，Dapr 代表您的服务订阅 pubsub 组件，并在消息到达时将其传递到您的服务的端点。

以下概述视频和演示展示了 Dapr pubsub 的工作原理。

在下图中，“shipping”服务和“email”服务都已订阅由“cart”服务发布的主题。每个服务加载指向相同 pubsub 消息代理组件的 pubsub 组件配置文件；例如：Redis Streams、NATS Streaming、Azure Service Bus 或 GCP pubsub。

在下图中，Dapr API 将“cart”服务的“order”主题发布到“shipping”和“email”订阅服务的“order”端点。

查看 Dapr 支持的 pubsub 组件的完整列表。

Secrets 管理概述

Mon, 01 Jan 0001 00:00:00 +0000

应用程序通常使用专用的 secret 存储来保存敏感信息。例如，您可以使用存储在 secret 存储中的连接字符串、密钥、令牌和其他应用程序级别的 secret 来对数据库、服务和外部系统进行身份验证，例如 AWS Secrets Manager, Azure Key Vault, Hashicorp Vault 等。

为了访问这些 secret 存储，应用程序需要导入 secret 存储的 SDK。在多云场景中，这种情况更具挑战性，因为可能会使用不同供应商特定的 secret 存储。

Secrets 管理 API

Dapr 的专用 secrets 构建块 API 使开发人员更容易从 secret 存储中使用应用程序 secret。要使用 Dapr 的 secret 存储构建块，您需要：

为特定的 secret 存储解决方案设置一个组件。
在应用程序代码中使用 Dapr secrets API 检索 secret。
可选地，在 Dapr 组件文件中引用 secret。

以下概述视频和演示展示了 Dapr secrets 管理的工作原理。

功能

Secrets 管理 API 构建块为您的应用程序带来了多种功能。

工作流概述

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 工作流让开发人员能够可靠地编写业务逻辑和集成。由于 Dapr 工作流是有状态的，它们支持长时间运行和容错应用程序，非常适合编排微服务。Dapr 工作流与其他 Dapr 构建块（如服务调用、发布订阅、状态管理和绑定）无缝协作。

Dapr 工作流的耐用性和弹性功能包括：

提供内置的工作流运行时以驱动 Dapr 工作流执行。
提供用于在代码中编写工作流的 SDK，支持多种编程语言。
提供用于管理工作流（启动、查询、暂停/恢复、触发事件、终止、清除）的 HTTP 和 gRPC API。
通过工作流组件与其他工作流运行时集成。

Dapr 工作流可以应用于以下场景：

涉及库存管理、支付系统和运输服务之间编排的订单处理。
协调多个部门和参与者任务的人力资源入职工作流。
在全国餐饮连锁店中协调数字菜单更新的推出。
涉及基于 API 的分类和存储的图像处理工作流。

功能

工作流和活动

使用 Dapr 工作流，您可以编写活动，然后在工作流中编排这些活动。工作流活动是：

工作流中的基本工作单元
用于调用其他（Dapr）服务、与状态存储交互以及发布订阅代理。

了解更多关于工作流活动的信息。

子工作流

除了活动之外，您还可以编写工作流以调度其他工作流作为子工作流。子工作流具有独立于启动它的父工作流的实例 ID、历史记录和状态，除了终止父工作流会终止由其创建的所有子工作流这一事实。子工作流还支持自动重试策略。

了解更多关于子工作流的信息。

定时器和提醒

与 Dapr actor 相同，您可以为任何时间范围安排类似提醒的持久延迟。

了解更多关于工作流定时器和提醒

使用 HTTP 调用管理工作流

当您使用工作流代码创建应用程序并使用 Dapr 运行它时，您可以调用驻留在应用程序中的特定工作流。每个单独的工作流可以：

通过 POST 请求启动或终止
通过 POST 请求触发以传递命名事件
通过 POST 请求暂停然后恢复
通过 POST 请求从您的状态存储中清除
通过 GET 请求查询工作流状态

了解更多关于如何使用 HTTP 调用管理工作流的信息。

可插拔组件概述

Mon, 01 Jan 0001 00:00:00 +0000

可插拔组件是指那些不包含在运行时中的组件，与 dapr init 中的内置组件相对。您可以配置 Dapr 使用这些可插拔组件，它们利用构建块 API，但注册方式与内置 Dapr 组件不同。

可插拔组件与内置组件

Dapr 提供了两种注册和创建组件的方法：

运行时中包含的内置组件，可以在components-contrib 仓库中找到。
独立部署和注册的可插拔组件。

这两种注册选项虽然都利用了 Dapr 的构建块 API，但实现过程不同。

组件详情	内置组件	可插拔组件
语言	只能用 Go 编写	可以用任何支持 gRPC 的语言编写
运行位置	作为 Dapr 运行时可执行文件的一部分	作为 pod 中的独立进程或容器运行，与 Dapr 本身分开运行。
与 Dapr 的注册方式	包含在 Dapr 代码库中	通过 Unix 域套接字（使用 gRPC）与 Dapr 注册
分发	随 Dapr 版本发布。组件的新功能与 Dapr 版本保持一致	独立于 Dapr 本身分发。可以在需要时添加新功能，并遵循自己的发布周期。
组件激活方式	Dapr 启动运行组件（自动）	用户启动组件（手动）

为什么创建可插拔组件？

在以下场景中，可插拔组件非常有用：

您需要一个私有组件。
您希望将组件与 Dapr 的发布过程分开。
您对 Go 不太熟悉，或者用 Go 实现组件并不理想。

特性

实现可插拔组件

要实现可插拔组件，您需要在组件中实现一个 gRPC 服务。实现 gRPC 服务需要三个步骤：

日志

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 生成的结构化日志会输出到 stdout，可以选择纯文本或 JSON 格式。默认情况下，所有 Dapr 进程（包括运行时或 sidecar，以及所有控制平面服务）都会以纯文本形式将日志写入控制台（stdout）。若要启用 JSON 格式的日志记录，您需要在运行 Dapr 进程时添加 --log-as-json 命令标志。

注意

如果您希望使用 Elastic Search 或 Azure Monitor 等搜索引擎来搜索日志，强烈建议使用 JSON 格式的日志，因为日志收集器和搜索引擎可以利用内置的 JSON 解析器更好地解析这些日志。

日志模式

Dapr 生成的日志遵循以下模式：

字段	描述	示例
time	ISO8601 时间戳	`2011-10-05T14:48:00.000Z`
level	日志级别 (info/warn/debug/error)	`info`
type	日志类型	`log`
msg	日志消息	`hello dapr!`
scope	日志范围	`dapr.runtime`
instance	容器名称	`dapr-pod-xxxxx`
app_id	Dapr 应用 ID	`dapr-app`
ver	Dapr 运行时版本	`1.9.0`

API 日志可能会添加其他结构化字段，具体请参阅 API 日志记录文档。

纯文本和 JSON 格式的日志

纯文本日志示例

time="2022-11-01T17:08:48.303776-07:00" level=info msg="starting Dapr Runtime -- version 1.9.0 -- commit v1.9.0-g5dfcf2e" instance=dapr-pod-xxxx scope=dapr.runtime type=log ver=1.9.0
time="2022-11-01T17:08:48.303913-07:00" level=info msg="log level set to: info" instance=dapr-pod-xxxx scope=dapr.runtime type=log ver=1.9.0

JSON 格式日志示例

{"instance":"dapr-pod-xxxx","level":"info","msg":"starting Dapr Runtime -- version 1.9.0 -- commit v1.9.0-g5dfcf2e","scope":"dapr.runtime","time":"2022-11-01T17:09:45.788005Z","type":"log","ver":"1.9.0"}
{"instance":"dapr-pod-xxxx","level":"info","msg":"log level set to: info","scope":"dapr.runtime","time":"2022-11-01T17:09:45.788075Z","type":"log","ver":"1.9.0"}

日志格式

Dapr 支持输出纯文本（默认）或 JSON 格式的日志。

健康 API 参考

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 提供健康检查功能，用于检查 Dapr 的就绪状态或存活状态，以及从 SDKs 检查初始化的就绪性。

获取 Dapr 健康状态

可以通过以下方式获取 Dapr 的健康状态：

检查 sidecar 的健康状况
检查 sidecar 的健康状况，包括组件的就绪性，适用于初始化期间。

等待 Dapr HTTP 端口可用

等待所有组件初始化完成，Dapr HTTP 端口可用，同时应用程序通道已初始化。例如，此端点用于 Kubernetes 的存活性探针。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/healthz

HTTP 响应代码

代码	描述
204	Dapr 是健康的
500	Dapr 是不健康的

URL 参数

参数	描述
daprPort	Dapr 端口

示例

curl -i http://localhost:3500/v1.0/healthz

等待 `/outbound` 路径的特定健康检查

等待所有组件初始化完成，Dapr HTTP 端口可用，但应用程序通道尚未建立。此端点允许您的应用程序在应用程序通道初始化之前调用 Dapr sidecar 的 API，例如使用 secret API 读取机密信息。在 Dapr SDKs 中，可以使用 waitForSidecar 方法（例如 .NET 和 Java SDKs）来检查 sidecar 是否已正确初始化，以便进行后续调用。

设置和配置 mTLS 证书

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 支持通过 Dapr 控制平面的 Sentry 服务对 Dapr 实例之间的通信进行传输加密。Sentry 服务是一个中央证书颁发机构 (CA)。

Dapr 允许操作员和开发人员使用自己的证书，或者让 Dapr 自动创建并保存自签名的根证书和颁发者证书。

有关 mTLS 的详细信息，请阅读安全概念部分。

如果没有提供自定义证书，Dapr 会自动创建并保存有效期为一年的自签名证书。在 Kubernetes 中，证书会保存到 Dapr 系统 pod 所在命名空间的 secret 中，仅对它们可访问。在自托管模式中，证书会保存到磁盘。

控制平面 Sentry 服务配置

mTLS 设置位于 Dapr 控制平面配置文件中。例如，当您将 Dapr 控制平面部署到 Kubernetes 时，此配置文件会自动创建，然后您可以编辑它。以下文件显示了在 daprsystem 命名空间中部署的配置资源中可用的 mTLS 设置：

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: daprsystem
 namespace: default
spec:
 mtls:
 enabled: true
 workloadCertTTL: "24h"
 allowedClockSkew: "15m"

此文件显示了默认的 daprsystem 配置设置。下面的示例向您展示如何在 Kubernetes 和自托管模式下更改和应用此配置到控制平面 Sentry 服务。

生产参考：actor

Mon, 01 Jan 0001 00:00:00 +0000

代理模式

actor代理有四种模式可供选择。每种模式都有不同的优缺点，您需要在开发和生产中进行权衡。

<?php
\Dapr\Actors\Generators\ProxyFactory::GENERATED;
\Dapr\Actors\Generators\ProxyFactory::GENERATED_CACHED;
\Dapr\Actors\Generators\ProxyFactory::ONLY_EXISTING;
\Dapr\Actors\Generators\ProxyFactory::DYNAMIC;

可以通过dapr.actors.proxy.generation配置键进行设置。

这是默认模式。在此模式下，每个请求都会生成一个类并通过eval执行。主要用于开发环境，不建议在生产中使用。

这与ProxyModes::GENERATED相同，但类会存储在一个临时文件中，因此不需要在每个请求时重新生成。由于无法判断何时更新缓存的类，因此不建议在开发中使用，但在无法手动生成文件时可以使用。

在此模式下，如果代理类不存在，则会抛出异常。这对于不希望在生产中生成代码的情况很有用。您必须确保类已生成并预加载/自动加载。

生成代理

您可以创建一个composer脚本以按需生成代理，以利用ONLY_EXISTING模式。

创建一个ProxyCompiler.php

<?php

class ProxyCompiler {
 private const PROXIES = [
 MyActorInterface::class,
 MyOtherActorInterface::class,
 ];
 
 private const PROXY_LOCATION = __DIR__.'/proxies/';
 
 public static function compile() {
 try {
 $app = \Dapr\App::create();
 foreach(self::PROXIES as $interface) {
 $output = $app->run(function(\DI\FactoryInterface $factory) use ($interface) {
 return \Dapr\Actors\Generators\FileGenerator::generate($interface, $factory);
 });
 $reflection = new ReflectionClass($interface);
 $dapr_type = $reflection->getAttributes(\Dapr\Actors\Attributes\DaprType::class)[0]->newInstance()->type;
 $filename = 'dapr_proxy_'.$dapr_type.'.php';
 file_put_contents(self::PROXY_LOCATION.$filename, $output);
 echo "Compiled: $interface";
 }
 } catch (Exception $ex) {
 echo "Failed to generate proxy for $interface\n{$ex->getMessage()} on line {$ex->getLine()} in {$ex->getFile()}\n";
 }
 }
}

然后在composer.json中为生成的代理添加一个psr-4自动加载器和一个脚本：

Dapr术语和定义

Mon, 01 Jan 0001 00:00:00 +0000

本页面详细介绍了您可能在Dapr文档中遇到的所有常见术语。

术语	定义	更多信息
应用程序	一个正在运行的服务或程序，通常是由用户创建和运行的。
构件	Dapr为用户提供的API，帮助创建微服务和应用程序。	Dapr构件
组件	模块化的功能单元，可以单独使用或与其他组件结合使用，由Dapr构件调用。	Dapr组件
配置	一个YAML文件，用于声明所有Dapr边车或Dapr控制平面的设置。在这里，您可以配置控制平面的mTLS设置，或应用程序实例的跟踪和中间件设置。	Dapr配置
Dapr	分布式应用运行时。	Dapr概述
Dapr控制平面	一组服务，是在托管平台（如Kubernetes集群）上安装Dapr的一部分。这使得启用Dapr的应用程序可以在平台上运行，并处理Dapr功能，如actor放置、Dapr边车注入或证书签发/轮换。	自托管概述 Kubernetes概述
HTTPEndpoint	HTTPEndpoint是一个Dapr资源，用于识别通过服务调用API访问的非Dapr端点。	服务调用API
命名空间	Dapr中的命名空间提供隔离功能，从而支持多租户。	了解更多关于命名空间的组件、服务调用、发布/订阅和actors
自主管理	在Windows/macOS/Linux机器上运行应用程序的能力，使用Dapr。Dapr提供在“自主管理”模式下运行的能力。	自主管理模式
服务	一个正在运行的应用程序或程序。这可以指您的应用程序或Dapr应用程序。
sidecar	一个与您的应用程序一起运行的程序，作为一个单独的进程或容器。	边车模式

使用 OpenTelemetry Collector 将跟踪信息发送到应用程序洞察

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 使用 Zipkin API 集成了 OpenTelemetry (OTEL) Collector。本指南演示了如何通过 Dapr 使用 OpenTelemetry Collector 将跟踪事件推送到 Azure 应用程序洞察。

前提条件

在 Kubernetes 上安装 Dapr
设置一个应用程序洞察资源并记录下你的应用程序洞察仪器密钥。

配置 OTEL Collector 以推送数据到应用程序洞察

要将事件推送到你的应用程序洞察实例，请在 Kubernetes 集群中安装 OTEL Collector。

查看 open-telemetry-collector-appinsights.yaml 文件。
用你的应用程序洞察仪器密钥替换 <INSTRUMENTATION-KEY> 占位符。

使用以下命令应用配置：

kubectl apply -f open-telemetry-collector-appinsights.yaml

配置 Dapr 以发送跟踪数据到 OTEL Collector

创建一个 Dapr 配置文件以启用跟踪，并部署一个使用 OpenTelemetry Collector 的跟踪导出组件。

使用此 collector-config.yaml 文件创建你自己的配置。
使用以下命令应用配置：
```
kubectl apply -f collector-config.yaml
```

部署应用程序并启用跟踪

在你希望参与分布式跟踪的容器中添加 dapr.io/config 注解以应用 appconfig 配置，如下例所示：

apiVersion: apps/v1
kind: Deployment
metadata:
 ...
spec:
 ...
 template:
 metadata:
 ...
 annotations:
 dapr.io/enabled: "true"
 dapr.io/app-id: "MyApp"
 dapr.io/app-port: "8080"
 dapr.io/config: "appconfig"

注意

如果你正在使用 Dapr 教程之一，例如分布式计算器，appconfig 配置已经设置好，因此不需要额外的配置。

你可以同时注册多个跟踪导出器，跟踪日志会被转发到所有注册的导出器。

.NET Dapr 插件组件的应用环境配置

Mon, 01 Jan 0001 00:00:00 +0000

.NET Dapr 插件组件应用可以配置依赖注入、日志记录和配置值，类似于 ASP.NET 应用。DaprPluggableComponentsApplication 提供了一组与 WebApplicationBuilder 类似的配置属性。

依赖注入

注册到服务的组件可以参与依赖注入。组件构造函数中的参数会在创建时被注入，前提是这些类型已在应用中注册。你可以通过 DaprPluggableComponentsApplication 提供的 IServiceCollection 来注册它们。

var app = DaprPluggableComponentsApplication.Create();

// 将 MyService 注册为 IService 的单例实现。
app.Services.AddSingleton<IService, MyService>();

app.RegisterService(
 "<service name>",
 serviceBuilder =>
 {
 serviceBuilder.RegisterStateStore<MyStateStore>();
 });

app.Run();

interface IService
{
 // ...
}

class MyService : IService
{
 // ...
}

class MyStateStore : IStateStore
{
 // 在创建 state 存储时注入 IService。
 public MyStateStore(IService service)
 {
 // ...
 }

 // ...
}

警告

不推荐使用 IServiceCollection.AddScoped()。因为此类实例的生命周期仅限于单个 gRPC 方法调用，这与组件实例的生命周期不一致。

日志记录

.NET Dapr 插件组件可以使用标准 .NET 日志机制。DaprPluggableComponentsApplication 提供了一个 ILoggingBuilder，可以通过它进行配置。

如何：注册一个可插拔组件

Mon, 01 Jan 0001 00:00:00 +0000

组件注册过程

使用 gRPC 的可插拔组件通常作为容器或进程运行，需要通过Unix 域套接字（简称 UDS）与 Dapr 运行时通信。它们会通过以下步骤自动被发现并注册到运行时中：

组件监听放置在共享卷上的Unix 域套接字。
Dapr 运行时列出共享卷中的所有Unix 域套接字。
Dapr 运行时连接每个套接字，并使用 gRPC 反射从组件实现的给定构建块 API 中发现所有 proto 服务。

一个组件可以同时实现多个组件接口。

虽然 Dapr 的内置组件已经集成在运行时中，但可插拔组件在与 Dapr 一起使用之前需要进行一些设置步骤。

可插拔组件需要在 Dapr 本身启动之前启动并准备好接收请求。
用于可插拔组件通信的Unix 域套接字文件需要对 Dapr 和可插拔组件都可访问。

在独立模式下，可插拔组件可以作为进程或容器运行。在 Kubernetes 上，可插拔组件作为容器运行，并由 Dapr 的 sidecar 注入器自动注入到应用程序的 pod 中，允许通过标准的Kubernetes 容器规范进行自定义。

这也改变了在 Dapr 和可插拔组件之间共享Unix 域套接字文件的方法。

注意

作为前提条件，操作系统必须支持 Unix 域套接字，任何 UNIX 或类 UNIX 系统（Mac、Linux 或用于本地开发的 WSL 对于 Windows 用户）都应该足够。

选择您的环境以开始使您的组件可被发现。

运行组件

在 Dapr 启动之前，您的组件和 Unix 套接字必须正在运行。

自定义序列化

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 使用 JSON 进行序列化，因此在发送或接收数据时，复杂类型的信息可能会丢失。

序列化

当从控制器返回对象、将对象传递给 DaprClient 或将对象存储在状态存储中时，只有公共属性会被扫描和序列化。您可以通过实现 \Dapr\Serialization\ISerialize 接口来自定义此行为。例如，如果您想创建一个序列化为字符串的 ID 类型，可以这样实现：

<?php

class MyId implements \Dapr\Serialization\Serializers\ISerialize 
{
 public string $id;
 
 public function serialize(mixed $value, \Dapr\Serialization\ISerializer $serializer): mixed
 {
 // $value === $this
 return $this->id; 
 }
}

这种方法适用于我们完全控制的类型，但不适用于库或 PHP 自带的类。对于这些情况，您需要在依赖注入容器中注册一个自定义序列化器：

<?php
// 在 config.php 中

class SerializeSomeClass implements \Dapr\Serialization\Serializers\ISerialize 
{
 public function serialize(mixed $value, \Dapr\Serialization\ISerializer $serializer): mixed 
 {
 // 序列化 $value 并返回结果
 }
}

return [
 'dapr.serializers.custom' => [SomeClass::class => new SerializeSomeClass()],
];

反序列化

反序列化的过程与序列化类似，只是使用的接口是 \Dapr\Deserialization\Deserializers\IDeserialize。

组件规范

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 通过资源规范来定义和注册组件。所有组件都被定义为资源，可以应用于任何运行 Dapr 的托管环境，不仅限于 Kubernetes。

通常，组件会被限制在特定的命名空间内，并通过作用域来限制对特定应用程序的访问。命名空间可以在组件清单中显式指定，或者由 API 服务器根据 Kubernetes 的上下文来自动分配。

注意

在自托管模式下，如果省略命名空间字段，daprd 会自动加载组件资源。然而，安全配置文件不会生效，因为 daprd 无论如何都能访问清单，这与 Kubernetes 的行为不同。

格式

apiVersion: dapr.io/v1alpha1
kind: Component
auth: 
 secretstore: <REPLACE-WITH-SECRET-STORE-NAME>
metadata:
 name: <REPLACE-WITH-COMPONENT-NAME>
 namespace: <REPLACE-WITH-COMPONENT-NAMESPACE>
spec:
 type: <REPLACE-WITH-COMPONENT-TYPE>
 version: v1
 initTimeout: <REPLACE-WITH-TIMEOUT-DURATION>
 ignoreErrors: <REPLACE-WITH-BOOLEAN>
 metadata:
 - name: <REPLACE-WITH-METADATA-NAME>
 value: <REPLACE-WITH-METADATA-VALUE>
scopes:
 - <REPLACE-WITH-APPID>
 - <REPLACE-WITH-APPID>

规范字段

字段	必需	详情	示例
apiVersion	Y	您调用的 Dapr（和 Kubernetes 如果适用）API 的版本	`dapr.io/v1alpha1`
kind	Y	资源的类型。对于组件，必须始终是 `Component`	`Component`
auth	N	secret 存储的名称，其中 `secretKeyRef` 在元数据中查找组件中使用的 secret 名称	参见如何：在组件中引用 secret
scopes	N	组件限制的应用程序，由其应用程序 ID 指定	`order-processor`, `checkout`
metadata	-	关于组件注册的信息
metadata.name	Y	组件的名称	`prod-statestore`
metadata.namespace	N	具有命名空间的托管环境中组件的命名空间	`myapp-namespace`
spec	-	关于组件资源的详细信息
spec.type	Y	组件的类型	`state.redis`
spec.version	Y	组件的版本	`v1`
spec.initTimeout	N	组件初始化的超时时间。默认是 5s	`5m`, `1h`, `20s`
spec.ignoreErrors	N	告诉 Dapr sidecar 如果组件加载失败继续初始化。默认是 false	`false`
spec.metadata	-	组件特定配置的键/值对。请参阅您的组件定义以获取字段
spec.metadata.name	Y	组件特定属性的名称及其值	`- name: secretsFile` `value: secrets.json`

模板化的元数据值

元数据值可以包含在 Dapr sidecar 启动时解析的模板标签。下表显示了可以在组件中使用的当前模板标签。

.NET Dapr 可插拔组件的生命周期

Mon, 01 Jan 0001 00:00:00 +0000

在 .NET Dapr 中，注册组件有两种方式：

组件作为单例运行，其生命周期由 SDK 管理
组件的生命周期由可插拔组件决定，可以是多实例或单例，视需要而定

单例组件

按类型注册的组件将作为单例运行：一个实例将为与该 socket 关联的所有配置组件提供服务。当仅存在一个该类型的组件并在 Dapr 应用程序之间共享时，这种方法是最佳选择。

var app = DaprPluggableComponentsApplication.Create();

app.RegisterService(
 "service-a",
 serviceBuilder =>
 {
 serviceBuilder.RegisterStateStore<SingletonStateStore>();
 });

app.Run();

class SingletonStateStore : IStateStore
{
 // ...
}

多实例组件

可以通过传递“工厂方法”来注册组件。对于与该 socket 关联的每个配置组件，该方法将被调用。该方法返回要与该组件关联的实例（无论是否共享）。当多个相同类型的组件可能配置有不同的元数据集时，或者当组件操作需要彼此隔离时，这种方法是最佳选择。

工厂方法会接收上下文信息，例如配置的 Dapr 组件的 ID，这些信息可用于区分不同的组件实例。

var app = DaprPluggableComponentsApplication.Create();

app.RegisterService(
 "service-a",
 serviceBuilder =>
 {
 serviceBuilder.RegisterStateStore(
 context =>
 {
 return new MultiStateStore(context.InstanceId);
 });
 });

app.Run();

class MultiStateStore : IStateStore
{
 private readonly string instanceId;

 public MultiStateStore(string instanceId)
 {
 this.instanceId = instanceId;
 }

 // ...
}

设置 KiND 集群

Mon, 01 Jan 0001 00:00:00 +0000

前提条件

安装：
- Docker
- kubectl
对于 Windows：
- 在 BIOS 中启用虚拟化
- 安装 Hyper-V

安装和配置 KiND

参考 KiND 文档进行安装。

使用 Docker Desktop 时，请确保您已进行推荐的设置。

配置并创建 KiND 集群

创建一个名为 kind-cluster-config.yaml 的文件，并粘贴以下内容：

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
 kubeadmConfigPatches:
 - |
 kind: InitConfiguration
 nodeRegistration:
 kubeletExtraArgs:
 node-labels: "ingress-ready=true"
 extraPortMappings:
 - containerPort: 80
 hostPort: 8081
 protocol: TCP
 - containerPort: 443
 hostPort: 8443
 protocol: TCP
- role: worker
- role: worker

此集群配置：

如何：实现可插拔组件

Mon, 01 Jan 0001 00:00:00 +0000

在本指南中，您将学习实现可插拔组件的原因和方法。要了解如何配置和注册可插拔组件，请参阅如何：注册可插拔组件。

实现可插拔组件

要实现可插拔组件，需在组件中实现 gRPC 服务。实现 gRPC 服务需要三个步骤：

找到 proto 定义文件

每个支持的服务接口（如状态存储、发布订阅、绑定、密钥存储）都提供了 proto 定义。

目前支持以下组件 API：

状态存储
发布订阅
绑定
密钥存储

组件	类型	gRPC 定义	内置参考实现	文档
状态存储	`state`	state.proto	Redis	概念, 如何, API 规范
发布订阅	`pubsub`	pubsub.proto	Redis	概念, 如何, API 规范
绑定	`bindings`	bindings.proto	Kafka	概念, 输入如何, 输出如何, API 规范
密钥存储	`secretstores`	secretstore.proto	Hashicorp/Vault	概念, 如何-secrets, API 规范

以下是可插拔组件状态存储的 gRPC 服务定义片段（[state.proto]）：

// StateStore 服务为状态存储组件提供 gRPC 接口。
service StateStore {
 // 使用给定的元数据初始化状态存储组件。
 rpc Init(InitRequest) returns (InitResponse) {}
 // 返回已实现的状态存储功能列表。
 rpc Features(FeaturesRequest) returns (FeaturesResponse) {}
 // Ping 状态存储。用于活跃性目的。
 rpc Ping(PingRequest) returns (PingResponse) {}
 
 // 从状态存储中删除指定的键。
 rpc Delete(DeleteRequest) returns (DeleteResponse) {}
 // 从给定的键获取数据。
 rpc Get(GetRequest) returns (GetResponse) {}
 // 设置指定键的值。
 rpc Set(SetRequest) returns (SetResponse) {}

 // 一次删除多个键。
 rpc BulkDelete(BulkDeleteRequest) returns (BulkDeleteResponse) {}
 // 一次检索多个键。
 rpc BulkGet(BulkGetRequest) returns (BulkGetResponse) {}
 // 一次设置多个键的值。
 rpc BulkSet(BulkSetRequest) returns (BulkSetResponse) {}
}

StateStore 服务接口总共公开了 9 个方法：

元数据 API 参考

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 提供了一个元数据 API，可以返回有关 sidecar 的信息，从而支持运行时发现。元数据端点返回以下信息：

运行时版本
已加载的资源列表（包括 components、subscriptions 和 HttpEndpoints）
注册的 actor 类型
启用的功能
应用程序连接的详细信息
自定义的临时属性信息。

元数据 API

组件

每个加载的组件提供其名称、类型和版本，以及支持的功能信息。这些功能适用于 state store 和 binding 组件类型。下表显示了给定版本的组件类型和能力列表。此列表可能会在将来扩展，仅代表当前已加载组件的能力。

组件类型	能力
State Store	ETAG, TRANSACTION, ACTOR, QUERY_API
Binding	INPUT_BINDING, OUTPUT_BINDING

HTTPEndpoints

每个加载的 HttpEndpoint 提供一个名称，以便轻松识别与运行时关联的 Dapr 资源。

启用的功能

通过配置规范启用的功能列表（包括构建时的覆盖）。

应用程序连接详细信息

元数据 API 返回与 Dapr 连接到应用程序相关的信息。这包括应用程序端口、协议、主机、最大并发性以及健康检查的详细信息。

属性

元数据 API 允许您以键值对的格式存储附加的属性信息。这些信息是临时的内存信息，如果 sidecar 重新加载则不会持久化。此信息应在 sidecar 创建时添加（例如，在应用程序启动后）。

获取 Dapr sidecar 信息

从元数据端点获取 Dapr sidecar 信息。

Placement API 参考

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 提供了一个 HTTP API /placement/state，用于 Placement 服务，公开 placement 表信息。该 API 在 sidecar 上与 healthz 使用相同的端口。这是一个未经身份验证的端点，默认情况下是禁用的。

要在自托管模式下启用 placement 元数据，可以设置 DAPR_PLACEMENT_METADATA_ENABLED 环境变量为 true，或者在 Placement 服务上使用 metadata-enabled 命令行参数。请参阅如何在自托管模式下运行 Placement 服务。

重要

在多租户模式下运行 placement 时，请禁用 metadata-enabled 命令行参数，以防止不同命名空间之间的数据泄露。

如果您在 Kubernetes 上使用 Helm 部署 Placement 服务，要启用 placement 元数据，请将 dapr_placement.metadataEnabled 设置为 true。

使用场景

placement 表 API 可用于检索当前的 placement 表，其中包含所有注册的 actor。这对于调试非常有帮助，并允许工具提取和展示关于 actor 的信息。

HTTP 请求

GET http://localhost:<healthzPort>/placement/state

HTTP 响应代码

代码	描述
200	成功返回 placement 表信息
500	无法返回 placement 表信息

HTTP 响应体

Placement 表 API 响应对象

使用 OpenTelemetry Collector 收集追踪信息并发送到 Jaeger

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 支持通过 OpenTelemetry (OTLP) 和 Zipkin 协议进行追踪信息的写入。然而，由于 Jaeger 对 Zipkin 的支持已被弃用，建议使用 OTLP。虽然 Jaeger 可以直接支持 OTLP，但在生产环境中，推荐使用 OpenTelemetry Collector 从 Dapr 收集追踪信息并发送到 Jaeger。这样可以让您的应用程序更高效地处理数据，并利用重试、批处理和加密等功能。更多信息请阅读 Open Telemetry Collector 文档。

在自托管模式下配置 Jaeger

本地设置

启动 Jaeger 的最简单方法是运行发布到 DockerHub 的预构建的 all-in-one Jaeger 镜像，并暴露 OTLP 端口：

docker run -d --name jaeger \
 -p 4317:4317 \
 -p 16686:16686 \
 jaegertracing/all-in-one:1.49

接下来，在本地创建以下 config.yaml 文件：

加密 API 参考

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 通过加密模块提供跨平台和跨语言的加密和解密支持。除了特定语言的 SDK之外，开发者还可以使用下面的 HTTP API 端点来调用这些功能。

HTTP API 仅用于开发和测试。在生产环境中，强烈推荐使用 SDK，因为它们实现了 gRPC API，提供比 HTTP API 更高的性能和功能。

加密数据

此端点允许您使用指定的密钥和加密组件加密以字节数组形式提供的值。

HTTP 请求

PUT http://localhost:<daprPort>/v1.0-alpha1/crypto/<crypto-store-name>/encrypt

URL 参数

参数	描述
daprPort	Dapr 端口
crypto-store-name	用于获取加密密钥的加密存储名称

注意，所有 URL 参数区分大小写。

请求头

通过设置请求头来配置其他加密参数。下表详细说明了每个加密请求需要设置的必需和可选请求头。

请求头键	描述	允许值	必需性
dapr-key-name	用于加密操作的密钥名称		是
dapr-key-wrap-algorithm	使用的密钥包装算法	`A256KW`, `A128CBC`, `A192CBC`, `RSA-OAEP-256`	是
dapr-omit-decryption-key-name	如果为 true，则在输出中省略请求头 `dapr-decryption-key-name` 中的解密密钥名称。	以下值将被接受为 true：`y`, `yes`, `true`, `t`, `on`, `1`	否
dapr-decryption-key-name	如果 `dapr-omit-decryption-key-name` 为 true，则包含要在输出中包含的预期解密密钥的名称。		仅当 `dapr-omit-decryption-key-name` 为 true 时必需
dapr-data-encryption-cipher	用于加密操作的密码	`aes-gcm` 或 `chacha20-poly1305`	否

HTTP 响应

响应体

加密请求的响应将其内容类型请求头设置为 application/octet-stream，因为它返回一个包含加密数据的字节数组。

作业API参考

Mon, 01 Jan 0001 00:00:00 +0000

注意

作业API目前处于测试阶段。

使用作业API，您可以预定未来的作业和任务。

HTTP API仅供开发和测试使用。在生产环境中，强烈推荐使用SDK，因为它们实现了gRPC API，提供比HTTP API更高的性能和功能。

调度作业

通过名称来调度作业。

POST http://localhost:3500/v1.0-alpha1/jobs/<name>

URL参数

注意

必须提供schedule或dueTime中的至少一个，也可以同时提供。

参数	描述
`name`	您正在调度的作业的名称
`data`	一个JSON格式的值或对象。
`schedule`	作业的可选计划。格式详情如下。
`dueTime`	作业应激活的时间，或"一次性"时间，如果未提供其他调度类型字段。接受RFC3339格式的时间字符串、Go持续时间字符串（从创建时间计算）或非重复的ISO8601格式。
`repeats`	作业应触发的次数。如果未设置，作业将无限期运行或直到过期。
`ttl`	作业的生存时间或过期时间。接受RFC3339格式的时间字符串、Go持续时间字符串（从作业创建时间计算）或非重复的ISO8601格式。

schedule

schedule接受systemd计时器风格的cron表达式，以及以’@‘为前缀的人类可读周期字符串。

systemd计时器风格的cron表达式包含6个字段：

秒	分钟	小时	月中的某天	月份	星期中的某天
0-59	0-59	0-23	1-31	1-12/jan-dec	0-6/sun-sat

示例 1

“0 30 * * * *” - 每小时的30分钟

示例 2

“0 15 3 * * *” - 每天03:15

周期字符串表达式：

条目	描述	等同于
@every	每隔运行一次 (例如 ‘@every 1h30m’)	N/A
@yearly (或 @annually)	每年运行一次，午夜，1月1日	0 0 0 1 1 *
@monthly	每月运行一次，午夜，月初	0 0 0 1 * *
@weekly	每周运行一次，周日午夜	0 0 0 * * 0
@daily (或 @midnight)	每天运行一次，午夜	0 0 0 * * *
@hourly	每小时运行一次，整点	0 0 * * * *

请求体

{
 "data": "some data",
 "dueTime": "30s"
}

HTTP响应代码

代码	描述
`204`	已接受
`400`	请求格式错误
`500`	请求格式正确，但dapr代码或调度器控制平面服务中出错

响应内容

以下示例curl命令创建一个名为jobforjabba的作业，并指定schedule、repeats和data。

会话API参考

Mon, 01 Jan 0001 00:00:00 +0000

Alpha

会话API目前为alpha阶段。

Dapr提供了一种API，用于与大型语言模型（LLMs）进行交互。通过提示缓存和模糊化个人身份信息（PII）等功能，提升了性能和安全性。

会话

通过此端点可以与LLMs进行会话。

POST /v1.0-alpha1/conversation/<llm-name>/converse

URL参数

参数	描述
`llm-name`	LLM组件的名称。查看所有可用会话组件的列表。

请求体

字段	描述
`conversationContext`	会话的上下文信息，用于维持对话状态。
`inputs`	用户输入的文本数组。
`parameters`	额外的参数配置。

请求示例

REQUEST = {
 "inputs": ["什么是Dapr", "为什么使用Dapr"],
 "parameters": {},
}

HTTP响应代码

代码	描述
`202`	请求已被接受
`400`	请求格式错误
`500`	请求格式正确，但Dapr代码或底层组件出错

响应示例

RESPONSE = {
 "outputs": [
 {
 "result": "Dapr是分布式应用运行时...",
 "parameters": {},
 },
 {
 "result": "Dapr可以帮助开发者...",
 "parameters": {},
 }
 ],
}

下一步

会话API概述

Azure API Management 与 Dapr 的集成策略

Mon, 01 Jan 0001 00:00:00 +0000

Azure API Management 是一种用于为后端服务创建一致且现代的 API 网关的方法，其中也包括使用 Dapr 构建的服务。您可以在自托管的 API Management 网关中启用 Dapr 支持，从而实现以下功能：

将请求转发至 Dapr 服务
向 Dapr 发布/订阅主题发送消息
激活 Dapr 输出绑定

试用 Dapr & Azure API Management 集成示例。

了解更多关于 Dapr 集成策略的信息

配置 Azure Kubernetes 服务 (AKS) 集群

Mon, 01 Jan 0001 00:00:00 +0000

本指南将引导您安装 Azure Kubernetes 服务 (AKS) 集群。如果您需要更多信息，请参考快速入门：使用 Azure CLI 部署 AKS 集群

先决条件

安装：
- Docker
- kubectl
- Azure CLI

部署 AKS 集群

在终端中登录到 Azure。
```
az login
```

设置您的默认订阅：

az account set -s [your_subscription_id]

创建资源组。

az group create --name [your_resource_group] --location [region]

创建 AKS 集群。若需使用特定版本的 Kubernetes，请使用 --kubernetes-version 参数（需 1.13.x 或更高版本）。

az aks create --resource-group [your_resource_group] --name [your_aks_cluster_name] --node-count 2 --enable-addons http_application_routing --generate-ssh-keys

获取 AKS 集群的访问凭据。

az aks get-credentials -n [your_aks_cluster_name] -g [your_resource_group]

AKS Edge Essentials

要使用 Azure Kubernetes 服务 (AKS) Edge Essentials 创建单机 K8s/K3s Linux-only 集群，您可以按照 AKS Edge Essentials 快速入门指南进行操作。

在 Kubernetes 上调试 daprd

Mon, 01 Jan 0001 00:00:00 +0000

概述

有时我们需要了解 Dapr sidecar (daprd) 的运行情况，特别是在诊断 Dapr 应用程序时，怀疑 Dapr 本身是否存在问题。此外，您可能正在为 Kubernetes 上的 Dapr 开发新功能，并需要调试您的代码。

本指南介绍如何使用 Dapr 的内置调试功能来调试 Kubernetes pod 中的 Dapr sidecar。要了解如何查看日志和排查 Kubernetes 中的 Dapr 问题，请参阅配置和查看 Dapr 日志指南。

前提条件

请参阅本指南了解如何将 Dapr 部署到您的 Kubernetes 集群。
按照本指南构建您将在下一步中部署的 Dapr 调试二进制文件。

初始化 Dapr 调试模式

如果 Dapr 已经安装在您的 Kubernetes 集群中，请先卸载它：

dapr uninstall -k

我们将使用 ‘helm’ 来安装 Dapr 调试二进制文件。有关更多信息，请参阅使用 Helm 安装。

首先配置一个名为 values.yml 的值文件，选项如下：

global:
 registry: docker.io/<your docker.io id>
 tag: "dev-linux-amd64"

然后进入从您的克隆 dapr/dapr 仓库中的 ‘dapr’ 目录，并执行以下命令：

Conductor: 企业级 Dapr 的 Kubernetes 解决方案

Mon, 01 Jan 0001 00:00:00 +0000

Diagrid Conductor 能快速且安全地连接到所有运行 Dapr 和 Dapr 化应用程序的 Kubernetes 集群，提供卓越的操作管理、安全性、可靠性以及洞察力和协作能力。

Dapr 管理自动化

一键完成 Dapr 的安装、升级和修补，选择性应用更新并自动回滚，确保您始终使用最新版本。

智能顾问：发现并自动化最佳实践

提供信息并自动应用生产环境的最佳实践，持续监测以防止配置错误，提高安全性、可靠性和性能。

资源使用报告与优化

通过分析历史资源使用情况，推荐应用程序的资源优化方案，显著降低 CPU 和内存成本。

应用程序可视化工具

应用程序图表提供服务和基础设施组件的动态概览，促进开发与运维团队之间的协作。

了解更多关于 Diagrid Conductor

操作指南：在 Kubernetes 中设置 Fluentd、Elastic search 和 Kibana

Mon, 01 Jan 0001 00:00:00 +0000

前提条件

Kubernetes (> 1.14)
kubectl
Helm 3

安装 Elastic search 和 Kibana

创建一个用于监控工具的 Kubernetes 命名空间
```
kubectl create namespace dapr-monitoring
```

添加 Elastic Search 的 Helm 仓库

helm repo add elastic https://helm.elastic.co
helm repo update

使用 Helm 安装 Elastic Search

默认情况下，chart 会创建 3 个副本，要求它们位于不同的节点上。如果您的集群少于 3 个节点，请指定较少的副本数。例如，将副本数设置为 1：
```
helm install elasticsearch elastic/elasticsearch --version 7.17.3 -n dapr-monitoring --set replicas=1
```
否则：
```
helm install elasticsearch elastic/elasticsearch --version 7.17.3 -n dapr-monitoring
```
如果您使用 minikube 或仅在开发过程中想禁用持久卷，可以使用以下命令：
```
helm install elasticsearch elastic/elasticsearch --version 7.17.3 -n dapr-monitoring --set persistence.enabled=false,replicas=1
```
安装 Kibana

IntelliJ

Mon, 01 Jan 0001 00:00:00 +0000

在开发Dapr应用程序时，通常会使用Dapr CLI来启动您的服务，例如：

dapr run --app-id nodeapp --app-port 3000 --dapr-http-port 3500 app.js

这会使用默认的组件yaml文件（在执行dapr init时创建），使您的服务能够与本地Redis容器交互。这种方式在初期非常有用，但如果您需要附加调试器来逐步调试代码，该怎么办？此时，您可以选择不通过Dapr CLI直接启动应用程序。

一种方法是先通过命令行运行dapr run --，然后启动您的代码并附加调试器。虽然这种方法可行，但需要在终端和IDE之间切换，并且对其他开发人员来说可能不够直观。

本文档将介绍如何直接在IntelliJ中使用dapr进行调试。在开始之前，请确保您已通过dapr init初始化了Dapr的开发环境。

让我们开始吧！

将Dapr添加为“外部工具”

首先，在修改配置文件之前，请退出IntelliJ。

IntelliJ配置文件位置

对于版本2020.1及以上，工具的配置文件应位于：

%USERPROFILE%\AppData\Roaming\JetBrains\IntelliJIdea2020.1\tools\

$HOME/.config/JetBrains/IntelliJIdea2020.1/tools/

~/Library/Application\ Support/JetBrains/IntelliJIdea2020.1/tools/

对于2019.3或更早版本，配置文件位置不同。请参见此处了解更多详情。

如有需要，请更改路径中的IntelliJ版本。

在<CONFIG PATH>/tools/External\ Tools.xml中创建或编辑文件（如有需要更改路径中的IntelliJ版本）。<CONFIG PATH>是操作系统相关的，如上所示。

添加一个新的<tool></tool>条目：

mtls expiry CLI 命令指南

Mon, 01 Jan 0001 00:00:00 +0000

描述

用于检查根证书颁发机构 (CA) 证书的有效期

支持的平台

Kubernetes

用法

dapr mtls expiry [flags]

标志

名称	环境变量	默认值	描述
`--help`, `-h`			显示 expiry 的帮助信息

示例

# 查看 Kubernetes 证书的有效期
dapr mtls expiry

操作指南：配置 New Relic 进行分布式追踪

Mon, 01 Jan 0001 00:00:00 +0000

前提条件

需要一个 New Relic 账户，该账户永久免费，每月可免费处理 100 GB 的数据，包含 1 个完全访问用户和无限数量的基本用户。

配置 Dapr 追踪

Dapr 可以直接将其捕获的指标和追踪数据发送到 New Relic。最简单的方式是通过配置 Dapr，将追踪数据以 Zipkin 格式发送到 New Relic 的 Trace API。

为了将数据集成到 New Relic 的 Telemetry Data Platform，您需要一个 New Relic Insights Insert API key。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: appconfig
 namespace: default
spec:
 tracing:
 samplingRate: "1"
 zipkin:
 endpointAddress: "https://trace-api.newrelic.com/trace/v1?Api-Key=<NR-INSIGHTS-INSERT-API-KEY>&Data-Format=zipkin&Data-Format-Version=2"

查看追踪

New Relic 分布式追踪概览

New Relic 分布式追踪详情

Redis

Mon, 01 Jan 0001 00:00:00 +0000

查询状态。
创建聚合视图。
进行备份。

注意

以下示例使用 Redis CLI 针对使用默认 Dapr 状态存储实现的 Redis 存储。

连接到 Redis

您可以使用官方的 redis-cli 或任何其他兼容 Redis 的工具连接到 Redis 状态存储以直接查询 Dapr 状态。如果您在容器中运行 Redis，最简单的使用 redis-cli 的方法是通过容器：

docker run --rm -it --link <Redis 容器的名称> redis redis-cli -h <Redis 容器的名称>

按应用 ID 列出键

要获取与应用程序 “myapp” 关联的所有状态键，请使用命令：

KEYS myapp*

上述命令返回现有键的列表，例如：

1) "myapp||balance"
2) "myapp||amount"

获取特定状态数据

Dapr 将状态值保存为哈希值。每个哈希值包含一个 “data” 字段，其中存储状态数据，以及一个 “version” 字段，作为 ETag，表示不断递增的版本。

例如，要通过键 “balance” 获取应用程序 “myapp” 的状态数据，请使用命令：

HGET myapp||balance data

要获取状态版本/ETag，请使用命令：

HGET myapp||balance version

读取 actor 状态

要获取与应用程序 ID 为 “mypets” 的 actor 类型 “cat” 的实例 ID 为 “leroy” 关联的所有状态键，请使用命令：

操作指南：控制并发和限制应用程序的速率

Mon, 01 Jan 0001 00:00:00 +0000

在分布式计算中，通常您可能只希望允许一定数量的请求同时执行。通过使用 Dapr 的 app-max-concurrency，您可以控制同时调用您应用程序的请求和事件数量。

默认情况下，app-max-concurrency 设置为 -1，表示不限制并发数量。

不同的方法

本指南主要介绍 app-max-concurrency，但您也可以使用 middleware.http.ratelimit 中间件来限制每秒的请求速率。理解这两种方法的区别非常重要：

middleware.http.ratelimit：限制每秒的请求数量
app-max-concurrency：限制在任意时间点的最大并发请求（和事件）数量。

有关该方法的更多信息，请参见速率限制中间件。

演示

观看此视频以了解如何控制并发和速率限制。

配置 `app-max-concurrency`

如果不使用 Dapr，您需要在应用程序中创建某种信号量并负责获取和释放它。

使用 Dapr，您无需对应用程序进行任何代码更改。

选择您希望配置 app-max-concurrency 的方式。

要在本地开发环境中使用 Dapr CLI 设置并发限制，请添加 app-max-concurrency 标志：

dapr run --app-max-concurrency 1 --app-port 5000 python ./app.py

上述示例将您的应用程序变成一个顺序处理服务。

操作指南：从存储中管理配置

Mon, 01 Jan 0001 00:00:00 +0000

本示例使用Redis配置存储组件来演示如何检索配置项。

注意

如果您还没有试过，请尝试配置快速入门，快速了解如何使用配置API。

在存储中创建配置项

在支持的配置存储中创建一个配置项。这可以是一个简单的键值项，使用您选择的任何键。本示例使用Redis配置存储组件。

使用Docker运行Redis

docker run --name my-redis -p 6379:6379 -d redis:6

保存一个配置项

使用Redis CLI，连接到Redis实例：

redis-cli -p 6379

保存一个配置项：

MSET orderId1 "101||1" orderId2 "102||1"

配置Dapr配置存储

将以下组件文件保存到您机器上的默认组件文件夹。您可以将其用作Dapr组件YAML：

对于Kubernetes使用kubectl。
使用Dapr CLI运行时。

注意

由于Redis配置组件与Redis statestore.yaml组件具有相同的元数据，如果您已经有Redis statestore.yaml，可以直接复制或修改Redis状态存储组件类型。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: configstore
spec:
 type: configuration.redis
 metadata:
 - name: redisHost
 value: localhost:6379
 - name: redisPassword
 value: <PASSWORD>

检索配置项

获取配置项

以下示例展示了如何使用Dapr配置API获取已保存的配置项。

//依赖项
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Dapr.Client;

//代码
namespace ConfigurationApi
{
 public class Program
 {
 private static readonly string CONFIG_STORE_NAME = "configstore";

 public static async Task Main(string[] args)
 {
 using var client = new DaprClientBuilder().Build();
 var configuration = await client.GetConfiguration(CONFIG_STORE_NAME, new List<string>() { "orderId1", "orderId2" });
 Console.WriteLine($"Got key=\n{configuration[0].Key} -> {configuration[0].Value}\n{configuration[1].Key} -> {configuration[1].Value}");
 }
 }
}

//依赖项
import io.dapr.client.DaprClientBuilder;
import io.dapr.client.DaprClient;
import io.dapr.client.domain.ConfigurationItem;
import io.dapr.client.domain.GetConfigurationRequest;
import io.dapr.client.domain.SubscribeConfigurationRequest;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

//代码
private static final String CONFIG_STORE_NAME = "configstore";

public static void main(String[] args) throws Exception {
 try (DaprClient client = (new DaprClientBuilder()).build()) {
 List<String> keys = new ArrayList<>();
 keys.add("orderId1");
 keys.add("orderId2");
 GetConfigurationRequest req = new GetConfigurationRequest(CONFIG_STORE_NAME, keys);
 try {
 Mono<List<ConfigurationItem>> items = client.getConfiguration(req);
 items.block().forEach(ConfigurationClient::print);
 } catch (Exception ex) {
 System.out.println(ex.getMessage());
 }
 }
}

#依赖项
from dapr.clients import DaprClient
#代码
with DaprClient() as d:
 CONFIG_STORE_NAME = 'configstore'
 keys = ['orderId1', 'orderId2']
 #Dapr启动时间
 d.wait(20)
 configuration = d.get_configuration(store_name=CONFIG_STORE_NAME, keys=[keys], config_metadata={})
 print(f"Got key={configuration.items[0].key} value={configuration.items[0].value} version={configuration.items[0].version}")

package main

import (
	"context"
 "fmt"

	dapr "github.com/dapr/go-sdk/client"
)

func main() {
	ctx := context.Background()
	client, err := dapr.NewClient()
	if err != nil {
		panic(err)
	}
	items, err := client.GetConfigurationItems(ctx, "configstore", ["orderId1","orderId2"])
	if err != nil {
		panic(err)
	}
 for key, item := range items {
 fmt.Printf("get config: key = %s value = %s version = %s",key,(*item).Value, (*item).Version)
 }
}

import { CommunicationProtocolEnum, DaprClient } from "@dapr/dapr";

// JS SDK尚不支持通过HTTP协议的配置API
const protocol = CommunicationProtocolEnum.GRPC;
const host = process.env.DAPR_HOST ?? "localhost";
const port = process.env.DAPR_GRPC_PORT ?? 3500;

const DAPR_CONFIGURATION_STORE = "configstore";
const CONFIGURATION_ITEMS = ["orderId1", "orderId2"];

async function main() {
 const client = new DaprClient(host, port, protocol);
 // 从配置存储中获取配置项
 try {
 const config = await client.configuration.get(DAPR_CONFIGURATION_STORE, CONFIGURATION_ITEMS);
 Object.keys(config.items).forEach((key) => {
 console.log("Configuration for " + key + ":", JSON.stringify(config.items[key]));
 });
 } catch (error) {
 console.log("Could not get config item, err:" + error);
 process.exit(1);
 }
}

main().catch((e) => console.error(e));

启动一个Dapr sidecar：

操作指南：调度和处理触发的作业

Mon, 01 Jan 0001 00:00:00 +0000

现在您已经了解了作业构建块提供的功能，让我们来看一个如何使用API的示例。下面的代码示例描述了一个为数据库备份应用程序调度作业并在触发时处理它们的应用程序，也就是作业因到达其到期时间而被返回到应用程序的时间。

启动调度器服务

当您在本地托管模式或Kubernetes上运行dapr init时，Dapr调度器服务会启动。

设置作业API

在您的代码中，配置并调度应用程序内的作业。

以下.NET SDK代码示例调度名为prod-db-backup的作业。作业数据包含有关您将定期备份的数据库的信息。在本示例中，您将：

定义在示例其余部分中使用的类型
在应用程序启动期间注册一个端点，以处理服务上的所有作业触发调用
向Dapr注册作业

在以下示例中，您将创建记录，序列化并与作业一起注册，以便在将来作业被触发时可以使用这些信息：

备份任务的名称（db-backup）
备份任务的Metadata，包括：
- 数据库名称（DBName）
- 数据库位置（BackupLocation）

创建一个ASP.NET Core项目，并从NuGet添加最新版本的Dapr.Jobs。

注意： 虽然您的项目不严格需要使用Microsoft.NET.Sdk.Web SDK来创建作业，但在撰写本文档时，只有调度作业的服务会接收到其触发调用。由于这些调用期望有一个可以处理作业触发的端点，并且需要Microsoft.NET.Sdk.Web SDK，因此建议您为此目的使用ASP.NET Core项目。

首先定义类型以持久化我们的备份作业数据，并将我们自己的JSON属性名称属性应用于属性，以便它们与其他语言示例保持一致。

//定义我们将用来表示作业数据的类型
internal sealed record BackupJobData([property: JsonPropertyName("task")] string Task, [property: JsonPropertyName("metadata")] BackupMetadata Metadata);
internal sealed record BackupMetadata([property: JsonPropertyName("DBName")]string DatabaseName, [property: JsonPropertyName("BackupLocation")] string BackupLocation);

接下来，作为应用程序设置的一部分，设置一个处理程序，该处理程序将在作业在您的应用程序上被触发时调用。此处理程序负责根据提供的作业名称识别应如何处理作业。

这通过在ASP.NET Core中注册一个处理程序来实现，路径为/job/<job-name>，其中<job-name>是参数化的，并传递给此处理程序委托，以满足Dapr期望有一个端点可用于处理触发的命名作业。

在您的Program.cs文件中填入以下内容：

using System.Text;
using System.Text.Json;
using Dapr.Jobs;
using Dapr.Jobs.Extensions;
using Dapr.Jobs.Models;
using Dapr.Jobs.Models.Responses;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDaprJobsClient();
var app = builder.Build();

//注册一个端点以接收和处理触发的作业
var cancellationTokenSource = new CancellationTokenSource(TimeSpan.FromSeconds(5));
app.MapDaprScheduledJobHandler((string jobName, DaprJobDetails jobDetails, ILogger logger, CancellationToken cancellationToken) => {
 logger?.LogInformation("Received trigger invocation for job '{jobName}'", jobName);
 switch (jobName)
 {
 case "prod-db-backup":
 // 反序列化作业负载元数据
 var jobData = JsonSerializer.Deserialize<BackupJobData>(jobDetails.Payload);
 
 // 处理备份操作 - 我们假设这在您的代码中已实现
 await BackupDatabaseAsync(jobData, cancellationToken);
 break;
 }
}, cancellationTokenSource.Token);

await app.RunAsync();

最后，作业本身需要在Dapr中注册，以便可以在以后触发。您可以通过将DaprJobsClient注入到类中并作为应用程序的入站操作的一部分执行此操作，但为了本示例的目的，它将放在您上面开始的Program.cs文件的底部。因为您将使用依赖注入注册的DaprJobsClient，所以首先创建一个范围以便可以访问它。

操作指南：使用 conversation API 与 LLM 对话

Mon, 01 Jan 0001 00:00:00 +0000

Alpha

conversation API 目前处于 alpha 阶段。

让我们开始使用 conversation API。在本指南中，您将学习如何：

配置一个可用的 Dapr 组件（echo），以便与 conversation API 搭配使用。
将 conversation 客户端集成到您的应用程序中。
使用 dapr run 启动连接。

配置 conversation 组件

创建一个名为 conversation.yaml 的新配置文件，并将其保存到应用程序目录中的组件或配置子文件夹中。

为您的 conversation.yaml 文件选择合适的 conversation 组件规范。

在这个场景中，我们使用一个简单的 echo 组件。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: echo
spec:
 type: conversation.echo
 version: v1

集成 conversation 客户端

以下示例使用 HTTP 客户端向 Dapr 的 sidecar HTTP 端点发送 POST 请求。您也可以使用 Dapr SDK 客户端。

using Dapr.AI.Conversation;
using Dapr.AI.Conversation.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDaprConversationClient();

var app = builder.Build();

var conversationClient = app.Services.GetRequiredService<DaprConversationClient>();
var response = await conversationClient.ConverseAsync("conversation",
 new List<DaprConversationInput>
 {
 new DaprConversationInput(
 "Please write a witty haiku about the Dapr distributed programming framework at dapr.io",
 DaprConversationRole.Generic)
 });

Console.WriteLine("Received the following from the LLM:");
foreach (var resp in response.Outputs)
{
 Console.WriteLine($"\t{resp.Result}");
}

package main

import (
	"context"
	"fmt"
	dapr "github.com/dapr/go-sdk/client"
	"log"
)

func main() {
	client, err := dapr.NewClient()
	if err != nil {
		panic(err)
	}

	input := dapr.ConversationInput{
		Message: "Please write a witty haiku about the Dapr distributed programming framework at dapr.io",
		// Role: nil, // Optional
		// ScrubPII: nil, // Optional
	}

	fmt.Printf("conversation input: %s\n", input.Message)

	var conversationComponent = "echo"

	request := dapr.NewConversationRequest(conversationComponent, []dapr.ConversationInput{input})

	resp, err := client.ConverseAlpha1(context.Background(), request)
	if err != nil {
		log.Fatalf("err: %v", err)
	}

	fmt.Printf("conversation output: %s\n", resp.Outputs[0].Result)
}

use dapr::client::{ConversationInputBuilder, ConversationRequestBuilder};
use std::thread;
use std::time::Duration;

type DaprClient = dapr::Client<dapr::client::TonicClient>;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
 // Sleep to allow for the server to become available
 thread::sleep(Duration::from_secs(5));

 // Set the Dapr address
 let address = "https://127.0.0.1".to_string();

 let mut client = DaprClient::connect(address).await?;

 let input = ConversationInputBuilder::new("Please write a witty haiku about the Dapr distributed programming framework at dapr.io").build();

 let conversation_component = "echo";

 let request =
 ConversationRequestBuilder::new(conversation_component, vec![input.clone()]).build();

 println!("conversation input: {:?}", input.message);

 let response = client.converse_alpha1(request).await?;

 println!("conversation output: {:?}", response.outputs[0].result);
 Ok(())
}

启动 conversation 连接

使用 dapr run 命令启动连接。例如，在这个场景中，我们在一个应用程序上运行 dapr run，其应用程序 ID 为 conversation，并指向 ./config 目录中的 conversation YAML 文件。

操作指南：使用锁

Mon, 01 Jan 0001 00:00:00 +0000

了解了Dapr分布式锁API构建块的功能后，学习如何在服务中使用它。在本指南中，我们将通过一个示例应用程序演示如何使用Redis锁组件获取锁。有关支持的锁存储类型，请参阅此参考页面。

下图展示了相同应用程序的两个实例尝试获取锁，其中一个成功，另一个被拒绝。

下图展示了相同应用程序的两个实例，其中一个实例释放锁，另一个实例随后成功获取锁。

下图展示了不同应用程序的两个实例在同一资源上获取不同的锁。

配置锁组件

将以下组件文件保存到您机器上的默认组件文件夹。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: lockstore
spec:
 type: lock.redis
 version: v1
 metadata:
 - name: redisHost
 value: localhost:6379
 - name: redisPassword
 value: <PASSWORD>

获取锁

curl -X POST http://localhost:3500/v1.0-alpha1/lock/lockstore
 -H 'Content-Type: application/json'
 -d '{"resourceId":"my_file_name", "lockOwner":"random_id_abc123", "expiryInSeconds": 60}'

using System;
using Dapr.Client;

namespace LockService
{
 class Program
 {
 [Obsolete("Distributed Lock API is in Alpha, this can be removed once it is stable.")]
 static async Task Main(string[] args)
 {
 string DAPR_LOCK_NAME = "lockstore";
 string fileName = "my_file_name";
 var client = new DaprClientBuilder().Build();
 
 await using (var fileLock = await client.Lock(DAPR_LOCK_NAME, fileName, "random_id_abc123", 60))
 {
 if (fileLock.Success)
 {
 Console.WriteLine("Success");
 }
 else
 {
 Console.WriteLine($"Failed to lock {fileName}.");
 }
 }
 }
 }
}

package main

import (
 "fmt"

 dapr "github.com/dapr/go-sdk/client"
)

func main() {
 client, err := dapr.NewClient()
 if err != nil {
 panic(err)
 }
 defer client.Close()
 
 resp, err := client.TryLockAlpha1(ctx, "lockstore", &dapr.LockRequest{
			LockOwner: "random_id_abc123",
			ResourceID: "my_file_name",
			ExpiryInSeconds: 60,
		})

 fmt.Println(resp.Success)
}

解锁现有锁

curl -X POST http://localhost:3500/v1.0-alpha1/unlock/lockstore
 -H 'Content-Type: application/json'
 -d '{"resourceId":"my_file_name", "lockOwner":"random_id_abc123"}'

using System;
using Dapr.Client;

namespace LockService
{
 class Program
 {
 static async Task Main(string[] args)
 {
 string DAPR_LOCK_NAME = "lockstore";
 var client = new DaprClientBuilder().Build();

 var response = await client.Unlock(DAPR_LOCK_NAME, "my_file_name", "random_id_abc123"));
 Console.WriteLine(response.status);
 }
 }
}

package main

import (
 "fmt"

 dapr "github.com/dapr/go-sdk/client"
)

func main() {
 client, err := dapr.NewClient()
 if err != nil {
 panic(err)
 }
 defer client.Close()
 
 resp, err := client.UnlockAlpha1(ctx, "lockstore", &UnlockRequest{
			LockOwner: "random_id_abc123",
			ResourceID: "my_file_name",
		})

 fmt.Println(resp.Status)
}

下一步

阅读分布式锁API概述以了解更多信息。

订阅规范

Mon, 01 Jan 0001 00:00:00 +0000

Subscription Dapr 资源允许您使用外部组件的 YAML 文件以声明方式订阅主题。

注意

任何订阅都可以限制在特定的命名空间内，并通过作用域限制访问特定的应用程序。

本指南介绍了两种订阅 API 版本：

v2alpha（默认规范）
v1alpha1（已弃用）

`v2alpha1` 格式

以下是 Subscription 资源的基本 v2alpha1 规范。v2alpha1 是订阅 API 的默认规范。

apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
 name: <REPLACE-WITH-NAME>
spec:
 topic: <REPLACE-WITH-TOPIC-NAME> # 必需
 routes: # 必需
 rules:
 - match: <REPLACE-WITH-CEL-FILTER>
 path: <REPLACE-WITH-PATH>
 pubsubname: <REPLACE-WITH-PUBSUB-NAME> # 必需
 deadLetterTopic: <REPLACE-WITH-DEADLETTERTOPIC-NAME> # 可选
 bulkSubscribe: # 可选
 enabled: <REPLACE-WITH-BOOLEAN-VALUE>
 maxMessagesCount: <REPLACE-WITH-VALUE>
 maxAwaitDurationMs: <REPLACE-WITH-VALUE>
scopes:
- <REPLACE-WITH-SCOPED-APPIDS>

规范字段

字段	必需	详情	示例
topic	Y	您的组件订阅的主题名称。	`orders`
routes	Y	此主题的路由配置，包括指定将消息发送到特定路径的条件。包括以下字段： match: 用于匹配事件的 CEL 表达式。如果未指定，则该路由被视为默认路由。 path: 匹配此规则的事件的路径。所有主题消息发送到的端点。	`match: event.type == "widget"` `path: /widgets`
pubsubname	N	您的 pub/sub 组件的名称。	`pubsub`
deadLetterTopic	N	转发无法投递消息的死信主题的名称。	`poisonMessages`
bulkSubscribe	N	启用批量订阅功能。	`true`, `false`

`v1alpha1` 格式

以下是 Subscription 资源的基本 v1alpha1 规范。v1alpha1 现已弃用。

功能和概念

Mon, 01 Jan 0001 00:00:00 +0000

在您已经从高层次了解了工作流构建块之后，让我们深入探讨 Dapr 工作流引擎和 SDK 所包含的功能和概念。Dapr 工作流在所有支持的语言中都提供了几个核心功能和概念。

注意

有关工作流状态管理的更多信息，请参阅工作流架构指南。

工作流

Dapr 工作流是您编写的函数，用于定义一系列按特定顺序执行的任务。Dapr 工作流引擎负责调度和执行这些任务，包括管理故障和重试。如果托管工作流的应用程序在多台机器上扩展，工作流引擎还可以在多台机器上负载均衡工作流及其任务的执行。

工作流可以调度多种类型的任务，包括：

用于执行自定义逻辑的活动
用于将工作流休眠任意时间长度的持久计时器
用于将较大的工作流分解为较小部分的子工作流
用于阻塞工作流直到接收到外部事件信号的外部事件等待器。这些任务在其相应的部分中有更详细的描述。

工作流标识

每个您定义的工作流都有一个类型名称，工作流的每次执行都需要一个唯一的_实例 ID_。工作流实例 ID 可以由您的应用程序代码生成，这在工作流对应于业务实体（如文档或作业）时很有用，或者可以是自动生成的 UUID。工作流的实例 ID 对于调试以及使用工作流 API管理工作流非常有用。

在任何给定时间，只能存在一个具有给定 ID 的工作流实例。然而，如果一个工作流实例完成或失败，其 ID 可以被新的工作流实例重用。但请注意，新工作流实例实际上会在配置的状态存储中替换旧的实例。

工作流重放

Dapr 工作流通过使用一种称为事件溯源的技术来维护其执行状态。工作流引擎不是将工作流的当前状态存储为快照，而是管理一个仅追加的历史事件日志，描述工作流所采取的各种步骤。当使用工作流 SDK 时，这些历史事件会在工作流“等待”计划任务的结果时自动存储。

当工作流“等待”计划任务时，它会从内存中卸载自己，直到任务完成。一旦任务完成，工作流引擎会再次调度工作流函数运行。此时的工作流函数执行被称为_重放_。

当工作流函数被重放时，它会从头开始再次运行。然而，当它遇到已经完成的任务时，工作流引擎不会再次调度该任务，而是：

将已完成任务的存储结果返回给工作流。
继续执行直到下一个“等待”点。

这种“重放”行为会持续到工作流函数完成或因错误而失败。

通过这种重放技术，工作流能够从任何“等待”点恢复执行，就像它从未从内存中卸载过一样。即使是先前运行的局部变量的值也可以恢复，而无需工作流引擎了解它们存储了什么数据。这种恢复状态的能力使 Dapr 工作流具有_持久性_和_容错性_。

注意

这里描述的工作流重放行为要求工作流函数代码是_确定性的_。确定性的工作流函数在提供完全相同的输入时采取完全相同的操作。了解有关确定性工作流代码限制的更多信息。

无限循环和永恒工作流

如工作流重放部分所述，工作流维护其所有操作的仅写事件溯源历史日志。为了避免资源使用失控，工作流必须限制其调度的操作数量。例如，确保您的工作流不会：

在其实现中使用无限循环
调度数千个任务。

您可以使用以下两种技术来编写可能需要调度极大量任务的工作流：

使用 continue-as-new API：
每个工作流 SDK 都公开了一个 continue-as-new API，工作流可以调用该 API 以使用新的输入和历史记录重新启动自己。continue-as-new API 特别适合实现“永恒工作流”，如监控代理，否则将使用 while (true) 类构造实现。使用 continue-as-new 是保持工作流历史记录小的好方法。

配置中间件组件

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 允许通过串联一系列中间件组件来定义自定义处理管道。您可以在以下两种场景中使用中间件管道：

基础模块 API - 在调用任何 Dapr HTTP API 时执行 HTTP 中间件组件。
服务间调用 - HTTP 中间件组件应用于服务间调用。

配置 API 中间件管道

启动时，Dapr sidecar 会为传入的 HTTP 调用构建一个中间件处理管道。默认情况下，管道由追踪和 CORS 中间件组成。可以通过 Dapr configuration 配置的其他中间件按定义顺序添加到管道中。该管道适用于所有 Dapr API 端点，包括 state、pubsub、service-invocation、bindings、secret、configuration、分布式锁等。

请求在路由到用户代码之前会依次经过所有定义的中间件组件，然后在返回给客户端之前以相反的顺序再次经过这些中间件，如下图所示。

在使用 httpPipeline 配置调用 Dapr HTTP API 时，HTTP 中间件组件会被执行。

以下配置示例定义了一个自定义管道，使用了 OAuth 2.0 中间件和大写中间件组件。在这种情况下，所有请求在转发到用户代码之前都通过 OAuth 2.0 协议进行授权，并转换为大写文本。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: pipeline
 namespace: default
spec:
 httpPipeline:
 handlers:
 - name: oauth2
 type: middleware.http.oauth2
 - name: uppercase
 type: middleware.http.uppercase

与其他组件一样，中间件组件可以在支持的中间件参考和dapr/components-contrib 仓库中找到。

配置和查看 Dapr 日志

Mon, 01 Jan 0001 00:00:00 +0000

本节将帮助您了解 Dapr 中日志的工作原理，以及如何配置和查看日志。

概述

日志有不同的可配置级别。以下列出的级别适用于系统组件和 Dapr sidecar 进程/容器：

error
warn
info
debug

error 级别输出最少，而 debug 级别输出最多。默认级别是 info，它在正常情况下为操作 Dapr 提供了足够的信息。

要设置输出级别，可以使用 --log-level 命令行选项。例如：

./daprd --log-level error
./placement --log-level debug

这将以 error 日志级别启动 Dapr 运行时二进制文件，并以 debug 日志级别启动 Dapr actor 放置服务。

独立模式下的日志

在使用 Dapr CLI 运行应用程序时，可以通过传递 log-level 参数来设置日志级别：

dapr run --log-level warn node myapp.js

如上所述，每个 Dapr 二进制文件都接受一个 --log-level 参数。例如，要以警告级别启动放置服务：

./placement --log-level warn

查看独立模式下的日志

当使用 Dapr CLI 运行 Dapr 时，您的应用程序日志输出和运行时输出将被重定向到同一会话，方便调试。例如，这是运行 Dapr 时的输出：

如何：发布消息并订阅主题

Mon, 01 Jan 0001 00:00:00 +0000

既然您已经了解了Dapr pubsub构建块的功能，接下来我们来看看如何在您的服务中应用它。下面的代码示例描述了一个使用两个服务处理订单的应用程序，每个服务都有Dapr sidecar：

一个结账服务，使用Dapr订阅消息队列中的主题。
一个订单处理服务，使用Dapr向RabbitMQ发布消息。

Dapr会自动将用户的负载封装在符合CloudEvents v1.0的格式中，并使用Content-Type头的值作为datacontenttype属性。了解更多关于CloudEvents的消息。

以下示例展示了如何在您的应用程序中发布和订阅名为orders的主题。

注意

如果您还没有，请尝试pubsub快速入门，快速了解如何使用pubsub。

设置Pub/Sub组件

第一步是设置pubsub组件：

当您运行dapr init时，Dapr会创建一个默认的Redis pubsub.yaml并在您的本地机器上运行一个Redis容器，位置如下：

在Windows上，位于%UserProfile%\.dapr\components\pubsub.yaml
在Linux/MacOS上，位于~/.dapr/components/pubsub.yaml

使用pubsub.yaml组件，您可以轻松地更换底层组件而无需更改应用程序代码。在此示例中，使用RabbitMQ。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: order-pub-sub
spec:
 type: pubsub.rabbitmq
 version: v1
 metadata:
 - name: host
 value: "amqp://localhost:5672"
 - name: durable
 value: "false"
 - name: deletedWhenUnused
 value: "false"
 - name: autoAck
 value: "false"
 - name: reconnectWait
 value: "0"
 - name: concurrency
 value: parallel
scopes:
 - orderprocessing
 - checkout

您可以通过创建一个包含该文件的组件目录（在此示例中为myComponents）并使用dapr run CLI命令的--resources-path标志来覆盖此文件。

如何：使用加密API

Mon, 01 Jan 0001 00:00:00 +0000

在您了解了Dapr作为加密构建块之后，让我们通过使用SDK来学习如何使用加密API。

注意

Dapr加密功能目前处于alpha测试阶段。

加密

在您的项目中使用Dapr SDK和gRPC API，您可以加密数据流，例如文件或字符串：

# 当传递数据（缓冲区或字符串）时，`encrypt`会返回一个包含加密信息的缓冲区
def encrypt_decrypt_string(dapr: DaprClient):
 message = 'The secret is "passw0rd"'

 # 加密消息
 resp = dapr.encrypt(
 data=message.encode(),
 options=EncryptOptions(
 # 加密组件的名称（必需）
 component_name=CRYPTO_COMPONENT_NAME,
 # 存储在加密组件中的密钥（必需）
 key_name=RSA_KEY_NAME,
 # 用于包装密钥的算法，必须由上述密钥支持。
 # 选项包括："RSA", "AES"
 key_wrap_algorithm='RSA',
 ),
 )

 # 该方法返回一个可读流，我们将其完整读取到内存中
 encrypt_bytes = resp.read()
 print(f'加密后的消息长度为 {len(encrypt_bytes)} 字节')

在您的项目中使用Dapr SDK和gRPC API，您可以加密缓冲区或字符串中的数据：

如何检索 Secret

Mon, 01 Jan 0001 00:00:00 +0000

在了解了Dapr Secret 构建块的功能后，接下来学习如何在服务中使用它。本指南将演示如何调用 Secret API，并从配置的 Secret 存储中将 Secret 检索到应用程序代码中。

提示

如果您还没有尝试过，请先查看 Secret 管理快速入门，以快速了解如何使用 Secret API。

配置 Secret 存储

在应用程序代码中检索 Secret 之前，您需要先配置一个 Secret 存储组件。此示例配置了一个使用本地 JSON 文件存储 Secret 的 Secret 存储。

警告

在生产环境中，不建议使用本地 Secret 存储。请查看其他安全管理 Secret 的方案。

在项目目录中，创建一个名为 secrets.json 的文件，内容如下：

{
 "secret": "Order Processing pass key"
}

创建一个名为 components 的新目录。进入该目录并创建一个名为 local-secret-store.yaml 的组件文件，内容如下：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: localsecretstore
spec:
 type: secretstores.local.file
 version: v1
 metadata:
 - name: secretsFile
 value: secrets.json  # Secret 文件的路径
 - name: nestedSeparator
 value: ":"

注意

Secret 存储 JSON 的路径是相对于您执行 dapr run 命令的位置。

更多信息：

如何使用多应用运行模板文件

Mon, 01 Jan 0001 00:00:00 +0000

注意

目前，多应用运行在 Kubernetes 中是一个预览功能。

多应用运行模板文件是一个 YAML 文件，您可以使用它一次运行多个应用。在本指南中，您将学习如何：

使用多应用运行模板
查看已启动的应用
停止多应用运行模板
结构化多应用运行模板文件

使用多应用运行模板

您可以通过以下两种方式之一使用多应用运行模板文件：

通过提供目录路径执行

当您提供目录路径时，CLI 会在该目录中寻找名为 dapr.yaml 的多应用运行模板文件。如果找不到该文件，CLI 会返回错误。

执行以下 CLI 命令以读取默认名为 dapr.yaml 的多应用运行模板文件：

# 如果给定目录路径，模板文件需要默认命名为 `dapr.yaml`

dapr run -f <dir_path>

dapr run -f <dir_path> -k

通过提供文件路径执行

如果多应用运行模板文件的名称不是 dapr.yaml，您可以将相对或绝对文件路径提供给命令：

dapr run -f ./path/to/<your-preferred-file-name>.yaml

dapr run -f ./path/to/<your-preferred-file-name>.yaml -k

查看已启动的应用

一旦多应用模板正在运行，您可以使用以下命令查看已启动的应用：

使用 OAuth 配置端点授权

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 的 OAuth 2.0 中间件允许您在 Dapr 端点上为 Web API 启用 OAuth 授权，支持授权码模式。您还可以将授权令牌注入到端点 API 中，这些令牌可用于通过客户端凭证模式对 API 调用的外部 API 进行授权。启用中间件后，所有通过 Dapr 的方法调用在传递给用户代码之前都需要进行授权。

这两种模式的主要区别在于，授权码模式需要用户交互并授权用户，而客户端凭证模式不需要用户交互，授权的是服务或应用程序。

在授权服务器上注册您的应用程序

不同的授权服务器提供不同的应用程序注册体验。以下是一些示例：

要配置 Dapr OAuth 中间件，您需要收集以下信息：

客户端 ID (参见这里)
客户端密钥 (参见这里)
范围 (参见这里)
授权 URL
令牌 URL

一些流行的授权服务器的授权/令牌 URL：

服务器	授权 URL	令牌 URL
Microsoft Entra ID	https://login.microsoftonline.com/{tenant}/oauth2/authorize	https://login.microsoftonline.com/{tenant}/oauth2/token
GitHub	https://github.com/login/oauth/authorize	https://github.com/login/oauth/access_token
Google	https://accounts.google.com/o/oauth2/v2/auth	https://accounts.google.com/o/oauth2/token https://www.googleapis.com/oauth2/v4/token
Twitter	https://api.twitter.com/oauth/authorize	https://api.twitter.com/oauth2/token

定义中间件组件

定义授权码模式组件

OAuth 中间件（授权码模式）由以下组件定义：

Dapr SDK中的序列化

Mon, 01 Jan 0001 00:00:00 +0000

Dapr的SDK应该提供两种用例的序列化功能。首先是通过请求和响应负载发送的API对象。其次是需要持久化的对象。对于这两种用例，SDK提供了默认的序列化。在Java SDK中，使用DefaultObjectSerializer类来进行JSON序列化。

服务调用

 DaprClient client = (new DaprClientBuilder()).build();
 client.invokeService("myappid", "saySomething", "My Message", HttpExtension.POST).block();

在上面的示例中，应用程序会收到一个针对saySomething方法的POST请求，请求负载为"My Message" - 引号是因为序列化器会将输入字符串序列化为JSON格式。

POST /saySomething HTTP/1.1
Host: localhost
Content-Type: text/plain
Content-Length: 12

"My Message"

状态管理

 DaprClient client = (new DaprClientBuilder()).build();
 client.saveState("MyStateStore", "MyKey", "My Message").block();

在此示例中，My Message将被保存。它没有加引号，因为Dapr的API会在内部解析JSON请求对象后再保存它。

[
 {
 "key": "MyKey",
 "value": "My Message"
 }
]

发布订阅

 DaprClient client = (new DaprClientBuilder()).build();
 client.publishEvent("TopicName", "My Message").block();

事件被发布，内容被序列化为byte[]并发送到Dapr sidecar。订阅者将以CloudEvent的形式接收它。CloudEvent定义data为字符串。Dapr SDK还为CloudEvent对象提供了内置的反序列化器。

 @PostMapping(path = "/TopicName")
 public void handleMessage(@RequestBody(required = false) byte[] body) {
 // Dapr的事件符合CloudEvent。
 CloudEvent event = CloudEvent.deserialize(body);
 }

绑定

在这种情况下，对象也被序列化为byte[]，输入绑定接收原始的byte[]并将其反序列化为预期的对象类型。

支持的运行时和SDK版本

Mon, 01 Jan 0001 00:00:00 +0000

介绍

本主题详细介绍了Dapr版本的支持策略、升级策略，以及在所有Dapr代码库（如运行时、CLI、SDK等）中如何传达弃用和重大更改的信息，适用于1.x及以上版本。

Dapr版本采用MAJOR.MINOR.PATCH的版本号格式。例如，1.0.0。

版本号	描述
`MAJOR`	当运行时有不兼容的更改时更新，例如API的更改。`MAJOR`版本也可能在有显著功能添加或更改时发布，以便与之前版本区分。
`MINOR`	作为常规发布节奏的一部分更新，包括新功能、错误修复和安全修复。
`PATCH`	针对关键问题（如P0问题）和安全修复进行更新。

支持的版本指的是：

如果版本存在关键问题，例如主线中断或安全问题，将发布修补程序。每个问题都根据具体情况进行评估。
对支持的版本进行问题调查。如果版本不再受支持，您需要升级到较新的版本以确定问题是否仍然存在。

从1.8.0版本开始，Dapr支持三个版本：当前版本和之前的两个版本。通常这些是MINOR版本更新。这意味着支持版本的动态窗口会向前移动，您有责任保持这些支持版本的最新状态。如果您使用较旧版本的Dapr，可能需要进行中间升级以达到支持的版本。

在major.minor版本发布之间至少有13周（3个月）的时间，给用户至少9个月的时间从不支持的版本进行升级。有关发布过程的更多详细信息，请阅读发布周期和节奏。

补丁支持适用于当前和之前的支持版本。

构建变体

Dapr的sidecar镜像被发布到GitHub容器注册表和Docker注册表。默认镜像包含所有组件。从1.11版本开始，Dapr还提供了仅包含稳定组件的sidecar镜像变体。

默认sidecar镜像：daprio/daprd:<version>或ghcr.io/dapr/daprd:<version>（例如ghcr.io/dapr/daprd:1.11.1）
稳定组件的sidecar镜像：daprio/daprd:<version>-stablecomponents或ghcr.io/dapr/daprd:<version>-stablecomponents（例如ghcr.io/dapr/daprd:1.11.1-stablecomponents）

在Kubernetes上，可以通过dapr.io/sidecar-image注释覆盖应用程序部署资源的sidecar镜像。有关更多信息，请参阅Dapr的参数和注释。如果未指定，则使用默认的’daprio/daprd:latest’镜像。

了解更多关于Dapr组件的认证生命周期。

支持的版本

下表显示了已一起测试并形成“打包”发布的Dapr版本。任何其他版本组合都不受支持。

发布日期	运行时	CLI	SDKs	仪表板	状态	发布说明
2024年9月16日	1.14.4	1.14.1	Java 1.12.0 Go 1.11.0 PHP 1.2.0 Python 1.14.0 .NET 1.14.0 JS 3.3.1	0.15.0	支持（当前）	v1.14.4发布说明
2024年9月13日	1.14.3	1.14.1	Java 1.12.0 Go 1.11.0 PHP 1.2.0 Python 1.14.0 .NET 1.14.0 JS 3.3.1	0.15.0	⚠️ 已召回	v1.14.3发布说明
2024年9月6日	1.14.2	1.14.1	Java 1.12.0 Go 1.11.0 PHP 1.2.0 Python 1.14.0 .NET 1.14.0 JS 3.3.1	0.15.0	支持（当前）	v1.14.2发布说明
2024年8月14日	1.14.1	1.14.1	Java 1.12.0 Go 1.11.0 PHP 1.2.0 Python 1.14.0 .NET 1.14.0 JS 3.3.1	0.15.0	支持（当前）	v1.14.1发布说明
2024年8月14日	1.14.0	1.14.0	Java 1.12.0 Go 1.11.0 PHP 1.2.0 Python 1.14.0 .NET 1.14.0 JS 3.3.1	0.15.0	支持（当前）	v1.14.0发布说明
2024年5月29日	1.13.4	1.13.0	Java 1.11.0 Go 1.10.0 PHP 1.2.0 Python 1.13.0 .NET 1.13.0 JS 3.3.0	0.14.0	支持	v1.13.4发布说明
2024年5月21日	1.13.3	1.13.0	Java 1.11.0 Go 1.10.0 PHP 1.2.0 Python 1.13.0 .NET 1.13.0 JS 3.3.0	0.14.0	支持	v1.13.3发布说明
2024年4月3日	1.13.2	1.13.0	Java 1.11.0 Go 1.10.0 PHP 1.2.0 Python 1.13.0 .NET 1.13.0 JS 3.3.0	0.14.0	支持	v1.13.2发布说明
2024年3月26日	1.13.1	1.13.0	Java 1.11.0 Go 1.10.0 PHP 1.2.0 Python 1.13.0 .NET 1.13.0 JS 3.3.0	0.14.0	支持	v1.13.1发布说明
2024年3月6日	1.13.0	1.13.0	Java 1.11.0 Go 1.10.0 PHP 1.2.0 Python 1.13.0 .NET 1.13.0 JS 3.3.0	0.14.0	支持	v1.13.0发布说明
2024年1月17日	1.12.4	1.12.0	Java 1.10.0 Go 1.9.1 PHP 1.2.0 Python 1.12.0 .NET 1.12.0 JS 3.2.0	0.14.0	支持	v1.12.4发布说明
2024年1月2日	1.12.3	1.12.0	Java 1.10.0 Go 1.9.1 PHP 1.2.0 Python 1.12.0 .NET 1.12.0 JS 3.2.0	0.14.0	支持	v1.12.3发布说明
2023年11月18日	1.12.2	1.12.0	Java 1.10.0 Go 1.9.1 PHP 1.2.0 Python 1.12.0 .NET 1.12.0 JS 3.2.0	0.14.0	支持	v1.12.2发布说明
2023年11月16日	1.12.1	1.12.0	Java 1.10.0 Go 1.9.1 PHP 1.2.0 Python 1.12.0 .NET 1.12.0 JS 3.2.0	0.14.0	支持	v1.12.1发布说明
2023年10月11日	1.12.0	1.12.0	Java 1.10.0 Go 1.9.0 PHP 1.1.0 Python 1.11.0 .NET 1.12.0 JS 3.1.2	0.14.0	支持	v1.12.0发布说明
2023年11月18日	1.11.6	1.11.0	Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0	0.13.0	不支持	v1.11.6发布说明
2023年11月3日	1.11.5	1.11.0	Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0	0.13.0	不支持	v1.11.5发布说明
2023年10月5日	1.11.4	1.11.0	Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0	0.13.0	不支持	v1.11.4发布说明
2023年8月31日	1.11.3	1.11.0	Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0	0.13.0	不支持	v1.11.3发布说明
2023年7月20日	1.11.2	1.11.0	Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0	0.13.0	不支持	v1.11.2发布说明
2023年6月22日	1.11.1	1.11.0	Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0	0.13.0	不支持	v1.11.1发布说明
2023年6月12日	1.11.0	1.11.0	Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0	0.13.0	不支持	v1.11.0发布说明
2023年11月18日	1.10.10	1.10.0	Java 1.8.0 Go 1.7.0 PHP 1.1.0 Python 1.9.0 .NET 1.10.0 JS 3.0.0	0.11.0	不支持
2023年7月20日	1.10.9	1.10.0	Java 1.8.0 Go 1.7.0 PHP 1.1.0 Python 1.9.0 .NET 1.10.0 JS 3.0.0	0.11.0	不支持
2023年6月22日	1.10.8	1.10.0	Java 1.8.0 Go 1.7.0 PHP 1.1.0 Python 1.9.0 .NET 1.10.0 JS 3.0.0	0.11.0	不支持
2023年5月15日	1.10.7	1.10.0	Java 1.8.0 Go 1.7.0 PHP 1.1.0 Python 1.9.0 .NET 1.10.0 JS 3.0.0	0.11.0	不支持
2023年5月12日	1.10.6	1.10.0	Java 1.8.0 Go 1.7.0 PHP 1.1.0 Python 1.9.0 .NET 1.10.0 JS 3.0.0	0.11.0	不支持
2023年4月13日	1.10.5	1.10.0	Java 1.8.0 Go 1.6.0 PHP 1.1.0 Python 1.9.0 .NET 1.10.0 JS 3.0.0	0.11.0	不支持
2023年3月16日	1.10.4	1.10.0	Java 1.8.0 Go 1.6.0 PHP 1.1.0 Python 1.9.0 .NET 1.10.0 JS 2.5.0	0.11.0	不支持
2023年3月14日	1.10.3	1.10.0	Java 1.8.0 Go 1.6.0 PHP 1.1.0 Python 1.9.0 .NET 1.10.0 JS 2.5.0	0.11.0	不支持
2023年2月24日	1.10.2	1.10.0	Java 1.8.0 Go 1.6.0 PHP 1.1.0 Python 1.9.0 .NET 1.10.0 JS 2.5.0	0.11.0	不支持
2023年2月20日	1.10.1	1.10.0	Java 1.8.0 Go 1.6.0 PHP 1.1.0 Python 1.9.0 .NET 1.10.0 JS 2.5.0	0.11.0	不支持
2023年2月14日	1.10.0	1.10.0	Java 1.8.0 Go 1.6.0 PHP 1.1.0 Python 1.9.0 .NET 1.10.0 JS 2.5.0	0.11.0	不支持
2022年12月2日	1.9.5	1.9.1	Java 1.7.0 Go 1.6.0 PHP 1.1.0 Python 1.8.3 .NET 1.9.0 JS 2.4.2	0.11.0	不支持
2022年11月17日	1.9.4	1.9.1	Java 1.7.0 Go 1.6.0 PHP 1.1.0 Python 1.8.3 .NET 1.9.0 JS 2.4.2	0.11.0	不支持
2022年11月4日	1.9.3	1.9.1	Java 1.7.0 Go 1.6.0 PHP 1.1.0 Python 1.8.3 .NET 1.9.0 JS 2.4.2	0.11.0	不支持
2022年11月1日	1.9.2	1.9.1	Java 1.7.0 Go 1.6.0 PHP 1.1.0 Python 1.8.1 .NET 1.9.0 JS 2.4.2	0.11.0	不支持
2022年10月26日	1.9.1	1.9.1	Java 1.7.0 Go 1.6.0 PHP 1.1.0 Python 1.8.1 .NET 1.9.0 JS 2.4.2	0.11.0	不支持
2022年10月13日	1.9.0	1.9.1	Java 1.7.0 Go 1.6.0 PHP 1.1.0 Python 1.8.3 .NET 1.9.0 JS 2.4.2	0.11.0	不支持
2022年10月26日	1.8.6	1.8.1	Java 1.6.0 Go 1.5.0 PHP 1.1.0 Python 1.7.0 .NET 1.8.0 JS 2.3.0	0.11.0	不支持
2022年10月13日	1.8.5	1.8.1	Java 1.6.0 Go 1.5.0 PHP 1.1.0 Python 1.7.0 .NET 1.8.0 JS 2.3.0	0.11.0	不支持
2022年8月10日	1.8.4	1.8.1	Java 1.6.0 Go 1.5.0 PHP 1.1.0 Python 1.7.0 .NET 1.8.0 JS 2.3.0	0.11.0	不支持
2022年7月29日	1.8.3	1.8.0	Java 1.6.0 Go 1.5.0 PHP 1.1.0 Python 1.7.0 .NET 1.8.0 JS 2.3.0	0.11.0	不支持
2022年7月21日	1.8.2	1.8.0	Java 1.6.0 Go 1.5.0 PHP 1.1.0 Python 1.7.0 .NET 1.8.0 JS 2.3.0	0.11.0	不支持
2022年7月20日	1.8.1	1.8.0	Java 1.6.0 Go 1.5.0 PHP 1.1.0 Python 1.7.0 .NET 1.8.0 JS 2.3.0	0.11.0	不支持
2022年7月7日	1.8.0	1.8.0	Java 1.6.0 Go 1.5.0 PHP 1.1.0 Python 1.7.0 .NET 1.8.0 JS 2.3.0	0.11.0	不支持
2022年10月26日	1.7.5	1.7.0	Java 1.5.0 Go 1.4.0 PHP 1.1.0 Python 1.6.0 .NET 1.7.0 JS 2.2.1	0.10.0	不支持
2022年5月31日	1.7.4	1.7.0	Java 1.5.0 Go 1.4.0 PHP 1.1.0 Python 1.6.0 .NET 1.7.0 JS 2.2.1	0.10.0	不支持
2022年5月17日	1.7.3	1.7.0	Java 1.5.0 Go 1.4.0 PHP 1.1.0 Python 1.6.0 .NET 1.7.0 JS 2.2.1	0.10.0	不支持
2022年4月22日	1.7.2	1.7.0	Java 1.5.0 Go 1.4.0 PHP 1.1.0 Python 1.6.0 .NET 1.7.0 JS 2.1.0	0.10.0	不支持
2022年4月20日	1.7.1	1.7.0	Java 1.5.0 Go 1.4.0 PHP 1.1.0 Python 1.6.0 .NET 1.7.0 JS 2.1.0	0.10.0	不支持
2022年4月7日	1.7.0	1.7.0	Java 1.5.0 Go 1.4.0 PHP 1.1.0 Python 1.6.0 .NET 1.7.0 JS 2.1.0	0.10.0	不支持
2022年4月20日	1.6.2	1.6.0	Java 1.4.0 Go 1.3.1 PHP 1.1.0 Python 1.5.0 .NET 1.6.0 JS 2.0.0	0.9.0	不支持
2022年3月25日	1.6.1	1.6.0	Java 1.4.0 Go 1.3.1 PHP 1.1.0 Python 1.5.0 .NET 1.6.0 JS 2.0.0	0.9.0	不支持
2022年1月25日	1.6.0	1.6.0	Java 1.4.0 Go 1.3.1 PHP 1.1.0 Python 1.5.0 .NET 1.6.0 JS 2.0.0	0.9.0	不支持

SDK兼容性

SDK和运行时承诺除了安全问题所需的更改外，不会有重大更改。如果需要，所有重大更改都会在发布说明中宣布。

使用 CloudEvents 进行消息传递

Mon, 01 Jan 0001 00:00:00 +0000

为了实现消息路由并为每条消息提供额外的上下文，Dapr 采用 CloudEvents 1.0 规范作为其消息格式。通过 Dapr 发送到主题的任何消息都会自动被包装在 CloudEvents 信封中，使用 Content-Type 头部值作为 datacontenttype 属性。

Dapr 使用 CloudEvents 为事件负载提供额外的上下文，从而实现以下功能：

跟踪
事件数据的正确反序列化的内容类型
发送应用程序的验证

您可以选择以下三种方法之一通过发布订阅发布 CloudEvent：

发送一个发布订阅事件，然后由 Dapr 包装在 CloudEvent 信封中。
通过覆盖标准 CloudEvent 属性来替换 Dapr 提供的特定 CloudEvents 属性。
将您自己的 CloudEvent 信封作为发布订阅事件的一部分编写。

Dapr 生成的 CloudEvents 示例

向 Dapr 发送发布操作会自动将其包装在一个包含以下字段的 CloudEvent 信封中：

id
source
specversion
type
traceparent
traceid
tracestate
topic
pubsubname
time
datacontenttype (可选)

以下示例演示了 Dapr 为发布到 orders 主题的操作生成的 CloudEvent，其中包括：

一个 W3C traceid，唯一标识消息
data 和 CloudEvent 的字段，其中数据内容被序列化为 JSON

{
 "topic": "orders",
 "pubsubname": "order_pub_sub",
 "traceid": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01",
 "tracestate": "",
 "data": {
 "orderId": 1
 },
 "id": "5929aaac-a5e2-4ca1-859c-edfe73f11565",
 "specversion": "1.0",
 "datacontenttype": "application/json; charset=utf-8",
 "source": "checkout",
 "type": "com.dapr.event.sent",
 "time": "2020-09-23T06:23:21Z",
 "traceparent": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01"
}

作为另一个 v1.0 CloudEvent 的示例，以下显示了在 CloudEvent 消息中以 JSON 序列化的 XML 内容的数据：

发布和订阅非CloudEvents消息

Mon, 01 Jan 0001 00:00:00 +0000

在将Dapr集成到您的应用程序时，由于兼容性原因或某些应用程序不使用Dapr，某些服务可能仍需要通过不封装在CloudEvents中的pub/sub消息进行通信。这些消息被称为“原始”pub/sub消息。Dapr允许应用程序发布和订阅原始事件，这些事件未封装在CloudEvent中以实现兼容性。

发布原始消息

Dapr应用程序可以将原始事件发布到pub/sub主题中，而不需要CloudEvent封装，以便与非Dapr应用程序兼容。

警告

不使用CloudEvents会禁用对跟踪、每个messageId的事件去重、内容类型元数据以及任何其他基于CloudEvent架构构建的功能的支持。

要禁用CloudEvent封装，请在发布请求中将rawPayload元数据设置为true。这样，订阅者可以接收这些消息而无需解析CloudEvent架构。

curl -X "POST" http://localhost:3500/v1.0/publish/pubsub/TOPIC_A?metadata.rawPayload=true -H "Content-Type: application/json" -d '{"order-number": "345"}'

from dapr.clients import DaprClient

with DaprClient() as d:
 req_data = {
 'order-number': '345'
 }
 # 创建一个带有内容类型和主体的类型化消息
 resp = d.publish_event(
 pubsub_name='pubsub',
 topic_name='TOPIC_A',
 data=json.dumps(req_data),
 publish_metadata={'rawPayload': 'true'}
 )
 # 打印请求
 print(req_data, flush=True)

<?php

require_once __DIR__.'/vendor/autoload.php';

$app = \Dapr\App::create();
$app->run(function(\DI\FactoryInterface $factory) {
 $publisher = $factory->make(\Dapr\PubSub\Publish::class, ['pubsub' => 'pubsub']);
 $publisher->topic('TOPIC_A')->publish('data', ['rawPayload' => 'true']);
});

订阅原始消息

Dapr应用程序还可以订阅来自不使用CloudEvent封装的现有pub/sub主题的原始事件。

操作指南：将消息路由到不同的事件处理程序

Mon, 01 Jan 0001 00:00:00 +0000

pubsub 路由实现了基于内容的路由，这是一种使用 DSL 而不是命令式应用程序代码的消息模式。通过 pubsub 路由，您可以根据 CloudEvents 的内容，将消息路由到应用程序中的不同 URI/路径和事件处理程序。如果没有匹配的路由，则可以使用可选的默认路由。随着您的应用程序扩展以支持多个事件版本或特殊情况，这种方法将非常有用。

虽然可以通过代码实现路由，但将路由规则与应用程序分离可以提高可移植性。

此功能适用于声明式和编程式订阅方法，但不适用于流式订阅。

声明式订阅

对于声明式订阅，使用 dapr.io/v2alpha1 作为 apiVersion。以下是使用路由的 subscriptions.yaml 示例：

apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
 name: myevent-subscription
spec:
 pubsubname: pubsub
 topic: inventory
 routes:
 rules:
 - match: event.type == "widget"
 path: /widgets
 - match: event.type == "gadget"
 path: /gadgets
 default: /products
scopes:
 - app1
 - app2

编程式订阅

在编程方法中，返回的是 routes 结构而不是 route。JSON 结构与声明式 YAML 匹配：

import flask
from flask import request, jsonify
from flask_cors import CORS
import json
import sys

app = flask.Flask(__name__)
CORS(app)

@app.route('/dapr/subscribe', methods=['GET'])
def subscribe():
 subscriptions = [
 {
 'pubsubname': 'pubsub',
 'topic': 'inventory',
 'routes': {
 'rules': [
 {
 'match': 'event.type == "widget"',
 'path': '/widgets'
 },
 {
 'match': 'event.type == "gadget"',
 'path': '/gadgets'
 },
 ],
 'default': '/products'
 }
 }]
 return jsonify(subscriptions)

@app.route('/products', methods=['POST'])
def ds_subscriber():
 print(request.json, flush=True)
 return json.dumps({'success':True}), 200, {'ContentType':'application/json'}
app.run()

const express = require('express')
const bodyParser = require('body-parser')
const app = express()
app.use(bodyParser.json({ type: 'application/*+json' }));

const port = 3000

app.get('/dapr/subscribe', (req, res) => {
 res.json([
 {
 pubsubname: "pubsub",
 topic: "inventory",
 routes: {
 rules: [
 {
 match: 'event.type == "widget"',
 path: '/widgets'
 },
 {
 match: 'event.type == "gadget"',
 path: '/gadgets'
 },
 ],
 default: '/products'
 }
 }
 ]);
})

app.post('/products', (req, res) => {
 console.log(req.body);
 res.sendStatus(200);
});

app.listen(port, () => console.log(`consumer app listening on port ${port}!`))

 [Topic("pubsub", "inventory", "event.type ==\"widget\"", 1)]
 [HttpPost("widgets")]
 public async Task<ActionResult<Stock>> HandleWidget(Widget widget, [FromServices] DaprClient daprClient)
 {
 // Logic
 return stock;
 }

 [Topic("pubsub", "inventory", "event.type ==\"gadget\"", 2)]
 [HttpPost("gadgets")]
 public async Task<ActionResult<Stock>> HandleGadget(Gadget gadget, [FromServices] DaprClient daprClient)
 {
 // Logic
 return stock;
 }

 [Topic("pubsub", "inventory")]
 [HttpPost("products")]
 public async Task<ActionResult<Stock>> HandleProduct(Product product, [FromServices] DaprClient daprClient)
 {
 // Logic
 return stock;
 }

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"

	"github.com/gorilla/mux"
)

const appPort = 3000

type subscription struct {
	PubsubName string `json:"pubsubname"`
	Topic string `json:"topic"`
	Metadata map[string]string `json:"metadata,omitempty"`
	Routes routes `json:"routes"`
}

type routes struct {
	Rules []rule `json:"rules,omitempty"`
	Default string `json:"default,omitempty"`
}

type rule struct {
	Match string `json:"match"`
	Path string `json:"path"`
}

// This handles /dapr/subscribe
func configureSubscribeHandler(w http.ResponseWriter, _ *http.Request) {
	t := []subscription{
		{
			PubsubName: "pubsub",
			Topic: "inventory",
			Routes: routes{
				Rules: []rule{
					{
						Match: `event.type == "widget"`,
						Path: "/widgets",
					},
					{
						Match: `event.type == "gadget"`,
						Path: "/gadgets",
					},
				},
				Default: "/products",
			},
		},
	}

	w.WriteHeader(http.StatusOK)
	json.NewEncoder(w).Encode(t)
}

func main() {
	router := mux.NewRouter().StrictSlash(true)
	router.HandleFunc("/dapr/subscribe", configureSubscribeHandler).Methods("GET")
	log.Fatal(http.ListenAndServe(fmt.Sprintf(":%d", appPort), router))
}

<?php

require_once __DIR__.'/vendor/autoload.php';

$app = \Dapr\App::create(configure: fn(\DI\ContainerBuilder $builder) => $builder->addDefinitions(['dapr.subscriptions' => [
 new \Dapr\PubSub\Subscription(pubsubname: 'pubsub', topic: 'inventory', routes: (
 rules: => [
 ('match': 'event.type == "widget"', path: '/widgets'),
 ('match': 'event.type == "gadget"', path: '/gadgets'),
 ]
 default: '/products')),
]]));
$app->post('/products', function(
 #[\Dapr\Attributes\FromBody]
 \Dapr\PubSub\CloudEvent $cloudEvent,
 \Psr\Log\LoggerInterface $logger
 ) {
 $logger->alert('Received event: {event}', ['event' => $cloudEvent]);
 return ['status' => 'SUCCESS'];
 }
);
$app->start();

通用表达式语言 (CEL)

在这些示例中，根据 event.type，应用程序将被调用于：

重大变更和弃用

Mon, 01 Jan 0001 00:00:00 +0000

重大变更

重大变更是指对以下内容的修改，这些修改可能导致现有的第三方应用程序或脚本在升级到下一个稳定的小版本的 Dapr 工件（如 SDK、CLI、runtime 等）后出现编译错误或运行时问题：

代码行为
架构
默认配置值
命令行参数
发布的指标
Kubernetes 资源模板
公开访问的 API
公开可见的 SDK 接口、方法、类或属性

以下情况可以立即应用重大变更：

版本未达到 1.0.0 的项目
预览功能
Alpha API
SDK 中的预览或 Alpha 接口、类、方法或属性
处于 Alpha 或 Beta 阶段的 Dapr 组件
github.com/dapr/components-contrib 的接口
文档和博客中的 URL
例外情况，需要修复关键错误或安全漏洞。

应用重大变更的流程

应用重大变更需要遵循以下流程：

弃用通知必须作为发布的一部分进行发布。
重大变更将在弃用公告发布后的两个版本后生效。
- 例如，功能 X 在 1.0.0 版本说明中宣布弃用，然后将在 1.2.0 中移除。

弃用

弃用可以应用于：

API，包括 alpha API
预览功能
组件
CLI
可能导致安全漏洞的功能

弃用信息会在发布说明中名为“弃用”的部分中列出，说明：

当前弃用的功能将在未来某个版本中不再受支持。例如，发布 x.y.z。这至少是在两个版本之前。
在发布说明中记录用户需要采取的任何步骤以修改其代码、操作等（如果适用）。

在宣布未来的重大变更后，该变更将在 2 个版本或 6 个月后生效，以较长者为准。弃用的功能应响应警告，但除此之外不执行任何操作。

为 .NET SDK 贡献

Mon, 01 Jan 0001 00:00:00 +0000

欢迎！

如果你正在阅读这篇文章，说明你可能对为 Dapr 和/或 Dapr .NET SDK 做出贡献感兴趣。欢迎加入这个项目，感谢你对贡献的兴趣！

请查看文档，了解 Dapr 的定义及其目标，并通过 Discord 联系我们。告诉我们你想如何贡献，我们很乐意提供想法和建议。

有很多方式可以为 Dapr 做出贡献：

为 Dapr 运行时或 Dapr .NET SDK 提交错误报告
提出新的运行时功能或 SDK 功能
改进 Dapr 大项目或 Dapr .NET SDK 专门的文档
添加新的或改进现有的组件，以实现各种构建块
增强 .NET 可插拔组件 SDK 功能
改进 Dapr .NET SDK 代码库和/或修复错误（详见下文）

如果你是代码库的新手，请在 Discord 的 #dotnet-sdk 频道中询问如何进行更改或提出一般性问题。你不需要获得许可即可进行任何工作，但请注意，如果某个问题已分配给某人，这表明可能已经有人开始处理它了。特别是如果自上次活动以来已经有一段时间，请随时联系他们，看看他们是否仍然有兴趣继续，或者你是否可以接手，并提交你的实现的 pull request。

如果你想将自己分配给一个问题，请在对话中回复 “/assign”，机器人会将你分配给它。

我们将一些问题标记为 good-first-issue 或 help wanted，表明这些问题可能是小的、独立的更改。

如果你不确定你的实现，请将其创建为草稿 pull request，并通过标记 @dapr/maintainers-dotnet-sdk 向 .NET 维护者征求反馈，并提供一些关于你需要帮助的上下文。

贡献规则和最佳实践

在为 .NET SDK 贡献时，应遵循以下规则和最佳实践。

Pull Requests

仅包含格式更改的 pull request 通常不被鼓励。pull request 应该寻求修复错误、添加新功能或改进现有功能。

Dapr API 日志

Mon, 01 Jan 0001 00:00:00 +0000

API 日志记录可以让您查看应用程序对 Dapr sidecar 的 API 调用情况。这对于监控应用程序行为或进行调试非常有用。您还可以将 Dapr API 日志记录与 Dapr 日志事件结合使用（参见配置和查看 Dapr 日志），以便更好地利用日志记录功能。

概述

API 日志记录默认情况下是禁用的。

要启用 API 日志记录，可以在启动 daprd 进程时使用 --enable-api-logging 命令行选项。例如：

./daprd --enable-api-logging

在自托管模式下配置 API 日志记录

当使用 Dapr CLI 运行应用程序时，要启用 API 日志记录，请传递 --enable-api-logging 标志：

dapr run \
 --enable-api-logging \
 -- node myapp.js

在自托管模式下查看 API 日志

使用 Dapr CLI 运行 Dapr 时，您的应用程序日志输出和 Dapr 运行时日志输出会被重定向到同一会话中，便于调试。

下面的示例显示了一些 API 日志：

$ dapr run --enable-api-logging -- node myapp.js

ℹ️ Starting Dapr with id order-processor on port 56730
✅ You are up and running! Both Dapr and your app logs will appear here.
.....
INFO[0000] HTTP API Called app_id=order-processor instance=mypc method="POST /v1.0/state/mystate" scope=dapr.runtime.http-info type=log useragent=Go-http-client/1.1 ver=edge
== APP == INFO:root:Saving Order: {'orderId': '483'}
INFO[0000] HTTP API Called app_id=order-processor instance=mypc method="GET /v1.0/state/mystate/key123" scope=dapr.runtime.http-info type=log useragent=Go-http-client/1.1 ver=edge
== APP == INFO:root:Getting Order: {'orderId': '483'}
INFO[0000] HTTP API Called app_id=order-processor instance=mypc method="DELETE /v1.0/state/mystate" scope=dapr.runtime.http-info type=log useragent=Go-http-client/1.1 ver=edge
== APP == INFO:root:Deleted Order: {'orderId': '483'}
INFO[0000] HTTP API Called app_id=order-processor instance=mypc method="PUT /v1.0/metadata/cliPID" scope=dapr.runtime.http-info type=log useragent=Go-http-client/1.1 ver=edge

在 Kubernetes 中配置 API 日志记录

您可以通过在 pod 规范模板中添加以下注释来为 sidecar 启用 API 日志：

在 Dapr 中启用 API 令牌认证

Mon, 01 Jan 0001 00:00:00 +0000

默认情况下，Dapr 通过网络边界限制对其公共 API 的访问。如果您计划在该边界之外公开 Dapr API，或者您的部署需要额外的安全级别，请考虑为 Dapr API 启用令牌认证。这意味着 Dapr 将要求每个传入的 gRPC 和 HTTP 请求在通过之前包含认证令牌。

创建令牌

Dapr 通过共享令牌进行 API 认证。您可以自由定义要使用的 API 令牌。

虽然 Dapr 对共享令牌的格式没有具体要求，但一个好的做法是生成一个随机字节序列并将其编码为 Base64。例如，以下命令生成一个随机的 32 字节密钥并将其编码为 Base64：

openssl rand 16 | base64

在 Dapr 中配置 API 令牌认证

对于 Kubernetes 或自托管 Dapr 部署，令牌认证配置略有不同：

自托管

在自托管场景中，Dapr 会检查 DAPR_API_TOKEN 环境变量是否存在。如果在 daprd 进程启动时设置了该环境变量，Dapr 将对其公共 API 强制执行认证：

export DAPR_API_TOKEN=<token>

要更新配置的令牌，请将 DAPR_API_TOKEN 环境变量更新为新值并重新启动 daprd 进程。

Kubernetes

在 Kubernetes 部署中，Dapr 使用 Kubernetes secret 存储来保存共享令牌。要配置 Dapr API 认证，首先创建一个新的 secret：

如何使用 Testcontainers Dapr 模块进行集成

Mon, 01 Jan 0001 00:00:00 +0000

您可以通过 Diagrid 提供的 Testcontainers Dapr 模块，在本地为您的 Java 应用集成 Dapr。只需在您的 Maven 项目中添加以下依赖项：

<dependency>
 <groupId>io.diagrid.dapr</groupId>
 <artifactId>testcontainers-dapr</artifactId>
 <version>0.10.x</version>
</dependency>

如果您使用 Spring Boot，也可以使用 Spring Boot Starter。

了解更多关于 Testcontainers Dapr 模块

Azure Functions 运行时的 Dapr 扩展

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 通过一个扩展与 Azure Functions 运行时集成，使函数能够轻松地与 Dapr 交互。

Azure Functions 提供了一种事件驱动的编程模型。
Dapr 提供了云原生的构建模块。

该扩展结合了两者的优势，适用于无服务器和事件驱动的应用程序。

体验 Dapr 扩展 for Azure Functions

为 Go SDK 贡献

Mon, 01 Jan 0001 00:00:00 +0000

在为 Go SDK 贡献时，贡献者应该遵循以下规则和最佳实践。

示例

examples 目录包含用户可以运行的代码示例，以尝试各种 Go SDK 包和扩展的特定功能。在编写新的和更新的示例时，请注意：

所有示例应能在 Windows、Linux 和 MacOS 上运行。虽然 Go 代码在不同操作系统之间是一致的，但任何示例的前置/后置命令应通过 tabpane 提供不同的选项。
包含下载和安装任何必要前提条件的步骤。即使是刚安装操作系统的用户，也应该能够顺利开始并完成示例而不出现错误。可以链接到外部下载页面。

文档

daprdocs 目录包含被渲染到 Dapr Docs 网站的 markdown 文件。当文档网站构建时，此仓库会被克隆并配置，以便其内容与文档内容一起呈现。在编写文档时，请注意：

除了这些规则外，还应遵循 docs guide 中的所有规则。
所有文件和目录应以 go- 为前缀，以确保在所有 Dapr 文档中文件和目录名称的全局唯一性。

设置 Google Kubernetes Engine (GKE) 集群

Mon, 01 Jan 0001 00:00:00 +0000

前提条件

安装:
- kubectl
- Google Cloud SDK

创建新集群

运行以下命令以创建 GKE 集群：

$ gcloud services enable container.googleapis.com && \
 gcloud container clusters create $CLUSTER_NAME \
 --zone $ZONE \
 --project $PROJECT_ID

更多选项请参阅：

Google Cloud SDK 文档。
通过 Cloud Console 创建集群以获得更具互动性的体验。

私有 GKE 集群的 Sidecar 注入

私有集群的 Sidecar 注入需要额外步骤。

在私有 GKE 集群中，自动创建的主访问防火墙规则未开放 Dapr 所需的 4000 端口用于 Sidecar 注入。

查看相关的防火墙规则：

$ gcloud compute firewall-rules list --filter="name~gke-${CLUSTER_NAME}-[0-9a-z]*-master"

更新现有规则以允许 Kubernetes 主节点访问 4000 端口：

$ gcloud compute firewall-rules update <firewall-rule-name> --allow tcp:10250,tcp:443,tcp:4000

获取 `kubectl` 的凭据

运行以下命令以获取您的凭据：

为 Java SDK 贡献

Mon, 01 Jan 0001 00:00:00 +0000

贡献 Java SDK 时，应该遵循以下规则和最佳实践。

示例

examples 目录中包含用户可以运行的代码示例，用于尝试各种 Java SDK 包和扩展的特定功能。在编写或更新示例时，请注意：

所有示例应能在 Windows、Linux 和 MacOS 上运行。虽然 Java 代码在不同操作系统上是一致的，但任何示例的前置或后续命令应通过 tabpane 提供不同的选项。
包含下载和安装所有必要前提条件的步骤。即使是全新安装操作系统的用户，也应该能够顺利开始并完成示例。可以链接到外部下载页面。

文档

daprdocs 目录中包含的 markdown 文件会被渲染到 Dapr Docs 网站上。当文档网站构建时，此仓库会被克隆并配置，以便其内容与文档内容一起渲染。在编写文档时，请注意：

除了这些规则外，还应遵循 docs guide 中的所有规则。
所有文件和目录名称应以 java- 为前缀，以确保在所有 Dapr 文档中具有全局唯一性。

贡献到 JavaScript SDK

Mon, 01 Jan 0001 00:00:00 +0000

在为 JavaScript SDK 贡献时，应遵循以下规则和最佳实践。

💡 你可以运行 npm pretty-fix 来格式化所有文件

提交指南

Dapr JavaScript SDK 遵循 Conventional Commits 规范。自动生成的变更日志工具会根据提交信息自动生成变更日志。以下是编写提交信息的指南：

格式

type(scope)!: subject

type: 提交的类型是以下之一：
- feat: 新功能。
- fix: 错误修复。
- docs: 文档更改。
- refactor: 重构特定代码部分，不引入新功能或错误修复。
- style: 代码风格改进。
- perf: 性能改进。
- test: 测试套件的更改。
- ci: CI 系统的更改。
- build: 构建系统的更改（我们目前没有，所以不适用）。
- chore: 其他不符合上述类型的更改。这不会出现在变更日志中。
scope: 提交更改的代码库部分。如果更改了多个部分，或没有特定部分被修改，则留空，不加括号。示例：
- 添加 test 的提交：
```
test(actors): add an actor test
```
- 一次更改多项的提交：
```
style: adopt eslint
```
对于示例的更改，范围应为示例名称，前缀为 examples/：
- ❌ fix(agnoster): commit subject
- ✅ fix(examples/http/actor): commit subject
!: 这个符号放在 scope（或 type 如果范围为空）之后，表示提交引入了重大更改。

如何：使用 KEDA 自动扩展 Dapr 应用

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 通过其构建块 API 方法和众多 pubsub 组件，简化了消息处理应用程序的编写。由于 Dapr 可以在虚拟机、裸机、云或边缘 Kubernetes 等多种环境中运行，因此 Dapr 应用程序的自动扩展由其运行环境的管理层负责。

在 Kubernetes 环境中，Dapr 与 KEDA 集成，KEDA 是一个用于 Kubernetes 的事件驱动自动扩展器。Dapr 的许多 pubsub 组件与 KEDA 提供的扩展器功能相似，因此可以轻松配置您的 Dapr 部署在 Kubernetes 上使用 KEDA 根据负载进行自动扩展。

在本指南中，您将配置一个可扩展的 Dapr 应用程序，并在 Kafka 主题上进行负载管理。不过，您可以将此方法应用于 Dapr 提供的任何 pubsub 组件。

注意

如果您正在使用 Azure 容器应用，请参阅官方 Azure 文档以了解使用 KEDA 扩展器扩展 Dapr 应用程序。

安装 KEDA

要安装 KEDA，请按照 KEDA 网站上的部署 KEDA说明进行操作。

安装和部署 Kafka

如果您无法访问 Kafka 服务，可以使用 Helm 将其安装到您的 Kubernetes 集群中以进行此示例：

helm repo add confluentinc https://confluentinc.github.io/cp-helm-charts/
helm repo update
kubectl create ns kafka
helm install kafka confluentinc/cp-helm-charts -n kafka \
		--set cp-schema-registry.enabled=false \
		--set cp-kafka-rest.enabled=false \
		--set cp-kafka-connect.enabled=false

检查 Kafka 部署的状态：

mtls renew certificate CLI 命令参考

Mon, 01 Jan 0001 00:00:00 +0000

描述

此命令用于更新即将到期的 Dapr 证书。例如，Dapr Sentry 服务会生成应用程序使用的默认根证书和颁发者证书。详情请参见安全的 Dapr 到 Dapr 通信

支持的平台

Kubernetes

用法

dapr mtls renew-certificate [flags]

标志

名称	默认值	描述
`--help`, `-h`		renew-certificate 的帮助信息
`--kubernetes`, `-k`	`false`	支持的平台
`--valid-until`	365 天	新创建证书的有效期
`--restart`	false	重启 Dapr 控制平面服务（Sentry 服务、Operator 服务和 Placement 服务器）
`--timeout`	300 秒	证书更新过程的超时时间
`--ca-root-certificate`		用户提供的 PEM 根证书的文件路径
`--issuer-public-certificate`		用户提供的 PEM 颁发者证书的文件路径
`--issuer-private-key`		用户提供的 PEM 颁发者私钥的文件路径
`--private-key`		用户提供的用于生成根证书的 root.key 文件

示例

通过生成全新证书来更新证书

为 Kubernetes 集群生成新的根证书和颁发者证书，默认有效期为 365 天。证书不会立即应用于 Dapr 控制平面。

操作指南：为 Dapr 日志配置 New Relic

Mon, 01 Jan 0001 00:00:00 +0000

前提条件

注册一个 New Relic 账户，享受每月 100 GB 的免费数据摄取、1 个免费完全访问用户和无限制的免费基本用户。

背景

New Relic 提供了一个 Fluent Bit 输出插件，可以轻松地将日志转发到 New Relic Logs。该插件也可以作为独立的 Docker 镜像使用，并在 Kubernetes 集群中以 DaemonSet 的形式安装，我们称之为 Kubernetes 插件。

本文档将解释如何在集群中安装此插件，推荐使用 Helm chart，也可以通过应用 Kubernetes 清单手动安装。

安装

使用 Helm chart 安装（推荐）

按照官方说明安装 Helm。
添加 New Relic 官方 Helm chart 仓库。
运行以下命令通过 Helm 安装 New Relic Logging Kubernetes 插件，并将占位符 YOUR_LICENSE_KEY 替换为您的 New Relic 许可证密钥：

Helm 3

helm install newrelic-logging newrelic/newrelic-logging --set licenseKey=YOUR_LICENSE_KEY

Helm 2

helm install newrelic/newrelic-logging --name newrelic-logging --set licenseKey=YOUR_LICENSE_KEY

对于欧盟用户，请在上述命令中添加 --set endpoint=https://log-api.eu.newrelic.com/log/v1。

为 Python SDK 贡献

Mon, 01 Jan 0001 00:00:00 +0000

在贡献 Python SDK 时，应该遵循以下规则和最佳实践。

示例

examples 目录包含用户可以运行的代码示例，以体验各种 Python SDK 包和扩展的特定功能。在编写或更新示例时，请注意：

所有示例应在 Windows、Linux 和 MacOS 上均可运行。虽然 Python 代码在不同操作系统之间是一致的，但任何示例的前置或后续命令应通过 tabpane 提供不同操作系统的选项。
包含下载和安装所有必要前提条件的步骤。即使是刚安装操作系统的人也应该能够顺利开始并完成示例，而不会遇到错误。可以链接到外部下载页面。

文档

daprdocs 目录包含会被渲染到 Dapr Docs 网站的 markdown 文件。当文档网站构建时，此仓库会被克隆并配置，以便其内容与文档内容一起呈现。在编写文档时，请注意：

除了这些规则外，还应遵循 docs guide 中的所有规则。
所有文件和目录名称应以 python- 为前缀，以确保在所有 Dapr 文档中具有唯一性。

Github Dapr Bot 命令

请查看 daprbot 文档以了解您可以在此仓库中使用的 Github 命令来完成常见任务。例如，您可以在问题的评论中运行 /assign 来将问题分配给某个用户或用户组。

贡献 Rust SDK

Mon, 01 Jan 0001 00:00:00 +0000

在您为 Rust SDK 贡献时，请遵循以下规则和最佳实践。

示例

examples 目录包含用户可以运行的代码示例，以尝试各种 Rust SDK 包和扩展的特定功能。它还包含用于验证的组件示例。在编写或更新示例时，请注意以下几点：

所有示例应能在 Windows、Linux 和 MacOS 上运行。虽然 Rust 代码在不同操作系统之间基本一致，但由于少量操作系统功能限制，任何示例的前置/后置命令都应通过 tabpane 提供不同选项。
包含下载和安装所有必要前提条件的步骤。刚安装操作系统的人应该能够顺利开始并完成示例而不出错。可以链接到外部下载页面。
示例应经过验证，并包含自动化的 markdown 步骤，并添加到验证工作流 TBA。

文档

daprdocs 目录包含将被渲染到 Dapr Docs 网站的 markdown 文件。当文档网站构建时，此仓库会被克隆并配置，以便其内容与文档内容一起渲染。在编写文档时，请注意：

除了这些规则外，还应遵循 docs guide 中的所有规则。
所有文件和目录应以 rust- 为前缀，以确保在所有 Dapr 文档中文件/目录名称的全局唯一性。

更新 Protobufs

要从 dapr/dapr 仓库中提取 protobufs，您可以在仓库根目录运行以下脚本：

./update-protos.sh

默认情况下，脚本从 Dapr 仓库的 master 分支获取最新的 proto 更新。如果您需要选择特定的发布或版本，请使用 -v 标志：

./update-protos.sh -v v1.13.0

SQL server

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 在保存和检索状态时不对状态值进行转换。Dapr 要求所有状态存储实现遵循特定的键格式（参见状态管理规范）。您可以直接与底层存储交互来操作状态数据，例如：

查询状态。
创建聚合视图。
进行备份。

连接到 SQL Server

连接到 SQL Server 实例的最简单方法是使用：

Azure Data Studio（Windows、macOS、Linux）
SQL Server Management Studio（Windows）

注意

当您为 Dapr 配置 Azure SQL 数据库时，您需要指定具体的表名。以下 Azure SQL 示例假设您已经连接到具有名为 “states” 的表的正确数据库。

按应用程序 ID 列出键

要获取与应用程序 “myapp” 关联的所有状态键，请使用以下查询：

SELECT * FROM states WHERE [Key] LIKE 'myapp||%'

上述查询返回所有 ID 包含 “myapp||” 的行，这是状态键的前缀。

获取特定状态数据

要通过键 “balance” 获取应用程序 “myapp” 的状态数据，请使用以下查询：

SELECT * FROM states WHERE [Key] = 'myapp||balance'

读取返回行的 Data 字段。要获取状态版本/ETag，请使用以下命令：

SELECT [RowVersion] FROM states WHERE [Key] = 'myapp||balance'

获取过滤的状态数据

要获取 JSON 数据中值 “color” 等于 “blue” 的所有状态数据，请使用以下查询：

报告安全问题

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 项目和维护者将安全性视为操作和设计软件的核心关注点。从 Dapr 二进制文件到 GitHub 发布流程，我们采取了多种措施以确保用户应用程序和数据的安全。有关 Dapr 安全功能的更多信息，请访问安全页面。

涵盖的存储库和问题

提到“Dapr 中的安全漏洞”时，指的是dapr GitHub 组织下任何存储库中的安全问题。

此报告流程仅适用于 Dapr 项目本身的安全问题，不适用于使用 Dapr 的应用程序或不影响安全性的问题。

如果问题无法通过对上述涵盖的存储库之一的更改来解决，建议在适当的存储库中创建 GitHub 问题或在 Discord 中提出问题。

**如果您不确定，**请谨慎行事，在通过 GitHub、Discord 或其他渠道提出问题之前，使用报告流程进行联系。

明确不涵盖：漏洞扫描器报告

我们不接受仅仅是从漏洞扫描工具复制粘贴输出的报告，除非已经专门确认工具报告的漏洞确实存在于 Dapr 中，包括 CLI、Dapr SDKs、components-contrib 存储库或 Dapr 组织下的任何其他存储库。

我们也使用这些工具，并根据它们的输出采取行动。然而，当这些报告被发送到我们的安全邮件列表时，通常是误报，因为这些工具往往只检查库的存在，而不考虑库在上下文中的使用方式。

如果我们收到的报告似乎只是来自扫描器的漏洞列表，我们保留忽略它的权利。

这尤其适用于工具生成的漏洞标识符不是公开可见或以某种方式是专有的情况。我们可以查找 CVE 或其他公开可用的标识符以获取更多详细信息，但不能对专有标识符执行相同操作。

安全联系人

有权阅读您的安全报告的人列在maintainers.md中。

报告流程

用英语描述问题，最好附上一些示例配置或代码，以便重现问题。解释为什么您认为这是 Dapr 中的安全问题。
将这些信息放入电子邮件中。使用描述性标题。
发送电子邮件至Security (security@dapr.io)

响应

响应时间可能会受到周末、假期、休息或时区差异的影响。尽管如此，维护者团队会尽快回复，理想情况下在 3 个工作日内。

如果团队得出结论认为报告的问题确实是 Dapr 项目中的安全漏洞，至少两名维护者团队成员会尽快讨论下一步，理想情况下在 24 小时内。

一旦团队决定报告是真实漏洞，团队中的一名成员会回复报告者，确认问题并建立披露时间表，应该尽快进行。

分类、响应、修补和公告应在 30 天内完成。

弹性说明

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 的弹性资源使您能够定义和应用容错策略。这些弹性说明会在 Dapr sidecar 启动时生效。

注意

任何弹性资源都可以限制在特定的命名空间中，并通过作用域限制对特定应用程序集的访问。

格式

apiVersion: dapr.io/v1alpha1
kind: Resiliency
metadata:
 name: <替换为资源名称>
version: v1alpha1
scopes:
 - <替换为作用域应用程序ID>
spec:
 policies: # 必需
 timeouts:
 timeoutName: <替换为时间值> # 使用唯一名称替换
 retries:
 retryName: # 使用唯一名称替换
 policy: <替换为策略值>
 duration: <替换为持续时间>
 maxInterval: <替换为最大间隔>
 maxRetries: <替换为最大重试次数>
 matching:
 httpStatusCodes: <替换为HTTP状态码>
 gRPCStatusCodes: <替换为gRPC状态码>
 circuitBreakers:
 circuitBreakerName: # 使用唯一名称替换
 maxRequests: <替换为最大请求数>
 timeout: <替换为超时时间> 
 trip: <替换为连续失败次数>
targets: # 必需
 apps:
 appID: # 替换为应用程序ID
 timeout: <替换为超时名称>
 retry: <替换为重试名称>
 circuitBreaker: <替换为断路器名称>
 actors:
 myActorType: 
 timeout: <替换为超时名称>
 retry: <替换为重试名称>
 circuitBreaker: <替换为断路器名称>
 circuitBreakerCacheSize: <替换为缓存大小>
 components:
 componentName: # 替换为组件名称
 outbound:
 timeout: <替换为超时名称>
 retry: <替换为重试名称>
 circuitBreaker: <替换为断路器名称>

说明字段

字段	必需	详情	示例
policies	Y	弹性策略的配置，包括： `timeouts` `retries` `circuitBreakers` 查看所有内置策略的更多示例	timeout: `general` retry: `retryForever` circuit breaker: `simpleCB`
targets	Y	使用弹性策略的应用程序、actor 或组件的配置。在弹性目标指南中查看更多示例	`apps` `components` `actors`

声明式、流式和编程式订阅类型

Mon, 01 Jan 0001 00:00:00 +0000

发布/订阅 API 订阅类型

Dapr 应用程序可以通过三种订阅类型来订阅已发布的主题，这三种类型支持相同的功能：声明式、流式和编程式。

订阅类型	描述
声明式	订阅在外部文件中定义。声明式方法将 Dapr 的依赖从代码中移除，允许现有应用程序无需更改代码即可订阅主题。
流式	订阅在应用程序代码中定义。流式订阅是动态的，允许在运行时添加或删除订阅。它们不需要在应用程序中设置订阅端点（这是编程式和声明式订阅所需的），使其在代码中易于配置。流式订阅也不需要应用程序配置 sidecar 来接收消息。
编程式	订阅在应用程序代码中定义。编程式方法实现了静态订阅，并需要在代码中设置一个端点。

下面的示例演示了通过 orders 主题在 checkout 应用程序和 orderprocessing 应用程序之间的发布/订阅消息。示例首先以声明式，然后以编程式演示了相同的 Dapr 发布/订阅组件。

声明式订阅

注意

此功能目前处于预览状态。 Dapr 可以实现“热重载”声明式订阅，从而在不需要重启的情况下自动获取更新。这通过 HotReload 功能门控启用。为了防止重新处理或丢失未处理的消息，在 Dapr 和您的应用程序之间的飞行消息在热重载事件期间不受影响。

您可以使用外部组件文件声明性地订阅一个主题。此示例使用名为 subscription.yaml 的 YAML 组件文件：

apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
 name: order
spec:
 topic: orders
 routes:
 default: /orders
 pubsubname: pubsub
scopes:
- orderprocessing

这里的订阅名为 order：

使用名为 pubsub 的发布/订阅组件订阅名为 orders 的主题。
设置 route 字段以将所有主题消息发送到应用程序中的 /orders 端点。
设置 scopes 字段以将此订阅的访问范围仅限于 ID 为 orderprocessing 的应用程序。

运行 Dapr 时，设置 YAML 组件文件路径以指向 Dapr 的组件。

工作流模式

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 工作流简化了微服务架构中复杂且有状态的协调需求。以下部分描述了几种可以从 Dapr 工作流中受益的应用程序模式。

任务链

在任务链模式中，工作流中的多个步骤按顺序运行，一个步骤的输出可以作为下一个步骤的输入。任务链工作流通常涉及创建一系列需要对某些数据执行的操作，例如过滤、转换和归约。

在某些情况下，工作流的步骤可能需要在多个微服务之间进行协调。为了提高可靠性和可扩展性，您还可能使用队列来触发各个步骤。

虽然模式简单，但实现中隐藏了许多复杂性。例如：

如果某个微服务长时间不可用，会发生什么？
可以自动重试失败的步骤吗？
如果不能，如何促进先前完成步骤的回滚（如果适用）？
除了实现细节之外，是否有办法可视化工作流，以便其他工程师可以理解它的作用和工作原理？

Dapr 工作流通过允许您在所选编程语言中将任务链模式简洁地实现为简单函数来解决这些复杂性，如以下示例所示。

import dapr.ext.workflow as wf


def task_chain_workflow(ctx: wf.DaprWorkflowContext, wf_input: int):
 try:
 result1 = yield ctx.call_activity(step1, input=wf_input)
 result2 = yield ctx.call_activity(step2, input=result1)
 result3 = yield ctx.call_activity(step3, input=result2)
 except Exception as e:
 yield ctx.call_activity(error_handler, input=str(e))
 raise
 return [result1, result2, result3]


def step1(ctx, activity_input):
 print(f'步骤 1: 接收到输入: {activity_input}.')
 # 执行一些操作
 return activity_input + 1


def step2(ctx, activity_input):
 print(f'步骤 2: 接收到输入: {activity_input}.')
 # 执行一些操作
 return activity_input * 2


def step3(ctx, activity_input):
 print(f'步骤 3: 接收到输入: {activity_input}.')
 # 执行一些操作
 return activity_input ^ 2


def error_handler(ctx, error):
 print(f'执行错误处理程序: {error}.')
 # 执行一些补偿操作

注意工作流重试策略将在 Python SDK 的未来版本中提供。

如何使用：配置 secret 访问范围

Mon, 01 Jan 0001 00:00:00 +0000

当您为应用程序配置了 secret 存储后，Dapr 应用程序默认可以访问该存储中定义的所有 secret。

您可以通过在应用程序配置中定义 secret 访问范围策略，来限制 Dapr 应用程序对特定 secret 的访问权限。

secret 访问范围策略适用于任何secret 存储，包括：

本地 secret 存储
Kubernetes secret 存储
公有云 secret 存储

有关如何设置secret 存储的详细信息，请阅读如何：检索 secret。

观看此视频以了解如何在应用程序中使用 secret 访问范围的演示。

场景 1：拒绝访问 secret 存储中的所有 secret

在此示例中，所有 secret 访问都被拒绝给运行在 Kubernetes 集群上的应用程序，该集群配置了名为 mycustomsecretstore 的Kubernetes secret 存储。除了用户定义的自定义存储外，示例还配置了 Kubernetes 默认存储（名为 kubernetes），以确保所有 secret 都被拒绝访问。了解有关 Kubernetes 默认 secret 存储的更多信息。

定义以下 appconfig.yaml 配置，并使用命令 kubectl apply -f appconfig.yaml 将其应用于 Kubernetes 集群。

操作指南：限制从 secret 存储中读取的 secret

Mon, 01 Jan 0001 00:00:00 +0000

除了定义哪些应用程序可以访问特定组件之外，您还可以将命名的 secret 存储组件限制为应用程序的一个或多个 secret。通过定义 allowedSecrets 和/或 deniedSecrets 列表，可以限制应用程序仅访问特定的 secret。

有关配置资源的更多信息：

配置 secret 访问

Configuration 规范下的 secrets 部分包含以下属性：

secrets:
 scopes:
 - storeName: kubernetes
 defaultAccess: allow
 allowedSecrets: ["redis-password"]
 - storeName: localstore
 defaultAccess: allow
 deniedSecrets: ["redis-password"]

下表列出了 secret 范围的属性：

属性	类型	描述
storeName	string	secret 存储组件的名称。storeName 在列表中必须是唯一的
defaultAccess	string	访问修饰符。接受的值为 “allow”（默认）或 “deny”
allowedSecrets	list	可以访问的 secret 键列表
deniedSecrets	list	不能访问的 secret 键列表

当 allowedSecrets 列表中存在至少一个元素时，应用程序只能访问列表中定义的那些 secret。

HTTPEndpoint 规范

Mon, 01 Jan 0001 00:00:00 +0000

HTTPEndpoint 是一种 Dapr 资源，用于让 Dapr 应用程序能够调用非 Dapr 的端点。

注意

HTTPEndpoint 资源可以被限制在特定的命名空间中，并通过作用域来限制对特定应用程序集的访问。

格式

apiVersion: dapr.io/v1alpha1
kind: HTTPEndpoint
metadata:
 name: <NAME> 
spec:
 baseUrl: <REPLACE-WITH-BASEURL> # 必填。需包含 "http://" 或 "https://" 前缀。
 headers: # 可选
 - name: <REPLACE-WITH-A-HEADER-NAME>
 value: <REPLACE-WITH-A-HEADER-VALUE>
 - name: <REPLACE-WITH-A-HEADER-NAME>
 secretKeyRef:
 name: <REPLACE-WITH-SECRET-NAME>
 key: <REPLACE-WITH-SECRET-KEY>
 clientTLS:
 rootCA:
 secretKeyRef:
 name: <REPLACE-WITH-SECRET-NAME>
 key: <REPLACE-WITH-SECRET-KEY>
 certificate:
 secretKeyRef:
 name: <REPLACE-WITH-SECRET-NAME>
 key: <REPLACE-WITH-SECRET-KEY>
 privateKey:
 secretKeyRef:
 name: <REPLACE-WITH-SECRET-NAME>
 key: <REPLACE-WITH-SECRET-KEY>
scopes: # 可选
 - <REPLACE-WITH-SCOPED-APPIDS>
auth: # 可选
 secretStore: <REPLACE-WITH-SECRETSTORE>

规范字段

字段	必填	详情	示例
baseUrl	是	非 Dapr 端点的基本 URL	`"https://api.github.com"`, `"http://api.github.com"`
headers	否	服务调用的 HTTP 请求头	`name: "Accept-Language" value: "en-US"` `name: "Authorization" secretKeyRef.name: "my-secret" secretKeyRef.key: "myGithubToken"`
clientTLS	否	启用 TLS 认证到一个端点，支持使用根证书、客户端证书和私钥的标准组合

操作指南：使用 Prometheus 监控指标

Mon, 01 Jan 0001 00:00:00 +0000

本地设置 Prometheus

在本地计算机上，您可以选择安装并作为进程运行 Prometheus，或者将其作为Docker 容器运行。

安装

注意

如果您计划将 Prometheus 作为 Docker 容器运行，则无需单独安装 Prometheus。请参阅容器部分的说明。

请按照此处提供的步骤，根据您的操作系统安装 Prometheus。

配置

安装完成后，您需要创建一个配置文件。

以下是一个示例 Prometheus 配置，请将其保存为文件，例如 /tmp/prometheus.yml 或 C:\Temp\prometheus.yml：

global:
 scrape_interval: 15s # 默认情况下，每 15 秒收集一次指标。

# 包含一个收集端点的配置：
# 这里是 Prometheus 自身。
scrape_configs:
 - job_name: 'dapr'

 # 覆盖全局默认值，每 5 秒从此 job 收集指标。
 scrape_interval: 5s

 static_configs:
 - targets: ['localhost:9090'] # 如果不是默认值，请替换为 Dapr 指标端口

作为进程运行

使用您的配置文件运行 Prometheus，以开始从指定目标收集指标。

./prometheus --config.file=/tmp/prometheus.yml --web.listen-address=:8080

我们更改了端口以避免与 Dapr 自身的指标端点冲突。

操作指南：设置 Zipkin 进行分布式追踪

Mon, 01 Jan 0001 00:00:00 +0000

配置自托管模式

在自托管模式下，运行 dapr init 时：

系统会默认创建一个 YAML 文件，路径为 $HOME/.dapr/config.yaml（Linux/Mac）或 %USERPROFILE%\.dapr\config.yaml（Windows）。在执行 dapr run 时，系统会默认引用该文件，除非您指定了其他配置：

config.yaml

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: daprConfig
 namespace: default
spec:
 tracing:
 samplingRate: "1"
 zipkin:
 endpointAddress: "http://localhost:9411/api/v2/spans"

运行 dapr init 时，openzipkin/zipkin 的 Docker 容器会自动启动。您也可以手动启动：

使用 Docker 启动 Zipkin：

docker run -d -p 9411:9411 openzipkin/zipkin

使用 dapr run 启动应用程序时，默认会引用 $HOME/.dapr/config.yaml 或 %USERPROFILE%\.dapr\config.yaml 中的配置文件。您可以通过 Dapr CLI 的 --config 参数来指定其他配置：

dapr run --app-id mynode --app-port 3000 node app.js

查看追踪

要查看追踪数据，请在浏览器中访问 http://localhost:9411，您将看到 Zipkin 的用户界面。

配置弹性Kubernetes服务（EKS）集群

Mon, 01 Jan 0001 00:00:00 +0000

本指南将引导您配置一个弹性Kubernetes服务（EKS）集群。如果您需要更多信息，请参考创建一个Amazon EKS集群

前提条件

需要安装以下工具：

部署一个EKS集群

在终端中配置AWS凭证。
```
aws configure
```

创建一个名为cluster-config.yaml的新文件，并将以下内容添加到其中，将[your_cluster_name]、[your_cluster_region]和[your_k8s_version]替换为相应的值：

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
 name: [your_cluster_name]
 region: [your_cluster_region]
 version: [your_k8s_version]
 tags:
 karpenter.sh/discovery: [your_cluster_name]

iam:
 withOIDC: true

managedNodeGroups:
 - name: mng-od-4vcpu-8gb
 desiredCapacity: 2
 minSize: 1
 maxSize: 5
 instanceType: c5.xlarge
 privateNetworking: true

addons:
 - name: vpc-cni 
 attachPolicyARNs:
 - arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy
 - name: coredns
 version: latest 
 - name: kube-proxy
 version: latest
 - name: aws-ebs-csi-driver
 wellKnownPolicies: 
 ebsCSIController: true

通过运行以下命令创建集群：

性能分析与调试

Mon, 01 Jan 0001 00:00:00 +0000

在实际应用中，程序可能会出现资源使用高峰的问题。CPU和内存的使用高峰在很多情况下是常见的。

Dapr 允许用户通过其性能分析服务端点使用 pprof 启动按需性能分析会话，以检测并发、性能、CPU 和内存使用等问题。

启用性能分析

Dapr 支持在 Kubernetes 和独立模式下启用性能分析。

独立模式

在独立模式下启用性能分析时，可以通过 Dapr CLI 传递 --enable-profiling 和 --profile-port 标志：注意，profile-port 是可选的，如果未指定，Dapr 会自动选择一个可用端口。

dapr run --enable-profiling --profile-port 7777 python myapp.py

Kubernetes

在 Kubernetes 中启用性能分析，只需在 Dapr 注解的 pod 中添加 dapr.io/enable-profiling 注解：

 annotations:
 dapr.io/enabled: "true"
 dapr.io/app-id: "rust-app"
 dapr.io/enable-profiling: "true"

调试性能分析会话

启用性能分析后，可以启动性能分析会话来调查 Dapr 运行时的情况。

独立模式

对于独立模式，首先找到需要分析的 Dapr 实例：

dapr list
APP ID DAPR PORT APP PORT COMMAND AGE CREATED PID
node-subscriber 3500 3000 node app.js 12s 2019-09-09 15:11.24 896

获取 DAPR PORT，如果已按上述步骤启用性能分析，现在可以使用 pprof 对 Dapr 进行分析。查看上面的 Kubernetes 示例以获取一些有用的命令来分析 Dapr。

操作指南：为服务调用配置应用访问控制列表

Mon, 01 Jan 0001 00:00:00 +0000

通过访问控制，您可以配置策略，限制调用应用程序在被调用应用程序上通过服务调用可以执行的操作。您可以在配置模式中定义访问控制策略规范，以限制访问：

从特定操作到被调用应用程序，以及
从调用应用程序到HTTP动词。

访问控制策略在配置中指定，并应用于被调用应用程序的Dapr sidecar。对被调用应用程序的访问基于匹配的策略操作。

您可以为所有调用应用程序提供一个默认的全局操作。如果未指定访问控制策略，默认行为是允许所有调用应用程序访问被调用应用程序。

查看访问策略示例。

术语

`trustDomain`

“信任域”是用于管理信任关系的逻辑分组。每个应用程序都被分配一个信任域，可以在访问控制列表策略规范中指定。如果未定义策略规范或指定了空的信任域，则使用默认值“public”。信任域用于在TLS证书中生成应用程序的身份。

应用程序身份

Dapr请求sentry服务为所有应用程序生成一个SPIFFE ID。此ID附加在TLS证书中。

SPIFFE ID的格式为：**spiffe://\<trustdomain>/ns/\<namespace\>/\<appid\>**。

对于匹配策略，从调用应用程序的TLS证书中提取调用应用程序的信任域、命名空间和应用程序ID值。这些值与策略规范中指定的信任域、命名空间和应用程序ID值进行匹配。如果这三者都匹配，则进一步匹配更具体的策略。

配置属性

下表列出了访问控制、策略和操作的不同属性：

访问控制

属性	类型	描述
`defaultAction`	string	当没有其他策略匹配时的全局默认操作
`trustDomain`	string	分配给应用程序的信任域。默认值为“public”。
`policies`	string	确定调用应用程序可以在被调用应用程序上执行哪些操作的策略

策略

属性	类型	描述
`app`	string	允许/拒绝服务调用的调用应用程序的AppId
`namespace`	string	需要与调用应用程序的命名空间匹配的命名空间值
`trustDomain`	string	需要与调用应用程序的信任域匹配的信任域。默认值为“public”
`defaultAction`	string	如果找到应用程序但没有匹配的特定操作，则应用程序级别的默认操作
`operations`	string	允许从调用应用程序进行的操作

操作

属性	类型	描述
`name`	string	允许在被调用应用程序上进行的操作的路径名称。通配符“”可以用于路径中进行匹配。通配符“*”可以用于匹配多个路径下的内容。
`httpVerb`	list	调用应用程序可以使用的特定HTTP动词列表。通配符“*”可以用于匹配任何HTTP动词。未用于grpc调用。
`action`	string	访问修饰符。接受的值为“allow”（默认）或“deny”

策略规则

如果未指定访问策略，默认行为是允许所有应用程序访问被调用应用程序上的所有方法。
如果未指定全局默认操作且未定义特定应用程序策略，则空访问策略被视为未指定访问策略。默认行为是允许所有应用程序访问被调用应用程序上的所有方法。
如果未指定全局默认操作但已定义了一些特定应用程序策略，则我们采用更安全的选项，假设全局默认操作为拒绝访问被调用应用程序上的所有方法。
如果定义了访问策略且无法验证传入应用程序凭据，则全局默认操作生效。
如果传入应用程序的信任域或命名空间与应用程序策略中指定的值不匹配，则忽略应用程序策略，全局默认操作生效。

策略优先级

最具体的匹配策略对应的操作生效，按以下顺序排列：

配置指标

Mon, 01 Jan 0001 00:00:00 +0000

默认情况下，每个Dapr系统进程都会发出Go运行时和进程指标，并拥有自己的Dapr指标。

Prometheus端点

Dapr sidecar提供了一个与Prometheus兼容的指标端点，您可以通过抓取该端点来更好地了解Dapr的运行状况。

使用CLI配置指标

指标应用程序端点默认是启用的。您可以通过传递命令行参数--enable-metrics=false来禁用它。

默认的指标端口是9090。您可以通过传递命令行参数--metrics-port给daprd来更改此设置。

在Kubernetes中配置指标

您还可以通过在应用程序部署上设置dapr.io/enable-metrics: "false"注解来启用或禁用特定应用程序的指标。禁用指标导出器后，daprd不会打开指标监听端口。

以下Kubernetes部署示例显示了如何显式启用指标，并将端口指定为"9090"。

apiVersion: apps/v1
kind: Deployment
metadata:
 name: nodeapp
 labels:
 app: node
spec:
 replicas: 1
 selector:
 matchLabels:
 app: node
 template:
 metadata:
 labels:
 app: node
 annotations:
 dapr.io/enabled: "true"
 dapr.io/app-id: "nodeapp"
 dapr.io/app-port: "3000"
 dapr.io/enable-metrics: "true"
 dapr.io/metrics-port: "9090"
 spec:
 containers:
 - name: node
 image: dapriosamples/hello-k8s-node:latest
 ports:
 - containerPort: 3000
 imagePullPolicy: Always

使用应用程序配置启用指标

您还可以通过应用程序配置启用指标。要默认禁用Dapr sidecar中的指标收集，请将spec.metrics.enabled设置为false。

工作流架构

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 工作流允许开发者使用多种编程语言的普通代码定义工作流。工作流引擎运行在 Dapr sidecar 内部，并协调作为应用程序一部分部署的工作流代码。本文描述了：

Dapr 工作流引擎的架构
工作流引擎如何与应用程序代码交互
工作流引擎如何融入整体 Dapr 架构
不同的工作流后端如何与工作流引擎协作

有关如何在应用程序中编写 Dapr 工作流的更多信息，请参见如何：编写工作流。

Dapr 工作流引擎的内部支持来自于 Dapr 的 actor 运行时。下图展示了 Kubernetes 模式下的 Dapr 工作流架构：

要使用 Dapr 工作流构建块，您需要在应用程序中使用 Dapr 工作流 SDK 编写工作流代码，该 SDK 内部通过 gRPC 流连接到 sidecar。这会注册工作流和任何工作流活动，或工作流可以调度的任务。

引擎直接嵌入在 sidecar 中，并通过 durabletask-go 框架库实现。此框架允许您更换不同的存储提供者，包括为 Dapr 创建的存储提供者，该提供者在幕后利用内部 actor。由于 Dapr 工作流使用 actor，您可以将工作流状态存储在状态存储中。

Sidecar 交互

当工作流应用程序启动时，它使用工作流编写 SDK 向 Dapr sidecar 发送 gRPC 请求，并根据服务器流式 RPC 模式获取工作流工作项流。这些工作项可以是从“启动一个新的 X 工作流”（其中 X 是工作流的类型）到“调度活动 Y，输入 Z 以代表工作流 X 运行”的任何内容。

适用于 Azure Kubernetes Service (AKS) 的 Dapr 扩展

Mon, 01 Jan 0001 00:00:00 +0000

在 AKS 上安装 Dapr 的推荐方法是使用 AKS Dapr 扩展。该扩展提供以下功能：

通过 Azure CLI 命令行参数支持所有原生 Dapr 配置功能
可选择自动升级 Dapr 运行时的小版本

注意

如果通过 AKS 扩展安装 Dapr，最佳实践是继续使用该扩展进行 Dapr 的后续管理，而不是使用 Dapr CLI。混合使用这两种工具可能会导致冲突并产生意外行为。

使用 AKS 的 Dapr 扩展的先决条件：

了解有关 AKS 的 Dapr 扩展的更多信息

死信主题

Mon, 01 Jan 0001 00:00:00 +0000

介绍

在某些情况下，应用程序可能由于各种原因无法处理消息。例如，可能会出现获取处理消息所需数据的临时问题，或者应用程序的业务逻辑失败并返回错误。死信主题用于处理这些无法投递的消息，并将其转发到订阅应用程序。这可以减轻应用程序处理失败消息的负担，使开发人员可以编写代码从死信主题中读取消息，修复后重新发送，或者选择放弃这些消息。

死信主题通常与重试策略和处理死信主题消息的订阅一起使用。

当配置了死信主题时，任何无法投递到应用程序的消息都会被放置在死信主题中，以便转发到处理这些消息的订阅。这可以是同一个应用程序或完全不同的应用程序。

即使底层系统不支持，Dapr 也为其所有的 pubsub 组件启用了死信主题。例如，AWS SNS 组件有一个死信队列，RabbitMQ有死信主题。您需要确保正确配置这些组件。

下图展示了死信主题的工作原理。首先，消息从 orders 主题的发布者发送。Dapr 代表订阅者应用程序接收消息，但 orders 主题的消息未能投递到应用程序的 /checkout 端点，即使经过重试也是如此。由于投递失败，消息被转发到 poisonMessages 主题，该主题将其投递到 /failedMessages 端点进行处理，在这种情况下是在同一个应用程序上。failedMessages 处理代码可以选择丢弃消息或重新发送新消息。

使用声明式订阅配置死信主题

以下 YAML 显示了如何为从 orders 主题消费的消息配置名为 poisonMessages 的死信主题。此订阅的范围限定为具有 checkout ID 的应用程序。

apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
 name: order
spec:
 topic: orders
 routes: 
 default: /checkout
 pubsubname: pubsub
 deadLetterTopic: poisonMessages
scopes:
- checkout

使用流式订阅配置死信主题

	var deadLetterTopic = "poisonMessages"
	sub, err := cl.Subscribe(context.Background(), client.SubscriptionOptions{
		PubsubName: "pubsub",
		Topic: "orders",
		DeadLetterTopic: &deadLetterTopic,
	})

使用编程订阅配置死信主题

从 /subscribe 端点返回的 JSON 显示了如何为从 orders 主题消费的消息配置名为 poisonMessages 的死信主题。

使用令牌认证对Dapr请求进行身份验证

Mon, 01 Jan 0001 00:00:00 +0000

对于一些构建块，例如pubsub、service-invocation和输入bindings，Dapr与应用程序通过HTTP或gRPC进行通信。为了让应用程序能够验证来自Dapr sidecar的请求，您可以配置Dapr在HTTP请求的头部或gRPC请求的元数据中发送一个API令牌。

创建令牌

Dapr使用共享令牌进行API认证。您可以自由定义API令牌。

虽然Dapr对共享令牌没有强制格式，但一个好的做法是生成一个随机字节序列并将其编码为Base64。例如，这个命令生成一个随机的32字节密钥并将其编码为Base64：

openssl rand 16 | base64

在Dapr中配置应用API令牌认证

令牌认证配置在Kubernetes或selfhosted Dapr部署中略有不同：

Selfhosted

在selfhosted场景中，Dapr会检查APP_API_TOKEN环境变量是否存在。如果在daprd进程启动时设置了该环境变量，Dapr在调用应用程序时会包含该令牌：

export APP_API_TOKEN=<token>

要更新配置的令牌，修改APP_API_TOKEN环境变量为新值并重启daprd进程。

Kubernetes

在Kubernetes部署中，Dapr使用Kubernetes secrets存储来保存共享令牌。首先，创建一个新的secret：

kubectl create secret generic app-api-token --from-literal=token=<token>

注意，您需要在每个希望启用应用令牌认证的命名空间中创建上述secret

要指示Dapr在向应用程序发送请求时使用secret中的令牌，请在您的Deployment模板规范中添加一个注解：

annotations:
 dapr.io/enabled: "true"
 dapr.io/app-token-secret: "app-api-token" # Kubernetes secret的名称

部署时，Dapr Sidecar Injector会自动创建一个secret引用并将实际值注入到APP_API_TOKEN环境变量中。

轮换令牌

Selfhosted

要在selfhosted中更新配置的令牌，修改APP_API_TOKEN环境变量为新值并重启daprd进程。

Kubernetes

要在Kubernetes中更新配置的令牌，修改之前创建的secret中的新令牌在每个命名空间中。您可以使用kubectl patch命令来完成此操作，但更简单的方法是使用清单更新这些：

apiVersion: v1
kind: Secret
metadata:
 name: app-api-token
type: Opaque
data:
 token: <your-new-token>

然后将其应用到每个命名空间：

kubectl apply --file token-secret.yaml --namespace <namespace-name>

要让Dapr开始使用新令牌，请触发对每个部署的滚动升级：

预览功能

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 的预览功能在首次发布时被视为实验性功能。

要使用运行时的预览功能，必须在 Dapr 的应用程序配置中通过预览设置功能进行显式选择加入。有关更多信息，请参阅如何启用预览功能。

对于 CLI，不需要显式选择加入，只需使用首次提供该功能的版本即可。

当前预览功能

功能	描述	设置	文档	引入版本
可插拔组件	允许创建基于 gRPC 的自托管组件，这些组件可以用任何支持 gRPC 的语言编写。支持以下组件 API：状态存储、pub/sub、bindings	N/A	可插拔组件概念	v1.9
Kubernetes 的多应用运行	从单个配置文件配置多个 Dapr 应用程序，并在 Kubernetes 上通过单个命令运行	`dapr run -k -f`	多应用运行	v1.12
工作流	将工作流作为代码编写，以在应用程序中自动化和编排任务，如消息传递、状态管理和故障处理	N/A	工作流概念	v1.10
加密	加密或解密数据而无需管理密钥	N/A	加密概念	v1.11
actor 状态 TTL	允许 actor 将记录保存到状态存储中，并设置生存时间 (TTL) 以自动清理旧数据。在当前实现中，带有 TTL 的 actor 状态可能无法被客户端正确反映。请阅读 actor 状态事务以获取更多信息。	`ActorStateTTL`	actor 状态事务	v1.11
组件热重载	允许 Dapr 加载的组件进行“热重载”。当在 Kubernetes 中或在自托管模式下更新文件中的组件规范时，组件会被重新加载。对 actor 状态存储和工作流后端的更改将被忽略。	`HotReload`	热重载	v1.13
订阅热重载	允许声明性订阅进行“热重载”。当在 Kubernetes 中更新订阅时，或在自托管模式下更新文件中的订阅时，订阅会被重新加载。重载时不会影响正在进行的消息。	`HotReload`	热重载	v1.14
调度器 actor 提醒	调度器 actor 提醒是存储在调度器控制平面服务中的 actor 提醒，与存储在放置控制平面服务中的 actor 提醒系统不同。`SchedulerReminders` 预览功能默认设置为 `true`，但您可以通过将其设置为 `false` 来禁用调度器 actor 提醒。	`SchedulerReminders`	调度器 actor 提醒	v1.14

使用指南：选择性启用 Dapr Sidecar 的 API

Mon, 01 Jan 0001 00:00:00 +0000

在零信任网络环境中，或通过前端将 Dapr Sidecar 暴露给外部流量时，建议仅启用应用程序实际使用的 Dapr Sidecar API。这样可以减少潜在的攻击风险，并确保 Dapr API 仅限于应用程序的实际需求。

Dapr 允许您通过使用 Dapr 配置设置 API 白名单或黑名单来控制应用程序可以访问哪些 API。

默认设置

如果未指定 API 白名单或黑名单，默认情况下将允许访问所有 Dapr API。

如果只定义了黑名单，则除黑名单中定义的 API 外，所有 Dapr API 都被允许访问。
如果只定义了白名单，则仅允许白名单中列出的 Dapr API。
如果同时定义了白名单和黑名单，则黑名单中的 API 优先于白名单。
如果两者都未定义，则允许访问所有 API。

例如，以下配置为 HTTP 和 gRPC 启用所有 API：

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: myappconfig
 namespace: default
spec:
 tracing:
 samplingRate: "1"

使用白名单

启用特定的 HTTP API

以下示例启用 state v1.0 HTTP API，并禁用所有其他 HTTP API：

Alpha 和 Beta API

Mon, 01 Jan 0001 00:00:00 +0000

Alpha API

模块/API	gRPC	HTTP	描述	文档	引入版本
查询状态	查询状态 proto	`v1.0-alpha1/state/statestore/query`	状态查询 API 可以让您检索、过滤和排序存储在状态存储组件中的键值数据。	查询状态 API	v1.5
分布式锁	锁 proto	`/v1.0-alpha1/lock`	分布式锁 API 可以让您对资源进行锁定。	分布式锁 API	v1.8
批量发布	批量发布 proto	`v1.0-alpha1/publish/bulk`	批量发布 API 允许您在单个请求中向主题发布多条消息。	批量发布和订阅 API	v1.10
批量订阅	批量订阅 proto	N/A	批量订阅应用程序回调可以在一次调用中接收来自主题的多条消息。	批量发布和订阅 API	v1.10
加密	加密 proto	`v1.0-alpha1/crypto`	加密 API 可以执行复杂的加密操作来加密和解密消息。	加密 API	v1.11
任务	任务 proto	`v1.0-alpha1/jobs`	任务 API 可以让您调度和编排任务。	任务 API	v1.14
对话	对话 proto	`v1.0-alpha1/conversation`	使用对话 API 可以在不同的大型语言模型之间进行交流。	对话 API	v1.15

Beta API

当前没有 Beta API。

操作指南：为分布式追踪设置 Datadog

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 捕获的指标和追踪信息可以通过 OpenTelemetry Collector 的 Datadog 导出器直接发送到 Datadog。

使用 OpenTelemetry Collector 和 Datadog 配置 Dapr 追踪

您可以使用 OpenTelemetry Collector 的 Datadog 导出器来配置 Dapr，为 Kubernetes 集群中的每个应用程序创建追踪，并将这些追踪信息收集到 Datadog 中。

在开始之前，请先设置 OpenTelemetry Collector。

在 datadog 导出器的配置部分，将您的 Datadog API 密钥添加到 ./deploy/opentelemetry-collector-generic-datadog.yaml 文件中：
```
data:
 otel-collector-config:
 ...
 exporters:
 ...
 datadog:
 api:
 key: <YOUR_API_KEY>
```

运行以下命令以应用 opentelemetry-collector 的配置。

kubectl apply -f ./deploy/open-telemetry-collector-generic-datadog.yaml

设置一个 Dapr 配置文件以启用追踪，并部署一个使用 OpenTelemetry Collector 的追踪导出器组件。

如何：在 GitHub Actions 工作流中使用 Dapr CLI

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 可以通过 GitHub Marketplace 上的 Dapr 工具安装器与 GitHub Actions 进行集成。这个安装器会将 Dapr CLI 添加到您的工作流中，使您能够在不同环境中部署、管理和升级 Dapr。

使用 Dapr 工具安装器安装 Dapr CLI

请将以下代码片段复制并粘贴到您的应用程序的 YAML 文件中：

- name: Dapr 工具安装器
 uses: dapr/setup-dapr@v1

dapr/setup-dapr action 可以在 macOS、Linux 和 Windows 运行器上安装指定版本的 Dapr CLI。安装完成后，您可以运行任何 Dapr CLI 命令来管理您的 Dapr 环境。

有关所有输入的详细信息，请参阅 action.yml 元数据文件。

示例

例如，如果您的应用程序使用了 Azure Kubernetes Service (AKS) 的 Dapr 扩展，那么您的应用程序 YAML 文件可能如下所示：

- name: 安装 Dapr
 uses: dapr/setup-dapr@v1
 with:
 version: '1.16.9'

- name: 初始化 Dapr
 shell: bash
 run: |
 # 获取用于 dapr init 的 K8s 凭据
 az aks get-credentials --resource-group ${{ env.RG_NAME }} --name "${{ steps.azure-deployment.outputs.aksName }}"

 # 初始化 Dapr 
 # 将 Dapr init 日志分组，以便可以折叠这些行。
 echo "::group::初始化 Dapr"
 dapr init --kubernetes --wait --runtime-version ${{ env.DAPR_VERSION }}
 echo "::endgroup::"

 dapr status --kubernetes
 working-directory: ./demos/demo3

下一步

了解更多关于 GitHub Actions 的信息。
通过教程学习 GitHub Actions 如何与您的 Dapr 容器应用程序（Azure 容器应用程序）协作。

如何使用Grafana监控指标

Mon, 01 Jan 0001 00:00:00 +0000

可用的仪表板

grafana-system-services-dashboard.json模板展示了Dapr系统组件的状态，包括dapr-operator、dapr-sidecar-injector、dapr-sentry和dapr-placement：

grafana-sidecar-dashboard.json模板展示了Dapr sidecar 的状态，包括sidecar 的健康状况/资源使用情况、HTTP和gRPC的吞吐量/延迟、actor、mTLS等：

grafana-actor-dashboard.json模板展示了Dapr sidecar 的状态、actor 调用的吞吐量/延迟、timer/reminder触发器和基于回合的并发性：

前提条件

设置Prometheus

在Kubernetes上设置

安装Grafana

添加Grafana Helm仓库：

helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

安装图表：
```
helm install grafana grafana/grafana -n dapr-monitoring
```
注意

如果您使用Minikube或希望在开发中禁用持久卷，可以使用以下命令禁用：

配置规范

Mon, 01 Jan 0001 00:00:00 +0000

Configuration 是一种 Dapr 资源，用于配置 Dapr sidecar、控制平面等。

Sidecar 配置格式

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: <REPLACE-WITH-NAME>
 namespace: <REPLACE-WITH-NAMESPACE>
spec:
 api:
 allowed:
 - name: <REPLACE-WITH-API>
 version: <VERSION>
 protocol: <HTTP-OR-GRPC>
 tracing:
 samplingRate: <REPLACE-WITH-INTEGER>
 stdout: true
 otel:
 endpointAddress: <REPLACE-WITH-ENDPOINT-ADDRESS>
 isSecure: <TRUE-OR-FALSE>
 protocol: <HTTP-OR-GRPC>
 metrics:
 enabled: <TRUE-OR-FALSE>
 rules:
 - name: <METRIC-NAME>
 labels:
 - name: <LABEL-NAME>
 regex: {}
 recordErrorCodes: <TRUE-OR-FALSE>
 latencyDistributionBuckets:
 - <BUCKET-VALUE-MS-0>
 - <BUCKET-VALUE-MS-1>
 http:
 increasedCardinality: <TRUE-OR-FALSE>
 pathMatching: 
 - <PATH-A>
 - <PATH-B>
 excludeVerbs: <TRUE-OR-FALSE>
 httpPipeline: # 用于接收的 http 调用
 handlers:
 - name: <HANDLER-NAME>
 type: <HANDLER-TYPE>
 appHttpPipeline: # 用于发送的 http 调用
 handlers:
 - name: <HANDLER-NAME>
 type: <HANDLER-TYPE>
 nameResolution:
 component: <NAME-OF-NAME-RESOLUTION-COMPONENT>
 version: <NAME-RESOLUTION-COMPONENT-VERSION>
 configuration:
 <NAME-RESOLUTION-COMPONENT-METADATA-CONFIGURATION>
 secrets:
 scopes:
 - storeName: <NAME-OF-SCOPED-STORE>
 defaultAccess: <ALLOW-OR-DENY>
 deniedSecrets: <REPLACE-WITH-DENIED-SECRET>
 components:
 deny:
 - <COMPONENT-TO-DENY>
 accessControl:
 defaultAction: <ALLOW-OR-DENY>
 trustDomain: <REPLACE-WITH-TRUST-DOMAIN>
 policies:
 - appId: <APP-NAME>
 defaultAction: <ALLOW-OR-DENY>
 trustDomain: <REPLACE-WITH-TRUST-DOMAIN>
 namespace: "default"
 operations:
 - name: <OPERATION-NAME>
 httpVerb: ['POST', 'GET']
 action: <ALLOW-OR-DENY>

规范字段

字段	必需	详情	示例
accessControl	N	应用于 Dapr sidecar 的被调用应用程序。可以配置策略来限制调用应用程序通过服务调用对被调用应用程序执行的操作。	了解更多关于 `accessControl` 配置的信息。
api	N	用于仅启用应用程序使用的 Dapr sidecar API。	了解更多关于 `api` 配置的信息。
httpPipeline	N	配置 API 中间件管道	中间件管道配置概述了解更多关于 `httpPipeline` 配置的信息。
appHttpPipeline	N	配置应用程序中间件管道	中间件管道配置概述了解更多关于 `appHttpPipeline` 配置的信息。
components	N	用于指定不能初始化的组件类型的拒绝列表。	了解更多关于 `components` 配置的信息。
features	N	定义启用/禁用的预览功能。	了解更多关于 `features` 配置的信息。
logging	N	配置 Dapr 运行时中的日志记录方式。	了解更多关于 `logging` 配置的信息。
metrics	N	启用或禁用应用程序的监控指标。	了解更多关于 `metrics` 配置的信息。
nameResolution	N	服务调用模块的名称解析配置规范。	了解更多关于每个组件的 `nameResolution` 配置的信息。
secrets	N	限制 Dapr 应用程序可以访问的密钥。	了解更多关于 `secrets` 配置的信息。
tracing	N	为应用程序开启追踪。	了解更多关于 `tracing` 配置的信息。

控制平面格式

与 Dapr 一起安装的 daprsystem 配置文件应用全局设置，仅在 Dapr 部署到 Kubernetes 时生效。

如何：编写一个工作流

Mon, 01 Jan 0001 00:00:00 +0000

本文提供了如何编写由Dapr工作流引擎执行的工作流的高级概述。

注意

如果您还没有尝试过，请尝试工作流快速入门，以快速了解如何使用工作流。

以代码形式编写工作流

Dapr工作流逻辑是通过通用编程语言实现的，这使您可以：

使用您喜欢的编程语言（无需学习新的DSL或YAML模式）。
访问语言的标准库。
构建您自己的库和抽象。
使用调试器并检查本地变量。
为您的工作流编写单元测试，就像应用程序逻辑的其他部分一样。

Dapr sidecar不加载任何工作流定义。相反，sidecar仅负责驱动工作流的执行，而所有具体的工作流任务则由应用程序的一部分来处理。

编写工作流任务

工作流任务是工作流中的基本工作单元，是在业务流程中被编排的任务。

定义您希望工作流执行的工作流任务。任务是一个函数定义，可以接受输入并返回输出。以下示例创建了一个名为hello_act的任务，用于打印当前计数器的值。hello_act是一个从WorkflowActivityContext类派生的函数。

def hello_act(ctx: WorkflowActivityContext, input):
 global counter
 counter += input
 print(f'New counter value is: {counter}!', flush=True)

查看上下文中的hello_act工作流任务。

定义您希望工作流执行的工作流任务。任务被封装在实现工作流任务的WorkflowActivityContext类中。

如何：设置 pub/sub 命名空间消费者组

Mon, 01 Jan 0001 00:00:00 +0000

您已经配置了 Dapr 的 pub/sub API 构建块，并且您的应用程序正在使用集中式消息代理顺利地发布和订阅主题。如果您想为应用程序执行简单的 A/B 测试、蓝/绿部署，甚至金丝雀部署，该怎么办？即使使用 Dapr，这也可能很困难。

Dapr 通过其 pub/sub 命名空间消费者组机制解决了大规模的多租户问题。

没有命名空间消费者组

假设您有一个 Kubernetes 集群，其中两个应用程序（App1 和 App2）部署在同一个命名空间（namespace-a）中。App2 发布到一个名为 order 的主题，而 App1 订阅名为 order 的主题。这将创建两个以您的应用程序命名的消费者组（App1 和 App2）。

为了在使用集中式消息代理时进行简单的测试和部署，您创建了另一个命名空间，其中包含两个具有相同 app-id 的应用程序，App1 和 App2。

Dapr 使用单个应用程序的 app-id 创建消费者组，因此消费者组名称将保持为 App1 和 App2。

为了避免这种情况，您需要在代码中“潜入”一些东西来更改 app-id，具体取决于您运行的命名空间。这种方法既麻烦又容易出错。

使用命名空间消费者组

Dapr 不仅允许您使用 UUID 和 pod 名称的 consumerID 更改消费者组的行为，还提供了一个存在于 pub/sub 组件元数据中的 命名空间机制。例如，使用 Redis 作为您的消息代理：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: pubsub
spec:
 type: pubsub.redis
 version: v1
 metadata:
 - name: redisHost
 value: localhost:6379
 - name: redisPassword
 value: ""
 - name: consumerID
 value: "{namespace}"

通过将 consumerID 配置为 {namespace} 值，您可以在不同的命名空间中使用相同的 app-id 和相同的主题。

操作指南：配置 Dapr 使用 gRPC

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 提供了用于本地调用的 HTTP 和 gRPC API。gRPC 适用于低延迟、高性能的场景，并支持通过 proto 客户端进行语言集成。您可以查看自动生成的客户端（Dapr SDKs）的完整列表。

Dapr 运行时提供了一个 proto 服务，应用程序可以通过 gRPC 与其进行通信。

Dapr 不仅可以通过 gRPC 被调用，还可以通过 gRPC 与应用程序通信。为此，应用程序需要托管一个 gRPC 服务器并实现 Dapr appcallback 服务。

配置 Dapr 通过 gRPC 与应用程序通信

在自托管模式下运行时，使用 --app-protocol 标志告诉 Dapr 使用 gRPC 与应用程序通信：

dapr run --app-protocol grpc --app-port 5005 node app.js

这告诉 Dapr 通过端口 5005 使用 gRPC 与您的应用程序通信。

如何：在你的 Dapr 应用中使用 gRPC 接口

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 提供了用于本地调用的 HTTP 和 gRPC API。gRPC 适用于低延迟、高性能的场景，并通过 proto 客户端进行语言集成。

在 Dapr SDK 文档中查找自动生成的客户端列表。

Dapr 运行时提供了一个 proto 服务，应用可以通过 gRPC 与其通信。

除了通过 gRPC 调用 Dapr，Dapr 还支持通过代理方式进行服务到服务的调用。在 gRPC 服务调用指南中了解更多。

本指南演示了如何使用 Go SDK 配置和调用 Dapr 的 gRPC。

配置 Dapr 通过 gRPC 与应用通信

在自托管模式下运行时，使用 --app-protocol 标志指定 Dapr 使用 gRPC 与应用通信。

dapr run --app-protocol grpc --app-port 5005 node app.js

这使 Dapr 通过端口 5005 使用 gRPC 与应用进行通信。

操作指南：如何处理大容量 HTTP 请求体

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 默认限制请求体大小为 4MB。您可以通过以下方法更改此限制：

使用 dapr.io/http-max-request-size 注解，或
使用 --dapr-http-max-request-size 参数。

在自托管模式下运行时，使用 --dapr-http-max-request-size 参数来设置 Dapr 的请求体大小限制：

dapr run --dapr-http-max-request-size 16 node app.js

这将把 Dapr 的最大请求体大小设置为 16 MB。

在 Kubernetes 中，您可以在部署的 YAML 文件中添加以下注解：

apiVersion: apps/v1
kind: Deployment
metadata:
 name: myapp
 namespace: default
 labels:
 app: myapp
spec:
 replicas: 1
 selector:
 matchLabels:
 app: myapp
 template:
 metadata:
 labels:
 app: myapp
 annotations:
 dapr.io/enabled: "true"
 dapr.io/app-id: "myapp"
 dapr.io/app-port: "8000"
 dapr.io/http-max-request-size: "16"
#...

操作指南：处理大型HTTP头部大小

Mon, 01 Jan 0001 00:00:00 +0000

Dapr的HTTP头部读取缓冲区大小默认限制为4KB。如果您发送的HTTP头部超过4KB，可能会遇到请求头部过大的服务调用错误。

您可以通过以下方法增加HTTP头部大小：

使用dapr.io/http-read-buffer-size注解，或
在使用CLI时添加--dapr-http-read-buffer-size标志。

在自托管模式下运行时，使用--dapr-http-read-buffer-size标志来配置Dapr，以便使用非默认的HTTP头部大小：

dapr run --dapr-http-read-buffer-size 16 node app.js

这会将Dapr的最大读取缓冲区大小设置为16 KB。

在Kubernetes上，您可以在部署的YAML文件中设置以下注解：

apiVersion: apps/v1
kind: Deployment
metadata:
 name: myapp
 namespace: default
 labels:
 app: myapp
spec:
 replicas: 1
 selector:
 matchLabels:
 app: myapp
 template:
 metadata:
 labels:
 app: myapp
 annotations:
 dapr.io/enabled: "true"
 dapr.io/app-id: "myapp"
 dapr.io/app-port: "8000"
 dapr.io/http-read-buffer-size: "16"
#...

操作指南：配置 New Relic 以收集和分析指标

Mon, 01 Jan 0001 00:00:00 +0000

前提条件

New Relic 账户，永久免费，每月提供 100 GB 的免费数据摄取，1 个免费完全访问用户，无限制的免费基本用户

背景信息

New Relic 支持 Prometheus 的 OpenMetrics 集成。

本文档将介绍如何在集群中安装该集成，建议使用 Helm chart 进行安装。

安装步骤

根据官方说明安装 Helm。
按照这些说明添加 New Relic 官方 Helm chart 仓库。
运行以下命令通过 Helm 安装 New Relic Logging Kubernetes 插件，并将 YOUR_LICENSE_KEY 替换为您的 New Relic 许可证密钥：
```
helm install nri-prometheus newrelic/nri-prometheus --set licenseKey=YOUR_LICENSE_KEY
```

查看指标

如何：管理工作流

Mon, 01 Jan 0001 00:00:00 +0000

现在您已经在应用程序中编写了工作流及其活动，您可以使用HTTP API调用来启动、终止和获取工作流的信息。有关更多信息，请阅读工作流API参考。

在代码中管理您的工作流。在编写工作流指南中的工作流示例中，工作流通过以下API在代码中注册：

start_workflow: 启动工作流的一个实例
get_workflow: 获取工作流状态的信息
pause_workflow: 暂停或挂起一个工作流实例，稍后可以恢复
resume_workflow: 恢复一个暂停的工作流实例
raise_workflow_event: 在工作流上触发一个事件
purge_workflow: 删除与特定工作流实例相关的所有元数据
terminate_workflow: 终止或停止特定的工作流实例

from dapr.ext.workflow import WorkflowRuntime, DaprWorkflowContext, WorkflowActivityContext
from dapr.clients import DaprClient

# 合适的参数
instanceId = "exampleInstanceID"
workflowComponent = "dapr"
workflowName = "hello_world_wf"
eventName = "event1"
eventData = "eventData"

# 启动工作流
start_resp = d.start_workflow(instance_id=instanceId, workflow_component=workflowComponent,
 workflow_name=workflowName, input=inputData, workflow_options=workflowOptions)

# 获取工作流信息
getResponse = d.get_workflow(instance_id=instanceId, workflow_component=workflowComponent)

# 暂停工作流
d.pause_workflow(instance_id=instanceId, workflow_component=workflowComponent)

# 恢复工作流
d.resume_workflow(instance_id=instanceId, workflow_component=workflowComponent)

# 在工作流上触发一个事件
d.raise_workflow_event(instance_id=instanceId, workflow_component=workflowComponent,
 event_name=eventName, event_data=eventData)

# 清除工作流
d.purge_workflow(instance_id=instanceId, workflow_component=workflowComponent)

# 终止工作流
d.terminate_workflow(instance_id=instanceId, workflow_component=workflowComponent)

在代码中管理您的工作流。在编写工作流指南中的工作流示例中，工作流通过以下API在代码中注册：

如何：使用StatefulSets水平扩展订阅者

Mon, 01 Jan 0001 00:00:00 +0000

与在Deployments中Pod是临时的不同，StatefulSets通过为每个Pod保持固定的身份，使得在Kubernetes上可以部署有状态应用程序。

以下是一个使用Dapr的StatefulSet示例：

apiVersion: apps/v1
kind: StatefulSet
metadata:
 name: python-subscriber
spec:
 selector:
 matchLabels:
 app: python-subscriber  # 必须匹配.spec.template.metadata.labels
 serviceName: "python-subscriber"
 replicas: 3
 template:
 metadata:
 labels:
 app: python-subscriber # 必须匹配.spec.selector.matchLabels
 annotations:
 dapr.io/enabled: "true"
 dapr.io/app-id: "python-subscriber"
 dapr.io/app-port: "5001"
 spec:
 containers:
 - name: python-subscriber
 image: ghcr.io/dapr/samples/pubsub-python-subscriber:latest
 ports:
 - containerPort: 5001
 imagePullPolicy: Always

在通过Dapr订阅pubsub主题时，应用程序可以定义一个consumerID，这个ID决定了订阅者在队列或主题中的位置。利用StatefulSets中Pod的固定身份，您可以为每个Pod分配一个唯一的consumerID，从而实现订阅者应用程序的水平扩展。Dapr会跟踪每个Pod的名称，并可以在组件中使用{podName}标记来声明。

当扩展某个主题的订阅者数量时，每个Dapr组件都有特定的设置来决定其行为。通常，对于多个消费者有两种选择：

广播：发布到主题的每条消息将被所有订阅者接收。
共享：一条消息仅由一个订阅者接收（而不是所有订阅者）。

Kafka通过consumerID为每个订阅者分配独立的位置。当实例重新启动时，它会使用相同的consumerID继续从上次的位置处理消息，而不会遗漏任何消息。以下组件示例展示了如何让多个Pod使用Kafka组件：

限制 Pub/sub 主题访问

Mon, 01 Jan 0001 00:00:00 +0000

介绍

命名空间或组件范围可以用来限制组件的访问权限，使其仅对特定应用程序可用。这些应用程序范围的设置确保只有具有特定 ID 的应用程序才能使用该组件。

除了这种通用的组件范围外，还可以对 pub/sub 组件进行以下限制：

哪些主题可以被使用（发布或订阅）
哪些应用程序被允许发布到特定主题
哪些应用程序被允许订阅特定主题

这被称为 pub/sub 主题范围控制。

为每个 pub/sub 组件定义 pub/sub 范围。您可能有一个名为 pubsub 的 pub/sub 组件，它有一组范围，另一个 pubsub2 则有不同的范围。

要使用此主题范围，可以为 pub/sub 组件设置三个元数据属性：

spec.metadata.publishingScopes
- 一个以分号分隔的应用程序列表和以逗号分隔的主题列表，允许该应用程序发布到该主题列表
- 如果在 publishingScopes 中未指定任何内容（默认行为），则所有应用程序都可以发布到所有主题
- 要拒绝应用程序发布到任何主题的能力，请将主题列表留空（app1=;app2=topic2）
- 例如，app1=topic1;app2=topic2,topic3;app3= 将允许 app1 仅发布到 topic1，app2 仅发布到 topic2 和 topic3，app3 则不能发布到任何主题。
spec.metadata.subscriptionScopes
- 一个以分号分隔的应用程序列表和以逗号分隔的主题列表，允许该应用程序订阅该主题列表
- 如果在 subscriptionScopes 中未指定任何内容（默认行为），则所有应用程序都可以订阅所有主题
- 例如，app1=topic1;app2=topic2,topic3 将允许 app1 仅订阅 topic1，app2 仅订阅 topic2 和 topic3
spec.metadata.allowedTopics
- 一个为所有应用程序允许的主题的逗号分隔列表。
- 如果未设置 allowedTopics（默认行为），则所有主题都是有效的。如果存在，subscriptionScopes 和 publishingScopes 仍然生效。
- publishingScopes 或 subscriptionScopes 可以与 allowedTopics 结合使用以添加细粒度限制
spec.metadata.protectedTopics
- 一个为所有应用程序保护的主题的逗号分隔列表。
- 如果一个主题被标记为保护，则必须通过 publishingScopes 或 subscriptionScopes 明确授予应用程序发布或订阅权限才能发布/订阅该主题。

这些元数据属性可用于所有 pub/sub 组件。以下示例使用 Redis 作为 pub/sub 组件。

操作指南：在Dapr sidecar中安装证书

Mon, 01 Jan 0001 00:00:00 +0000

Dapr sidecar可以通过配置来信任与外部服务通信所需的证书。这在需要信任自签名证书的场景中非常有用，例如：

使用HTTP绑定
为sidecar配置出站代理

支持信任证书颁发机构（CA）证书和叶子证书。

当sidecar作为容器运行时，可以进行以下配置。

使用卷挂载将证书配置为可用于sidecar容器。
将sidecar容器中的环境变量SSL_CERT_DIR指向包含证书的目录。

注意： 对于Windows容器，请确保容器以管理员权限运行，以便可以安装证书。

以下示例展示了如何使用Docker Compose在sidecar容器中安装证书（证书位于本地的./certificates目录中）：

version: '3'
services:
 dapr-sidecar:
 image: "daprio/daprd:edge" # dapr版本必须至少为v1.8
 command: [
 "./daprd",
 "-app-id", "myapp",
 "-app-port", "3000",
 ]
 volumes:
 - "./components/:/components"
 - "./certificates:/certificates" # （步骤1）将证书文件夹挂载到sidecar容器
 environment:
 - "SSL_CERT_DIR=/certificates" # （步骤2）将环境变量设置为证书文件夹的路径
 # 对于Windows容器，取消注释下面的行
 # user: ContainerAdministrator

注意： 当sidecar不在容器内运行时，证书必须直接安装在主机操作系统上。

操作指南：配置 Azure Monitor 以搜索日志和收集指标

Mon, 01 Jan 0001 00:00:00 +0000

前提条件

使用配置映射启用 Prometheus 指标抓取

确认 Azure Monitor Agents (AMA) 正在运行。

$ kubectl get pods -n kube-system
NAME READY STATUS RESTARTS AGE
...
ama-logs-48kpv 2/2 Running 0 2d13h
ama-logs-mx24c 2/2 Running 0 2d13h
ama-logs-rs-f9bbb9898-vbt6k 1/1 Running 0 30h
ama-logs-sm2mz 2/2 Running 0 2d13h
ama-logs-z7p4c 2/2 Running 0 2d13h
...

使用配置映射启用 Prometheus 指标端点抓取。

可以使用 azm-config-map.yaml 来启用 Prometheus 指标端点抓取。

如果 Dapr 安装在不同的命名空间，需要修改 monitor_kubernetes_pod_namespaces 数组的值。例如：

...
 prometheus-data-collection-settings: |-
 [prometheus_data_collection_settings.cluster]
 interval = "1m"
 monitor_kubernetes_pods = true
 monitor_kubernetes_pods_namespaces = ["dapr-system", "default"]
 [prometheus_data_collection_settings.node]
 interval = "1m"
...

应用配置映射：

如何使用 Dapr Kubernetes Operator

Mon, 01 Jan 0001 00:00:00 +0000

您可以通过 Dapr Kubernetes Operator 来管理 Dapr 的控制平面。这个工具可以帮助您自动化管理在 Kubernetes 环境中 Dapr 控制平面的生命周期任务。

安装和使用 Dapr Kubernetes Operator

消息生存时间 (TTL)

Mon, 01 Jan 0001 00:00:00 +0000

介绍

Dapr 支持为每条消息设置生存时间 (TTL)。这意味着应用程序可以为每条消息指定生存时间，过期后订阅者将不会收到这些消息。

所有 Dapr 发布/订阅组件都兼容消息 TTL，因为 Dapr 在运行时内处理 TTL 逻辑。只需在发布消息时设置 ttlInSeconds 元数据即可。

在某些组件中，例如 Kafka，可以通过 retention.ms 在主题中配置生存时间，详见文档。使用 Dapr 的消息 TTL，使用 Kafka 的应用程序现在可以为每条消息设置生存时间，而不仅限于每个主题。

原生消息 TTL 支持

当发布/订阅组件原生支持消息生存时间时，Dapr 仅转发生存时间配置而不添加额外逻辑，保持行为的可预测性。这在组件以不同方式处理过期消息时非常有用。例如，在 Azure Service Bus 中，过期消息会被存储在死信队列中，而不是简单地删除。

注意

您还可以在创建时为给定的消息代理设置消息 TTL。查看您正在使用的组件的特定特性，以确定这是否合适。

支持的组件

Azure Service Bus

Azure Service Bus 支持实体级别的生存时间。这意味着消息有默认的生存时间，但也可以在发布时设置为更短的时间跨度。Dapr 传播消息的生存时间元数据，并让 Azure Service Bus 直接处理过期。

非 Dapr 订阅者

如果消息由不使用 Dapr 的订阅者消费，过期消息不会自动丢弃，因为过期是由 Dapr 运行时在 Dapr sidecar 接收到消息时处理的。然而，订阅者可以通过在云事件中添加逻辑来处理 expiration 属性，以编程方式丢弃过期消息，该属性遵循 RFC3339 格式。

当非 Dapr 订阅者使用诸如 Azure Service Bus 等原生处理消息 TTL 的组件时，他们不会收到过期消息。在这种情况下，不需要额外的逻辑。

操作指南：启用预览功能

Mon, 01 Jan 0001 00:00:00 +0000

在 Dapr 中，预览功能在首次发布时被视为实验功能。这些预览功能需要您明确选择启用才能使用。您需要在 Dapr 的配置文件中进行此选择。

预览功能是通过在运行应用程序实例时设置配置来启用的。

配置属性

Configuration 规范下的 features 部分包含以下属性：

属性	类型	描述
`name`	字符串	启用/禁用的预览功能的名称
`enabled`	布尔值	指定功能是否启用或禁用的布尔值

启用预览功能

预览功能需要在配置中指定。以下是一个包含多个功能的完整配置示例：

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: featureconfig
spec:
 tracing:
 samplingRate: "1"
 zipkin:
 endpointAddress: "http://zipkin.default.svc.cluster.local:9411/api/v2/spans"
 features:
 - name: Feature1
 enabled: true
 - name: Feature2
 enabled: true

要在本地运行 Dapr 时启用预览功能，可以更新默认配置或使用 dapr run 指定单独的配置文件。

批量发布和订阅消息

Mon, 01 Jan 0001 00:00:00 +0000

alpha

批量发布和订阅API目前处于alpha阶段。

通过批量发布和订阅API，您可以在单个请求中发布和订阅多个消息。在开发需要发送或接收大量消息的应用程序时，使用批量操作可以通过减少Dapr sidecar、应用程序和底层pubsub代理之间的请求总数来提高吞吐量。

批量发布消息

批量发布消息时的限制

批量发布API允许您通过单个请求将多个消息发布到一个主题。它是非事务性的，这意味着在一个批量请求中，某些消息可能会成功发布，而某些可能会失败。如果有消息发布失败，批量发布操作将返回失败消息的列表。

批量发布操作不保证消息的顺序。

示例

import io.dapr.client.DaprClientBuilder;
import io.dapr.client.DaprPreviewClient;
import io.dapr.client.domain.BulkPublishResponse;
import io.dapr.client.domain.BulkPublishResponseFailedEntry;
import java.util.ArrayList;
import java.util.List;

class BulkPublisher {
 private static final String PUBSUB_NAME = "my-pubsub-name";
 private static final String TOPIC_NAME = "topic-a";

 public void publishMessages() {
 try (DaprPreviewClient client = (new DaprClientBuilder()).buildPreviewClient()) {
 // 创建要发布的消息列表
 List<String> messages = new ArrayList<>();
 for (int i = 0; i < 10; i++) {
 String message = String.format("这是消息 #%d", i);
 messages.add(message);
 }

 // 使用批量发布API发布消息列表
 BulkPublishResponse<String> res = client.publishEvents(PUBSUB_NAME, TOPIC_NAME, "text/plain", messages).block();
 }
 }
}


import { DaprClient } from "@dapr/dapr";

const pubSubName = "my-pubsub-name";
const topic = "topic-a";

async function start() {
 const client = new DaprClient();

 // 向主题发布多个消息。
 await client.pubsub.publishBulk(pubSubName, topic, ["message 1", "message 2", "message 3"]);

 // 使用显式批量发布消息向主题发布多个消息。
 const bulkPublishMessages = [
 {
 entryID: "entry-1",
 contentType: "application/json",
 event: { hello: "foo message 1" },
 },
 {
 entryID: "entry-2",
 contentType: "application/cloudevents+json",
 event: {
 specversion: "1.0",
 source: "/some/source",
 type: "example",
 id: "1234",
 data: "foo message 2",
 datacontenttype: "text/plain"
 },
 },
 {
 entryID: "entry-3",
 contentType: "text/plain",
 event: "foo message 3",
 },
 ];
 await client.pubsub.publishBulk(pubSubName, topic, bulkPublishMessages);
}

start().catch((e) => {
 console.error(e);
 process.exit(1);
});

using System;
using System.Collections.Generic;
using Dapr.Client;

const string PubsubName = "my-pubsub-name";
const string TopicName = "topic-a";
IReadOnlyList<object> BulkPublishData = new List<object>() {
 new { Id = "17", Amount = 10m },
 new { Id = "18", Amount = 20m },
 new { Id = "19", Amount = 30m }
};

using var client = new DaprClientBuilder().Build();

var res = await client.BulkPublishEventAsync(PubsubName, TopicName, BulkPublishData);
if (res == null) {
 throw new Exception("从dapr返回的响应为空");
}
if (res.FailedEntries.Count > 0)
{
 Console.WriteLine("某些事件发布失败！");
 foreach (var failedEntry in res.FailedEntries)
 {
 Console.WriteLine("EntryId: " + failedEntry.Entry.EntryId + " 错误信息: " +
 failedEntry.ErrorMessage);
 }
}
else
{
 Console.WriteLine("所有事件已发布！");
}

import requests
import json

base_url = "http://localhost:3500/v1.0-alpha1/publish/bulk/{}/{}"
pubsub_name = "my-pubsub-name"
topic_name = "topic-a"
payload = [
 {
 "entryId": "ae6bf7c6-4af2-11ed-b878-0242ac120002",
 "event": "first text message",
 "contentType": "text/plain"
 },
 {
 "entryId": "b1f40bd6-4af2-11ed-b878-0242ac120002",
 "event": {
 "message": "second JSON message"
 },
 "contentType": "application/json"
 }
]

response = requests.post(base_url.format(pubsub_name, topic_name), json=payload)
print(response.status_code)

package main

import (
 "fmt"
 "strings"
 "net/http"
 "io/ioutil"
)

const (
 pubsubName = "my-pubsub-name"
 topicName = "topic-a"
 baseUrl = "http://localhost:3500/v1.0-alpha1/publish/bulk/%s/%s"
)

func main() {
 url := fmt.Sprintf(baseUrl, pubsubName, topicName)
 method := "POST"
 payload := strings.NewReader(`[
 {
 "entryId": "ae6bf7c6-4af2-11ed-b878-0242ac120002",
 "event": "first text message",
 "contentType": "text/plain"
 },
 {
 "entryId": "b1f40bd6-4af2-11ed-b878-0242ac120002",
 "event": {
 "message": "second JSON message"
 },
 "contentType": "application/json"
 }
]`)

 client := &http.Client {}
 req, _ := http.NewRequest(method, url, payload)

 req.Header.Add("Content-Type", "application/json")
 res, err := client.Do(req)
 // ...
}

curl -X POST http://localhost:3500/v1.0-alpha1/publish/bulk/my-pubsub-name/topic-a \
 -H 'Content-Type: application/json' \
 -d '[
 {
 "entryId": "ae6bf7c6-4af2-11ed-b878-0242ac120002",
 "event": "first text message",
 "contentType": "text/plain"
 },
 {
 "entryId": "b1f40bd6-4af2-11ed-b878-0242ac120002",
 "event": {
 "message": "second JSON message"
 },
 "contentType": "application/json"
 },
 ]'

Invoke-RestMethod -Method Post -ContentType 'application/json' -Uri 'http://localhost:3500/v1.0-alpha1/publish/bulk/my-pubsub-name/topic-a' `
-Body '[
 {
 "entryId": "ae6bf7c6-4af2-11ed-b878-0242ac120002",
 "event": "first text message",
 "contentType": "text/plain"
 },
 {
 "entryId": "b1f40bd6-4af2-11ed-b878-0242ac120002",
 "event": {
 "message": "second JSON message"
 },
 "contentType": "application/json"
 },
 ]'

批量订阅消息

批量订阅API允许您在单个请求中从一个主题订阅多个消息。正如我们从如何：发布和订阅主题中所知，有三种方式可以订阅主题：

操作指南：为 Dapr sidecar 配置 Secret 环境变量

Mon, 01 Jan 0001 00:00:00 +0000

在某些情况下，Dapr sidecar 需要注入环境变量。这可能是因为某个组件、第三方库或模块需要通过环境变量进行配置或自定义行为。这在生产和非生产环境中都很有用。

概述

在 Dapr 1.15 中，引入了新的 dapr.io/env-from-secret 注解，类似于 dapr.io/env。通过这个注解，你可以将环境变量注入到 Dapr sidecar 中，其值来自于一个 secret。

注解格式

注解的格式如下：

单个键的 secret: <ENV_VAR_NAME>=<SECRET_NAME>
多个键/值的 secret: <ENV_VAR_NAME>=<SECRET_NAME>:<SECRET_KEY>

<ENV_VAR_NAME> 必须符合 C_IDENTIFIER 格式，遵循 [A-Za-z_][A-Za-z0-9_]* 的正则表达式：

必须以字母或下划线开头
其余部分可以包含字母、数字或下划线

由于 secretKeyRef 的限制，name 字段是必需的，因此 name 和 key 必须同时设置。从 Kubernetes 文档的 “env.valueFrom.secretKeyRef.name” 部分了解更多信息。在这种情况下，Dapr 会将两者设置为相同的值。

配置单个键的 secret 环境变量

在以下示例中，dapr.io/env-from-secret 注解被添加到 Deployment 中。

apiVersion: apps/v1
kind: Deployment
metadata:
 name: nodeapp
spec:
 template:
 metadata:
 annotations:
 dapr.io/enabled: "true"
 dapr.io/app-id: "nodeapp"
 dapr.io/app-port: "3000"
 dapr.io/env-from-secret: "AUTH_TOKEN=auth-headers-secret"
 spec:
 containers:
 - name: node
 image: dapriosamples/hello-k8s-node:latest
 ports:
 - containerPort: 3000
 imagePullPolicy: Always

dapr.io/env-from-secret 注解的值为 "AUTH_TOKEN=auth-headers-secret" 被注入为：

如何：与 Kratix 集成

Mon, 01 Jan 0001 00:00:00 +0000

在 Kratix 市场中，Dapr 可以用于构建满足您需求的定制平台。

注意

Dapr Helm chart 生成的静态公钥和私钥对会被发布在仓库中。此 promise 仅适用于本地演示。如果您计划将此 promise 用于其他用途，建议手动更新 promise 中的所有 secret，并使用您自己的凭据。

只需安装 Dapr Promise，即可在所有匹配的集群上安装 Dapr。

安装 Dapr Promise

Dapr Visual Studio Code 扩展概述

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 提供了一个预览版的 Dapr Visual Studio Code 扩展，专为本地开发设计。该扩展为用户提供多种功能，以便更好地管理 Dapr 应用程序，并调试支持的 Dapr 语言的应用程序，包括 .NET、Go、PHP、Python 和 Java。

在 VSCode 中打开

功能

脚手架 Dapr 调试任务

Dapr 扩展利用 Visual Studio Code 的内置调试功能帮助您调试应用程序。

通过 Dapr: Scaffold Dapr Tasks 命令面板操作，您可以更新现有的 task.json 和 launch.json 文件，以便在开始调试时启动和配置 Dapr sidecar。

确保为您的应用程序设置了启动配置。(了解更多)
使用 Ctrl+Shift+P 打开命令面板
选择 Dapr: Scaffold Dapr Tasks
使用 F5 或通过运行视图运行您的应用程序和 Dapr sidecar。

脚手架 Dapr 组件

在将 Dapr 添加到应用程序时，您可能希望创建一个独立的组件目录，以区别于 dapr init 初始化的默认组件。

要使用默认的 statestore、pubsub 和 zipkin 组件创建一个专用的组件文件夹，请使用 Dapr: Scaffold Dapr Components 命令面板操作。

使用 Dapr HTTP 服务 SDK for Go 入门

Mon, 01 Jan 0001 00:00:00 +0000

前置条件

首先导入 Dapr Go 的 service/http 包：

daprd "github.com/dapr/go-sdk/service/http"

创建和启动服务

要创建一个 HTTP Dapr 服务，首先需要在特定地址上创建一个 Dapr 回调实例：

s := daprd.NewService(":8080")

或者结合现有的 http.ServeMux 使用特定地址创建服务，以便与现有服务器集成：

mux := http.NewServeMux()
mux.HandleFunc("/", myOtherHandler)
s := daprd.NewServiceWithMux(":8080", mux)

创建服务实例后，你可以添加任意数量的事件、绑定和服务调用处理程序。定义好这些逻辑后，就可以启动服务：

if err := s.Start(); err != nil && err != http.ErrServerClosed {
	log.Fatalf("error: %v", err)
}

事件处理

要处理来自特定主题的事件，你需要在启动服务之前添加至少一个主题事件处理程序：

sub := &common.Subscription{
	PubsubName: "messages",
	Topic: "topic1",
	Route: "/events",
}
err := s.AddTopicEventHandler(sub, eventHandler)
if err != nil {
	log.Fatalf("error adding topic subscription: %v", err)
}

处理程序方法可以是任何符合预期签名的方法：

func eventHandler(ctx context.Context, e *common.TopicEvent) (retry bool, err error) {
	log.Printf("event - PubsubName:%s, Topic:%s, ID:%s, Data: %v", e.PubsubName, e.Topic, e.ID, e.Data)
	// 处理事件
	return true, nil
}

你可以选择使用路由规则根据 CloudEvent 的内容将消息路由到不同的处理程序。

sub := &common.Subscription{
	PubsubName: "messages",
	Topic: "topic1",
	Route: "/important",
	Match: `event.type == "important"`,
	Priority: 1,
}
err := s.AddTopicEventHandler(sub, importantHandler)
if err != nil {
	log.Fatalf("error adding topic subscription: %v", err)
}

你还可以创建一个自定义类型来实现 TopicEventSubscriber 接口以处理事件：

HowTo: 配置具有多个命名空间的 Pub/Sub 组件

Mon, 01 Jan 0001 00:00:00 +0000

在某些情况下，应用程序可能会跨多个命名空间分布，并通过 PubSub 共享队列或主题。在这种情况下，需要在每个命名空间中配置 PubSub 组件。

注意

命名空间是 Dapr 用于限定应用程序和组件范围的概念。本示例使用 Kubernetes 命名空间，但 Dapr 组件命名空间范围可以在任何支持的平台上使用。阅读 How-To: 将组件限定到一个或多个应用程序以获取有关限定组件的更多信息。

本示例使用 PubSub 示例。Redis 安装和订阅者位于 namespace-a，而发布者 UI 位于 namespace-b。即使 Redis 安装在另一个命名空间，或者您使用托管云服务如 Azure ServiceBus、AWS SNS/SQS 或 GCP PubSub，该解决方案也同样适用。

以下是使用命名空间的示例图。

下表显示了哪些资源部署到哪些命名空间：

资源	namespace-a	namespace-b
Redis 主节点	✅	❌
Redis 副本	✅	❌
Dapr 的 PubSub 组件	✅	✅
Node 订阅者	✅	❌
Python 订阅者	✅	❌
React UI 发布者	❌	✅

注意

所有 pub/sub 组件都支持通过命名空间或组件范围将 pub/sub 主题限制到特定应用程序。

前提条件

在 Kubernetes 上安装 Dapr，因为 Dapr 在集群级别工作。
检出并进入 PubSub 快速入门的目录。

设置 `namespace-a`

创建命名空间并切换 kubectl 使用它。

服务调用性能

Mon, 01 Jan 0001 00:00:00 +0000

本文提供了在不同托管环境中运行Dapr所需组件的服务调用API性能基准和资源利用率。

系统概述

Dapr由两个主要部分组成：数据平面和控制平面。数据平面是运行在应用程序旁边的sidecar，而控制平面负责配置sidecar并提供证书和身份管理等功能。

自托管组件

sidecar（数据平面）
Sentry（可选，控制平面）
Placement（可选，控制平面）

更多信息请参见Dapr自托管模式概述。

Kubernetes组件

sidecar（数据平面）
Sentry（可选，控制平面）
Placement（可选，控制平面）
Operator（控制平面）
sidecar注入器（控制平面）

更多信息请参见Dapr在Kubernetes上的概述。

Dapr v1.0的性能总结

服务调用API是一个反向代理，内置了服务发现功能，用于连接其他服务。这包括跟踪、指标、用于流量传输加密的mTLS，以及通过重试网络分区和连接错误来实现的弹性。

通过服务调用，您可以实现从HTTP到HTTP、HTTP到gRPC、gRPC到HTTP和gRPC到gRPC的调用。Dapr在sidecar之间的通信中始终使用gRPC，但保留了应用程序调用时使用的协议语义。服务调用是与Dapr actor通信的底层机制。

更多信息请参见服务调用概述。

Kubernetes性能测试设置

测试在一个3节点的Kubernetes集群上进行，使用普通硬件，每个节点配备4核CPU和8GB RAM，没有任何网络加速。设置包括一个负载测试器（Fortio）pod，其中注入了一个Dapr sidecar，调用服务调用API以到达不同节点上的pod。

测试参数：

每秒1000个请求
sidecar限制为0.5 vCPU
启用sidecar mTLS
启用sidecar遥测（采样率为0.1的跟踪）
1KB的负载

基准测试包括直接、未加密的流量，没有遥测，直接从负载测试器到目标应用程序。

控制平面性能

Dapr控制平面在非高可用模式下运行时使用总共0.009 vCPU和61.6 Mb，这意味着每个系统组件只有一个副本。在高可用生产设置中运行时，Dapr控制平面消耗约0.02 vCPU和185 Mb。

组件	vCPU	内存
Operator	0.001	12.5 Mb
Sentry	0.005	13.6 Mb
sidecar注入器	0.002	14.6 Mb
Placement	0.001	20.9 Mb

有许多因素会影响每个系统组件的CPU和内存消耗。这些因素在下表中显示。

组件	vCPU	内存
Operator	请求组件、配置和订阅的pod数量
Sentry	证书请求数量
sidecar注入器	准入请求数量
Placement	actor重新平衡操作数量	连接的actor主机数量

数据平面性能

Dapr sidecar每秒处理1000个请求时使用0.48 vCPU和23Mb内存。在端到端的调用中，Dapr sidecar（客户端和服务器）在第90百分位延迟中增加约1.40 ms，在第99百分位延迟中增加约2.10 ms。端到端是指从一个应用程序发出请求到另一个应用程序接收响应的全过程。这在此图的步骤1-7中显示。

Azure 身份验证

Mon, 01 Jan 0001 00:00:00 +0000

大多数 Dapr 的 Azure 组件支持使用 Microsoft Entra ID 进行身份验证。通过这种方式：

管理员可以充分利用 Azure 基于角色的访问控制 (RBAC) 的精细权限。
在 Azure 服务（如 Azure 容器应用、Azure Kubernetes 服务、Azure 虚拟机或其他 Azure 平台服务）上运行的应用程序可以使用托管身份 (MI) 和工作负载身份。这些功能使您的应用程序能够在不需要管理敏感凭据的情况下进行身份验证。

关于 Microsoft Entra ID 的身份验证

Microsoft Entra ID 是 Azure 的身份和访问管理 (IAM) 解决方案，用于对用户和服务进行身份验证和授权。

Microsoft Entra ID 基于 OAuth 2.0 等开放标准，允许服务（应用程序）获取访问令牌以请求 Azure 服务，包括 Azure 存储、Azure 服务总线、Azure 密钥保管库、Azure Cosmos DB、Azure PostgreSQL 数据库、Azure SQL 等。

在 Azure 术语中，应用程序也被称为“服务主体”。

一些 Azure 组件提供其他身份验证方法，例如基于“共享密钥”或“访问令牌”的系统。尽管这些方法在 Dapr 中是有效且受支持的，但建议尽可能使用 Microsoft Entra ID 对 Dapr 组件进行身份验证，以利用其众多优势，包括：

Dapr 在 Kubernetes 上的概述

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 可以在任何支持的 Kubernetes 版本上运行。为此，Dapr 部署了一些 Kubernetes 服务，这些服务提供了良好的集成，使得在 Kubernetes 上运行 Dapr 应用程序变得简单。

Kubernetes 服务	描述
`dapr-operator`	管理 Dapr 的组件更新和 Kubernetes 服务端点（如状态存储、发布/订阅等）
`dapr-sidecar-injector`	将 Dapr 注入到已标注的部署 pod 中，并添加环境变量 `DAPR_HTTP_PORT` 和 `DAPR_GRPC_PORT`，以便用户应用程序可以轻松与 Dapr 通信，而无需硬编码 Dapr 端口。
`dapr-placement`	专用于actor。创建映射表，将 actor 实例映射到 pod
`dapr-sentry`	管理服务之间的 mTLS 并充当证书颁发机构。更多信息请参阅安全概述

支持的版本

Dapr 对 Kubernetes 的支持遵循 Kubernetes 版本偏差政策。

将 Dapr 部署到 Kubernetes 集群

阅读在 Kubernetes 集群上部署 Dapr以了解如何将 Dapr 部署到您的 Kubernetes 集群。

将 Dapr 添加到 Kubernetes 部署

要在 Kubernetes 集群中部署和运行启用 Dapr 的应用程序，只需在 pod 中添加一些注释即可。例如，在以下示例中，您的 Kubernetes pod 被标注为：

Dapr 自托管模式概述

Mon, 01 Jan 0001 00:00:00 +0000

概述

Dapr 可以配置为在本地开发者机器或生产环境的虚拟机上运行自托管模式。每个服务都会有一个 Dapr 运行时进程（或称为 sidecar），该进程配置为使用状态存储、发布/订阅、绑定组件和其他构建块。

初始化

Dapr 可以通过 Docker（默认）或 slim-init 模式进行初始化。它也可以在离线或隔离环境中初始化和运行。

注意

您也可以使用 Podman 代替 Docker 作为容器运行时。请参阅使用 Podman 初始化 Dapr 以获取更多详细信息。在由于各种网络限制无法安装 Docker 的情况下，这可能会很有用。

默认的 Docker 设置提供了即用的功能，包含以下容器和配置：

一个 Redis 容器，配置为同时用于状态管理和发布/订阅的默认组件。
一个 Zipkin 容器，用于诊断和跟踪。
默认的 Dapr 配置和组件安装在 $HOME/.dapr/ (Mac/Linux) 或 %USERPROFILE%\.dapr\ (Windows)。

dapr-placement 服务负责管理 actor 的分布方案和键范围设置。此服务不作为容器启动，仅在您使用 Dapr actor 时才需要。有关 actor Placement 服务的更多信息，请阅读 actor 概述。

使用 Dapr 启动应用程序

您可以使用 dapr run CLI 命令启动 Dapr sidecar 进程和您的应用程序。其他参数和标志可以在这里找到。

名称解析

Dapr 使用名称解析组件在服务调用构建块中进行服务发现。默认情况下，Dapr 在自托管模式下使用 mDNS。

使用 Dapr 客户端 Python SDK 入门

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 客户端包使您能够从 Python 应用程序与其他 Dapr 应用程序进行交互。

注意

如果您还没有尝试过，请尝试其中一个快速入门，以快速了解如何使用 Dapr Python SDK 和 API 构建块。

准备工作

在开始之前，安装 Dapr Python 包。

导入客户端包

dapr 包包含 DaprClient，用于创建和使用客户端。

from dapr.clients import DaprClient

初始化客户端

您可以通过多种方式初始化 Dapr 客户端：

默认值：

如果不提供参数初始化客户端，它将使用 Dapr sidecar 实例的默认值 (127.0.0.1:50001)。

from dapr.clients import DaprClient

with DaprClient() as d:
 # 使用客户端

在初始化时指定端点：

在构造函数中传递参数时，gRPC 端点优先于任何配置或环境变量。

from dapr.clients import DaprClient

with DaprClient("mydomain:50051?tls=true") as d:
 # 使用客户端

配置选项：

Dapr Sidecar 端点

您可以使用标准化的 DAPR_GRPC_ENDPOINT 环境变量来指定 gRPC 端点。当设置了此变量时，可以在没有任何参数的情况下初始化客户端：

export DAPR_GRPC_ENDPOINT="mydomain:50051?tls=true"

from dapr.clients import DaprClient

with DaprClient() as d:
 # 客户端将使用环境变量中指定的端点

旧的环境变量 DAPR_RUNTIME_HOST、DAPR_HTTP_PORT 和 DAPR_GRPC_PORT 也被支持，但 DAPR_GRPC_ENDPOINT 优先。

使用 Dapr actor Python SDK 入门

Mon, 01 Jan 0001 00:00:00 +0000

Dapr actor 包使您能够从 Python 应用程序与 Dapr 虚拟 actor 交互。

先决条件

已安装 Dapr CLI
已初始化 Dapr 环境
已安装 Python 3.8+
已安装 Dapr Python 包

actor 接口

接口定义了 actor 实现和调用 actor 的客户端之间共享的协议。由于客户端可能依赖于此协议，通常将其定义在与 actor 实现分开的模块中是有意义的。

from dapr.actor import ActorInterface, actormethod

class DemoActorInterface(ActorInterface):
 @actormethod(name="GetMyData")
 async def get_my_data(self) -> object:
 ...

actor 服务

actor 服务负责托管虚拟 actor。它是一个从基类 Actor 派生并实现 actor 接口中定义的类。

可以使用以下 Dapr actor 扩展之一创建 actor：

actor 客户端

actor 客户端用于实现调用 actor 接口中定义的方法。

import asyncio

from dapr.actor import ActorProxy, ActorId
from demo_actor_interface import DemoActorInterface

async def main():
 # 创建代理客户端
 proxy = ActorProxy.create('DemoActor', ActorId('1'), DemoActorInterface)

 # 在客户端上调用方法
 resp = await proxy.GetMyData()

示例

访问此页面获取可运行的 actor 示例。

actor 性能激活

Mon, 01 Jan 0001 00:00:00 +0000

本文介绍了在 Kubernetes 上 Dapr 中 actor 的服务调用 API 的性能基准和资源使用情况。

系统概述

在 Dapr 中使用 actor 的应用程序需要考虑两个方面。首先，actor 调用的路由由 Dapr 的边车（sidecar）处理。其次，actor 的运行时在应用程序端实现和处理，这依赖于所使用的 SDK。目前，性能测试使用 Java SDK 在应用程序中提供 actor 运行时。

Kubernetes 组件

边车（数据平面）
Placement（actor 所需，控制平面将 actor 类型映射到主机）
Operator（控制平面）
边车注入器（控制平面）
Sentry（可选，控制平面）

Dapr v1.0 的性能总结

Dapr 边车中的 actor API 负责识别注册了特定 actor 类型的主机，并将请求路由到拥有该 actor ID 的合适主机。主机运行应用程序的一个实例，并使用 Dapr SDK（.Net、Java、Python 或 PHP）通过 HTTP 处理 actor 请求。

本次测试通过 Dapr 的 HTTP API 直接调用 actor。

有关更多信息，请参见 actor 概述。

Kubernetes 性能测试设置

测试在一个由 3 个节点组成的 Kubernetes 集群上进行，使用普通硬件，每个节点配备 4 核 CPU 和 8GB RAM，没有网络加速。设置包括一个负载测试器（Fortio）pod，其中注入了一个 Dapr 边车，调用服务 API 以访问不同节点上的 pod。

使用 Dapr 服务（回调）SDK for Go 入门

Mon, 01 Jan 0001 00:00:00 +0000

Dapr gRPC 服务 SDK for Go

前置条件

首先，导入 Dapr Go 服务/gRPC 包：

daprd "github.com/dapr/go-sdk/service/grpc"

创建和启动服务

要创建一个 gRPC Dapr 服务，首先需要在特定地址上创建一个 Dapr 回调实例：

s, err := daprd.NewService(":50001")
if err != nil {
 log.Fatalf("无法启动服务器: %v", err)
}

或者，使用地址和现有的 net.Listener，以便与现有的服务器监听器结合：

list, err := net.Listen("tcp", "localhost:0")
if err != nil {
	log.Fatalf("gRPC 监听器创建失败: %s", err)
}
s := daprd.NewServiceWithListener(list)

创建服务实例后，你可以为该服务添加任意数量的事件、绑定和服务调用处理程序，如下所示。定义好逻辑后，你就可以启动服务：

if err := s.Start(); err != nil {
 log.Fatalf("服务器错误: %v", err)
}

事件处理

要处理来自特定主题的事件，你需要在启动服务之前添加至少一个主题事件处理程序：

sub := &common.Subscription{
		PubsubName: "messages",
		Topic: "topic1",
	}
if err := s.AddTopicEventHandler(sub, eventHandler); err != nil {
 log.Fatalf("添加主题订阅时出错: %v", err)
}

处理程序方法可以是任何符合预期签名的方法：

func eventHandler(ctx context.Context, e *common.TopicEvent) (retry bool, err error) {
	log.Printf("事件 - PubsubName:%s, Topic:%s, ID:%s, Data: %v", e.PubsubName, e.Topic, e.ID, e.Data)
	// 在这里处理事件
	return true, nil
}

你可以选择使用路由规则根据 CloudEvent 的内容将消息路由到不同的处理程序。

sub := &common.Subscription{
	PubsubName: "messages",
	Topic: "topic1",
	Route: "/important",
	Match: `event.type == "important"`,
	Priority: 1,
}
err := s.AddTopicEventHandler(sub, importantHandler)
if err != nil {
	log.Fatalf("添加主题订阅时出错: %v", err)
}

你还可以创建一个自定义类型来实现 TopicEventSubscriber 接口，以处理你的事件：

如何使用 Podman 在自托管模式下运行 Dapr

Mon, 01 Jan 0001 00:00:00 +0000

本文介绍了如何在 Windows/Linux/macOS 机器或虚拟机上使用 Podman 运行 Dapr。

准备工作

设置 Dapr 环境

要设置 Dapr 控制平面容器并创建默认配置文件，请执行以下命令：

dapr init --container-runtime podman

以进程方式运行应用程序和 sidecar

可以使用 dapr run CLI 命令启动 Dapr sidecar 和您的应用程序：

dapr run --app-id myapp --app-port 5000 -- dotnet run

此命令会启动 daprd sidecar 和您的应用程序。

以进程方式运行应用程序，sidecar 作为 Docker 容器运行

如果您希望在 Docker 容器中运行 Dapr，而应用程序在主机上以进程方式运行，则需要配置 Podman 使用主机网络，以便 Dapr 和应用程序可以共享 localhost 网络接口。

在 Linux 主机上运行 Podman 时，可以使用以下命令启动 Dapr：

podman run --network="host" --mount type=bind,source="$(pwd)"/components,target=/components daprio/daprd:edge ./daprd -app-id <my-app-id> -app-port <my-app-port>

然后，您可以在主机上运行您的应用程序，它们可以通过 localhost 网络接口进行连接。

在 Kubernetes 集群上部署 Dapr

Mon, 01 Jan 0001 00:00:00 +0000

在 Kubernetes 上设置 Dapr 时，你可以使用 Dapr CLI 或 Helm。

混合集群

Dapr CLI 和 Dapr Helm chart 默认会部署到带有标签 kubernetes.io/os=linux 的节点上。如果你的应用程序需要，你也可以将 Dapr 部署到 Windows 节点。更多信息请参见部署到混合 Linux/Windows Kubernetes 集群。

使用 Dapr CLI 安装

你可以使用 Dapr CLI 在 Kubernetes 集群中安装 Dapr。

先决条件

安装：
- Dapr CLI
- kubectl
创建一个带有 Dapr 的 Kubernetes 集群。以下是一些有用的链接：

安装选项

你可以从官方 Helm chart 或私有 chart 安装 Dapr，并使用自定义命名空间等。

如何：在 Java SDK 中编写和管理 Dapr 工作流

Mon, 01 Jan 0001 00:00:00 +0000

我们来创建一个 Dapr 工作流，并通过控制台调用它。通过提供的工作流示例，您将：

使用 Java 工作流工作者执行工作流实例
利用 Java 工作流客户端和 API 调用来启动和终止工作流实例

在自托管模式下，此示例使用 dapr init 的默认配置运行。

准备工作

Dapr CLI 和已初始化的环境。
Java JDK 11（或更高版本）：
- Oracle JDK，或
- OpenJDK
Apache Maven，版本 3.x。

Docker Desktop

确保您使用的是最新版本的 proto 绑定

设置环境

克隆 Java SDK 仓库并进入其中。

git clone https://github.com/dapr/java-sdk.git
cd java-sdk

运行以下命令以安装运行此工作流示例所需的 Dapr Java SDK 依赖项。

mvn clean install

从 Java SDK 根目录，导航到 Dapr 工作流示例。

cd examples

运行 `DemoWorkflowWorker`

DemoWorkflowWorker 类在 Dapr 的工作流运行时引擎中注册了 DemoWorkflow 的实现。在 DemoWorkflowWorker.java 文件中，您可以找到 DemoWorkflowWorker 类和 main 方法：

如何：使用 Visual Studio Code 调试 Dapr 应用程序

Mon, 01 Jan 0001 00:00:00 +0000

手动调试

在开发 Dapr 应用程序时，通常使用 Dapr CLI 启动服务，命令如下：

dapr run --app-id nodeapp --app-port 3000 --dapr-http-port 3500 app.js

一种将调试器附加到服务的方法是先在命令行中使用正确的参数运行 daprd，然后启动代码并附加调试器。虽然这种方法可行，但需要额外的步骤，并且需要为那些可能克隆您的仓库并希望直接点击“播放”按钮开始调试的开发人员提供一些指导。

如果您的应用程序由多个微服务组成，并且每个微服务都有一个 Dapr 辅助进程，那么在 Visual Studio Code 中同时调试它们会非常有帮助。本页面将使用 hello world 快速入门来展示如何配置 VSCode 以使用 VSCode 调试调试多个 Dapr 应用程序。

先决条件

安装 Dapr 扩展。您将在后续步骤中使用它提供的 tasks。
可选地克隆 hello world 快速入门

步骤 1：配置 launch.json

文件 .vscode/launch.json 包含 VS Code 调试运行的启动配置。该文件定义了用户开始调试时将启动什么以及如何配置。每种编程语言的配置都可以在 Visual Studio Code marketplace 中找到。

生成调试配置

Dapr VSCode 扩展提供内置的脚手架来为您生成 launch.json 和 tasks.json。

了解更多

在 hello world 快速入门的例子中，启动了两个应用程序，每个都有自己的 Dapr 辅助进程。一个是用 Node.JS 编写的，另一个是用 Python 编写的。您会注意到每个配置都包含一个 daprd run 的 preLaunchTask 和一个 daprd stop 的 postDebugTask。

如何使用 Docker 自托管 Dapr

Mon, 01 Jan 0001 00:00:00 +0000

本文介绍如何在 Windows/Linux/macOS 机器或虚拟机上使用 Docker 运行 Dapr。

前提条件

设置 Dapr 环境

运行以下命令以初始化 Dapr 控制平面并创建默认配置文件：

dapr init

以进程形式运行应用和 sidecar

使用 dapr run CLI 命令启动 Dapr sidecar 和您的应用程序：

dapr run --app-id myapp --app-port 5000 -- dotnet run

此命令将启动 daprd sidecar 并运行 dotnet run，从而启动您的应用程序。

应用以进程形式运行，sidecar 以 Docker 容器形式运行

如果您希望在 Docker 容器中运行 Dapr，而应用程序在主机上以进程形式运行，则需要配置 Docker 使用主机网络，以便 Dapr 和应用程序可以共享 localhost 网络接口。

注意

Docker 的 host 网络模式仅支持 Linux 主机。

在 Linux 主机上运行 Docker 守护进程时，可以使用以下命令启动 Dapr：

使用 Dapr CLI 进行 Dapr .NET SDK 开发

Mon, 01 Jan 0001 00:00:00 +0000

Dapr CLI

可以将其视为 .NET 伴侣指南：使用 Docker 的 Dapr 自托管指南的补充。

Dapr CLI 通过初始化本地的 Redis 容器、Zipkin 容器、placement 服务和 Redis 的组件清单，为您提供了一个良好的基础环境。这使您能够在全新安装且无需额外设置的情况下使用以下功能模块：

您可以使用 dapr run 命令来运行 .NET 服务，作为本地开发的一种策略。为每个服务运行此命令以启动您的应用程序。

优势： 由于这是 Dapr 默认安装的一部分，因此设置简单
劣势： 这会在您的机器上运行长时间的 Docker 容器，可能不太理想
劣势： 这种方法的可扩展性较差，因为需要为每个服务运行一个单独的命令

使用 Dapr CLI

对于每个服务，您需要选择：

用于寻址的唯一应用 ID (app-id)
用于 HTTP 的唯一监听端口 (port)

您还应该决定存储组件的位置 (components-path)。

可以从多个终端运行以下命令以启动每个服务，并替换相应的值。

dapr run --app-id <app-id> --app-port <port> --components-path <components-path> -- dotnet run -p <project> --urls http://localhost:<port>

解释： 此命令使用 dapr run 启动每个服务及其附属进程。命令的前半部分（在 -- 之前）将所需的配置传递给 Dapr CLI。命令的后半部分（在 -- 之后）将所需的配置传递给 dotnet run 命令。

使用 Dapr Workflow Python SDK 入门

Mon, 01 Jan 0001 00:00:00 +0000

注意

Dapr Workflow 目前处于 alpha 阶段。

我们来创建一个 Dapr 工作流，并通过控制台调用它。通过提供的 hello world 工作流示例，您将会：

运行一个使用 DaprClient 的 Python 控制台应用程序
利用 Python 工作流 SDK 和 API 调用来启动、暂停、恢复、终止和清除工作流实例

此示例使用 dapr init 的默认配置在本地模式下运行。

在 Python 示例项目中，app.py 文件包含应用程序的设置，其中包括：

工作流定义
工作流活动定义
工作流和工作流活动的注册

先决条件

已安装 Dapr CLI
已初始化 Dapr 环境
已安装 Python 3.8+
已安装 Dapr Python 包和工作流扩展
确保您使用的是最新的 proto 绑定（proto 绑定是用于定义服务接口的协议缓冲区文件）

设置环境

运行以下命令以安装使用 Dapr Python SDK 运行此工作流示例的必要依赖。

pip3 install -r demo_workflow/requirements.txt

克隆 [Python SDK 仓库]。

git clone https://github.com/dapr/python-sdk.git

从 Python SDK 根目录导航到 Dapr 工作流示例。

使用开发容器开发Dapr应用

Mon, 01 Jan 0001 00:00:00 +0000

Visual Studio Code 的开发容器扩展允许您使用一个自包含的 Docker 容器作为完整的开发环境，而无需在本地文件系统中安装任何额外的软件包、库或工具。

Dapr 提供了预构建的 C# 和 JavaScript/TypeScript 开发容器，您可以选择其中一个来快速搭建开发环境。请注意，这些预构建的容器会自动更新到 Dapr 的最新版本。

我们还发布了一个开发容器功能，可以在任何开发容器中安装 Dapr CLI。

设置开发环境

先决条件

使用开发容器功能添加 Dapr CLI

您可以使用开发容器功能在任何开发容器中安装 Dapr CLI。

为此，请编辑您的 devcontainer.json 文件，并在 "features" 部分添加以下两个对象：

"features": {
 // 安装 Dapr CLI
 "ghcr.io/dapr/cli/dapr-cli:0": {},
 // 启用 Docker（通过 Docker-in-Docker）
 "ghcr.io/devcontainers/features/docker-in-docker:2": {},
 // 或者，使用 Docker-outside-of-Docker（使用主机中的 Docker）
 //"ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},
}

保存 JSON 文件并重新构建托管您开发环境的容器后，您将拥有 Dapr CLI（和 Docker），并可以通过在容器中运行以下命令来安装 Dapr：

dapr init

示例：为 Dapr 创建 Java 开发容器

以下是一个用于开发 Dapr Java 应用的开发容器示例，基于官方 Java 17 开发容器镜像。

操作指南：在离线或隔离环境中运行Dapr

Mon, 01 Jan 0001 00:00:00 +0000

概述

通常情况下，Dapr初始化时会从网络下载二进制文件并拉取镜像来设置开发环境。然而，Dapr也支持使用预先下载的安装包进行离线或隔离安装，这可以通过Docker或精简模式来实现。每个Dapr版本的安装包都被构建成一个Dapr安装包，可以下载。通过使用这个安装包和Dapr CLI的init命令，你可以在没有网络访问的环境中安装Dapr。

设置

在进行隔离初始化之前，需要预先下载一个Dapr安装包，其中包含CLI、运行时和仪表板的内容。这避免了在本地初始化Dapr时需要下载二进制文件和Docker镜像。

下载特定版本的Dapr安装包。例如，daprbundle_linux_amd64.tar.gz，daprbundle_windows_amd64.zip。
解压缩安装包。
要安装Dapr CLI，将daprbundle/dapr (Windows为dapr.exe)二进制文件复制到合适的位置：
- 对于Linux/MacOS - /usr/local/bin
- 对于Windows，创建一个目录并将其添加到系统PATH。例如，创建一个名为c:\dapr的目录，并通过编辑系统环境变量将此目录添加到路径中。
注意：如果Dapr CLI没有移动到合适的位置，你可以直接使用包中的本地dapr CLI二进制文件。上述步骤是为了将其移动到常用位置并添加到路径中。

初始化Dapr环境

Dapr可以在有或没有Docker容器的隔离环境中初始化。

使用Docker初始化Dapr

（前提条件：环境中可用Docker）

进入安装包目录并运行以下命令：

dapr init --from-dir .

对于Linux用户，如果你使用sudo运行Docker命令，你需要使用“sudo dapr init”

如果你不是在安装包目录下运行上述命令，请提供安装包目录的完整路径。例如，假设安装包目录路径是$HOME/daprbundle，运行dapr init --from-dir $HOME/daprbundle以获得相同的效果。

输出应类似于以下内容：

 正在进行超空间跳跃...
ℹ️ 正在安装最新的运行时版本
↘ 正在提取二进制文件并设置组件... 已加载镜像：daprio/dapr:$version
✅ 提取二进制文件并设置组件完成。
✅ 二进制文件提取和组件设置已完成。
ℹ️ daprd二进制文件已安装到$HOME/.dapr/bin。
ℹ️ dapr_placement容器正在运行。
ℹ️ 使用`docker ps`检查正在运行的容器。
✅ 成功！Dapr已启动并运行。要开始使用，请访问：https://aka.ms/dapr-getting-started

注意：要模拟在线 Dapr初始化，使用dapr init，你也可以运行Redis和Zipkin容器，如下所示：

1. docker run --name "dapr_zipkin" --restart always -d -p 9411:9411 openzipkin/zipkin
2. docker run --name "dapr_redis" --restart always -d -p 6379:6379 redislabs/rejson

不使用Docker初始化Dapr

或者，为了让CLI不安装任何默认配置文件或运行任何Docker容器，可以使用init命令的--slim标志。这样只会安装Dapr的二进制文件。

如何创建新的 Microsoft Entra ID 应用程序和服务主体

Mon, 01 Jan 0001 00:00:00 +0000

先决条件

一个 Azure 订阅
Azure CLI
jq
OpenSSL（默认包含在所有 Linux 和 macOS 系统中，以及 WSL 中）
确保您使用的是 bash 或 zsh shell

使用 Azure CLI 登录 Azure

在新终端中，运行以下命令：

az login
az account set -s [your subscription id]

创建 Microsoft Entra ID 应用程序

使用以下命令创建 Microsoft Entra ID 应用程序：

# 应用程序 / 服务主体的友好名称
APP_NAME="dapr-application"

# 创建应用程序
APP_ID=$(az ad app create --display-name "${APP_NAME}" | jq -r .appId)

选择传递凭据的方式。

要创建一个客户端密钥，运行以下命令。

在 Kubernetes 集群上升级 Dapr

Mon, 01 Jan 0001 00:00:00 +0000

您可以通过 Dapr CLI 或 Helm 来升级 Kubernetes 集群上的 Dapr 控制平面。

注意

请参阅 Dapr 版本政策以获取 Dapr 升级路径的指导。

使用 Dapr CLI 升级

您可以使用 Dapr CLI 来升级 Dapr。

前提条件

安装 Dapr CLI
一个现有的运行 Dapr 的 Kubernetes 集群

将现有集群升级到 1.16.9

dapr upgrade -k --runtime-version=1.16.9

您可以使用 Dapr CLI 提供所有可用的 Helm chart 配置。

如何在没有 Docker 的环境中以自托管模式运行 Dapr

Mon, 01 Jan 0001 00:00:00 +0000

前提条件

安装 Dapr CLI

初始化无容器的 Dapr

Dapr CLI 提供了一个选项，可以使用 slim init 初始化 Dapr，而无需依赖 Docker 来创建默认的开发环境。安装 Dapr CLI 后，使用以下命令进行 slim init 初始化：

dapr init --slim

这将安装两个不同的二进制文件：

daprd
placement

placement 二进制文件用于在 Dapr 自托管安装中启用 actor。

在 slim init 模式下，不会安装用于状态管理或消息发布/订阅的默认组件（如 Redis）。这意味着，除了服务调用外，安装时没有其他内置功能可用。您可以根据需要设置自己的环境和自定义组件。

如果配置了状态存储，则可以进行基于 actor 的服务调用，具体说明请参见以下章节。

执行服务调用

请参阅 Hello Dapr slim 示例，了解如何在 slim init 模式下执行服务调用。

启用状态管理或消息发布/订阅

请参阅在无 Docker 的自托管模式下配置 Redis 的文档，以启用本地状态存储或用于消息传递的发布/订阅代理。

启用 actor

要启用 actor placement：

在本地运行 placement 服务。
启用支持 ETags 的事务性状态存储以使用 actor。例如，在自托管模式下配置的 Redis。

默认情况下，placement 二进制文件安装在：

使用 .NET Aspire 进行 Dapr .NET SDK 开发

Mon, 01 Jan 0001 00:00:00 +0000

.NET Aspire

.NET Aspire 是一款开发工具，旨在通过提供一个框架，简化外部软件与 .NET 应用程序的集成过程。该框架允许第三方服务轻松地与您的软件集成、监控和配置。

Aspire 通过与流行的 IDE（包括 Microsoft Visual Studio、Visual Studio Code、JetBrains Rider 等）深度集成，简化了本地开发。在启动调试器的同时，自动启动并配置对其他集成（包括 Dapr）的访问。

虽然 Aspire 也支持将应用程序部署到各种云平台（如 Microsoft Azure 和 Amazon AWS），但本指南不涉及部署相关内容。更多信息请参阅 Aspire 的文档这里。

先决条件

Dapr .NET SDK 兼容 .NET 6、.NET 8 和 .NET 9，但 .NET Aspire 仅支持 .NET 8 和 .NET 9。
一个符合 OCI 标准的容器运行时，例如 Docker Desktop 或 Podman
安装并初始化 Dapr v1.13 或更高版本

通过 CLI 使用 .NET Aspire

我们将从创建一个全新的 .NET 应用程序开始。打开您喜欢的 CLI 并导航到您希望创建新 .NET 解决方案的目录。首先使用以下命令安装一个模板，该模板将创建一个空的 Aspire 应用程序：

dotnet new install Aspire.ProjectTemplates

安装完成后，继续在当前目录中创建一个空的 .NET Aspire 应用程序。-n 参数允许您指定输出解决方案的名称。如果省略，.NET CLI 将使用输出目录的名称，例如 C:\source\aspiredemo 将导致解决方案被命名为 aspiredemo。本教程的其余部分将假设解决方案名为 aspiredemo。

如何使用托管身份

Mon, 01 Jan 0001 00:00:00 +0000

托管身份可以自动进行身份验证，因为您的应用程序运行在具有系统分配或用户分配身份的 Azure 服务上。

要开始使用，您需要在各种 Azure 服务中启用托管身份作为服务选项/功能，这与 Dapr 无关。启用后，会在后台为 Microsoft Entra ID（以前称为 Azure Active Directory ID）创建一个身份（或应用程序）。

然后，您的 Dapr 服务可以利用该身份与 Microsoft Entra ID 进行认证，过程是透明的，您无需指定任何凭据。

在本指南中，您将学习如何：

通过官方 Azure 文档将您的身份授予您正在使用的 Azure 服务
在您的组件中设置系统管理或用户分配身份

以上是全部内容。

注意

在您的组件 YAML 中，如果使用用户分配身份，您只需要 azureClientId 属性。否则，您可以省略此属性，默认使用系统管理身份。

授予服务访问权限

为特定 Azure 资源（由资源范围标识）设置必要的 Microsoft Entra ID 角色分配或自定义权限给您的系统管理或用户分配身份。

您可以为新的或现有的 Azure 资源设置托管身份。说明取决于所使用的服务。请查看以下官方文档以获取最合适的说明：

Azure Kubernetes Service (AKS)
Azure Container Apps (ACA)
Azure App Service（包括 Azure Web Apps 和 Azure Functions）
Azure Virtual Machines (VM)
Azure Virtual Machines Scale Sets (VMSS)
Azure Container Instance (ACI)

在为您的 Azure 资源分配系统管理身份后，您将获得如下信息：

Kubernetes 生产指南

Mon, 01 Jan 0001 00:00:00 +0000

集群和容量要求

Dapr 对 Kubernetes 的支持遵循 Kubernetes 版本偏差政策。

以下资源配置可作为起始参考。具体要求会因集群规模、pod 数量及其他因素而有所不同。请根据您的环境进行测试以确定合适的配置值。在生产环境中，建议不要为 Dapr 控制平面组件设置内存限制，以避免出现 OOMKilled pod 状态。

部署	CPU	内存
Operator	限制: 1, 请求: 100m	请求: 100Mi
Sidecar Injector	限制: 1, 请求: 100m	请求: 30Mi
Sentry	限制: 1, 请求: 100m	请求: 30Mi
Placement	限制: 1, 请求: 250m	请求: 75Mi

注意

有关更多信息，请参阅 Kubernetes 文档中的 CPU 和内存资源单位及其含义。

Helm

使用 Helm 安装 Dapr 时，默认未设置限制/请求值。每个组件都有一个 resources 选项（例如，dapr_dashboard.resources），您可以根据需要调整 Dapr 控制平面的资源配置。

Helm chart 说明提供了详细信息和示例。

对于本地/开发安装，您可以选择不配置 resources 选项。

可选组件

以下 Dapr 控制平面部署是可选的：

使用 Dapr Shared 部署 Dapr 到每个节点或每个集群

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 会自动为您的应用程序注入一个 sidecar，以启用 Dapr API，从而实现最佳的可用性和可靠性。

Dapr Shared 提供了两种替代的部署策略：通过 Kubernetes 的 DaemonSet 实现每节点部署，或通过 Deployment 实现每集群部署。

DaemonSet: 当以 Kubernetes 的 DaemonSet 资源运行 Dapr Shared 时，daprd 容器会在集群中的每个 Kubernetes 节点上运行。这可以减少应用程序与 Dapr 之间的网络延迟。
Deployment: 当以 Kubernetes 的 Deployment 运行 Dapr Shared 时，Kubernetes 调度器会决定 daprd 容器实例在集群中的哪个节点上运行。

Dapr Shared 部署

对于您部署的每个 Dapr 应用程序，您需要使用不同的 shared.appId 来部署 Dapr Shared Helm chart。

为什么选择 Dapr Shared？

默认情况下，当 Dapr 安装到 Kubernetes 集群中时，Dapr 控制平面会将 Dapr 作为 sidecar 注入到带有 Dapr 注释（dapr.io/enabled: "true"）的应用程序中。sidecar 提供了许多优势，包括提高弹性，因为每个应用程序都有一个实例，并且应用程序与 sidecar 之间的所有通信都无需经过网络。

使用 Project Tye 进行 Dapr .NET SDK 开发

Mon, 01 Jan 0001 00:00:00 +0000

Project Tye

.NET Project Tye 是一个专为简化运行多个 .NET 服务而设计的微服务开发工具。Tye 允许您将多个 .NET 服务、进程和容器镜像的配置整合为一个可运行的应用程序。

对于 .NET Dapr 开发者来说，Tye 的优势在于：

Tye 可以自动化使用 dapr CLI
Tye 遵循 .NET 的约定，对 .NET 服务几乎无需额外配置
Tye 能够管理容器中依赖项的生命周期

优缺点：

优点： Tye 可以自动化上述所有步骤。您无需再担心端口或应用程序 ID 等细节。
优点： 由于 Tye 也可以管理容器，您可以将这些容器作为应用程序的一部分定义，并避免机器上长时间运行的容器。

使用 Tye

按照 Tye 入门指南安装 tye CLI，并为您的应用程序创建 tye.yaml 文件。

接下来，按照 Tye Dapr 配方中的步骤添加 Dapr。确保在 tye.yaml 中使用 components-path 指定组件文件夹的相对路径。

然后，添加任何额外的容器依赖项，并将组件定义添加到您之前创建的文件夹中。

您应该得到如下内容：

name: store-application
extensions:

 # Dapr 的配置在这里。
- name: dapr
 components-path: <components-path> 

# 要运行的服务在这里。
services:
 
 # 名称将用作应用程序 ID。对于 .NET 项目，Tye 只需要项目文件的路径。
- name: orders
 project: orders/orders.csproj
- name: products
 project: products/products.csproj
- name: store
 project: store/store.csproj

 # 您想要运行的容器需要一个镜像名称和一组要暴露的端口。
- name: redis
 image: redis
 bindings:
 - port: 6973

将 tye.yaml 和应用程序代码一起提交到源代码管理中。

操作指南：持久化调度器任务

Mon, 01 Jan 0001 00:00:00 +0000

调度器服务负责将任务写入其嵌入的Etcd数据库并调度执行。默认情况下，调度器服务数据库会将数据写入大小为1Gb的持久卷声明（Persistent Volume Claim），使用集群的默认存储类。这意味着在大多数Kubernetes部署中运行调度器服务不需要额外参数，但如果没有默认的StorageClass或在生产环境中运行时，您将需要进行额外的配置。

警告

调度器的默认存储大小为1Gi，这对于大多数生产部署来说可能不够。请注意，当启用SchedulerReminders预览功能时，调度器会用于actor提醒、工作流以及任务API。您可能需要考虑重新安装Dapr，并将调度器存储增加到至少16Gi或更多。有关更多信息，请参见下面的ETCD存储磁盘大小部分。

生产环境设置

ETCD存储磁盘大小

调度器的默认存储大小为1Gb。这个大小对于大多数生产部署来说可能不够。当存储大小超出时，调度器将记录类似以下的错误：

error running scheduler: etcdserver: mvcc: database space exceeded

确定存储大小的安全上限并不是一门精确的科学，主要取决于应用程序任务的数量、持久性和数据负载大小。任务API和actor提醒（启用SchedulerReminders预览功能时）会根据应用程序的使用情况进行映射。工作流（启用SchedulerReminders预览功能时）会创建大量的任务作为actor提醒，但这些任务是短暂的，与每个工作流执行的生命周期相匹配。工作流创建的任务的数据负载通常为空或很小。

调度器使用Etcd作为其存储后端数据库。根据设计，Etcd以预写日志（WAL）和快照的形式持久化历史事务和数据。这意味着调度器的实际磁盘使用量将高于当前可观察的数据库状态，通常是多个倍数。

在安装时设置存储大小

如果您需要增加现有调度器的存储大小，请参见下面的增加现有调度器存储大小部分。要增加新Dapr安装的存储大小（在此示例中为16Gi），您可以使用以下命令：

dapr init -k --set dapr_scheduler.cluster.storageSize=16Gi --set dapr_scheduler.etcdSpaceQuota=16Gi

helm upgrade --install dapr dapr/dapr \
--version=1.16 \
--namespace dapr-system \
--create-namespace \
--set dapr_scheduler.cluster.storageSize=16Gi \
--set dapr_scheduler.etcdSpaceQuota=16Gi \
--wait

增加现有调度器存储大小

警告

并非所有存储提供商都支持动态卷扩展。请参阅您的存储提供商文档以确定是否支持此功能，以及如果不支持该怎么办。

默认情况下，每个调度器会为每个副本创建一个大小为1Gi的持久卷和持久卷声明，使用默认的standard存储类。这些将类似于以下内容，在此示例中我们以HA模式运行调度器。

操作指南：持久化调度器作业

Mon, 01 Jan 0001 00:00:00 +0000

调度器服务负责将作业写入嵌入式数据库并进行调度执行。默认情况下，调度器服务会将数据写入本地卷dapr_scheduler，这意味着数据在重启时会被持久化。

此本地卷的主机文件位置通常位于/var/lib/docker/volumes/dapr_scheduler/_data或~/.local/share/containers/storage/volumes/dapr_scheduler/_data，具体取决于您的容器运行时。请注意，如果您使用的是Docker Desktop，此卷位于Docker Desktop虚拟机的文件系统中，可以通过以下命令访问：

docker run -it --privileged --pid=host debian nsenter -t 1 -m -u -n -i sh

调度器的持久卷可以通过使用预先存在的自定义卷进行修改，或者由Dapr自动创建。

注意

默认情况下，dapr init会在您的驱动器上创建一个名为dapr_scheduler的本地持久卷。如果Dapr已经安装，您需要完全卸载控制平面，然后才能使用新的持久卷重新创建调度器容器。

dapr init --scheduler-volume my-scheduler-volume

在自托管环境中升级 Dapr 的步骤

Mon, 01 Jan 0001 00:00:00 +0000

卸载当前的 Dapr 部署：

注意
这将删除默认的 $HOME/.dapr 目录、二进制文件和所有容器（dapr_redis、dapr_placement 和 dapr_zipkin）。如果在 Linux 上运行 docker 命令需要使用 sudo，请使用 sudo。
```
dapr uninstall --all
```
访问本指南以下载并安装最新版本的 CLI。
初始化 Dapr 运行时：
```
dapr init
```

确认您正在使用最新版本的 Dapr (v1.16.9)：

$ dapr --version

CLI version: 1.16
Runtime version: 1.16

Dapr AI 客户端

Mon, 01 Jan 0001 00:00:00 +0000

Dapr AI 客户端包使您能够与 Dapr sidecar 提供的 AI 功能进行交互。

生命周期的管理

DaprConversationClient 是专门用于与 Dapr conversation API 交互的客户端版本。它可以与 DaprClient 和其他 Dapr 客户端一起注册而不会出现问题。

它通过 TCP 套接字与 Dapr sidecar 通信，以便访问网络资源。

为了获得最佳性能，建议创建一个长期存在的 DaprConversationClient 实例，并在整个应用程序中共享使用。DaprConversationClient 实例是线程安全的，适合共享。

这可以通过依赖注入来实现。注册方法支持以单例、作用域实例或瞬态（每次注入时重新创建）的方式进行注册，但也可以利用 IConfiguration 或其他注入服务中的值进行注册，这在每个类中从头创建客户端时是不切实际的。

避免为每个操作都创建一个新的 DaprConversationClient。

通过 DaprConversationClientBuilder 配置 DaprConversationClient

可以通过在 DaprConversationClientBuilder 类上调用方法来配置 DaprConversationClient，然后调用 .Build() 来创建客户端。每个 DaprConversationClient 的设置是独立的，并且在调用 .Build() 后无法更改。

var daprConversationClient = new DaprConversationClientBuilder()
 .UseDaprApiToken("abc123") // 指定用于验证到其他 Dapr sidecar 的 API 令牌
 .Build();

DaprConversationClientBuilder 包含以下设置：

Dapr sidecar 的 HTTP 端点
Dapr sidecar 的 gRPC 端点
用于配置 JSON 序列化的 JsonSerializerOptions 对象
用于配置 gRPC 的 GrpcChannelOptions 对象
用于验证请求到 sidecar 的 API 令牌
用于创建 SDK 使用的 HttpClient 实例的工厂方法
用于在向 sidecar 发出请求时使用的 HttpClient 实例的超时

SDK 将读取以下环境变量来配置默认值：

如何：在 .NET SDK 中编写和管理 Dapr 任务

Mon, 01 Jan 0001 00:00:00 +0000

我们来创建一个端点，该端点将在 Dapr 任务触发时被调用，然后在同一个应用中调度该任务。我们将使用此处提供的简单示例，进行以下演示，并通过它来解释如何使用间隔或 Cron 表达式自行调度一次性或重复性任务。在本指南中，您将：

部署一个 .NET Web API 应用程序 (JobsSample)
利用 Dapr .NET 任务 SDK 调度任务调用并设置被触发的端点

在 .NET 示例项目中：

主要的 Program.cs 文件是整个演示的核心。

前提条件

Dapr CLI
初始化的 Dapr 环境
已安装 .NET 6、.NET 8 或 .NET 9
项目中已安装 Dapr.Jobs NuGet 包

注意

请注意，虽然 .NET 6 是 Dapr v1.15 中支持的最低版本，但从 v1.16 开始，Dapr 仅支持 .NET 8 和 .NET 9。

设置环境

克隆 .NET SDK 仓库。

git clone https://github.com/dapr/dotnet-sdk.git

从 .NET SDK 根目录，导航到 Dapr 任务示例。

cd examples/Jobs

本地运行应用程序

要运行 Dapr 应用程序，您需要启动 .NET 程序和一个 Dapr sidecar。导航到 JobsSample 目录。

DaprJobsClient 使用指南

Mon, 01 Jan 0001 00:00:00 +0000

生命周期管理

DaprJobsClient 是专门用于与 Dapr Jobs API 交互的 Dapr 客户端。它可以与 DaprClient 和其他 Dapr 客户端一起注册而不会出现问题。

它通过 TCP 套接字与 Dapr sidecar 通信，并实现了 IDisposable 接口以便快速清理资源。

为了获得最佳性能，建议创建一个长生命周期的 DaprJobsClient 实例，并在整个应用程序中共享使用。DaprJobsClient 实例是线程安全的，适合在多个线程中共享。

可以通过依赖注入来实现这一点。注册方法支持以单例、作用域实例或瞬态方式注册，但也可以利用 IConfiguration 或其他注入服务中的值进行注册，这样就不需要在每个类中重新创建客户端。

避免为每个操作创建一个新的 DaprJobsClient 并在操作完成后销毁它。

通过 DaprJobsClientBuilder 配置 DaprJobsClient

可以通过 DaprJobsClientBuilder 类上的方法来配置 DaprJobsClient，然后调用 .Build() 来创建客户端。每个 DaprJobsClient 的设置是独立的，调用 .Build() 后无法更改。

var daprJobsClient = new DaprJobsClientBuilder()
 .UseDaprApiToken("abc123") // 指定用于验证到其他 Dapr sidecar 的 API 令牌
 .Build();

DaprJobsClientBuilder 包含以下设置：

Dapr sidecar 的 HTTP 端点
Dapr sidecar 的 gRPC 端点
用于配置 JSON 序列化的 JsonSerializerOptions 对象
用于配置 gRPC 的 GrpcChannelOptions 对象
用于验证请求到 sidecar 的 API 令牌
用于创建 SDK 使用的 HttpClient 实例的工厂方法
用于在向 sidecar 发出请求时使用的 HttpClient 实例的超时

SDK 将读取以下环境变量来配置默认值：

Dapr .NET SDK 中更全面的错误模型

Mon, 01 Jan 0001 00:00:00 +0000

Dapr .NET SDK 支持由 Dapr 运行时实现的更全面的错误模型。这个模型为应用程序提供了一种丰富错误信息的方式，提供更多上下文信息，使应用程序的用户能够更好地理解问题并更快地解决。您可以在这里阅读更多关于更全面错误模型的信息，并可以在这里找到实现这些错误的 Dapr proto 文件。

Dapr .NET SDK 实现了 Dapr 运行时支持的所有细节，这些细节在 Dapr.Common.Exceptions 命名空间中实现，并可以通过 DaprException 的扩展方法 TryGetExtendedErrorInfo 进行访问。目前，此细节提取仅支持存在细节的 RpcException。

// 扩展错误信息的示例用法

try
{
 // 使用 Dapr 客户端执行某些操作，该操作抛出 DaprException。
}
catch (DaprException daprEx)
{
 if (daprEx.TryGetExtendedErrorInfo(out DaprExtendedErrorInfo errorInfo))
 {
 Console.WriteLine(errorInfo.Code);
 Console.WriteLine(errorInfo.Message);

 foreach (DaprExtendedErrorDetail detail in errorInfo.Details)
 {
 Console.WriteLine(detail.ErrorType);
 switch (detail.ErrorType)
 {
 case ExtendedErrorType.ErrorInfo:
 Console.WriteLine(detail.Reason);
 Console.WriteLine(detail.Domain);
 break;
 default:
 Console.WriteLine(detail.TypeUrl);
 break;
 }
 }
 }
}

DaprExtendedErrorInfo

包含与错误相关的 Code（状态码）和 Message（错误信息），这些信息从内部的 RpcException 解析而来。还包含从异常细节中解析的 DaprExtendedErrorDetails 集合。

DaprExtendedErrorDetail

所有细节都实现了抽象的 DaprExtendedErrorDetail，并具有相关的 DaprExtendedErrorType。

使用 Docker-Compose 进行 Dapr .NET SDK 开发

Mon, 01 Jan 0001 00:00:00 +0000

Docker-Compose

这可以看作是 .NET 伴侣指南：使用 Docker 的 Dapr 自托管指南的补充。

docker-compose 是 Docker Desktop 附带的一个命令行工具，您可以用它同时运行多个容器。它提供了一种自动化管理多个容器生命周期的方法，为面向 Kubernetes 的应用程序提供类似于生产环境的开发体验。

优势在于： docker-compose 帮助您管理容器，您可以将依赖项作为应用程序的一部分进行定义，并停止机器上长时间运行的容器。
劣势在于： 需要较多的前期投入，服务需要先容器化。
劣势在于： 如果您不熟悉 Docker，可能会遇到调试和故障排除的困难。

使用 docker-compose

从 .NET 的角度来看，使用 Dapr 的 docker-compose 并不需要特别的指导。docker-compose 负责运行容器，一旦您的服务在容器中，配置它就和其他编程技术类似。

💡 应用端口

在容器中，ASP.NET Core 应用程序默认监听 80 端口。请记住这一点，以便在配置 --app-port 时使用。

总结这种方法：

为每个服务创建一个 Dockerfile
创建一个 docker-compose.yaml 并将其提交到源代码库

要了解如何编写 docker-compose.yaml，您可以从 Hello, docker-compose 示例开始。

类似于使用 dapr run 本地运行，对于每个服务，您需要选择一个唯一的 app-id。选择容器名称作为 app-id 可以帮助您更容易记住。

compose 文件至少应包含以下内容：

容器之间通信所需的网络
每个服务的容器
一个 <service>-daprd sidecar 容器，指定服务的端口和 app-id
在容器中运行的其他依赖项（例如 redis）
可选：Dapr placement 容器（用于 actor）

您还可以查看 eShopOnContainers 示例应用程序中的更大示例。

在自托管环境中卸载 Dapr

Mon, 01 Jan 0001 00:00:00 +0000

以下 CLI 命令用于移除 Dapr sidecar 二进制文件和 placement 容器：

dapr uninstall

上述命令不会移除在 dapr init 时默认安装的 Redis 或 Zipkin 容器，以防您将它们用于其他用途。要移除 Redis、Zipkin、actor placement 容器，以及位于 $HOME/.dapr 或 %USERPROFILE%\.dapr\ 的默认 Dapr 目录，请运行以下命令：

dapr uninstall --all

注意

对于 Linux/MacOS 用户，如果您使用 sudo 运行 docker 命令，或者 Dapr 安装在 /usr/local/bin（默认安装路径），则需要使用 sudo dapr uninstall 来移除 Dapr 二进制文件和/或容器。

如何：在 .NET SDK 中编写和管理 Dapr 流式订阅

Mon, 01 Jan 0001 00:00:00 +0000

我们来创建一个使用流式功能的发布/订阅主题或队列的订阅。我们将使用此处提供的简单示例，进行演示，并逐步讲解如何在运行时配置消息处理程序，而无需预先配置端点。在本指南中，您将会学习如何：

部署一个 .NET Web API 应用程序 (StreamingSubscriptionExample)
使用 Dapr .NET Messaging SDK 动态订阅发布/订阅主题。

前提条件

Dapr CLI
已初始化的 Dapr 环境
安装 .NET 6、.NET 8 或 .NET 9
项目中安装 Dapr.Messaging NuGet 包

注意

请注意，虽然 .NET 6 是 Dapr v1.15 中支持的最低版本，但只有 .NET 8 和 .NET 9 将在 v1.16 及更高版本中继续受到支持。

设置环境

克隆 .NET SDK 仓库。

git clone https://github.com/dapr/dotnet-sdk.git

从 .NET SDK 根目录，导航到 Dapr 流式发布/订阅示例。

cd examples/Client/PublishSubscribe

本地运行应用程序

要运行 Dapr 应用程序，您需要启动 .NET 程序和一个 Dapr sidecar。导航到 StreamingSubscriptionExample 目录。

cd StreamingSubscriptionExample

我们将运行一个命令，同时启动 Dapr sidecar 和 .NET 程序。

DaprPublishSubscribeClient 使用指南

Mon, 01 Jan 0001 00:00:00 +0000

生命周期管理

DaprPublishSubscribeClient 是 Dapr 客户端的一个版本，专门用于与 Dapr 消息 API 交互。它可以与 DaprClient 和其他 Dapr 客户端一起注册而不会出现问题。

它通过 TCP 套接字与 Dapr sidecar 通信，维护对网络资源的访问，并实现了 IAsyncDisposable 接口以支持资源的快速清理。

为了获得最佳性能，建议创建一个长生命周期的 DaprPublishSubscribeClient 实例，并在整个应用程序中共享使用。DaprPublishSubscribeClient 实例是线程安全的，适合共享使用。

可以通过依赖注入来实现这一点。注册方法支持以单例、作用域实例或瞬态（每次注入时重新创建）的方式进行注册，但也可以通过 IConfiguration 或其他注入服务的值来注册，这在每个类中从头创建客户端时是不切实际的。

避免为每个操作创建一个 DaprPublishSubscribeClient 并在操作完成后销毁它。DaprPublishSubscribeClient 应仅在您不再希望接收订阅事件时才被销毁，因为销毁它将取消正在进行的新事件接收。

通过 DaprPublishSubscribeClientBuilder 配置 DaprPublishSubscribeClient

可以通过在 DaprPublishSubscribeClientBuilder 类上调用方法来配置 DaprPublishSubscribeClient，然后调用 .Build() 来创建客户端本身。每个 DaprPublishSubscribeClient 的设置是独立的，并且在调用 .Build() 之后无法更改。

var daprPubsubClient = new DaprPublishSubscribeClientBuilder()
 .UseDaprApiToken("abc123") // 指定用于认证到其他 Dapr sidecar 的 API 令牌
 .Build();

DaprPublishSubscribeClientBuilder 包含以下设置：

Dapr sidecar 的 HTTP 端点
Dapr sidecar 的 gRPC 端点
用于配置 JSON 序列化的 JsonSerializerOptions 对象
用于配置 gRPC 的 GrpcChannelOptions 对象
用于认证请求到 sidecar 的 API 令牌
用于创建 SDK 使用的 HttpClient 实例的工厂方法
用于在向 sidecar 发出请求时使用的 HttpClient 实例的超时

SDK 将读取以下环境变量来配置默认值：

部署到混合 Linux/Windows Kubernetes 集群

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 支持在以下类型的 Kubernetes 集群上运行您的微服务：

Windows
Linux
两者的组合

这在分阶段将遗留应用程序迁移到 Dapr Kubernetes 集群时特别有用。

Kubernetes 使用 节点亲和性 的概念来指定您的应用程序应在 Linux 节点还是 Windows 节点上启动。当部署到同时具有 Windows 和 Linux 节点的集群时，您必须为应用程序设置亲和性规则，否则 Kubernetes 调度器可能会将您的应用程序启动在错误类型的节点上。

先决条件

在开始之前，设置一个具有 Windows 节点的 Kubernetes 集群。许多 Kubernetes 提供商支持自动配置启用 Windows 的 Kubernetes 集群。

按照您首选提供商的说明设置启用 Windows 的集群。

设置集群后，验证 Windows 和 Linux 节点是否可用。

kubectl get nodes -o wide

NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
aks-nodepool1-11819434-vmss000000 Ready agent 6d v1.17.9 10.240.0.4 <none> Ubuntu 16.04.6 LTS 4.15.0-1092-azure docker://3.0.10+azure
aks-nodepool1-11819434-vmss000001 Ready agent 6d v1.17.9 10.240.0.35 <none> Ubuntu 16.04.6 LTS 4.15.0-1092-azure docker://3.0.10+azure
aks-nodepool1-11819434-vmss000002 Ready agent 5d10h v1.17.9 10.240.0.129 <none> Ubuntu 16.04.6 LTS 4.15.0-1092-azure docker://3.0.10+azure
akswin000000 Ready agent 6d v1.17.9 10.240.0.66 <none> Windows Server 2019 Datacenter 10.0.17763.1339 docker://19.3.5
akswin000001 Ready agent 6d v1.17.9 10.240.0.97 <none> Windows Server 2019 Datacenter 10.0.17763.1339 docker://19.3.5

安装 Dapr 控制平面

如果您使用 Dapr CLI 或通过 Helm chart 安装，只需按照正常的部署程序进行：在 Kubernetes 集群上安装 Dapr

在 Kubernetes Job 中运行 Dapr

Mon, 01 Jan 0001 00:00:00 +0000

Dapr sidecar 被设计为一个长期运行的进程。在 Kubernetes Job 的环境中，这种行为可能会阻碍作业的完成。

为了解决这个问题，Dapr sidecar 提供了一个 Shutdown 端点，用于关闭 sidecar。

在运行一个基本的 Kubernetes Job 时，你需要调用 sidecar 的 /shutdown 端点，以便优雅地停止 sidecar，并使作业被视为 Completed。

如果作业在没有调用 Shutdown 的情况下完成，作业会处于 NotReady 状态，而 daprd 容器会一直运行下去。

停止 Dapr sidecar 会导致容器中的就绪性和存活性探测失败。

为了防止 Kubernetes 尝试重启你的作业，请将作业的 restartPolicy 设置为 Never。

在调用 shutdown HTTP API 时，请确保使用 POST HTTP 动词。例如：

apiVersion: batch/v1
kind: Job
metadata:
 name: job-with-shutdown
spec:
 template:
 metadata:
 annotations:
 dapr.io/enabled: "true"
 dapr.io/app-id: "with-shutdown"
 spec:
 containers:
 - name: job
 image: alpine
 command: ["/bin/sh", "-c", "apk --no-cache add curl && sleep 20 && curl -X POST localhost:3500/v1.0/shutdown"]
 restartPolicy: Never

你也可以从任何 Dapr SDK 调用 Shutdown。例如，对于 Go SDK：

操作指南：将 Pod 卷挂载到 Dapr sidecar

Mon, 01 Jan 0001 00:00:00 +0000

Dapr sidecar 可以配置为挂载应用程序 Pod 上的任何 Kubernetes 卷。这些卷可以通过 daprd (sidecar) 容器以只读或读写模式访问。如果配置了一个卷进行挂载但在 Pod 中不存在，Dapr 会记录一个警告并忽略该卷。

有关不同类型卷的更多信息，请查看 Kubernetes 文档。

配置

您可以在部署的 YAML 文件中设置以下注解：

注解	描述
`dapr.io/volume-mounts`	用于只读卷挂载
`dapr.io/volume-mounts-rw`	用于读写卷挂载

这些注解是以逗号分隔的 volume-name:path/in/container 对。请确保相应的卷在 Pod 规范中已定义。

在官方容器镜像中，Dapr 以用户 ID (UID) 65532 运行。请确保挂载卷内的文件夹和文件对用户 65532 可读写。

虽然您可以在 Dapr sidecar 容器内的任何文件夹中挂载卷，但为了避免冲突并确保未来的兼容性，建议将所有挂载点放置在以下位置之一或其子文件夹中：

位置	描述
`/mnt`	推荐用于存储 Dapr sidecar 进程可读写的持久数据的卷。
`/tmp`	推荐用于存储临时数据的卷，例如临时磁盘。

示例

基本部署资源示例

在下面的 Deployment 资源示例中：

my-volume1 在 sidecar 容器内以只读模式挂载到 /mnt/sample1
my-volume2 在 sidecar 容器内以只读模式挂载到 /mnt/sample2
my-volume3 在 sidecar 容器内以读写模式挂载到 /tmp/sample3

apiVersion: apps/v1
kind: Deployment
metadata:
 name: myapp
 namespace: default
 labels:
 app: myapp
spec:
 replicas: 1
 selector:
 matchLabels:
 app: myapp
 template:
 metadata:
 labels:
 app: myapp
 annotations:
 dapr.io/enabled: "true"
 dapr.io/app-id: "myapp"
 dapr.io/app-port: "8000"
 dapr.io/volume-mounts: "my-volume1:/mnt/sample1,my-volume2:/mnt/sample2"
 dapr.io/volume-mounts-rw: "my-volume3:/tmp/sample3"
 spec:
 volumes:
 - name: my-volume1
 hostPath:
 path: /sample
 - name: my-volume2
 persistentVolumeClaim:
 claimName: pv-sample
 - name: my-volume3
 emptyDir: {}
...

使用本地文件 secret 存储自定义 secret 存储

由于任何类型的 Kubernetes 卷都可以附加到 sidecar，您可以使用本地文件 secret 存储从各种地方读取 secret。例如，如果您有一个运行在 10.201.202.203 的网络文件共享 (NFS) 服务器，secret 存储在 /secrets/stage/secrets.json，您可以将其用作 secret 存储。

IActorProxyFactory 接口

Mon, 01 Jan 0001 00:00:00 +0000

在使用 actor 类或 ASP.NET Core 项目时，推荐使用 IActorProxyFactory 接口来创建 actor 客户端。

通过 AddActors(...) 方法，actor 服务将通过 ASP.NET Core 的依赖注入机制进行注册。

在 actor 实例之外： IActorProxyFactory 实例作为单例服务通过依赖注入提供。
在 actor 实例内部： IActorProxyFactory 实例作为属性 (this.ProxyFactory) 提供。

以下是在 actor 内部创建代理的示例：

public Task<MyData> GetDataAsync()
{
 var proxy = this.ProxyFactory.CreateActorProxy<IOtherActor>(ActorId.CreateRandom(), "OtherActor");
 await proxy.DoSomethingGreat();

 return this.StateManager.GetStateAsync<MyData>("my_data");
}

在本指南中，您将学习如何使用 IActorProxyFactory。

提示

对于不使用依赖注入的应用程序，您可以使用 ActorProxy 的静态方法。由于 ActorProxy 方法容易出错，建议在配置自定义设置时尽量避免使用。

确定 actor

IActorProxyFactory 的所有 API 都需要提供 actor 的类型和 id 以便与其通信。对于强类型客户端，您还需要提供其接口之一。

actor 类型 在整个应用程序中唯一标识 actor 实现。
actor id 唯一标识该类型的一个实例。

如果您没有 actor id 并希望与新实例通信，可以使用 ActorId.CreateRandom() 创建一个随机 id。随机 id 是一个加密强标识符，运行时将在您与其交互时创建一个新的 actor 实例。

DaprClient 使用

Mon, 01 Jan 0001 00:00:00 +0000

生命周期管理

DaprClient 使用 TCP 套接字来访问网络资源，与 Dapr sidecar 进行通信。它实现了 IDisposable 接口，以便快速清理资源。

依赖注入

通过 AddDaprClient() 方法可以在 ASP.NET Core 中注册 Dapr 客户端。此方法接受一个可选的配置委托，用于配置 DaprClient，以及一个 ServiceLifetime 参数，允许您为注册的资源指定不同的生命周期，默认是 Singleton。

以下示例展示了如何使用默认值注册 DaprClient：

services.AddDaprClient();

您可以通过配置委托在 DaprClientBuilder 上指定选项来配置 DaprClient，例如：

services.AddDaprClient(daprBuilder => {
 daprBuilder.UseJsonSerializerOptions(new JsonSerializerOptions {
 WriteIndented = true,
 MaxDepth = 8
 });
 daprBuilder.UseTimeout(TimeSpan.FromSeconds(30));
});

另一个重载允许访问 DaprClientBuilder 和 IServiceProvider，以便进行更高级的配置，例如从依赖注入容器中获取服务：

services.AddSingleton<SampleService>();
services.AddDaprClient((serviceProvider, daprBuilder) => {
 var sampleService = serviceProvider.GetRequiredService<SampleService>();
 var timeoutValue = sampleService.TimeoutOptions;
 
 daprBuilder.UseTimeout(timeoutValue);
});

手动实例化

除了依赖注入，您还可以使用静态客户端构建器手动创建 DaprClient。

为了优化性能，建议创建一个长生命周期的 DaprClient 实例，并在整个应用程序中共享。DaprClient 是线程安全的，适合共享使用。

避免为每个操作创建一个新的 DaprClient 实例并在操作完成后释放它。

配置 DaprClient

在调用 .Build() 创建客户端之前，可以通过 DaprClientBuilder 类上的方法来配置 DaprClient。每个 DaprClient 对象的设置是独立的，创建后无法更改。

var daprClient = new DaprClientBuilder()
 .UseJsonSerializerSettings( ... ) // 配置 JSON 序列化器
 .Build();

默认情况下，DaprClientBuilder 会按以下顺序优先获取配置值：

DaprWorkflowClient 使用

Mon, 01 Jan 0001 00:00:00 +0000

生命周期管理

DaprWorkflowClient 可以访问网络资源，这些资源通过 TCP 套接字与 Dapr sidecar 以及其他用于管理和操作工作流的类型进行通信。DaprWorkflowClient 实现了 IAsyncDisposable 接口，以便快速清理资源。

依赖注入

AddDaprWorkflow() 方法用于通过 ASP.NET Core 的依赖注入机制注册 Dapr 工作流服务。此方法需要一个选项委托，用于定义您希望在应用程序中注册和使用的每个工作流和活动。

注意

此方法会尝试注册一个 DaprClient 实例，但仅在尚未以其他生命周期注册的情况下才有效。例如，如果之前以单例生命周期调用了 AddDaprClient()，那么无论为工作流客户端选择何种生命周期，都会始终使用单例。DaprClient 实例用于与 Dapr sidecar 通信，如果尚未注册，则在 AddDaprWorkflow() 注册期间提供的生命周期将用于注册 DaprWorkflowClient 及其依赖项。

单例注册

默认情况下，AddDaprWorkflow 方法会以单例生命周期注册 DaprWorkflowClient 和相关服务。这意味着服务只会被实例化一次。

以下是在典型的 Program.cs 文件中注册 DaprWorkflowClient 的示例：

builder.Services.AddDaprWorkflow(options => {
 options.RegisterWorkflow<YourWorkflow>();
 options.RegisterActivity<YourActivity>();
});

var app = builder.Build();
await app.RunAsync();

作用域注册

虽然默认的单例注册通常适用，但您可能希望指定不同的生命周期。这可以通过在 AddDaprWorkflow 中传递一个 ServiceLifetime 参数来实现。例如，您可能需要将另一个作用域服务注入到 ASP.NET Core 处理管道中，该管道需要 DaprClient 使用的上下文，如果前者服务注册为单例，则无法使用。

以下示例演示了这一点：

builder.Services.AddDaprWorkflow(options => {
 options.RegisterWorkflow<YourWorkflow>();
 options.RegisterActivity<YourActivity>();
}, ServiceLifecycle.Scoped);

var app = builder.Build();
await app.RunAsync();

瞬态注册

最后，Dapr 服务也可以使用瞬态生命周期注册，这意味着每次注入时都会重新初始化。这在以下示例中演示：

开始使用 Dapr Python gRPC 服务扩展

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Python SDK 提供了一个用于创建 Dapr 服务的内置 gRPC 服务器扩展 dapr.ext.grpc。

安装

您可以通过以下命令下载并安装 Dapr gRPC 服务器扩展：

pip install dapr-ext-grpc

注意

开发包包含与 Dapr 运行时预发布版本兼容的功能和行为。在安装 <code>dapr-dev</code> 包之前，请确保卸载任何稳定版本的 Python SDK 扩展。

pip3 install dapr-ext-grpc-dev

示例

您可以使用 App 对象来创建一个服务器。

监听服务调用请求

可以使用 InvokeMethodRequest 和 InvokeMethodResponse 对象来处理传入的请求。

以下是一个简单的服务示例，它会监听并响应请求：

from dapr.ext.grpc import App, InvokeMethodRequest, InvokeMethodResponse

app = App()

@app.method(name='my-method')
def mymethod(request: InvokeMethodRequest) -> InvokeMethodResponse:
 print(request.metadata, flush=True)
 print(request.text(), flush=True)

 return InvokeMethodResponse(b'INVOKE_RECEIVED', "text/plain; charset=UTF-8")

app.run(50051)

完整示例可以在这里找到。

使用 .NET SDK 进行 Pub/Sub 故障排查

Mon, 01 Jan 0001 00:00:00 +0000

Pub/Sub 故障排查

Pub/Sub 的常见问题是应用程序中的 Pub/Sub 端点未被调用。

这个问题可以分为几个层次，每个层次有不同的解决方案：

应用程序没有接收到来自 Dapr 的任何流量
应用程序没有向 Dapr 注册 Pub/Sub 端点
Pub/Sub 端点已在 Dapr 中注册，但请求没有到达预期的端点

步骤 1：提高日志级别

这一点很重要。后续步骤将依赖于您查看日志输出的能力。ASP.NET Core 默认日志设置几乎不记录任何内容，因此您需要更改它。

调整日志详细程度以包括 ASP.NET Core 的 Information 日志，如此处所述。将 Microsoft 键设置为 Information。

步骤 2：验证您可以接收到来自 Dapr 的流量

像往常一样启动应用程序（dapr run ...）。确保在命令行中包含 --app-port 参数。Dapr 需要知道您的应用程序正在监听流量。默认情况下，ASP.NET Core 应用程序将在本地开发中监听 5000 端口的 HTTP。
等待 Dapr 启动完成
检查日志

您应该看到类似这样的日志条目：

info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
 Request starting HTTP/1.1 GET http://localhost:5000/.....

在初始化过程中，Dapr 会向您的应用程序发送一些请求以进行配置。如果找不到这些请求，则意味着出现了问题。请通过问题或 Discord 请求帮助（包括日志）。如果您看到对应用程序的请求，请继续执行下一步。

步骤 3：验证端点注册

像往常一样启动应用程序（dapr run ...）。
使用命令行中的 curl（或其他 HTTP 测试工具）访问 /dapr/subscribe 端点。

如何：在 .NET SDK 中编写和管理 Dapr 工作流

Mon, 01 Jan 0001 00:00:00 +0000

我们来创建一个 Dapr 工作流并通过控制台调用它。在提供的订单处理工作流示例中，控制台会提示如何进行购买和补货。在本指南中，您将：

部署一个 .NET 控制台应用程序 (WorkflowConsoleApp)。
使用 .NET 工作流 SDK 和 API 调用来启动和查询工作流实例。

在 .NET 示例项目里：

主要的 Program.cs 文件包含应用程序的设置，包括工作流和工作流活动的注册。
工作流定义位于 Workflows 目录中。
工作流活动定义位于 Activities 目录中。

先决条件

注意

Dapr.Workflows 在 v1.15 中支持 .NET 7 或更高版本。然而，从 Dapr v1.16 开始，仅支持 .NET 8 和 .NET 9。

设置环境

克隆 .NET SDK 仓库。

git clone https://github.com/dapr/dotnet-sdk.git

从 .NET SDK 根目录，导航到 Dapr 工作流示例。

cd examples/Workflow

本地运行应用程序

要运行 Dapr 应用程序，您需要启动 .NET 程序和一个 Dapr sidecar。导航到 WorkflowConsoleApp 目录。

Dapr Python SDK 与 FastAPI 集成指南

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Python SDK 通过 dapr-ext-fastapi 扩展实现与 FastAPI 的集成。

安装

您可以通过以下命令下载并安装 Dapr FastAPI 扩展：

pip install dapr-ext-fastapi

注意

开发版包含与 Dapr 运行时预发布版本兼容的功能。在安装 <code>dapr-dev</code> 包之前，请先卸载任何稳定版本的 Python SDK 扩展。

pip install dapr-ext-fastapi-dev

示例

订阅不同类型的事件

import uvicorn
from fastapi import Body, FastAPI
from dapr.ext.fastapi import DaprApp
from pydantic import BaseModel

class RawEventModel(BaseModel):
 body: str

class User(BaseModel):
 id: int
 name = 'Jane Doe'

class CloudEventModel(BaseModel):
 data: User
 datacontenttype: str
 id: str
 pubsubname: str
 source: str
 specversion: str
 topic: str
 traceid: str
 traceparent: str
 tracestate: str
 type: str 
 
app = FastAPI()
dapr_app = DaprApp(app)

# 处理任意结构的事件（简单但不够可靠）
# dapr publish --publish-app-id sample --topic any_topic --pubsub pubsub --data '{"id":"7", "desc": "good", "size":"small"}'
@dapr_app.subscribe(pubsub='pubsub', topic='any_topic')
def any_event_handler(event_data = Body()):
 print(event_data) 

# 为了更稳健，根据发布者是否使用 CloudEvents 选择以下之一

# 处理使用 CloudEvents 发送的事件
# dapr publish --publish-app-id sample --topic cloud_topic --pubsub pubsub --data '{"id":"7", "name":"Bob Jones"}'
@dapr_app.subscribe(pubsub='pubsub', topic='cloud_topic')
def cloud_event_handler(event_data: CloudEventModel):
 print(event_data) 

# 处理未使用 CloudEvents 发送的原始事件
# curl -X "POST" http://localhost:3500/v1.0/publish/pubsub/raw_topic?metadata.rawPayload=true -H "Content-Type: application/json" -d '{"body": "345"}'
@dapr_app.subscribe(pubsub='pubsub', topic='raw_topic')
def raw_event_handler(event_data: RawEventModel):
 print(event_data) 

if __name__ == "__main__":
 uvicorn.run(app, host="0.0.0.0", port=30212)

创建一个 actor

from fastapi import FastAPI
from dapr.ext.fastapi import DaprActor
from demo_actor import DemoActor

app = FastAPI(title=f'{DemoActor.__name__}服务')

# 添加 Dapr actor 扩展
actor = DaprActor(app)

@app.on_event("startup")
async def startup_event():
 # 注册 DemoActor
 await actor.register_actor(DemoActor)

@app.get("/GetMyData")
def get_my_data():
 return "{'message': 'myData'}"

编写和运行actor

Mon, 01 Jan 0001 00:00:00 +0000

编写actor

ActorHost

ActorHost：

是所有actor构造函数所需的参数
由运行时提供的
必须传递给基类的构造函数
包含允许该actor实例与运行时通信的所有状态信息

internal class MyActor : Actor, IMyActor, IRemindable
{
 public MyActor(ActorHost host) // 在构造函数中接收ActorHost
 : base(host) // 将ActorHost传递给基类的构造函数
 {
 }
}

由于ActorHost包含actor特有的状态信息，您不需要将其实例传递给代码的其他部分。建议仅在测试中创建您自己的ActorHost实例。

依赖注入

actor支持通过依赖注入将额外的参数传递到构造函数中。您定义的任何其他参数都将从依赖注入容器中获取其值。

internal class MyActor : Actor, IMyActor, IRemindable
{
 public MyActor(ActorHost host, BankService bank) // 在构造函数中接收BankService
 : base(host)
 {
 ...
 }
}

一个actor类型应该只有一个public构造函数。actor系统使用ActivatorUtilities模式来创建actor实例。

您可以在Startup.cs中注册类型以进行依赖注入以使其可用。阅读更多关于注册类型的不同方法。

// 在Startup.cs中
public void ConfigureServices(IServiceCollection services)
{
 ...

 // 使用依赖注入注册额外的类型。
 services.AddSingleton<BankService>();
}

每个actor实例都有其自己的依赖注入范围，并在执行操作后在内存中保留一段时间。在此期间，与actor关联的依赖注入范围也被视为活动状态。该范围将在actor被停用时释放。

如果actor在构造函数中注入IServiceProvider，actor将接收到与其范围关联的IServiceProvider的引用。IServiceProvider可以用于将来动态解析服务。

internal class MyActor : Actor, IMyActor, IRemindable
{
 public MyActor(ActorHost host, IServiceProvider services) // 在构造函数中接收IServiceProvider
 : base(host)
 {
 ...
 }
}

使用此模式时，避免创建许多实现IDisposable的瞬态服务。由于与actor关联的范围可能被视为有效时间较长，您可能会在内存中积累许多服务。有关更多信息，请参阅依赖注入指南。

IDisposable和actor

actor可以实现IDisposable或IAsyncDisposable。建议您依赖依赖注入进行资源管理，而不是在应用程序代码中实现释放功能。仅在确实必要的情况下提供释放支持。

日志记录

在actor类内部，您可以通过基类Actor上的属性访问ILogger实例。此实例连接到ASP.NET Core日志系统，应该用于actor内部的所有日志记录。阅读更多关于日志记录。您可以配置各种不同的日志格式和输出接收器。

使用_结构化日志记录_和_命名占位符_，如下例所示：

public Task<MyData> GetDataAsync()
{
 this.Logger.LogInformation("获取状态时间为 {CurrentTime}", DateTime.UtcNow);
 return this.StateManager.GetStateAsync<MyData>("my_data");
}

记录日志时，避免使用格式字符串，如：$"获取状态时间为 {DateTime.UtcNow}"

日志记录应使用命名占位符语法，这提供了更好的性能和与日志系统的集成。

使用显式actor类型名称

默认情况下，客户端看到的actor的_类型_是从actor实现类的_名称_派生的。默认名称将是类名（不包括命名空间）。

如果需要，您可以通过将ActorAttribute属性附加到actor实现类来指定显式类型名称。

.NET SDK 中的 Actor 序列化

Mon, 01 Jan 0001 00:00:00 +0000

Actor 序列化

Dapr actor 包使您能够在 .NET 应用程序中使用 Dapr 虚拟 actor，您可以选择使用弱类型或强类型客户端。每种方式都有不同的序列化方法。本文档将回顾这些差异，并传达一些在任一场景中需要理解的关键基本规则。

请注意，由于序列化方法的不同，弱类型和强类型 actor 客户端不能交替使用。使用一个 actor 客户端持久化的数据将无法通过另一个 actor 客户端访问，因此在整个应用程序中选择一种并一致使用非常重要。

弱类型 Dapr Actor 客户端

本节将介绍如何配置 C# 类型，以便在使用弱类型 actor 客户端时正确进行序列化和反序列化。这些客户端使用基于字符串的方法名称，并通过 System.Text.Json 序列化器来处理请求和响应负载。请注意，这个序列化框架并不是 Dapr 特有的，而是由 .NET 团队在 .NET GitHub 仓库中单独维护的。

当使用弱类型 Dapr Actor 客户端从各种 actor 调用方法时，不需要独立序列化或反序列化方法负载，因为 SDK 会透明地为您处理这些操作。

客户端将使用您构建的 .NET 版本中可用的最新 System.Text.Json 版本，序列化受相关 .NET 文档中提供的所有固有功能的影响。

序列化器将配置为使用 JsonSerializerOptions.Web 默认选项，除非通过自定义选项配置覆盖，这意味着将应用以下内容：

属性名称的反序列化以不区分大小写的方式进行
属性名称的序列化使用驼峰命名法，除非属性被 [JsonPropertyName] 属性覆盖
反序列化将从数字和/或字符串值读取数值

基本序列化

在以下示例中，我们展示了一个名为 Doodad 的简单类，尽管它也可以是一个记录。

public class Doodad
{
 public Guid Id { get; set; }
 public string Name { get; set; }
 public int Count { get; set; }
}

默认情况下，这将使用类型中成员的名称以及实例化时的值进行序列化：

{"id": "a06ced64-4f42-48ad-84dd-46ae6a7e333d", "name": "DoodadName", "count": 5}

覆盖序列化属性名称

可以通过将 [JsonPropertyName] 属性应用于所需属性来覆盖默认属性名称。

Dapr Python SDK 与 Flask 集成

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Python SDK 使用 flask-dapr 扩展来实现与 Flask 的集成。

安装

您可以通过以下命令下载并安装 Dapr Flask 扩展：

pip install flask-dapr

注意

开发版包含与 Dapr 运行时预发布版本兼容的功能和行为。在安装 <code>dapr-dev</code> 包之前，请确保卸载任何已安装的稳定版 Python SDK 扩展。

pip install flask-dapr-dev

示例

from flask import Flask
from flask_dapr.actor import DaprActor

from dapr.conf import settings
from demo_actor import DemoActor

app = Flask(f'{DemoActor.__name__}Service')

# 启用 DaprActor Flask 扩展
actor = DaprActor(app)

# 注册 DemoActor
actor.register_actor(DemoActor)

# 设置方法路由
@app.route('/GetMyData', methods=['GET'])
def get_my_data():
 return {'message': 'myData'}, 200

# 运行应用程序
if __name__ == '__main__':
 app.run(port=settings.HTTP_APP_PORT)

如何：在 .NET SDK 中运行和使用虚拟 actor

Mon, 01 Jan 0001 00:00:00 +0000

Dapr actor 包使您能够从 .NET 应用程序中与 Dapr 虚拟 actor 交互。在本指南中，您将学习如何：

创建一个 actor (MyActor)。
在客户端应用程序上调用其方法。

MyActor --- MyActor.Interfaces
 |
 +- MyActorService
 |
 +- MyActorClient

接口项目 (\MyActor\MyActor.Interfaces)

此项目包含 actor 的接口定义。actor 接口可以在任何项目中定义，名称不限。接口定义了 actor 实现和调用 actor 的客户端共享的 actor 合约：

actor 实现
调用 actor 的客户端

由于客户端项目可能依赖于它，最好将其定义在与 actor 实现分开的程序集内。

actor 服务项目 (\MyActor\MyActorService)

此项目实现了托管 actor 的 ASP.Net Core Web 服务。它包含 actor 的实现，MyActor.cs。actor 实现是一个类，它：

派生自基础类型 actor
实现 MyActor.Interfaces 项目中定义的接口。

actor 类还必须实现一个构造函数，该构造函数接受一个 ActorService 实例和一个 ActorId，并将它们传递给基础 actor 类。

actor 客户端项目 (\MyActor\MyActorClient)

此项目包含 actor 客户端的实现，该客户端调用在 actor 接口中定义的 MyActor 的方法。

如何在 .NET SDK 中创建和使用 Dapr AI 会话

Mon, 01 Jan 0001 00:00:00 +0000

前提条件

注意事项

.NET 6 是此版本中 Dapr .NET SDK 包的最低支持版本。仅 .NET 8 和 .NET 9 将在 Dapr v1.16 及更高版本中得到支持。

安装

要开始使用 Dapr AI .NET SDK 客户端，请从 NuGet 安装 Dapr.AI 包：

dotnet add package Dapr.AI

DaprConversationClient 通过 TCP 套接字形式维护对网络资源的访问，用于与 Dapr sidecar 通信。

依赖注入

AddDaprAiConversation() 方法将注册 Dapr 客户端到 ASP.NET Core 的依赖注入中，这是使用此包的推荐方法。此方法接受一个可选的选项委托，用于配置 DaprConversationClient，以及一个 ServiceLifetime 参数，允许您为注册的服务指定不同的生命周期，而不是默认的 Singleton 值。

以下示例假设所有默认值均可接受，并足以注册 DaprConversationClient：

services.AddDaprAiConversation();

可选的配置委托用于通过在 DaprConversationClientBuilder 上指定选项来配置 DaprConversationClient，如下例所示：

Mon, 01 Jan 0001 00:00:00 +0000

yaml type: docs title: “AWS Bedrock” linkTitle: “AWS Bedrock” description: AWS Bedrock conversation组件的详细信息

组件格式

一个Dapr conversation.yaml 组件文件的结构如下：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: awsbedrock
spec:
 type: conversation.aws.bedrock
 metadata:
 - name: endpoint
 value: "http://localhost:4566"
 - name: model
 value: amazon.titan-text-express-v1
 - name: cacheTTL
 value: 10m

警告

上述示例中，secret以明文字符串形式使用。建议使用secret存储来保护secret，详情请参阅此处。

规格元数据字段

字段	必需	详情	示例
`endpoint`	N	组件连接到AWS模拟器的端点。不建议在生产环境中使用。	`http://localhost:4566`
`model`	N	使用的语言模型（LLM）。默认为Amazon的Bedrock默认提供商模型。	`amazon.titan-text-express-v1`
`cacheTTL`	N	提示缓存的生存时间（TTL），即缓存过期时间。使用Golang持续时间格式。	`10m`

Actor 工作流后端

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

在 Dapr 中，Actor 工作流后端是默认的后端。如果没有明确指定工作流后端，系统将自动使用 Actor 后端。

使用 Actor 工作流后端无需定义任何组件，它可以直接使用。

不过，如果您想将 Actor 工作流后端显式定义为一个组件，可以参考以下示例：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: actorbackend
spec:
 type: workflowbackend.actor
 version: v1

Aerospike

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要配置 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> # 可选

警告

上述示例使用未加密的字符串作为 secret。建议使用 secret 存储来保护 secret，如此处所述。

配置元数据字段

字段	必需	详情	示例
hosts	Y	数据库服务器的主机名/端口	`"localhost:3000"`, `"aerospike:3000,aerospike2:3000"`
namespace	Y	Aerospike 命名空间	`"namespace"`
set	N	数据库中的 setName	`"myset"`

设置 Aerospike

您可以使用 Docker 在本地运行 Aerospike：

annotate CLI 命令参考

Mon, 01 Jan 0001 00:00:00 +0000

描述

在 Kubernetes 配置中添加 Dapr 注解。这允许您在部署文件中添加或更改 Dapr 注解。有关每个可用注解的详细说明，请参见 Kubernetes 注解。

支持的平台

Kubernetes

用法

dapr annotate [flags] CONFIG-FILE

标志

名称	默认值	描述
`--kubernetes, -k`		将注解应用于 Kubernetes 资源。必需
`--api-token-secret`		用于 API token 的 secret
`--app-id, -a`		要注解的应用 ID
`--app-max-concurrency`	`-1`	允许的最大并发请求数
`--app-port, -p`	`-1`	用于暴露应用的端口
`--app-protocol`		应用使用的协议：`http`（默认），`grpc`，`https`，`grpcs`，`h2c`
`--app-token-secret`		用于应用 token 的 secret
`--config, -c`		要注解的配置文件
`--cpu-limit`		为 sidecar 设置的 CPU 限制。查看有效值这里。
`--cpu-request`		为 sidecar 设置的 CPU 请求。查看有效值这里。
`--dapr-image`		用于 dapr sidecar 容器的镜像
`--enable-debug`	`false`	启用调试
`--enable-metrics`	`false`	启用指标
`--enable-profile`	`false`	启用分析
`--env`		要设置的环境变量（键值对，逗号分隔）
`--graceful-shutdown-seconds`	`-1`	等待应用关闭的秒数
`--help, -h`		annotate 的帮助信息
`--listen-addresses`		sidecar 监听的地址。要监听所有 IPv4 地址，请使用 `0.0.0.0`。要监听所有 IPv6 地址，请使用 `[::]`。
`--liveness-probe-delay`	`-1`	sidecar 用于存活探测的延迟。阅读更多这里。
`--liveness-probe-period`	`-1`	sidecar 用于存活探测的周期。阅读更多这里。
`--liveness-probe-threshold`	`-1`	sidecar 用于存活探测的阈值。阅读更多这里。
`--liveness-probe-timeout`	`-1`	sidecar 用于存活探测的超时。阅读更多这里。
`--log-level`		使用的日志级别
`--max-request-body-size`	`-1`	使用的最大请求体大小
`--http-read-buffer-size`	`-1`	HTTP 头读取缓冲区的最大大小（以千字节为单位）
`--memory-limit`		为 sidecar 设置的内存限制。查看有效值这里
`--memory-request`		为 sidecar 设置的内存请求
`--metrics-port`	`-1`	用于暴露指标的端口
`--namespace, -n`		资源目标所在的命名空间（仅在设置 `--resource` 时可用）
`--readiness-probe-delay`	`-1`	sidecar 用于就绪探测的延迟。阅读更多这里。
`--readiness-probe-period`	`-1`	sidecar 用于就绪探测的周期。阅读更多这里。
`--readiness-probe-threshold`	`-1`	sidecar 用于就绪探测的阈值。阅读更多这里。
`--readiness-probe-timeout`	`-1`	sidecar 用于就绪探测的超时。阅读更多这里。
`--resource, -r`		要注解的 Kubernetes 资源目标
`--enable-api-logging`		为 Dapr sidecar 启用 API 日志记录
`--unix-domain-socket-path`		用于与 Dapr sidecar 通信的 Linux 域套接字路径
`--volume-mounts`		要以只读模式挂载到 sidecar 容器的 pod 卷列表
`--volume-mounts-rw`		要以读写模式挂载到 sidecar 容器的 pod 卷列表
`--disable-builtin-k8s-secret-store`		禁用内置的 Kubernetes secret 存储
`--placement-host-address`		Dapr actor 放置服务器的地址列表（逗号分隔）

警告

如果未使用 --app-id, -a 提供应用 ID，将自动生成一个格式为 <namespace>-<kind>-<name> 的 ID。

示例

# 注解输入中找到的第一个部署
kubectl get deploy -l app=node -o yaml | dapr annotate -k - | kubectl apply -f -

# 按名称在链中注解多个部署
kubectl get deploy -o yaml | dapr annotate -k -r nodeapp - | dapr annotate -k -r pythonapp - | kubectl apply -f -

# 从文件或目录中按名称注解特定命名空间中的部署
dapr annotate -k -r nodeapp -n namespace mydeploy.yaml | kubectl apply -f -

# 从 URL 按名称注解部署
dapr annotate -k -r nodeapp --log-level debug https://raw.githubusercontent.com/dapr/quickstarts/master/tutorials/hello-kubernetes/deploy/node.yaml | kubectl apply -f -

Anthropic

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

一个Dapr conversation.yaml 组件文件的结构如下：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: anthropic
spec:
 type: conversation.anthropic
 metadata:
 - name: key
 value: "mykey"
 - name: model
 value: claude-3-5-sonnet-20240620
 - name: cacheTTL
 value: 10m

警告

上述示例中，secret使用了明文字符串。建议使用secret存储，如此处所述。

元数据字段说明

字段	必需	详情	示例
`key`	Y	Anthropic的API密钥。	`"mykey"`
`model`	N	要使用的Anthropic LLM。默认为`claude-3-5-sonnet-20240620`	`claude-3-5-sonnet-20240620`
`cacheTTL`	N	提示缓存的过期时间。使用Golang的持续时间格式。	`10m`

Apache Kafka

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要设置 Apache Kafka 的发布/订阅功能，您需要创建一个类型为 pubsub.kafka 的组件。请参阅 pub/sub broker 组件文件了解 ConsumerID 是如何自动生成的。阅读如何：发布和订阅指南了解如何创建和应用发布/订阅配置。

所有组件的元数据字段值可以使用模板化的元数据值，这些值会在 Dapr sidecar 启动时解析。例如，您可以选择使用 {namespace} 作为 consumerGroup，以便在不同命名空间中使用相同的 appId 和主题，如本文所述。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: kafka-pubsub
spec:
 type: pubsub.kafka
 version: v1
 metadata:
 - name: brokers # 必需字段，Kafka broker 连接设置
 value: "dapr-kafka.myapp.svc.cluster.local:9092"
 - name: consumerGroup # 可选字段，用于输入绑定。
 value: "{namespace}"
 - name: consumerID # 可选字段。如果未提供，运行时将自动创建。
 value: "channel1"
 - name: clientID # 可选字段，用于 Kafka brokers 的客户端跟踪 ID。
 value: "my-dapr-app-id"
 - name: authType # 必需字段。
 value: "password"
 - name: saslUsername # 如果 authType 是 `password`，则必需。
 value: "adminuser"
 - name: saslPassword # 如果 authType 是 `password`，则必需。
 secretKeyRef:
 name: kafka-secrets
 key: saslPasswordSecret
 - name: saslMechanism
 value: "SHA-512"
 - name: maxMessageBytes # 可选字段。
 value: 1024
 - name: consumeRetryInterval # 可选字段。
 value: 200ms
 - name: heartbeatInterval # 可选字段。
 value: 5s
 - name: sessionTimeout # 可选字段。
 value: 15s
 - name: version # 可选字段。
 value: 2.0.0
 - name: disableTls # 可选字段。禁用 TLS。在生产环境中不安全！请阅读 `Mutual TLS` 部分以了解如何使用 TLS。
 value: "true"
 - name: consumerFetchMin # 可选字段。高级设置。请求中要获取的最小消息字节数 - broker 将等待直到至少有这么多可用。
 value: 1
 - name: consumerFetchDefault # 可选字段。高级设置。每个请求中从 broker 获取的默认消息字节数。
 value: 2097152
 - name: channelBufferSize # 可选字段。高级设置。内部和外部通道中要缓冲的事件数量。
 value: 512
 - name: schemaRegistryURL # 可选字段。当使用 Schema Registry Avro 序列化/反序列化时。Schema Registry URL。
 value: http://localhost:8081
 - name: schemaRegistryAPIKey # 可选字段。当使用 Schema Registry Avro 序列化/反序列化时。Schema Registry API Key。
 value: XYAXXAZ
 - name: schemaRegistryAPISecret # 可选字段。当使用 Schema Registry Avro 序列化/反序列化时。Schema Registry 凭证 API Secret。
 value: "ABCDEFGMEADFF"
 - name: schemaCachingEnabled # 可选字段。当使用 Schema Registry Avro 序列化/反序列化时。启用模式缓存。
 value: true
 - name: schemaLatestVersionCacheTTL # 可选字段。当使用 Schema Registry Avro 序列化/反序列化时。发布具有最新模式的消息时的模式缓存 TTL。
 value: 5m
 - name: escapeHeaders # 可选字段。
 value: false

有关使用 secretKeyRef 的详细信息，请参阅如何在组件中引用 secrets 的指南。

Apple 推送通知服务绑定说明

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要配置 Apple 推送通知绑定，请创建一个类型为 bindings.apns 的组件。请参阅本指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.apns
 version: v1
 metadata:
 - name: development
 value: "<bool>"
 - name: key-id
 value: "<APPLE_KEY_ID>"
 - name: team-id
 value: "<APPLE_TEAM_ID>"
 - name: private-key
 secretKeyRef:
 name: <SECRET>
 key: "<SECRET-KEY-NAME>"

元数据字段说明

字段	必需	绑定功能支持	详情	示例
`development`	Y	输出	指定使用哪个 APNs 服务。设置为 `"true"` 使用开发服务，或 `"false"` 使用生产服务。默认值：`"true"`	`"true"`
`key-id`	Y	输出	来自 Apple 开发者门户的私钥标识符	`"private-key-id`"
`team-id`	Y	输出	来自 Apple 开发者门户的组织或作者标识符	`"team-id"`
`private-key`	Y	输出	这是一个 PKCS #8 格式的私钥。建议将私钥存储在 secret 存储中，而不是直接在配置中暴露。详情请参见此处	`"pem file"`

私钥

APNS 绑定需要一个加密私钥来生成 APNS 服务的身份验证令牌。私钥可以从 Apple 开发者门户生成，并以 PKCS #8 文件形式提供，存储在 PEM 格式中。建议将私钥存储在 Dapr 的 secret 存储中，而不是直接在绑定的配置文件中。

AWS DynamoDB 绑定说明

Mon, 01 Jan 0001 00:00:00 +0000

组件配置格式

要配置 AWS DynamoDB 绑定，请创建一个类型为 bindings.aws.dynamodb 的组件。请参考本指南了解如何创建和应用绑定配置。

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

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.aws.dynamodb
 version: v1
 metadata:
 - name: table
 value: "items"
 - name: region
 value: "us-west-2"
 - name: accessKey
 value: "*****************"
 - name: secretKey
 value: "*****************"
 - name: sessionToken
 value: "*****************"

警告

上述示例中使用了明文字符串作为密钥。建议使用密钥存储来保存密钥，详情请参阅此处。

规范元数据字段

字段	必需	绑定支持	详情	示例
`table`	Y	输出	DynamoDB 表名	`"items"`
`region`	Y	输出	AWS DynamoDB 实例所在的特定 AWS 区域	`"us-east-1"`
`accessKey`	Y	输出	访问此资源的 AWS 访问密钥	`"key"`
`secretKey`	Y	输出	访问此资源的 AWS 秘密访问密钥	`"secretAccessKey"`
`sessionToken`	N	输出	使用的 AWS 会话令牌	`"sessionToken"`

重要

当在 EKS（AWS Kubernetes）上与应用程序一起运行 Dapr sidecar（daprd）时，如果您使用的节点/Pod 已经附加了定义访问 AWS 资源的 IAM 策略，则不需要在组件配置中提供 AWS 访问密钥、秘密密钥和令牌。

绑定支持

此组件支持具有以下操作的输出绑定：

AWS DynamoDB

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要设置 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"

警告

上述示例使用明文字符串作为 secret。建议使用 secret 存储来存储 secret，如此处所述。

主键

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

AWS Kinesis 绑定规范

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要设置 AWS Kinesis 绑定，需创建一个类型为 bindings.aws.kinesis 的组件。请参阅本指南以了解如何创建和应用绑定配置。

请参阅此处以了解如何设置 AWS Kinesis 数据流。请参阅认证到 AWS以获取与认证相关的属性信息。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.aws.kinesis
 version: v1
 metadata:
 - name: streamName
 value: "KINESIS_STREAM_NAME" # Kinesis 流名称
 - name: consumerName
 value: "KINESIS_CONSUMER_NAME" # Kinesis 消费者名称
 - name: mode
 value: "shared" # shared - 共享吞吐量或 extended - 扩展/增强扇出
 - name: region
 value: "AWS_REGION" # 请替换为实际的 AWS 区域
 - name: accessKey
 value: "AWS_ACCESS_KEY" # 请替换为实际的 AWS 访问密钥
 - name: secretKey
 value: "AWS_SECRET_KEY" # 请替换为实际的 AWS 秘密访问密钥
 - name: sessionToken
 value: "*****************"
 - name: direction
 value: "input, output"

警告

上述示例中使用了明文字符串作为 secret。建议使用 secret 存储来存储 secret，如此处所述。

规范元数据字段

字段	必需	绑定支持	详情	示例
`mode`	否	输入	Kinesis 流模式。`shared`- 共享吞吐量，`extended` - 扩展/增强扇出方法。更多详情请参阅此处。默认为 `"shared"`	`"shared"`, `"extended"`
`streamName`	是	输入/输出	AWS Kinesis 流名称	`"stream"`
`consumerName`	是	输入	AWS Kinesis 消费者名称	`"myconsumer"`
`region`	是	输出	部署 AWS Kinesis 实例的特定 AWS 区域	`"us-east-1"`
`accessKey`	是	输出	访问此资源的 AWS 访问密钥	`"key"`
`secretKey`	是	输出	访问此资源的 AWS 秘密访问密钥	`"secretAccessKey"`
`sessionToken`	否	输出	使用的 AWS 会话令牌	`"sessionToken"`
`direction`	否	输入/输出	绑定的方向	`"input"`, `"output"`, `"input, output"`

重要

在 EKS（AWS Kubernetes）上运行 Dapr sidecar（daprd）与您的应用程序一起时，如果节点/Pod 已附加了定义访问 AWS 资源的 IAM 策略，则不应在组件规范中提供 AWS 访问密钥、秘密密钥和令牌。

绑定支持

此组件支持输入和输出绑定接口。

AWS S3 绑定规范

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要设置 AWS S3 绑定，您需要创建一个类型为 bindings.aws.s3 的组件。此绑定可以与其他兼容 S3 的服务一起使用，例如 Minio。请参阅本指南以了解如何创建和应用绑定配置。

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

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.aws.s3
 version: v1
 metadata:
 - name: bucket
 value: "mybucket"
 - name: region
 value: "us-west-2"
 - name: endpoint
 value: "s3.us-west-2.amazonaws.com"
 - name: accessKey
 value: "*****************"
 - name: secretKey
 value: "*****************"
 - name: sessionToken
 value: "mysession"
 - name: decodeBase64
 value: "<bool>"
 - name: encodeBase64
 value: "<bool>"
 - name: forcePathStyle
 value: "<bool>"
 - name: disableSSL
 value: "<bool>"
 - name: insecureSSL
 value: "<bool>"
 - name: storageClass
 value: "<string>"

警告

上面的示例中使用了明文字符串作为密钥。建议使用密钥存储来存储密钥，如此处所述。

规范元数据字段

字段	必需	绑定支持	详情	示例
`bucket`	Y	输出	要写入的 S3 bucket 名称	`"bucket"`
`region`	Y	输出	特定的 AWS 区域	`"us-east-1"`
`endpoint`	N	输出	特定的 AWS 端点	`"s3.us-east-1.amazonaws.com"`
`accessKey`	Y	输出	访问此资源的 AWS 访问密钥	`"key"`
`secretKey`	Y	输出	访问此资源的 AWS secret 访问密钥	`"secretAccessKey"`
`sessionToken`	N	输出	要使用的 AWS 会话令牌	`"sessionToken"`
`forcePathStyle`	N	输出	Amazon S3 SDK 支持虚拟主机样式和路径样式访问。`"true"` 表示路径样式格式，如 `"https://<endpoint>/<your bucket>/<key>"`。`"false"` 表示主机样式格式，如 `"https://<your bucket>.<endpoint>/<key>"`。默认为 `"false"`	`"true"`, `"false"`
`decodeBase64`	N	输出	配置在保存到 bucket 存储之前解码 base64 文件内容。（在保存二进制内容文件的情况下）。`"true"` 是唯一允许的正值。其他正值变体如 `"True", "1"` 不可接受。默认为 `false`	`"true"`, `"false"`
`encodeBase64`	N	输出	配置在返回内容之前对 base64 文件内容进行编码。（在打开二进制内容文件的情况下）。`"true"` 是唯一允许的正值。其他正值变体如 `"True", "1"` 不可接受。默认为 `"false"`	`"true"`, `"false"`
`disableSSL`	N	输出	允许连接到非 `https://` 端点。默认为 `"false"`	`"true"`, `"false"`
`insecureSSL`	N	输出	当连接到 `https://` 端点时，接受无效或自签名证书。默认为 `"false"`	`"true"`, `"false"`
`storageClass`	N	输出	在创建操作期间对象的所需存储类。有效的 AWS 存储类类型可以在此处找到	`STANDARD_IA`

重要

当在 EKS（AWS Kubernetes）上与应用程序一起运行 Dapr sidecar（daprd）时，如果您使用的节点/Pod 已经附加了定义访问 AWS 资源的 IAM 策略，则不得在您使用的组件规范定义中提供 AWS 访问密钥、secret 密钥和令牌。

S3 Bucket 创建

使用 Minio

Minio 是一种将本地存储暴露为兼容 S3 的块存储的服务，尤其在开发环境中是 S3 的流行替代品。您也可以使用 S3 绑定与 Minio 一起使用，只需进行一些配置调整：

AWS Secrets Manager

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要设置 AWS Secrets Manager 的密钥存储，需创建一个类型为 secretstores.aws.secretmanager 的组件。请参阅本指南了解如何创建和应用密钥存储配置。请参阅本指南以引用 secrets以检索和使用 Dapr 组件的密钥。

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

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: awssecretmanager
spec:
 type: secretstores.aws.secretmanager
 version: v1
 metadata:
 - name: region
 value: "[aws_region]"
 - name: accessKey
 value: "[aws_access_key]"
 - name: secretKey
 value: "[aws_secret_key]"
 - name: sessionToken
 value: "[aws_session_token]"

警告

上述示例中使用了明文形式的字符串作为密钥。建议使用本地密钥存储，例如Kubernetes 密钥存储或本地文件来安全地存储密钥。

规格元数据字段

字段	必需	详情	示例
region	Y	部署 AWS Secrets Manager 实例的特定 AWS 区域	`"us-east-1"`
accessKey	Y	访问此资源的 AWS 访问密钥	`"key"`
secretKey	Y	访问此资源的 AWS 秘密访问密钥	`"secretAccessKey"`
sessionToken	N	要使用的 AWS 会话令牌	`"sessionToken"`

重要

当在 EKS（AWS Kubernetes）上与应用程序一起运行 Dapr sidecar（daprd）时，如果您使用的节点或 Pod 已经附加了定义访问 AWS 资源的 IAM 策略，则不应在组件规格中提供 AWS 访问密钥、秘密密钥和令牌。

可选的每请求元数据属性

从此密钥存储检索密钥时，可以提供以下可选查询参数：

AWS SES 绑定说明

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要配置 AWS 绑定，请创建一个类型为 bindings.aws.ses 的组件。有关如何创建和应用绑定配置的详细信息，请参阅本指南。

关于身份验证的更多信息，请参阅身份验证到 AWS。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: ses
spec:
 type: bindings.aws.ses
 version: v1
 metadata:
 - name: accessKey
 value: *****************
 - name: secretKey
 value: *****************
 - name: region
 value: "eu-west-1"
 - name: sessionToken
 value: mysession
 - name: emailFrom
 value: "sender@example.com"
 - name: emailTo
 value: "receiver@example.com"
 - name: emailCc
 value: "cc@example.com"
 - name: emailBcc
 value: "bcc@example.com"
 - name: subject
 value: "subject"

警告

上述示例中使用了明文字符串作为密钥。建议使用密钥存储来保存密钥，详情请参阅此处。

规范元数据字段

字段	必需	绑定支持	详情	示例
`region`	否	输出	AWS 区域	`"eu-west-1"`
`accessKey`	否	输出	访问资源的 AWS 访问密钥	`"key"`
`secretKey`	否	输出	访问资源的 AWS 秘密访问密钥	`"secretAccessKey"`
`sessionToken`	否	输出	使用的 AWS 会话令牌	`"sessionToken"`
`emailFrom`	否	输出	发件人的电子邮件地址	`"me@example.com"`
`emailTo`	否	输出	收件人的电子邮件地址	`"me@example.com"`
`emailCc`	否	输出	抄送的电子邮件地址	`"me@example.com"`
`emailBcc`	否	输出	密送的电子邮件地址	`"me@example.com"`
`subject`	否	输出	电子邮件的主题	`"subject of mail"`

重要

在 EKS（AWS Kubernetes）上运行 Dapr sidecar（daprd）时，如果节点/Pod 已附加了访问 AWS 资源的 IAM 策略，则不应在组件规范中提供 AWS 访问密钥、秘密密钥和令牌。

绑定支持

此组件支持以下操作的输出绑定：

AWS SNS 绑定组件规范

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要配置 AWS SNS 绑定，请创建一个类型为 bindings.aws.sns 的组件。有关如何创建和应用绑定配置的详细信息，请参阅本指南。

有关身份验证的详细信息，请参阅身份验证到 AWS。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.aws.sns
 version: v1
 metadata:
 - name: topicArn
 value: "mytopic"
 - name: region
 value: "us-west-2"
 - name: endpoint
 value: "sns.us-west-2.amazonaws.com"
 - name: accessKey
 value: "*****************"
 - name: secretKey
 value: "*****************"
 - name: sessionToken
 value: "*****************"

警告

上述示例中使用了明文字符串来表示密钥。建议使用密钥存储来管理这些密钥，详情请参阅此处。

规范元数据字段

字段	必需	绑定支持	详情	示例
`topicArn`	是	输出绑定	SNS 主题的 ARN（Amazon Resource Name）	`"arn:::topicarn"`
`region`	是	输出绑定	AWS 的特定区域	`"us-east-1"`
`endpoint`	否	输出绑定	AWS 的特定端点	`"sns.us-east-1.amazonaws.com"`
`accessKey`	是	输出绑定	访问资源的 AWS 访问密钥	`"key"`
`secretKey`	是	输出绑定	访问资源的 AWS 秘密访问密钥	`"secretAccessKey"`
`sessionToken`	否	输出绑定	使用的 AWS 会话令牌	`"sessionToken"`

重要

在 EKS（AWS Kubernetes）上与应用程序一起运行 Dapr sidecar（daprd）时，如果节点/Pod 已附加了访问 AWS 资源的 IAM 策略，则不应在组件规范中提供 AWS 访问密钥、秘密密钥和令牌。

绑定支持

此组件支持以下操作的输出绑定：

AWS SNS/SQS

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要设置AWS SNS/SQS pub/sub，创建一个类型为pubsub.aws.snssqs的组件。

默认情况下，AWS SNS/SQS组件会：

创建SNS主题
配置SQS队列
设置队列到主题的订阅

注意

如果您只有发布者而没有订阅者，那么只会创建SNS主题。

但是，如果您有订阅者，则会生成SNS、SQS及其动态或静态订阅。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: snssqs-pubsub
spec:
 type: pubsub.aws.snssqs
 version: v1
 metadata:
 - name: accessKey
 value: "AKIAIOSFODNN7EXAMPLE"
 - name: secretKey
 value: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
 - name: region
 value: "us-east-1"
 # - name: consumerID # 可选。如果未提供，运行时将创建一个。
 # value: "channel1"
 # - name: endpoint # 可选。
 # value: "http://localhost:4566"
 # - name: sessionToken # 可选（如果使用AssignedRole则必须；例如，临时accessKey和secretKey）
 # value: "TOKEN"
 # - name: messageVisibilityTimeout # 可选
 # value: 10
 # - name: messageRetryLimit # 可选
 # value: 10
 # - name: messageReceiveLimit # 可选
 # value: 10
 # - name: sqsDeadLettersQueueName # 可选
 # - value: "myapp-dlq"
 # - name: messageWaitTimeSeconds # 可选
 # value: 1
 # - name: messageMaxNumber # 可选
 # value: 10
 # - name: fifo # 可选
 # value: "true"
 # - name: fifoMessageGroupID # 可选
 # value: "app1-mgi"
 # - name: disableEntityManagement # 可选
 # value: "false"
 # - name: disableDeleteOnRetryLimit # 可选
 # value: "false"
 # - name: assetsManagementTimeoutSeconds # 可选
 # value: 5
 # - name: concurrencyMode # 可选
 # value: "single"
 # - name: concurrencyLimit # 可选
 # value: "0"

警告

上述示例使用明文字符串作为secret。建议使用secret存储来存储secret。

规格元数据字段

字段	必需	详情	示例
accessKey	Y	具有适当权限的AWS账户/角色的ID，用于SNS和SQS（见下文）	`"AKIAIOSFODNN7EXAMPLE"`
secretKey	Y	AWS用户/角色的secret。如果使用`AssumeRole`访问，还需要提供`sessionToken`	`"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"`
region	Y	SNS/SQS资产所在或将创建的AWS区域。请参阅此页面以获取有效区域。确保SNS和SQS在该区域可用	`"us-east-1"`
consumerID	N	消费者ID（消费者标签）将一个或多个消费者组织成一个组。具有相同消费者ID的消费者作为一个虚拟消费者工作；例如，消息仅由组中的一个消费者处理一次。如果未提供`consumerID`，Dapr运行时将其设置为Dapr应用程序ID（`appID`）值。请参阅pub/sub broker组件文件以了解如何自动生成ConsumerID。	可以设置为字符串值（如上例中的`"channel1"`）或字符串格式值（如`"{podName}"`等）。查看您可以在组件元数据中使用的所有模板标签。
endpoint	N	组件使用的AWS端点。仅用于本地开发，例如使用localstack。在生产AWS上运行时不需要`endpoint`	`"http://localhost:4566"`
sessionToken	N	要使用的AWS会话令牌。仅在使用临时安全凭证时需要会话令牌	`"TOKEN"`
messageReceiveLimit	N	消息接收的次数，在处理该消息失败后，一旦达到该次数，将导致从队列中删除该消息。如果指定了`sqsDeadLettersQueueName`，`messageReceiveLimit`是消息接收的次数，在处理该消息失败后，一旦达到该次数，将导致将消息移动到SQS死信队列。默认值：`10`	`10`
sqsDeadLettersQueueName	N	此应用程序的死信队列的名称	`"myapp-dlq"`
messageVisibilityTimeout	N	消息在发送给订阅者后从接收请求中隐藏的时间（以秒为单位）。默认值：`10`	`10`
messageRetryLimit	N	在处理消息失败后重新发送消息的次数，然后从队列中删除该消息。默认值：`10`	`10`
messageWaitTimeSeconds	N	调用等待消息到达队列的持续时间（以秒为单位），然后返回。如果有消息可用，调用会比`messageWaitTimeSeconds`更早返回。如果没有消息可用且等待时间到期，调用会成功返回一个空消息列表。默认值：`1`	`1`
messageMaxNumber	N	一次从队列中接收的最大消息数。默认值：`10`，最大值：`10`	`10`
fifo	N	使用SQS FIFO队列提供消息排序和去重。默认值：`"false"`。有关SQS FIFO的更多详细信息	`"true"`，`"false"`
fifoMessageGroupID	N	如果启用了`fifo`，指示Dapr为pubsub部署使用自定义消息组ID。这不是强制性的，因为Dapr为每个生产者创建一个自定义消息组ID，从而确保每个Dapr生产者的消息排序。默认值：`""`	`"app1-mgi"`
disableEntityManagement	N	当设置为true时，SNS主题、SQS队列和SQS到SNS的订阅不会自动创建。默认值：`"false"`	`"true"`，`"false"`
disableDeleteOnRetryLimit	N	当设置为true时，在重试并失败`messageRetryLimit`次处理消息后，重置消息可见性超时，以便其他消费者可以尝试处理，而不是从SQS中删除消息（默认行为）。默认值：`"false"`	`"true"`，`"false"`
assetsManagementTimeoutSeconds	N	AWS资产管理操作的超时时间（以秒为单位），在超时并取消之前。资产管理操作是对STS、SNS和SQS执行的任何操作，除了实现默认Dapr组件重试行为的消息发布和消费操作。该值可以设置为任何非负浮点数/整数。默认值：`5`	`0.5`，`10`
concurrencyMode	N	当从SQS批量接收消息时，按顺序调用订阅者（一次“单个”消息），或并发调用（“并行”）。默认值：`"parallel"`	`"single"`，`"parallel"`
concurrencyLimit	N	定义处理消息的最大并发工作者数量。当concurrencyMode设置为`"single"`时，此值被忽略。要避免限制并发工作者的数量，请将其设置为`0`。默认值：`0`	`100`

其他信息

符合AWS规范

Dapr创建的SNS主题和SQS队列名称符合AWS规范。默认情况下，Dapr根据消费者app-id创建SQS队列名称，因此Dapr可能会执行名称标准化以符合AWS规范。

AWS SQS 绑定规范

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要设置 AWS SQS 绑定，您需要创建一个类型为 bindings.aws.sqs 的组件。请参考本指南了解如何创建和应用绑定配置。

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

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.aws.sqs
 version: v1
 metadata:
 - name: queueName
 value: "items"
 - name: region
 value: "us-west-2"
 - name: accessKey
 value: "*****************"
 - name: secretKey
 value: "*****************"
 - name: sessionToken
 value: "*****************"
 - name: direction 
 value: "input, output"

警告

上述示例使用明文字符串作为密钥。建议使用密钥存储来保存密钥，如此处所述。

规范元数据字段

字段	必需	绑定支持	详情	示例
`queueName`	Y	输入/输出	SQS 队列名称	`"myqueue"`
`region`	Y	输入/输出	特定的 AWS 区域	`"us-east-1"`
`accessKey`	Y	输入/输出	访问此资源的 AWS 访问密钥	`"key"`
`secretKey`	Y	输入/输出	访问此资源的 AWS 秘密访问密钥	`"secretAccessKey"`
`sessionToken`	N	输入/输出	要使用的 AWS 会话令牌	`"sessionToken"`
`direction`	N	输入/输出	绑定的方向	`"input"`, `"output"`, `"input, output"`

重要

在 EKS（AWS Kubernetes）上与应用程序一起运行 Dapr sidecar（daprd）时，如果您使用的节点/Pod 已经附加了定义访问 AWS 资源的 IAM 策略，则不应在组件规范中提供 AWS 访问密钥、秘密密钥和令牌。

绑定支持

此组件支持输入和输出绑定接口。

AWS SSM 参数存储

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要设置 AWS SSM 参数存储的机密存储，需创建一个 secretstores.aws.parameterstore 类型的组件。请参阅本指南了解如何创建和应用机密存储配置。请参阅本指南，了解如何引用机密以检索和使用 Dapr 组件的机密。

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

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: awsparameterstore
spec:
 type: secretstores.aws.parameterstore
 version: v1
 metadata:
 - name: region
 value: "[aws_region]"
 - name: accessKey
 value: "[aws_access_key]"
 - name: secretKey
 value: "[aws_secret_key]"
 - name: sessionToken
 value: "[aws_session_token]"
 - name: prefix
 value: "[secret_name]"

警告

上述示例使用了明文字符串作为机密。建议使用本地机密存储，例如 Kubernetes 机密存储或本地文件来安全地存储密钥。

规格元数据字段

字段	必需	详细信息	示例
region	Y	部署 AWS SSM 参数存储实例的特定 AWS 区域	`"us-east-1"`
accessKey	Y	访问此资源的 AWS 访问密钥	`"key"`
secretKey	Y	访问此资源的 AWS 秘密访问密钥	`"secretAccessKey"`
sessionToken	N	要使用的 AWS 会话令牌	`"sessionToken"`
prefix	N	用于指定多个 SSM 参数存储机密存储组件的前缀。	`"prefix"`

重要

在 EKS（AWS Kubernetes）上运行 Dapr sidecar（daprd）时，如果节点/Pod 已附加了访问 AWS 资源的 IAM 策略，则不应在组件规格中提供 AWS 访问密钥、秘密密钥和令牌。

创建 AWS SSM 参数存储实例

请参考 AWS 文档以设置 AWS SSM 参数存储：https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html。

Azure Blob Storage 绑定指南

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要配置 Azure Blob Storage 绑定，需创建一个类型为 bindings.azure.blobstorage 的组件。请参考本指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.azure.blobstorage
 version: v1
 metadata:
 - name: accountName
 value: myStorageAccountName
 - name: accountKey
 value: ***********
 - name: containerName
 value: container1
# - name: decodeBase64
# value: <bool>
# - name: getBlobRetryCount
# value: <integer>
# - name: publicAccessLevel
# value: <publicAccessLevel>

警告

上述示例中，secret 以明文字符串形式使用。建议使用 secret 存储来保护 secret，具体方法请参见此处。

元数据字段说明

字段	必需	绑定支持	详情	示例
`accountName`	Y	输入/输出	Azure 存储账户的名称	`"myexmapleaccount"`
`accountKey`	Y*	输入/输出	Azure 存储账户的访问密钥。仅在不使用 Microsoft Entra ID 认证时需要。	`"access-key"`
`containerName`	Y	输出	要写入的 Blob Storage 容器的名称	`myexamplecontainer`
`endpoint`	N	输入/输出	可选的自定义端点 URL。这在使用 Azurite 模拟器或使用 Azure 存储的自定义域时很有用（尽管这不是官方支持的）。端点必须是完整的基本 URL，包括协议（`http://` 或 `https://`）、IP 或 FQDN，以及可选端口。	`"http://127.0.0.1:10000"`
`decodeBase64`	N	输出	配置在保存到 Blob Storage 之前解码 base64 文件内容。（在保存具有二进制内容的文件时）。默认为 `false`	`true`, `false`
`getBlobRetryCount`	N	输出	指定在从 RetryReader 读取时将进行的最大 HTTP GET 请求次数。默认为 `10`	`1`, `2`
`publicAccessLevel`	N	输出	指定容器中的数据是否可以公开访问以及访问级别（仅在容器由 Dapr 创建时使用）。默认为 `none`	`blob`, `container`, `none`

Microsoft Entra ID 认证

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

Azure Blob 存储

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要设置 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]"

警告

上述示例中，secret 使用了明文字符串。建议使用 secret 存储来存储 secret，如此处所述。

版本控制

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

Azure Cosmos DB (Gremlin API) 绑定组件说明

Mon, 01 Jan 0001 00:00:00 +0000

组件格式

要配置 Azure Cosmos DB (Gremlin API) 绑定，请创建一个类型为 bindings.azure.cosmosdb.gremlinapi 的组件。请参阅本指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.azure.cosmosdb.gremlinapi
 version: v1
 metadata:
 - name: url
 value: "wss://******.gremlin.cosmos.azure.com:443/"
 - name: masterKey
 value: "*****"
 - name: username
 value: "*****"

警告

上述示例使用了明文形式的字符串作为密钥。建议使用密钥存储来存储密钥，如此处所述。

规范元数据字段

字段	是否必需	支持的绑定类型	说明	示例
`url`	Y	输出	Gremlin API 的 Cosmos DB URL	`"wss://******.gremlin.cosmos.azure.com:443/"`
`masterKey`	Y	输出	Cosmos DB 账户的主密钥	`"masterKey"`
`username`	Y	输出	Cosmos DB 数据库的用户名	`"/dbs/<database_name>/colls/<graph_name>"`

Azure Cosmos DB (SQL API) 绑定说明

Mon, 01 Jan 0001 00:00:00 +0000

组件配置格式

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

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.azure.cosmosdb
 version: v1
 metadata:
 - name: url
 value: "https://******.documents.azure.com:443/"
 - name: masterKey
 value: "*****"
 - name: database
 value: "OrderDb"
 - name: collection
 value: "Orders"
 - name: partitionKey
 value: "<message>"

警告

上述示例中，secret 以明文字符串形式使用。建议使用 secret 存储来存储 secret，如此处所述。

规范元数据字段

字段	必需	绑定支持	详情	示例
`url`	Y	输出	Cosmos DB 的 URL	`"https://******.documents.azure.com:443/"`
`masterKey`	Y	输出	Cosmos DB 帐户的主密钥	`"master-key"`
`database`	Y	输出	Cosmos DB 数据库的名称	`"OrderDb"`
`collection`	Y	输出	数据库容器的名称。	`"Orders"`
`partitionKey`	Y	输出	从文档负载中提取的分区键的名称。此名称必须与创建 Cosmos DB 容器时指定的分区键一致。	`"OrderId"`, `"message"`

有关更多信息，请参阅 Azure Cosmos DB 资源模型。