Actors on Dapr 文档库

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 的生命周期。

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 运行时配置的状态提供者中。

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。

命名空间中的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>

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

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 上注册一个基于定时器执行的回调。

如何启用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的文档。

操作指南：使用脚本与虚拟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重入 >>

如何：在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中。

Actors on Dapr 文档库

Actors 概述

Dapr 中的 Actor 模型

Dapr Actors 与 Dapr Workflow

Actor 的运行时特性

Actor 的生命周期

actor 运行时配置参数

示例

命名空间中的actor

注意

创建和配置命名空间

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

示例1：通过etcd中的前缀

示例2：通过SQLite中的表名

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

actor 定时器和提醒

actor 定时器

如何启用actor提醒分区

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

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

调用actor方法

注意

使用actors保存状态

下一步

相关链接

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

配置actor运行时以启用重入