这页专门解释一个最近很容易让人困惑的新概念：

• ClusterBus
• 集群控制面
• loopback / redis transport
• 为什么启动日志里会出现 集群控制面已启用

一句话先说清楚

HNCore 里的“集群控制面”不是 GUI 面板，也不是网页后台。

它指的是 HNCore 新提供的一层 统一集群通信基础设施，主要给下游插件复用，例如：

• HNAttribute 的跨服 reload
• HNAttribute 的跨服 refresh-player
• HNAttribute 的 debug / perf reset 广播
• 以后其他 HN 系列插件的跨服控制消息

它到底包含什么

当前 HNCore 里，集群控制面主要由这些部分组成：

• ClusterBus：统一消息总线入口
• ClusterActionRegistry：注册 namespace/action 动作处理器
• ClusterStatusService：提供当前节点、transport、metrics 等状态快照
• ClusterPingService：提供 ping/pong 连通性测试
• RedisClusterTransport：真正跨服时使用 Redis Pub/Sub
• LocalLoopbackTransport：Redis 不可用时的本地回环 transport

可以把它理解成：

• SharedPubSubService 更像“底层 Redis 通道能力”
• ClusterBus 更像“面向业务模块的统一集群控制层”

启动日志是什么意思

你可能会看到类似：

[HNCore] [警告] cluster.node-id 未配置，当前已回退为 paper@25565；多服环境请在 storage.yml 中为每台服设置唯一 node-id
[HNCore] [信息] 集群控制面已启用: nodeId=paper@25565, transport=loopback, channel=cluster.bus

这两句分别表示：

1）cluster.node-id 未配置

HNCore 需要知道“我这台服在集群里叫什么”。

如果你没有显式配置：

cluster:
  node-id: "lobby-1"

它会自动回退为：

服务器名@端口

例如：

paper@25565

这适合单机测试，但多服正式环境建议你为每台服手动配置唯一值。

2）transport=loopback

这表示：

• 当前 ClusterBus 已经建立起来了
• 但没有接到真正的跨服 Redis transport
• 所以消息只会在本服进程内回环
• 适合本地自测 handler / ping / status 流程
• 不能跨服

如果你想真正跨服，通常应该看到：

transport=redis

这个“控制面”在哪里可见

1）控制台启动日志

第一处入口就是启动日志本身。

2）命令：/hncore cluster status

这是最直接的可见入口：

/hncore cluster status

它会显示：

• 当前节点 ID
• requested transport
• 当前实际 transport
• channel
• ClusterBus 是否可用
• setup hint
• 已注册的 namespace / action
• published / received / handled / ignored / decode-fail 等 metrics

如果你只是想回答“现在是不是已经真正接上跨服总线了”，优先看这个命令。

3）命令：/hncore cluster ping

还可以直接做连通性检测：

/hncore cluster ping
/hncore cluster ping <nodeId>

语义分别是：

• ping：广播，收集超时窗口内所有回包节点
• ping <nodeId>：定向测试某个节点

如果当前还是 loopback，那它只能验证本服本进程内流程，不代表真实跨服已经可用。

配置位置

都在：

plugins/HNCore/storage.yml

新增的 cluster 配置节是：

cluster:
  node-id: ""
  transport: auto
  channel: "cluster.bus"
  ping-timeout-ms: 1500

字段说明

node-id

当前服务器在集群中的唯一标识。

多服正式环境建议显式填写，例如：

node-id: "lobby-1"

transport

可选值：

• auto
• redis
• loopback

语义：

• auto：优先 Redis，Redis 不可用就回退 loopback
• redis：强制要求 Redis；Redis 不可用时 ClusterBus 会保持不可用
• loopback：强制只走本地回环，不跨服

channel

ClusterBus 逻辑频道名。

如果真正走 Redis，最终发到 Redis 时还会叠加：

storage.redis.channel-prefix

所以多服要互通时，除了 Redis 地址一致，cluster.channel 和 storage.redis.channel-prefix 也应保持兼容。

ping-timeout-ms

/hncore cluster ping 默认等待回包的时间窗口，单位毫秒。

怎样才能从 loopback 变成 redis

最常见的前提是：

storage:
  redis:
    enabled: true
    host: 127.0.0.1
    port: 6379

cluster:
  node-id: "lobby-1"
  transport: auto
  channel: "cluster.bus"

然后执行：

/hncore reload
/hncore cluster status

如果 Redis 真的可用，通常你会看到：

• ClusterBus: 可用
• transport=redis
• setup hint 不再提示 loopback 回退

和 /hncore status 有什么区别

/hncore status

偏向查看：

• 共享数据库
• 共享存储 MySQL
• 共享存储 Redis
• 共享键值后端
• 共享消息总线（Pub/Sub）
• 共享物品库

/hncore cluster status

偏向查看：

• ClusterBus 节点 ID
• transport / channel
• setup hint
• action registry
• cluster metrics
• ping/pong 这一层的运行状态

简单说：

• 想看 Redis 有没有连上：先看 /hncore status
• 想看业务层集群控制面有没有真正就绪：看 /hncore cluster status

和 HNAttribute 的关系

HNAttribute 现在的集群同步已经迁移到 HNCore ClusterBus 上。

所以现在：

• /hnattr reload cluster
• /hnattr refresh <player> cluster
• /hnattr debug basic|off|reset cluster
• /hnattr perf reset cluster

都会通过 HNCore 的 ClusterBus 广播。

这也意味着，排查 HNAttribute 跨服问题时，应该优先看：

/hncore cluster status
/hncore status

而不是先去找 HNAttribute 自己有没有单独 Redis 开关。

最常见的三种状态

1）transport=loopback

表示：

• ClusterBus 已建立
• 仅本服本进程回环
• 适合单服测试
• 不跨服

2）transport=redis

表示：

• ClusterBus 已真正接上 Redis transport
• 可以跨服广播
• 这是多服正式环境最常见的目标状态

3）ClusterBus 不可用

通常表示：

• 你强制写了 transport=redis
• 但 Redis 当前不可用

这时应先修复 storage.redis.*，再执行：

/hncore reload

推荐排查顺序

如果你想确认“为什么集群广播没跨服”，最稳的顺序是：

/hncore status
/hncore cluster status
/hncore cluster ping

重点看：

1. storage.redis.enabled 是否为 true
2. 共享 Redis 是否真的 active
3. 当前 transport 是不是 redis
4. cluster.node-id 是否为唯一值
5. 多台服的 cluster.channel / channel-prefix 是否兼容

建议联动阅读

• storage.yml 配置说明
• 命令说明
• HNCore Java API
• HNAttribute 集成与 API