Cluster 集群模块

能力概览

• 节点发现：通过 seedNodes 入网，收到成员表后继续连接新发现节点，最终收敛为全连接。
• 节点缓存：本地缓存节点快照，可查询 self()、nodes()、node(nodeId)。
• 广播模式：默认 broadcast() 为可靠广播；也支持 broadcastBestEffort()。
• 传输安全：握手时校验 clusterName + clusterSecret(HMAC)，不匹配立即拒绝。
• 高性能边界：二进制帧协议、有界队列、独立监听线程池，避免业务监听器阻塞 IO 线程。

初始化

import yueyang.vostok.Vostok;
import yueyang.vostok.cluster.VKClusterConfig;

Vostok.Cluster.init(new VKClusterConfig()
    .clusterName("prod-order")
    .clusterSecret("replace-with-strong-shared-secret")
    .nodeId("order-node-01")
    .bindHost("0.0.0.0")
    .bindPort(18888)
    .advertiseHost("10.0.0.12")
    .advertisePort(18888)
    .seedNodes("10.0.0.10:18888", "10.0.0.11:18888")
    .label("zone", "sh-a")
    .label("service", "order")
);

boolean ready = Vostok.Cluster.awaitReady(5000);
System.out.println("cluster ready = " + ready);
System.out.println(Vostok.Cluster.self().getNodeId());

自动发现与节点状态

Cluster 运行时会缓存全部已知节点快照。节点状态按如下状态机推进：

JOINING -> ALIVE -> SUSPECT -> DEAD
                     \------> LEFT

• JOINING：握手刚完成，成员表还在收敛。
• ALIVE：心跳与成员同步正常。
• SUSPECT：超过 suspectTimeoutMs 未见心跳，先进入怀疑态，避免短暂网络抖动直接判死。
• DEAD：超过 deadTimeoutMs 仍未恢复。
• LEFT：节点主动关闭并广播离场帧。

List<VKClusterNode> snapshot = Vostok.Cluster.nodes();
for (VKClusterNode node : snapshot) {
    System.out.println(node.getNodeId() + " -> " + node.getStatus());
}

VKClusterNode peer = Vostok.Cluster.node("order-node-02");
if (peer != null && peer.getStatus() == VKClusterNodeStatus.ALIVE) {
    // 可以安全参与广播目标集合
}

广播与订阅

广播载荷固定为 topic + byte[]。订阅按 topic 精确匹配，不支持通配符。

import java.nio.charset.StandardCharsets;

VKClusterSubscription sub = Vostok.Cluster.on("order.created", message -> {
    String body = new String(message.getPayload(), StandardCharsets.UTF_8);
    System.out.println(message.getFromNodeId() + ": " + body);
});

VKClusterBroadcastResult result = Vostok.Cluster
    .broadcastReliable("order.created", "{\"id\":1001}".getBytes(StandardCharsets.UTF_8))
    .get();

System.out.println(result.getMode());
System.out.println(result.getTargetedNodes());
System.out.println(result.getAckedNodes());
System.out.println(result.getFailedNodes());

sub.cancel();
// 或者：Vostok.Cluster.off(sub);
// 或者：Vostok.Cluster.offAll("order.created");

两种广播模式

可靠广播 ACK 语义

可靠广播中的 ACK 表示“远端节点已经完成协议解析，并成功放入本地监听分发队列”。它不等价于业务回调执行成功，因此业务监听器内部仍应自行做好幂等与异常保护。

API 速查

VKClusterConfig 关键配置

运行时统计

Vostok.Cluster.stats() 返回当前节点的统计快照，可直接接入监控：

VKClusterStats stats = Vostok.Cluster.stats();
System.out.println(stats.getTotalNodes());
System.out.println(stats.getAliveNodes());
System.out.println(stats.getOpenConnections());
System.out.println(stats.getSentMessages());
System.out.println(stats.getReceivedMessages());
System.out.println(stats.getReliableRetries());
System.out.println(stats.getQueueDrops());
System.out.println(stats.getAuthFailures());
System.out.println(stats.getProtocolErrors());

• queueDrops：发送队列或监听分发队列满导致的快速丢弃次数。
• authFailures：握手 HMAC 或 clusterName 校验失败次数。
• protocolErrors：非法帧、协议版本不兼容、非法长度等协议异常次数。

生产建议

• 同一集群内节点数建议控制在 100 以内，首版按此规模优化。
• clusterSecret 建议使用高熵随机串，并与应用配置中心统一下发。
• advertiseHost 必须配置为其他节点可达地址，不要直接复用容器内环回地址。
• 业务监听器请尽量短平快；耗时逻辑建议在回调中再转交自己的业务线程池。
• 可靠广播是至少一次语义，业务层需要接受重复投递并保持幂等。
• 若只做弱一致通知，优先使用 broadcastBestEffort()，避免无意义重试。

错误码

关闭

Vostok.Cluster.close();

关闭时会尽量向已连接节点发送 LEAVE 帧，并等待短暂时间让对端将本节点状态推进到 LEFT。