Akka 到 Apache Pekko 迁移：许可证、包名与生态替换的完整路径

- Akka 2.6.x：最后一个 Apache 2.0 版本，社区仍在用，但无新特性与官方补丁
- Akka 2.7 / 2.8 / 2.9+：BSL 1.1，商业生产需授权
- Pekko 1.0.x：对应 Akka 2.6.x 的功能面，Apache 2.0
- Pekko 1.1.x：补齐 Scala 3 支持、若干 Streams 与 Cluster 修复
- 命名空间：com.typesafe.akka.* → org.apache.pekko.*
- 组织坐标：com.typesafe.akka → org.apache.pekko
- 配置文件前缀：akka.* → pekko.*（默认 reference.conf 同步改名）

# 列出所有含 akka 的依赖（含传递依赖）及其版本
sbt "dependencyTree" | grep -i akka | sort -u
# 只看被版本仲裁淘汰的冲突项
sbt "evicted"
# 找出是谁把 akka 拖进来的
sbt "whatDependsOn com.typesafe.akka akka-actor_2.13 2.6.20"

# Maven 侧等价操作
mvn dependency:tree -Dincludes=com.typesafe.akka:*

审计结论的三种走向：
1. 全是直接依赖 → 直接改坐标，成本最低
2. 有传递依赖但可排除 → 加 excludeRules，再评估该库是否真需要 Akka
3. 有传递依赖且不可排除 → 该库是迁移阻塞项，需先升级或替换它
   （典型：老版监控 agent、老版 Play/Akka HTTP 插件、自研内部库）

// build.sbt：迁移前
libraryDependencies ++= Seq(
  "com.typesafe.akka" %% "akka-actor-typed"  % "2.6.20",
  "com.typesafe.akka" %% "akka-cluster-typed" % "2.6.20",
  "com.typesafe.akka" %% "akka-stream"        % "2.6.20",
  "com.typesafe.akka" %% "akka-http"          % "10.2.10",
  "com.lightbend.akka" %% "akka-stream-alpakka-kafka" % "3.0.4"
)

// build.sbt：迁移后
libraryDependencies ++= Seq(
  "org.apache.pekko" %% "pekko-actor-typed"   % "1.1.2",
  "org.apache.pekko" %% "pekko-cluster-typed" % "1.1.2",
  "org.apache.pekko" %% "pekko-stream"        % "1.1.2",
  "org.apache.pekko" %% "pekko-http"          % "1.1.0",
  "org.apache.pekko" %% "pekko-connectors-kafka" % "1.1.0"
)

常见坐标映射表：
akka-actor / akka-actor-typed        → pekko-actor / pekko-actor-typed
akka-cluster / -typed / -sharding    → pekko-cluster / -typed / -sharding
akka-stream / akka-stream-typed      → pekko-stream / pekko-stream-typed
akka-http / akka-http-spray-json     → pekko-http / pekko-http-spray-json
akka-persistence / -typed            → pekko-persistence / -typed
akka-persistence-jdbc (Lightbend)    → pekko-persistence-jdbc
akka-management / -cluster-http      → pekko-management / -cluster-http
akka-discovery                       → pekko-discovery
akka-slf4j / akka-testkit            → pekko-slf4j / pekko-testkit

# 粗粒度批量替换（先在分支上跑，务必 review diff）
rg -l 'com\.typesafe\.akka' --type scala | xargs sed -i '' \
  's/com\.typesafe\.akka/org.apache.pekko/g'
rg -l 'import akka\.' --type scala | xargs sed -i '' \
  's/import akka\./import org.apache.pekko./g'

// scalafix 规则：把 import 与字符串常量一起改写
import scalafix.v1.*

class AkkaToPekko extends SemanticRule("AkkaToPekko") {
  override def fix(implicit doc: SemanticDocument): Patch =
    doc.tree.collect {
      case imp: Import if imp.toString.contains("akka.") =>
        Patch.replaceTree(imp, imp.toString.replace("akka.", "org.apache.pekko."))
      case lit: Lit.String if lit.value.contains("com.typesafe.akka") =>
        Patch.replaceTree(lit, lit.toString.replace("com.typesafe.akka", "org.apache.pekko"))
    }.asPatch
}

# 迁移前
akka {
  actor.provider = cluster
  remote.artery.canonical.hostname = "0.0.0.0"
  cluster.seed-nodes = ["pekko://OrderSystem@10.0.0.1:25520"]
}
# 迁移后
pekko {
  actor.provider = cluster
  remote.artery.canonical.hostname = "0.0.0.0"
  cluster.seed-nodes = ["pekko://OrderSystem@10.0.0.1:25520"]
}

import com.typesafe.config.ConfigFactory

val cfg = ConfigFactory.load()
// 打印最终生效的配置树，肉眼核对前缀
println(cfg.root().render())

// 主动断言关键配置项，让「静默回落」变成启动期失败
require(cfg.hasPath("pekko.actor.provider"), "缺少 pekko.actor.provider 配置")
require(cfg.getString("pekko.actor.provider") == "cluster", "provider 必须是 cluster")
require(cfg.getStringList("pekko.cluster.seed-nodes").size() > 0, "seed-nodes 不能为空")

# application.conf 中的序列化绑定：类名必须逐条改名
pekko {
  actor {
    serialization-bindings {
      "com.example.OrderEvent" = jackson-json   # 业务类不用改
      "akka.actor.DeadLetter"  = pekko-json     # 框架类要改
    }
    serializers {
      jackson-json = "com.example.JacksonSerializer"  # 自实现的不改
      pekko-json   = "org.apache.pekko.serialization.jackson.JacksonJsonSerializer"
    }
  }
}

