EC2与Docker环境下Akka Cluster节点未注册问题求助及架构说明

结合你描述的场景（Scalatra启动、多模块Actor系统、集群事件订阅），这类问题90%以上都和网络可达性、Akka核心配置、容器/EC2网络规则相关，我给你梳理几个关键排查和修复步骤：

1. 先把Akka Cluster的核心配置拉到正确轨道上 #

这是最容易踩坑的地方，Docker容器内部的网络和EC2主机网络是隔离的，绝对不能用容器内部的IP/hostname来配置Akka：

• 必须将akka.remote.artery.canonical.hostname设置为EC2实例的内网IP（同VPC集群）或公网IP（跨VPC），不能用localhost或者容器内部的随机IP；
• akka.remote.artery.canonical.port要和Docker映射的端口一致，同时确保这个端口在你提到的端口限制范围内；
• 种子节点akka.cluster.seed-nodes的地址必须是其他节点能直接访问到的（同样用EC2实例IP+映射端口）。

给你一个参考配置：

akka {
  actor {
    provider = cluster  # 必须启用集群Provider
  }
  remote {
    artery {
      canonical {
        hostname = "10.0.1.123"  # 替换成你的EC2实例内网IP
        port = 2551  # 对应Docker映射的端口
        # 如果有端口范围限制，加上这行
        port-range = 2551-2560
      }
    }
  }
  cluster {
    seed-nodes = [
      "akka://ClusterSystem@10.0.1.123:2551",  # 种子节点的EC2 IP+端口
      "akka://ClusterSystem@10.0.1.124:2551"
    ]
    # 可选：缩短节点状态检测超时，方便快速看到问题
    failure-detector {
      acceptable-heartbeat-pause = 10s
    }
  }
  # 开启调试日志，方便排查连接问题
  loglevel = DEBUG
  remote.log-remote-lifecycle-events = on
}

2. 检查Docker端口映射与EC2安全组规则 #

• Docker端口映射：启动容器时必须把Akka远程端口映射到EC2主机，比如：

  docker run -d -p 2551:2551 your-scalatra-akka-image
  

  如果你用了随机端口（-p 2551），那Akka配置里的port要设为0，同时确保port-range在允许的范围内。
• EC2安全组：必须开放Akka远程端口的入站规则，源地址设置为集群所有EC2实例的IP段（比如同VPC的CIDR：10.0.0.0/16），绝对不能只允许localhost或者单个IP，不然跨节点连不上。

3. 确认ServletContextListener中Actor系统的初始化逻辑 #

• 确保在Scalatra的ServletContextListener中，ActorSystem是在配置完全加载后才创建的，不要提前初始化导致配置未生效；
• 每个节点只能有一个属于集群的ActorSystem，排查是否有代码意外创建了多个ActorSystem（比如不同模块重复初始化），这会导致集群注册冲突；
• 在Listener中添加初始化日志，打印ActorSystem的名称、配置的hostname/port，确认加载的是你预期的配置。

4. 利用集群事件订阅定位问题 #

既然你已经订阅了MemberJoin/Up事件，那就把日志打细：

• 在MasterActor中收到MemberJoined事件时，打印完整的节点地址（member.address），确认是否有节点发送了Join请求；
• 如果收到UnreachableMember事件，说明节点之间能建立连接但心跳超时，大概率是网络延迟或者安全组规则有问题；
• 如果完全没收到Join事件，说明节点根本没连上种子节点，回去检查配置和网络。

5. Docker网络模式的特殊处理 #

如果你用了Docker的host网络模式（--net=host），容器会直接使用EC2主机的网络栈，此时Akka配置的hostname可以直接用EC2 IP，不需要端口映射，但要注意端口冲突问题；生产环境更推荐用默认桥接模式，配合正确的端口映射和安全组规则。

内容的提问来源于stack exchange，提问作者John Mullins