本文详解 hazelcast 在微服务（grpc 场景）中因 tcp-ip 发现配置不当导致集群无法组网的问题，提供 yaml 配置缺陷分析、java bean 动态配置替代方案及关键注意事项。
本文详解 hazelcast 在微服务（grpc 场景）中因 tcp-ip 发现配置不当导致集群无法组网的问题，提供 yaml 配置缺陷分析、java bean 动态配置替代方案及关键注意事项。
在基于 Spring Boot 的微服务架构中集成 Hazelcast 实现分布式缓存时，一个常见但易被忽视的问题是：两个服务虽共享同一集群名、启用 TCP-IP 发现，却始终无法形成多节点集群。如日志所示，[127.0.0.1]:9701 反复尝试连接 127.0.0.1:9702 失败并加入黑名单，最终仅形成单节点集群（Members {size:1}）。根本原因在于 YAML 配置存在语义错配与静态化缺陷。
? 问题核心：YAML 配置的三大误区
member-list 误用为“本机地址”
gRPC Server 的 hazelcast.yml 中将 127.0.0.1:9701 和 127.0.0.1:9702 同时写入 member-list，但该列表应声明其他成员的可连接地址，而非自身。Hazelcast 启动时会主动向列表中所有地址发起连接请求——此时 9702 尚未启动，必然触发 Connection refused。Client 端缺失明确的 member-list 或 public-address
Client 的 YAML 仅启用了 tcp-ip，却未指定 member-list（如 127.0.0.1:9701），导致其无法发现 Server；同时 public-address: 127.0.0.1:9702 仅用于对外宣告地址，不参与发现逻辑。端口自动分配与显式端口冲突
Server 配置了 port-count: 20 + auto-increment: true，但又强制 port: 9701，而 Client 固定使用 9702 ——若 Server 实际绑定端口非 9701（如被占用后自增为 9703），则 Client 的硬编码地址将彻底失效。
✅ 推荐方案：Java Config Bean 替代 YAML（更可控、更清晰）
摒弃易出错的 YAML 静态配置，改用 Java Bean 显式定义网络拓扑，可精准控制每个节点的角色与发现行为：
@Configuration
public class HazelcastConfiguration {
@Bean
public Config hazelcastConfig() {
NetworkConfig networkConfig = new NetworkConfig();
// 禁用多播（必须）
networkConfig.getJoin().getMulticastConfig().setEnabled(false);
// 启用 TCP-IP 发现，并指定 Server 地址（Client 角色）
TcpIpConfig tcpIpConfig = new TcpIpConfig();
tcpIpConfig.setEnabled(true);
tcpIpConfig.addMember("127.0.0.1:9701"); // 关键！指向已知 Server 地址
networkConfig.getJoin().setTcpIpConfig(tcpIpConfig);
// 显式设置本机监听端口（Server 角色需固定，Client 可设为 0 让系统分配）
networkConfig.setPort(9702); // Client 使用 9702，确保与 Server 不冲突
// 构建完整 Config
return new Config()
.setClusterName("banks_data")
.setNetworkConfig(networkConfig)
.addMapConfig(new MapConfig("banks-data-cache")
.setBackupCount(1)
.setMaxIdleSeconds(300)
.setEvictionConfig(new EvictionConfig()
.setEvictionPolicy(EvictionPolicy.LRU)
.setSize(10000)
)
);
}
}? 关键实践提示：
- Server 端：member-list 应为空（或仅含其他 Server），自身地址由 port + public-address 宣告；
- Client 端：member-list 必须包含至少一个活跃 Server 地址（如 127.0.0.1:9701），且 port 建议显式指定避免冲突；
- 本地开发慎用 127.0.0.1：容器化部署时需替换为服务名（如 hazelcast-server）或 Kubernetes Headless Service DNS；
- 防火墙与端口检查：确保 9701/9702 未被占用，且无防火墙拦截（telnet 127.0.0.1 9701 验证连通性）。
? 总结
Hazelcast 集群组建失败，本质是发现机制配置与实际运行时拓扑不匹配。YAML 的声明式语法容易掩盖地址语义（谁连谁、谁被谁连），而 Java Config 能通过 addMember() 精确表达“Client 主动发现 Server”的拓扑意图。务必遵循“Server 对外宣告、Client 主动寻址”原则，并在日志中重点观察 TcpIpJoiner 和 Connecting to /xxx 行为——这才是集群健康的直接证据。