持久化事件的兼容性边界：
- journal 里存的是「事件对象序列化后的字节」+ manifest 字符串
- manifest 默认是事件类的全限定名（FQCN）
- 若事件类在 akka 包下（罕见），换包名会读不出老事件
- 若事件类在业务包下（常见），字节可读，但 manifest 需能解析
- 对策：显式设置 event-adapters 或给事件类固定 manifest
- Cluster Sharding 的 entity id / shard 元数据同样含 FQCN，跨版本不通用

// Pekko Connectors Kafka：与 Alpakka 的 API 几乎逐字对应
import org.apache.pekko.kafka.scaladsl.{Consumer, Producer}
import org.apache.pekko.kafka.{ConsumerSettings, Subscriptions}

val done = Consumer
  .committableSource(consumerSettings, Subscriptions.topics("orders"))
  .mapAsync(8)(msg => process(msg.record.value()).map(_ => msg.committableOffset))
  .run()

// build.sbt：在迁移期强制隔离，防止传递依赖把 Akka 拖回来
excludeDependencies ++= Seq(
  ExclusionRule("com.typesafe.akka"),
  ExclusionRule("com.lightbend.akka")
)

// 若某模块只有 Akka 版本、短期内无法替换，用它自己的类加载器隔离
// 或者把它降级为独立进程，通过 HTTP/Kafka 边界通信
dependencyOverrides += "com.typesafe.akka" %% "akka-actor" % "2.6.20"

混装冲突的典型症状：
- ClassCastException: akka.actor.ActorRef cannot be cast to org.apache.pekko.actor.ActorRef
- 配置被后加载的 reference.conf 覆盖，行为随机漂移
- 日志出现两套 ActorSystem 的启动/关闭记录
- 序列化器查找失败：NoClassDefFoundError 或 SerializationException

集群迁移的硬约束：
- 同一集群内所有节点必须使用同一实现（全 Akka 或全 Pekko）
- 跨集群通信（Cluster Client / Sharding Proxy）同样要求实现一致
- 滚动升级不可行：需要整体切换或蓝绿两套集群
- 持久化层面相对宽松：表结构兼容，可共享数据库
- 消息层面严格：远程消息里的 FQCN 需两端一致

可灰度的边界：
✓ 单个服务独立切换（服务之间通过 HTTP/Kafka 通信）
✓ 无状态服务随时可切
✗ 同一个 Actor 集群内部逐节点切换
✗ 依赖远程消息类名的跨服务 Actor 通信

迁移阶段划分：
阶段 0：依赖审计——列出直接与传递的 Akka 依赖，标记是否有 BSL 版本
阶段 1：构建替换——坐标、包名、配置前缀全量改写，编译通过
阶段 2：单测回归——TestKit 用例跑通，序列化往返测试
阶段 3：本地/预发验证——集群启动、分片再平衡、持久化读写
阶段 4：灰度上线——单实例 → 单可用区 → 全量（无状态服务）
阶段 5：清理——移除 dependencyOverrides、删除混装排除规则

// 迁移期用抽象隔离，让「实现选择」成为一个可切换的开关
trait ClusterOps[F[_]] {
  def join(seedNodes: List[String]): F[Unit]
  def leave(): F[Unit]
}
// akka 实现与 pekko 实现分处不同 module，由构建配置决定注入哪一个
// 好处：迁移期可 A/B 对比，回滚只需换回依赖而非改代码

灰度检查项：
- 启动日志确认使用 Pekko 的 reference.conf（打印 pekko.version）
- ActorSystem 名称与 seed-nodes scheme 正确（pekko://）
- 集群成员数与分片分布符合预期
- 持久化读写：写入新事件 → 重启 → 读取历史事件
- 序列化：跨服务消息往返无 NoClassDefFoundError
- 指标：mailbox 深度、消息吞吐、GC 与迁移前基线对比
回滚前提：
- 事件 manifest 稳定（老版本可读新版本写的事件）
- 数据库表结构未做破坏性变更
- 依赖排除规则可一键撤销（放在独立 sbt 文件或 profile 中）

# 回滚验证脚本：用老版本镜像读取新版本写入的 journal
kubectl set image deploy/order-service app=registry/order-service:akka-2.6.20
kubectl rollout status deploy/order-service
kubectl logs deploy/order-service --since=5m | grep -i 'recovery\|journal'

import org.apache.pekko.persistence.jdbc.query.scaladsl.JdbcReadJournal
import org.apache.pekko.persistence.query.PersistenceQuery

// 用 Pekko 的读侧回放老版本写入的历史事件，验证 manifest 可解析
val readJournal: JdbcReadJournal =
  PersistenceQuery(system)
    .readJournalFor[JdbcReadJournal](JdbcReadJournal.Identifier)

val recovered: Source[OrderEvent, NotUsed] =
  readJournal
    .currentEventsByPersistenceId("order-42", 0L, Long.MaxValue)
    .collect { case e: EventEnvelope if e.event.isInstanceOf[OrderEvent] =>
      e.event.asInstanceOf[OrderEvent]
    }

recovered.runWith(Sink.seq).map { events =>
  require(events.nonEmpty, "读不到历史事件，manifest 可能不兼容")
  events
}