Redis Cluster 容器部署时 cluster-announce-ip 怎么填写节点可达地址

Redis Cluster 放进 Docker 或其他 NAT 网络后，最典型的故障是客户端第一次连接成功，执行命令却收到指向容器内网 IP 的 MOVED；或者 CLUSTER NODES 里出现 disconnected。这时 cluster-announce-ip 不能凭感觉填写宿主机地址、容器地址或 127.0.0.1，而应填写“从需要访问它的节点和客户端视角都能路由到的公告地址”。

实用判断是：每个节点都要同时明确客户端数据端点和 cluster bus 端点。公告 IP、客户端端口、bus 端口必须和实际网络路径成组匹配；只改一个 IP，不能修复端口映射或节点间不可达。

官方地址：https://redis.io/docs/latest/management/scaling/

下面按一次“容器内互通、容器外重定向失败”的故障复盘来处理。本文只讨论 NAT、容器网络和公告地址，不展开槽位迁移。

先分清两个网络视角

故障现场通常有两个地址：Redis 进程自动发现的容器地址，以及客户端真正能访问的地址。Redis Cluster 没有代理层，节点会通过拓扑把目标节点的 endpoint 返回给客户端；因此客户端看到错误的内网地址，就会在后续 MOVED 跳转时失败。

同时，Cluster 还使用独立的 cluster bus 做节点间握手、故障检测和配置传播。每个节点至少要有两个可达端口：服务客户端的 Redis 端口，以及节点之间使用的 bus 端口。默认情况下 bus 端口常由数据端口加 10000 得到，但存在映射时不能只看这个默认关系。

所以先问三个问题：客户端访问这个节点时走哪个地址和端口？其他 Redis 节点访问它的 bus 端口时走哪条路？容器重建后这个地址是否还会保持稳定？三个问题都能回答，才有资格把该地址写进公告配置。

三个 announce 参数要成组配置

在同一 Docker 网络中，若客户端和所有 Redis 节点都能直接访问固定容器 IP，可以把每个节点的容器 IP 作为公告 IP；如果客户端在容器外，则公告地址应改为外部客户端可路由的节点地址，并为每个节点匹配实际暴露的端口。不要把 127.0.0.1 当成集群共享地址：它在每个容器里都只代表当前容器自身。

# 每个节点使用自己的可路由公告地址，不能把三个节点都写成 127.0.0.1
cluster-announce-ip 172.28.0.31
# 客户端实际访问的 Redis 数据端口
cluster-announce-port 6379
# 节点之间实际互通的 cluster bus 端口
cluster-announce-bus-port 16379

如果宿主机把容器的 6379 映射成了 7001，并且客户端确实通过宿主机地址访问这个节点，那么公告端口就不能继续写成容器内部的 6379。但这类“每个节点端口不同、地址还要跨 NAT 映射”的组合很容易让 Cluster 失去一致的可达路径。更稳妥的部署方向是使用同一可路由网络并固定节点地址，或使用 host networking 让节点端口不发生重映射。

Compose 示例可以把地址和端口写在节点自己的启动配置中，避免靠容器启动时的随机 IP：

services:
  redis-1:
    image: redis:7
    command: >
      redis-server
      --cluster-enabled yes
      --cluster-config-file /data/nodes.conf
      --cluster-announce-ip 172.28.0.31
      --cluster-announce-port 6379
      --cluster-announce-bus-port 16379
    networks:
      redis-net:
        ipv4_address: 172.28.0.31 # 固定地址只在该网络内可路由

networks:
  redis-net:
    ipam:
      config:
        - subnet: 172.28.0.0/24 # 示例网段，按实际网络规划调整

这个示例的关键不是某个固定网段，而是“公告值、集群创建时登记的节点地址、客户端实际访问路径”三者一致。若采用 Kubernetes 等会变化的 Pod IP，则需要在启动时根据当前 Pod IP 生成配置，并同步处理节点状态文件；不要把一次启动得到的临时地址永久写死。

从 CLUSTER NODES 反查根因

修复后先看节点视图，而不是只看单个 PING。连接一个节点执行：

# 查看节点公告地址、客户端端口、bus 端口和连接状态
redis-cli -h 172.28.0.31 -p 6379 CLUSTER NODES
# 重点检查 ip:port@cport 是否为客户端与节点都能到达的地址
# 还要确认每一行的 link-state 为 connected

输出中的 ip:port@cport 是最有价值的证据：前一个端口是客户端端点，@ 后面是 cluster bus 端口。如果这里仍然出现容器内部不可达地址，说明公告配置没有被实际加载，或旧的节点状态文件仍保存着历史拓扑；如果地址正确但状态仍是 disconnected，优先检查 bus 端口、防火墙和容器网络路由。

防止下一次重建再次故障

把每个节点的公告 IP、数据端口、bus 端口和网络模式作为同一份部署清单管理；不要只在命令行临时改一个参数。发布前从客户端网络和节点网络各自验证端口可达，再检查 CLUSTER NODES 的公告值。若环境必须做复杂端口映射，Redis 官方建议优先重新设计网络拓扑，因为 Cluster 对 NAT 和端口重映射并不友好。

常见问题

cluster-announce-ip 应该填宿主机 IP 还是容器 IP？ 取决于谁需要访问它：所有访问者都能路由到容器 IP 时填容器 IP；外部客户端只能访问宿主机 IP 时才考虑宿主机 IP，并同步匹配每个节点的端口映射。

只设置 cluster-announce-ip 不设置 bus 端口可以吗？ 不建议。默认 bus 端口只有在没有重映射且网络路径一致时才可靠；发生 NAT 或端口转发时，应把三个 announce 参数一起按实际路径配置。