Akka 监督与监控完全指南:层级故障处理、DeathWatch 与异常恢复机制
Akka 监督与监控完全指南:层级故障处理、DeathWatch 与异常恢复机制
导读
本文围绕 Akka 的核心容错机制——监督(Supervision)与生命周期监控(Monitoring / DeathWatch) 展开,系统讲解 Actor 层次结构中失败如何被隔离、决策如何被委派,以及重启、恢复、停止三种故障处理指令的语义差异。文章以仓库文档 general/supervision.md 为主体骨架,结合 Typed API 实战文档 typed/fault-tolerance.md、Classic 文档 supervision-classic.md 以及 FaultHandling.scala 等源码实现,帮助读者掌握:异常与业务校验错误如何区分、/user 与 /system 顶层守护者的职责、重启时内部状态与 mailbox 的处置规则,以及如何用 Behaviors.supervise 与 SupervisorStrategy 编写声明式的故障处理策略。
监督(Supervision)的含义
两类异常:校验错误与失败
在 Akka 中,Actor 内部可能发生的异常分为两个截然不同的类别:
- 输入校验错误(validation errors):属于"可预期"的异常,可以用常规的
try-catch或语言标准库工具直接处理。这类错误本质上与业务逻辑耦合,应该建模为 Actor 协议的一部分(例如返回错误结果消息),而不是让 Actor 抛异常。 - 意外失败(failures):例如网络资源不可用、磁盘写入失败,或者应用逻辑中的 bug。这类异常超出了 Actor 自身的控制范围,发送方往往也无能为力,因此不适合建模进协议。
监督只处理失败(failures),不处理校验错误。 校验与可预期异常的处理属于业务逻辑的核心组成部分,而监督是作为"装饰"(decoration)附加到 Actor 上的,不会与 Actor 的消息处理逻辑交织在一起。这一点在 typed/fault-tolerance.md 中被进一步强调:对于失败,最适合的哲学是 "let it crash"——不在业务逻辑里混入细粒度的内部状态修复,而是把恢复责任上移,让 Actor 崩溃后以一个已知有效的新状态重新开始。
三种监督策略
根据被监督工作的性质与失败的性质,监督提供三种基础策略:
| 策略 | 行为 | 内部状态 |
|---|---|---|
| Resume(恢复) | 继续处理下一条消息,仿佛什么都没发生 | 保留累计的内部状态 |
| Restart(重启) | 清除内部状态,可能延迟后重新启动 | 状态被清空,从零开始 |
| Stop(停止) | 永久停止该 Actor | — |
由于 Actor 天然处于层级结构中,当某个 Actor 的所有子 Actor 都意外停止时,往往值得把永久性失败向上传播(escalate)——让该 Actor 自身重启或停止,以回到可用状态。这可以通过"监督 + watch 子 Actor 以获得终止通知"的组合来实现,具体示例见 typed/fault-tolerance.md#bubble 中的失败冒泡小节。
在 Classic 模型中,监督指令(Directive)实际有四种:在 Resume、Restart、Stop 之外还有 Escalate(升级)——把失败抛给上级监督者,由上级决定如何处理。这四种指令在源码 FaultHandling.scala 中对应 SupervisorStrategy.Directive 的四个成员:Resume、Restart、Stop、Escalate。
顶层 Actor:监督层次的根基
一个 ActorSystem 在创建期间会启动若干个顶层 Actor,它们是整个监督层次树的根。文档 general/supervision.md 重点介绍其中两个;Classic 文档 supervision-classic.md 则补充了完整的三个顶层监督者。
/user:用户守护者(User Guardian)
/user 是顶层用户 Actor,用于通过孵化子系统来引导(bootstrap)整个应用。所有通过 system.actorOf() / context.spawn() 创建的用户 Actor 都是它的后代。当 /user 守护者停止时,整个 ActorSystem 将随之关闭。 因此它相当于整个应用生命周期的根。
从 Akka 2.1 起,可以通过配置项 akka.actor.guardian-supervisor-strategy 指定一个 SupervisorStrategyConfigurator 的全限定类名,来自定义顶层用户 Actor 的监督策略。当守护者升级失败时,根守护者的响应是终止守护者,这实际上会关停整个 ActorSystem。相关的 SupervisorStrategyConfigurator 接口与 DefaultSupervisorStrategy、StoppingSupervisorStrategy 实现定义在 FaultHandling.scala。
/system:系统守护者(System Guardian)
/system 守护者是为了实现有序关闭而引入的特殊守护者:即使日志本身也是用 Actor 实现的,它也能保证在所有普通 Actor 终止期间日志保持可用。其实现方式是:系统守护者 watch 用户守护者,一旦观察到用户守护者停止,就启动自身的关闭流程。
从源码与文档可见,/system 下的顶层系统 Actor 采用一种"无限重启"策略:对所有 Exception 重启,但对 ActorInitializationException 和 ActorKilledException 则终止对应子 Actor,其余 Throwable 一律升级——升级将导致整个 ActorSystem 关闭。
/:根守护者(Root Guardian,Classic 补充)
根守护者是所有顶层 Actor 的"祖父",它使用 SupervisorStrategy.stoppingStrategy(遇到任何 Exception 就终止子 Actor,其余 Throwable 升级)来监督所有特殊 Actor。根守护者的监督者不是真实 Actor,而是被称为 "bubble-walker" 的合成 ActorRef:它会在遇到麻烦时停止其子 Actor,并在根守护者完全终止后把 ActorSystem 的 isTerminated 状态置为 true。
重启(Restart)意味着什么
当一个 Actor 在处理某条消息时失败,失败原因可以归入三类:
- 系统性(编程)错误:针对这条特定消息的代码缺陷;
- (瞬时)外部资源失败:处理消息过程中依赖的外部资源暂时不可用;
- Actor 内部状态损坏。
除非失败原因能被明确识别,否则第三种原因(状态损坏)无法被排除——这直接导致一个结论:内部状态需要被清除。如果监督者判断其他子 Actor 或自身不受该状态损坏影响(例如有意识地应用了 error kernel pattern,即把易失败的状态隔离在最底层子 Actor 中),那么最佳选择就是重启该 Actor。
重启的执行方式是:创建底层 Behavior 类的一个新实例,用新实例替换子 Actor 的 ActorRef 内部那个失败的旧实例。这种"用特殊引用封装 Actor"的能力,正是 Actor 可以被替换而不改变其引用身份的核心理由。重启后新 Actor 继续处理其 mailbox 中的消息——也就是说,重启对外部不可见,唯一的例外是:导致失败的那条消息不会被重新处理(见下文"消息丢失")。
在 Classic 实现中,重启由 dungeon/FaultHandling.scala 的 faultRecreate 驱动:先调用旧实例的 aroundPreRestart(执行 preRestart 钩子),再清空旧 Actor 字段并递归地重启/终止子 Actor。文档也特别指出:Actor 类 preRestart 钩子的默认行为是在重启前终止所有子 Actor,但该钩子可以被覆写;递归重启只作用于钩子执行后仍然存活的子 Actor。
生命周期监控(Lifecycle Monitoring / DeathWatch)
在 Akka 中,生命周期监控通常被称为 DeathWatch。
与父子之间特殊的监督关系不同,任何 Actor 都可以监控任何其他 Actor。由于 Actor 自创建起就"完全存活",且重启对监督者之外不可见,因此可供监控的状态变化只有一个:从存活到死亡的转变。监控用于把一个 Actor 与另一个 Actor 绑定,使前者能对后者的终止做出反应——这与监督"对失败做出反应"形成对比:监控对终止(termination)做出反应,监督对失败(failure)做出反应。
Terminated 消息与 DeathPactException
生命周期监控通过给监控者发送 Terminated 消息实现,其默认行为是:如果未显式处理,则抛出特殊的 DeathPactException。
- 开始监听:调用
ActorContext.watch(targetActorRef) - 停止监听:调用
ActorContext.unwatch(targetActorRef)
一个非常重要的性质:无论监控请求与目标终止在时间上谁先谁后,Terminated 消息都会被投递——即使注册监控时目标已经死亡,你依然会收到消息。
在 Typed API 中,如果被 watch 的子 Actor 是因为失败而停止,父 Actor 会收到携带失败原因的 ChildFailed 信号;ChildFailed 继承自 Terminated,所以如果不区分"正常停止"与"失败停止",可以用 Terminated 统一处理。若父 Actor 不处理 Terminated,它自身将以 DeathPactException 失败。
Actor 与异常:消息、邮箱与 Actor 的处置
当 Actor 处理消息过程中抛出异常(例如数据库异常)时,需要分别理解三件事。
消息会怎样
处理中的这条消息会丢失。 它被从 mailbox 取出并交给当前 behavior 后,一旦抛出异常,不会被放回 mailbox。因此若想重试某条消息,必须自己捕获异常并重试流程。务必为重试次数设置上限,否则系统可能陷入 livelock(持续消耗 CPU 却毫无进展)。
mailbox 会怎样
mailbox 不受影响。 如果 Actor 被重启,同一个 mailbox 原样保留,其中所有尚未处理的消息都会保留下来。
Actor 会怎样
Actor 会先被挂起(suspended),随后启动监督流程。 依据监督者的决定,Actor 会被:
- Resume:仿佛什么都没发生,继续处理;
- Restart:清空内部状态,从零开始;
- Terminated:停止。
Classic 实现中,失败先让子 Actor 挂起并发送特殊的系统消息 Failed 给父 Actor;父 Actor 在 dungeon/FaultHandling.scala 的 handleFailure 中校验失败确实来自当前已知的子 Actor(通过 UID 防止旧子 Actor 的迟到消息),然后调用 actor.supervisorStrategy.handleFailure(...) 得到指令并执行。值得注意的是,监督相关的通信走独立的系统 mailbox,与用户消息的 mailbox 分离,因此监督事件与普通消息之间不存在确定性顺序——用户无法影响正常消息与失败通知的相对次序。
Typed API 实战:用 Behaviors.supervise 声明监督策略
Typed 文档 typed/fault-tolerance.md 给出了从概念到代码的完整落地方式。Typed 与 Classic 的一个关键差异:默认情况下,Typed Actor 抛出异常且未定义监督策略时会被停止;而 Classic Actor 默认会被重启。
要定制监督行为,用 Behaviors.supervise 包裹 Actor 的 behavior,典型做法是在父 Actor 孵化子 Actor 时包裹。下面的示例均来自 SupervisionCompileOnly.scala。
基础:重启与恢复
遇到 IllegalStateException 时重启:
Behaviors.supervise(behavior).onFailureIllegalStateException
改为恢复(忽略失败,继续处理下一条消息):
Behaviors.supervise(behavior).onFailureIllegalStateException
限制重启次数:时间窗口算法
更复杂的重启策略可以限制重启频率,例如"10 秒内最多重启 10 次":
Behaviors
.supervise(behavior)
.onFailureIllegalStateException)
withLimit 的语义(Scala API 定义于 typed/SupervisorStrategy.scala):maxNrOfRetries 是在 withinTimeRange 时间窗口内允许的重启次数上限,窗口结束且未达到上限时计数重置;一旦超过上限,子 Actor 被停止。底层的时间窗口算法在 Classic 的 ChildRestartStats.requestRestartPermission(FaultHandling.scala)中实现:窗口自第一次重启时开启,在窗口内累计重启次数,超出则拒绝(导致停止);窗口过后重新开始计数。maxNrOfRetries 为负值表示不限制(Typed 的 restart 默认 maxRestarts = -1),withinTimeRange 为 Duration.Inf 表示无时间窗口。
嵌套:不同异常不同策略
supervise 调用可以嵌套,为不同异常类型配置不同策略:
Behaviors
.supervise(Behaviors.supervise(behavior).onFailureIllegalStateException)
.onFailureIllegalArgumentException
包装 behavior(Wrapping Behaviors):状态变化场景
函数式风格中常用"换 behavior"来存储状态(例如计数器用 counter(count) 返回新 behavior):
object Counter {
sealed trait Command
case class Increment(nr: Int) extends Command
case class GetCount(replyTo: ActorRef[Int]) extends Command
def apply(): Behavior[Command] =
Behaviors.supervise(counter(1)).onFailure(SupervisorStrategy.restart)
private def counter(count: Int): Behavior[Command] =
Behaviors.receiveMessage[Command] {
case Increment(nr: Int) => counter(count + nr)
case GetCount(replyTo) => replyTo ! count; Behaviors.same
}
}
此时只需要在顶层包一层监督即可:每次返回的 behavior 都会被自动重新包裹上监督者,无需在每个 counter(count) 调用处重复包装。
重启与可变状态:务必用 factory
需要特别强调:当 behavior 被重启时,重新安装的是最初传给 Behaviors.supervise 的那个原始 Behavior。这意味着如果它包含可变状态,它必须是一个通过 Behaviors.setup 创建的工厂方法;使用面向对象风格(继承 AbstractBehavior)时,也总是建议通过 Behaviors.setup 创建(见 style-guide 的 Behavior factory method 一节)。函数式风格如果状态捕获在不可变参数中,通常不需要工厂。
父 Actor 重启时子 Actor 的处置
默认行为:停止子 Actor
子 Actor 通常在 Behaviors.setup 块中孵化,而父 Actor 重启时会重新执行 setup 块。为了避免每次父 Actor 重启都重复孵化新子 Actor 导致资源泄漏,默认情况下父 Actor 重启会停止其子 Actor:
def parent: Behavior[String] = {
Behaviors
.supervise[String] {
Behaviors.setup { ctx =>
val child1 = ctx.spawn(child(0), "child1")
val child2 = ctx.spawn(child(0), "child2")
Behaviors.receiveMessage[String] { msg =>
val parts = msg.split(" ")
child1 ! parts(0)
child2 ! parts(1)
Behaviors.same
}
}
}
.onFailure(SupervisorStrategy.restart)
}
保留子 Actor:withStopChildren(false)
如果希望父 Actor 重启时子 Actor 不受影响(重启后的父实例保留失败前同样的子 Actor),需要把 supervise 放进 setup 块内部,并使用 SupervisorStrategy.restart.withStopChildren(false):
def parent2: Behavior[String] = {
Behaviors.setup { ctx =>
val child1 = ctx.spawn(child(0), "child1")
val child2 = ctx.spawn(child(0), "child2")
Behaviors
.supervise {
Behaviors.receiveMessage[String] { msg =>
val parts = msg.split(" ")
child1 ! parts(0)
child2 ! parts(1)
Behaviors.same
}
}
.onFailure(SupervisorStrategy.restart.withStopChildren(false))
}
}
这样 setup 块只在父 Actor 首次启动时执行一次,重启时不再执行。withStopChildren 的语义定义于 typed/SupervisorStrategy.scala,默认为 true(停止子 Actor)。
PreRestart 信号:重启前的资源清理
被监督的 Actor 在重启前会收到 PreRestart 信号,给它一个清理已创建资源的机会,这与 Actor 停止时收到的 PostStop 信号类似。注意:重启不会发出 PostStop,所以通常需要同时处理 PreRestart 和 PostStop 才能完整清理资源。PreRestart 信号返回的 behavior 会被忽略。
def withPreRestart: Behavior[String] = {
Behaviors
.supervise[String] {
Behaviors.setup { ctx =>
val resource = claimResource()
Behaviors
.receiveMessage[String] { msg =>
val parts = msg.split(" ")
resource.process(parts)
Behaviors.same
}
.receiveSignal {
case (_, signal) if signal == PreRestart || signal == PostStop =>
resource.close()
Behaviors.same
}
}
}
.onFailureException
}
在 Classic 实现中,preRestart 钩子由 dungeon/FaultHandling.scala 的 faultRecreate 调用;如果 preRestart 自身抛异常,只能记录日志(best-effort),无法阻止重启流程。
让失败在层级中冒泡(Bubble Failures)
在某些场景下,把"失败后该怎么办"的决策权上推到 Actor 层级的高处是有用的——这在 Classic Actor 中本来就是默认工作方式。实现方式是:父 Actor watch 子 Actor。如果子 Actor 因失败而停止,父 Actor 收到携带失败原因的 ChildFailed 信号;ChildFailed 继承自 Terminated。若父 Actor 也不处理 Terminated,它会以 DeathPactException 失败,如此层层向上,直到最顶层的父 Actor 收到失败通知并决定如何处理。
这种机制使得:一个子 Actor 的失败可以逐层冒泡,每一层 Actor 停止的同时把失败告知更上层。但默认情况下,原始异常只对直接父 Actor 可见(这通常是一件好事——不泄露实现细节)。如果确实希望原始异常一路冒泡,可以在每一层处理 Terminated 信号并重新抛出该异常。
完整的可运行示例见 FaultToleranceDocSpec.scala:Worker 抛 RuntimeException → MiddleManagement watch 子 Actor 但不处理 Terminated,于是以 DeathPactException 失败 → Boss 用 supervise(...).onFailureDeathPactException 兜底重启整个中层。测试用例(同文件 FaultToleranceDocSpec.scala)验证了失败后系统最终恢复服务的能力。
Classic 监督策略源码解析:Decider 与 One-For-One / All-For-One
从异常到指令:Decider
每个监督者都配置了一个把异常映射为监督指令的函数(Decider,类型为 PartialFunction[Throwable, Directive])。注意该函数不接收失败 Actor 的身份作为输入——如果需要对不同子 Actor 应用不同策略,正确做法是增加一层监督,而不是在一个层级里塞进过多逻辑。
FaultHandling.scala 中的默认 Decider(defaultDecider):
case _: ActorInitializationException => Stop
case _: ActorKilledException => Stop
case _: DeathPactException => Stop
case _: Exception => Restart
即:ActorInitializationException、ActorKilledException、DeathPactException 停止子 Actor,其余 Exception 重启;若是 Error(Throwable 而非 Exception)则升级。SupervisorStrategy.handleFailure(FaultHandling.scala)是主入口:先通过 decider 得到指令,然后分别走 resumeChild、processFailure(restart=true)、processFailure(restart=false) 或返回 false 表示升级(由父 Actor 重新抛出异常)。Resume 的失败以 Warning 级别记录日志,Restart 与 Stop 以 Error 级别记录,Escalate 不在本级记录(由上层处理),可用 loggingEnabled 关闭,或覆写 logFailure 定制日志。
OneForOneStrategy 与 AllForOneStrategy
Akka 内置两类监督策略(FaultHandling.scala):
OneForOneStrategy:仅对失败的那个子 Actor 应用指令;默认策略,未显式指定时即使用它。AllForOneStrategy:一个子 Actor 失败时,把指令应用到所有子 Actor。
AllForOneStrategy 适用于子 Actor 之间耦合极紧、一个失败会影响其余功能(" inextricably linked")的场景。文档提醒:由于重启不清空 mailbox,失败时通常最好终止子 Actor 并由监督者通过 watch 生命周期显式重建;否则要确保任何 Actor 接收"重启前入队、重启后处理"的消息都没有问题。另外,正常的停止(非失败触发)不会自动连带终止其他子 Actor——除非监督者不处理 Terminated 从而以 DeathPactException 失败(取决于其监督者可能重启它,默认 preRestart 会终止所有子 Actor)。从 AllForOne 监督者下孵化临时 Actor 时,其升级的失败会影响所有常驻 Actor,若不希望如此,应加装中间监督者。
两种策略都支持 maxNrOfRetries(负数表示无限制,超限则停止子 Actor)与 withinTimeRange(Duration.Inf 表示无时间窗口),并遵循上文所述的时间窗口算法。此外,父 Actor 因失败被重启时会连带重启所有子 Actor;恢复(Resume)一个 Actor 会连带恢复其所有下属,终止同样递归作用于所有下属。
结语
监督与监控是 Akka 实现"弹性(elastic)与韧性(resilient)"的两根支柱:监督把失败处理从业务逻辑中剥离出来,通过父子层级把恢复决策递归地委派给合适的层级;DeathWatch 则在 Actor 之间建立生命周期观察关系,让应用能对终止事件做出反应。理解 Resume / Restart / Stop / Escalate 的精确语义、顶层守护者(/user、/system、/)的分工,以及 Typed 的 Behaviors.supervise 与 SupervisorStrategy 的配置方式,是构建健壮 Actor 应用的基础。进一步深入学习可继续阅读 typed/fault-tolerance.md 的完整示例,以及 supervision-classic.md 的 Classic 对照说明。