Docker搭建Redis集群完全指南

Docker 搭建 Redis 集群完全指南：从原理到生产落地，踩坑实录

一篇讲透 Docker 环境下 Redis Cluster 的搭建、调优与生产级实战。含完整代码、避坑清单和 Spring Boot 接入方案，收藏即可复用。

为什么需要这篇？

Redis 集群是后端面试的高频考点，也是生产环境的高可用基石。但网上的教程大多停留在「跑通 demo」层面，真正落地时你会碰到：容器重启后集群崩溃、客户端被 MOVED 重定向到 127.0.0.1、从节点无法自动提升……
这篇文章把 设计思路、完整代码、核心踩坑、生产调优、应用接入 一次讲清楚。所有代码均可直接复制使用。
一、整体架构设计

采用 Redis Cluster 原生方案 + Docker Compose 编排，最小高可用规格为 3 主 3 从共 6 节点：

• 3 个主节点分担 16384 个哈希槽，负责读写
  
• 3 个从节点分别与主节点一一对应，提供故障转移能力
  
• 通过 Docker 自界说桥接网络实现容器间固定 IP 通信
  

1. [/code][code]┌──────────────────────────────────────────┐
2.     │         Docker Bridge Network             │
3.     │     (redis-cluster-net, 172.28.0.0/16)    │
4.     └──────────────────────────────────────────┘
5.         ↑          ↑          ↑          ↑

复制代码

┌────────┴───┐ ┌───┴──────┐ ┌─┴────────┐ ┌─┴────────┐
│ redis-7001 │ │redis-7002│ │redis-7003│ │  ...     │
│   (主)     │ │  (主)    │ │  (主)    │ │redis-7006│
└────────┬───┘ └───┬──────┘ └─┬────────┘ └─┬────────┘
↑          ↑          ↑             ↑
┌────────┴───┐ ┌───┴──────┐ ┌─┴────────┐ ┌─┴────────┐
│ redis-7004 │ │redis-7005│ │redis-7006│ │  (从)    │
│   (从)     │ │  (从)    │ │  (从)    │ │          │
└────────────┘ └──────────┘ └──────────┘ └──────────┘

