多节点集群
为静态多节点集群规划节点身份、地址、副本、存储、启动和就绪检查。
多节点部署的价值来自跨故障域的副本，而不是进程数量。节点必须使用同一制品和集群清单，但拥有唯一身份、独立状态和可达的 Transport 地址。
客户端 / 业务服务
|
TLS 与受控负载均衡
/ | \
节点 1 节点 2 节点 3
\ | /
私有节点间 Transport
磁盘/故障域 1 2 3（彼此独立）静态集群清单
三个节点的配置都必须包含相同的有序节点清单：
[cluster]
id = "prod-im-a"
listen_addr = "0.0.0.0:7000"
join_token = "从秘密系统注入"
initial_slot_count = 10
hash_slot_count = 256
slot_replica_n = 3
channel_replica_n = 3
nodes = [
{ id = 1, addr = "10.0.0.11:7000" },
{ id = 2, addr = "10.0.0.12:7000" },
{ id = 3, addr = "10.0.0.13:7000" }
]listen_addr 是本机绑定地址；nodes[].addr 是其他节点实际连接的地址。不要把 0.0.0.0、回环地址、短生命周期 Pod IP 或仅本机可解析的名称写进生产清单。
三节点、三副本没有节点余量
当 slot_replica_n = 3、channel_replica_n = 3 且只有三个可选数据节点时，任意一个节点不可用都会让新的写探针因“候选节点少于副本数”而失败，其他节点的 /readyz 会返回 503。Raft 多数仍在不等于节点仍适合接收完整新流量。若故障目标要求失去一台后仍保持三副本放置候选，至少需要四个合格数据节点，并继续验证路由、容量和恢复行为。
每个节点分别设置：
[node]
id = 1 # 节点 2 和 3 分别使用 2、3
data_dir = "/var/lib/wukongim"
[api]
listen_addr = "0.0.0.0:5001"
external_tcp_addr = "im.example.com:5100"
external_wss_addr = "wss://im.example.com/ws"共享负载均衡地址可以写入每个节点的 external_*；如果按节点返回地址，则必须保证每个值都可从目标客户端网络访问。
一致与唯一
| 必须一致 | 必须唯一 |
|---|---|
| 集群 ID、节点清单、Hash Slot 数 | 节点 ID |
| 副本策略、协议和制品版本 | 数据目录和持久卷 |
| Join Token 的有效值 | Transport 监听实例和广告地址 |
| 生产安全与观察策略 | 节点级日志、指标标签和故障域 |
已有数据后，不要随意改变集群 ID、节点 ID、Hash Slot 或副本设置。节点加入、迁移、扩缩容属于受控运维流程，不是编辑一个 TOML 并重启全部节点。
启动前
- 确认所有节点运行同一个制品摘要和配置版本。
- 验证每个节点能双向连接其他节点的
7000Transport。 - 验证 API、Gateway 和 Manager 端口没有冲突，外部地址从消费者网络可达。
- 挂载并检查每个节点的独立持久盘，确认容量、权限和告警。
- 替换固定凭据，关闭 Benchmark/Debug，并限制 Manager、指标和诊断网络。
- 在所有节点准备完成后启动服务；本页三节点、三副本示例需要三个节点都可用才能通过完整写就绪探针。
就绪与切流
对每个节点独立检查：
curl --fail http://10.0.0.11:5001/readyz
curl --fail http://10.0.0.12:5001/readyz
curl --fail http://10.0.0.13:5001/readyz只有返回 200 且 {"ready":true} 的节点才能进入 API/Gateway 后端池。/healthz 不能替代该检查。发布完成后还应验证：
/route返回的客户端地址真实可达；- 三节点在 Manager/指标中可见，节点身份没有重复；
- 发送、持久化、接收和重连同步完成一条端到端消息；
- 在预生产环境停止一个节点后，记录剩余节点的
/readyz状态与reason，并确认它符合容量和故障目标； - 节点恢复后，路由和副本状态回到预期。
用 Compose 证明配置，不证明生产
仓库 docker-compose.yml 和 docker/conf/node*.toml 是可执行的三节点开发参考，适合验证清单、端口、就绪和观察面。它们的固定凭据、Benchmark/Debug 能力、同机容器和本地目录不能证明独立故障域、生产安全或容量。
切流前继续完成生产检查清单。