Akka ClusterSharding：如何停止集群分片中的所有Actor？

以下是不同场景下可行的实现方式：

1. 官方内置API实现（推荐，适配Akka 2.6+版本） #

• 直接调用ClusterSharding提供的passivateAll方法，该方法是Akka官方为批量停服场景内置的能力，会自动向该Shard类型下所有运行中的实体发送Passivate消息，等待实体处理完当前请求后优雅终止，完全符合集群Sharding的生命周期管控规范。
  代码示例：

// Scala 示例
val shardRegion: ActorRef[ClusterSharding.Command] = ClusterSharding(system).shardRegion(YourEntity.TypeKey)
// 触发全量实体优雅停服
shardRegion ! ClusterSharding.PassivateAll()

// Java 示例
ActorRef<ClusterSharding.Command> shardRegion = ClusterSharding.get(system).shardRegion(YourEntity.TYPE_KEY);
shardRegion.tell(ClusterSharding.passivateAll());

2. 自定义实现（适配Akka 2.6以下低版本） #

• 低版本Akka没有内置passivateAll接口，可通过查询Shard状态+批量发送停服指令的方式实现：
  1. 向目标ShardRegion发送ClusterSharding.GetShardRegionState指令，查询当前所有存活的Shard以及对应实体ID列表
  2. 遍历所有实体ID，逐个发送Passivate消息或者自定义的停止指令
     代码示例：

// Scala 示例
shardRegion ! ClusterSharding.GetShardRegionState { state =>
  // 遍历所有Shard下的所有实体ID
  state.shards.foreach { shardState =>
    shardState.entityIds.foreach { entityId =>
      // 给每个实体发送停服指令
      shardRegion ! ClusterSharding.EntityEnvelope(entityId, ClusterSharding.Passivate())
    }
  }
}

该方案还支持灵活调整停止节奏，比如分批次添加延时停止，避免批量停服瞬间给集群带来过大压力。

3. 下线全量Shard服务场景实现 #

• 如果需求是不仅停止所有运行中的实体，还要下线该Shard类型的整个服务，可直接调用unregister方法：

// 注销对应类型的Shard注册，自动停止所有关联的Shard和实体
ClusterSharding(system).unregister(YourEntity.TypeKey)

该操作会先停止该Shard类型下所有运行中的实体和Shard实例，再清除集群中该Shard类型的注册信息，适合业务下线的场景。

注意事项 #

• 所有Passivate操作默认有超时阈值，可通过配置akka.cluster.sharding.passivate-timeout或者调用PassivateAll时自定义超时参数调整，避免异常实体卡住整体停服流程。
• 如果实体是持久化Actor，停止前要确认状态已经正确刷写到持久化存储，避免数据丢失。
• 批量停止过程中如果有新请求发送到已停止的实体，ClusterSharding会自动重新拉起对应实体，若要彻底避免实体重启，需要先切走前端流量再执行停止操作。

内容的提问来源于stack exchange，提问作者Karan Khanna