1. ### 节点拓扑规划
3. | 节点序号 | 容器名 | 服务端口 | 集群总线端口 | 初始角色 | 固定 IP |
4. |----------|--------|----------|--------------|----------|---------|
5. | 1 | redis-7001 | 7001 | 17001 | 主节点 | 172.28.0.11 |
6. | 2 | redis-7002 | 7002 | 17002 | 主节点 | 172.28.0.12 |
7. | 3 | redis-7003 | 7003 | 17003 | 主节点 | 172.28.0.13 |
8. | 4 | redis-7004 | 7004 | 17004 | 从节点 | 172.28.0.14 |
9. | 5 | redis-7005 | 7005 | 17005 | 从节点 | 172.28.0.15 |
10. | 6 | redis-7006 | 7006 | 17006 | 从节点 | 172.28.0.16 |
12. > **关键概念**：集群总线端口 = 服务端口 + 10000，是节点间心跳同步、故障转移、数据迁移的专用通道。**必须与服务端口一起映射**，否则 `CLUSTER MEET` 直接失败，这是 90% 新手组网踩的第一个坑。
14. ---
16. ## 二、落地实操：从 0 到集群
18. ### Step 1：准备配置文件
20. 每个节点独立一份 `redis.conf`，以下是生产级完整配置模板（以 7001 节点为例，其余节点仅改端口和 IP）：
22. ```conf
23. # ========== 基础网络 ==========
24. bind 0.0.0.0
25. protected-mode no
26. port 6379
27. daemonize no
29. # ========== 集群核心 ==========
30. cluster-enabled yes
31. cluster-config-file nodes.conf
32. cluster-node-timeout 5000
34. # 🔥 关键三件套：显式声明对外访问地址，彻底解决 MOVED 重定向到内网/回环地址的问题
35. cluster-announce-ip 172.28.0.11        # 容器固定 IP
36. cluster-announce-port 6379             # 容器内服务端口
37. cluster-announce-bus-port 16379        # 容器内总线端口
39. # ========== 安全认证（生产必开）==========
40. # 所有节点密码必须完全一致
41. requirepass your_redis_pwd
42. masterauth your_redis_pwd
44. # ========== 持久化 ==========
45. appendonly yes
46. appendfsync everysec
47. save 900 1
48. save 300 10
50. # ========== 内存管理 ==========
51. maxmemory 400mb
52. maxmemory-policy allkeys-lru

复制代码

亮点解读：

• cluster-announce-* 三件套配置：显式声明节点对外地点，防止容器重启后 IP 漂移导致集群脑裂，这是最容易被忽略的关键配置
  
• requirepass + masterauth 双保险：前者管控客户端访问，后者保障主从同步和总线通信认证，缺一不可
  
• maxmemory + allkeys-lru：前置内存上限和淘汰计谋，防止大 key 或流量突增导致节点 OOM
  

Step 2：编写 docker-compose.yml

1. version: '3.8'
3. # 自定义静态子网，彻底解决容器重启 IP 漂移问题
4. networks:
5.   redis-cluster-net:
6.     driver: bridge
7.     ipam:
8.       config:
9.         - subnet: 172.28.0.0/16
11. services:
12.   redis-7001:
13.     image: redis:7.2.5-alpine
14.     container_name: redis-7001
15.     restart: always
16.     ports:
17.       - "7001:6379"       # 客户端通信端口
18.       - "17001:16379"     # 集群总线端口（Gossip 协议专用）
19.     volumes:
20.       - ./cluster/7001/redis.conf:/etc/redis/redis.conf
21.       - ./cluster/7001/data:/data    # 全量挂载：含 AOF/RDB + 集群元数据 nodes.conf
22.     networks:
23.       redis-cluster-net:
24.         ipv4_address: 172.28.0.11
25.     mem_limit: 512m       # 资源配额，防止单节点 OOM 拖垮宿主机
26.     cpus: "0.5"
27.     command: redis-server /etc/redis/redis.conf
29.   redis-7002:
30.     image: redis:7.2.5-alpine
31.     container_name: redis-7002
32.     restart: always
33.     ports:
34.       - "7002:6379"
35.       - "17002:16379"
36.     volumes:
37.       - ./cluster/7002/redis.conf:/etc/redis/redis.conf
38.       - ./cluster/7002/data:/data
39.     networks:
40.       redis-cluster-net:
41.         ipv4_address: 172.28.0.12
42.     mem_limit: 512m
43.     cpus: "0.5"
44.     command: redis-server /etc/redis/redis.conf
46.   redis-7003:
47.     image: redis:7.2.5-alpine
48.     container_name: redis-7003
49.     restart: always
50.     ports:
51.       - "7003:6379"
52.       - "17003:16379"
53.     volumes:
54.       - ./cluster/7003/redis.conf:/etc/redis/redis.conf
55.       - ./cluster/7003/data:/data
56.     networks:
57.       redis-cluster-net:
58.         ipv4_address: 172.28.0.13
59.     mem_limit: 512m
60.     cpus: "0.5"
61.     command: redis-server /etc/redis/redis.conf
63.   redis-7004:
64.     image: redis:7.2.5-alpine
65.     container_name: redis-7004
66.     restart: always
67.     ports:
68.       - "7004:6379"
69.       - "17004:16379"
70.     volumes:
71.       - ./cluster/7004/redis.conf:/etc/redis/redis.conf
72.       - ./cluster/7004/data:/data
73.     networks:
74.       redis-cluster-net:
75.         ipv4_address: 172.28.0.14
76.     mem_limit: 512m
77.     cpus: "0.5"
78.     command: redis-server /etc/redis/redis.conf
80.   redis-7005:
81.     image: redis:7.2.5-alpine
82.     container_name: redis-7005
83.     restart: always
84.     ports:
85.       - "7005:6379"
86.       - "17005:16379"
87.     volumes:
88.       - ./cluster/7005/redis.conf:/etc/redis/redis.conf
89.       - ./cluster/7005/data:/data
90.     networks:
91.       redis-cluster-net:
92.         ipv4_address: 172.28.0.15
93.     mem_limit: 512m
94.     cpus: "0.5"
95.     command: redis-server /etc/redis/redis.conf
97.   redis-7006:
98.     image: redis:7.2.5-alpine
99.     container_name: redis-7006
100.     restart: always
101.     ports:
102.       - "7006:6379"
103.       - "17006:16379"
104.     volumes:
105.       - ./cluster/7006/redis.conf:/etc/redis/redis.conf
106.       - ./cluster/7006/data:/data
107.     networks:
108.       redis-cluster-net:
109.         ipv4_address: 172.28.0.16
110.     mem_limit: 512m
111.     cpus: "0.5"
112.     command: redis-server /etc/redis/redis.conf

复制代码

配置亮点总结：
设计点办理的问题自界说静态子网 + 固定 IP 分配容器重启后 IP 漂移导致集群节点失联双端口严酷映射（服务 + 总线）覆盖服务访问与 Gossip 通信两条核心链路配置与数据双目录挂载持久化 nodes.conf 集群身份元数据，容器重建不丢失节点身份内存/CPU 资源配额避免单节点 OOM 挤占宿主机资源alpine 精简镜像 + always 自愈兼顾镜像体积与服务可用性Step 3：启动容器 & 一键组建集群

1. # 启动所有容器
2. docker-compose up -d
4. # 等待节点完全启动
5. sleep 10
7. # 一键创建集群（--cluster-yes 跳过交互确认，适配 CI/CD）
8. docker exec -it redis-7001 redis-cli --cluster create \
9.   172.28.0.11:6379 \
10.   172.28.0.12:6379 \
11.   172.28.0.13:6379 \
12.   172.28.0.14:6379 \
13.   172.28.0.15:6379 \
14.   172.28.0.16:6379 \
15.   --cluster-replicas 1 \
16.   --cluster-yes

复制代码

Redis 会自动分配主从关系和 16384 个哈希槽，输出类似：

1. >>> Performing hash slots allocation on 6 nodes...
2. Master[0] -> Slots 0 - 5460
3. Master[1] -> Slots 5461 - 10922
4. Master[2] -> Slots 10923 - 16383
5. Adding replica ...
6. [OK] All nodes agree about slots configuration.

复制代码

致命提示：组网命令中 绝对不能用 127.0.0.1，必须填写宿主机真实 IP 或容器固定 IP。否则节点会把集群地点注册为本地回环，跨节点通信直接失败。

Step 4：验证集群状态

1. # 查看集群节点（确认 3 master + 3 slave）
2. redis-cli -h 127.0.0.1 -p 7001 cluster nodes
4. # 查看槽位分布
5. redis-cli -h 127.0.0.1 -p 7001 cluster slots
7. # 读写验证（-c 开启集群重定向）
8. redis-cli -c -h 127.0.0.1 -p 7001 -a your_redis_pwd set foo bar

复制代码

能正常重定向并返回 OK，说明分片和迁移机制工作正常。
三、生产级自动化部署脚本

以下脚本集成了 连通性预检 → 自动组网 → 健康校验 全流程，可直接接入 CI/CD 流水线：

1. #!/bin/bash
2. # ========== 全局变量 ==========
3. HOST_IP="宿主机真实IP"
4. PASSWORD="your_redis_pwd"
5. START_PORT=7001
6. NODE_COUNT=6
8. # ========== 前置校验：全节点连通性检测 ==========
9. echo "🔍 开始校验所有节点连通性..."
10. for ((i=0; i<NODE_COUNT; i++))
11. do
12.   port=$((START_PORT + i))
13.   if ! redis-cli -h $HOST_IP -p $port -a $PASSWORD ping > /dev/null 2>&1; then
14.     echo "❌ 节点$port 连通失败，请检查配置！"
15.     exit 1
16.   fi
17.   echo "✅ 节点$port 连通正常"
18. done
20. # ========== 非交互式组建集群 ==========
21. echo "🚀 开始组建 Redis 集群..."
22. echo "yes" | redis-cli -a $PASSWORD --cluster create \
23.   $HOST_IP:7001 $HOST_IP:7002 $HOST_IP:7003 \
24.   $HOST_IP:7004 $HOST_IP:7005 $HOST_IP:7006 \
25.   --cluster-replicas 1
27. # ========== 组网后健康校验 ==========
28. if [ $? -eq 0 ]; then
29.   echo "🎉 集群组建成功！集群状态："
30.   redis-cli -h $HOST_IP -p 7001 -a $PASSWORD cluster info | grep cluster_state
31. else
32.   echo "❌ 集群组建失败，请排查节点日志！"
33.   exit 1
34. fi

复制代码

脚本亮点：

• 前置连通性校验：提前拦截端口不通、暗码错误等基础问题，避免组网中途异常
  
• --cluster-yes 非交互模式：无需人工确认，直接接入自动化部署流水线
  
• 组网后自动健康校验：快速输出集群状态，降低部署后验证本钱
  

四、Spring Boot 接入 Redis 集群

集群搭好了，应用端怎么连？以下是 Spring Boot + Lettuce 的生产级配置：

1. # application.yml
2. spring:
3.   redis:
4.     cluster:
5.       nodes:
6.         - 192.168.1.100:7001
7.         - 192.168.1.100:7002
8.         - 192.168.1.100:7003
9.         - 192.168.1.100:7004
10.         - 192.168.1.100:7005
11.         - 192.168.1.100:7006
12.     password: your_redis_pwd
13.     lettuce:
14.       pool:
15.         max-active: 20
16.         max-idle: 10
17.       cluster:
18.         refresh:
19.           adaptive: true       # 自适应拓扑刷新
20.           period: 30s          # 定时刷新周期

复制代码

关键配置解读：

• adaptive: true：开启自顺应拓扑刷新，当集群发生扩缩容或故障转移时，客户端自动感知新拓扑，无需重启
  
• period: 30s：定时兜底刷新，防止自顺应事件丢失
  
• 使用 Lettuce 而非 Jedis：Lettuce 原生支持集群拓扑刷新和毗连池共享，线程安全，高并发场景性能更优
  

五、核心踩坑与技术难点

这是全文最值钱的部分——每一个都是真实踩过的坑：
序号技术难点问题表现根因办理方案1集群 IP 寻址异常（最高频）客户端报 MOVED 127.0.0.1；跨节点迁移失败；心跳失联Redis 默认注册容器内网 IP/回环地点，外部无法路由配置 cluster-announce-ip 显式声明对外 IP；组网命令禁用 127.0.0.12集群总线端口未映射CLUSTER MEET 超时，Gossip 协议不通只映射了服务端口，遗漏了总线端口每个节点同时暴露服务端口和总线端口（+10000），防火墙一并放行3自动故障转移失效主节点宕机，从节点无法提升，集群只读仅配了 requirepass，未配 masterauth；或各节点暗码差别等所有节点同时配置 requirepass + masterauth，暗码全集群统一4容器重启后集群崩溃节点丢失集群身份，槽位数据不可用nodes.conf 未持久化，容器重建后天生新节点 ID数据目录完整挂载到宿主机；搭配静态 IP，避免 IP 漂移5跨宿主机网络不通多服务器部署时节点无法建立心跳Docker bridge 网络为宿主机隔离，容器 IP 无法跨主机路由方案一：cluster-announce-ip + 宿主机端口映射；方案二：Docker Overlay 跨主机网络6单宿主机脑裂风险宿主机宕机全集群不可用3 个主节点全在同一台机器，不满意「半数以上存活」选举规则生产环境必须跨 3 台及以上宿主机部署主节点7在线扩缩容阻塞reshard 迁移槽位时哀求超时大 key 迁移或业务高峰期操作指定 --cluster-timeout，使用 pipeline 批量迁移，选择低峰期操作8监控盲区集群出问题后才发现，定位困难缺少监控体系接入 redis-exporter + Prometheus + Grafana，重点监控 cluster_state、cluster_slots_fail六、生产环境进阶建议

持久化计谋

• 开启 appendonly yes + appendfsync everysec，兼顾性能与安全
  
• 可叠加 aof-use-rdb-preamble yes 混合持久化，加快重启恢复
  
• 配合 save 900 1 / save 300 10 RDB 快照，双保险
  

监控告警

接入 redis-exporter + Prometheus + Grafana，核心告警规则：

1. # 典型告警规则
2. - alert: RedisClusterDown
3.   expr: redis_cluster_state != 1
4.   for: 1m
5.   labels:
6.     severity: critical
7.   annotations:
8.     summary: "Redis 集群状态异常"
10. - alert: RedisClusterSlotsFail
11.   expr: redis_cluster_slots_fail > 0
12.   for: 30s
13.   labels:
14.     severity: warning
15.   annotations:
16.     summary: "Redis 集群存在失败槽位"

复制代码

重点监控指标：cluster_state、cluster_slots_fail、cluster_known_nodes、各节点内存使用率。
动态扩缩容

• 扩容：redis-cli --cluster add-node 加入新节点 → reshard 迁移槽位
  
• 缩容：先 rebalance 迁移槽位 → 再 del-node 移除节点，全程在线不中断
  
• K8s 环境：生产建议使用 StatefulSet + Headless Service，让 Redis Cluster 自行管理节点 IP
  

故障转移验证

手动停止一个主节点容器，观察从节点是否自动提升为主；原主节点恢复后应自动转为从节点。假如失败，优先排查 masterauth 配置和暗码同等性。
七、整体架构全景图

总结

Docker + Compose 搭建 Redis Cluster，核心抓住 五个关键点：

• 端口双开：服务端口 + 集群总线端口（+10000），缺一不可
  
• IP 固定：静态子网 + 固定 IP 分配，或 cluster-announce-ip 显式声明，杜绝 IP 漂移
  
• 暗码统一：requirepass + masterauth 全节点同等，保障故障转移正常
  
• 数据持久化：完整挂载数据目录，持久化 nodes.conf + AOF/RDB
  
• 客户端适配：开启集群拓扑刷新（Lettuce adaptive），正确处置惩罚 MOVED 重定向
  

掌握这五点，无论是面试回答还是生产落地，都能稳扎稳打。
个人博客“www.javadashen.com”