Redis 高可用集群操作文档

对应部署见 部署文档。集群：命名空间 redis，RKE2 v1.35.6。 密码保存在交付目录 .secrets.env（本文以 $PW 代指 REDIS_PASSWORD）。 更新：2026-08-01

1. 连接信息速查

用途	地址	说明
写	redis-master.redis.svc.cluster.local:6379	始终指向当前主库
读	redis-read.redis.svc.cluster.local:6379	负载到全部从库
Sentinel	redis.redis.svc.cluster.local:26379	Sentinel 感知客户端，masterSet=mymaster

优先推荐应用使用 Sentinel 感知客户端（Lettuce / Redisson / redis-py sentinel）， 可感知故障转移且免去读写入口维护；非 Sentinel 客户端用 redis-master / redis-read 即可。

2. 日常巡检

export KUBECONFIG=~/.kube/config-122.31

# Pod 状态：3 节点 3/3 Running 跨节点分布；isMaster 标签恰好 1 个 true、其余 false
kubectl -n redis get pods -l app.kubernetes.io/instance=redis -L isMaster -o wide

# 主从复制：主库 connected_slaves=2，从库 master_link_status=up
kubectl -n redis exec -it <主库Pod> -c redis -- \
  redis-cli -a "$PW" --no-auth-warning INFO replication | grep -E 'role|connected_slaves'

# Sentinel 状态：num-other-sentinels=2、num-slaves=2
kubectl -n redis exec <主库Pod> -c sentinel -- \
  redis-cli -p 26379 -a "$PW" --no-auth-warning SENTINEL master mymaster | grep -E 'num-|flags'

# 读写服务后端
kubectl -n redis get endpoints redis-master redis-read

# 备份文件
kubectl -n redis exec deploy/redis-nfs-provisioner -- \
  sh -c 'ls -lh /persistentvolumes/redis-redis-backup-*/ 2>/dev/null | tail -5'

告警关注项：Sentinel flags 含 s_down/o_down、connected_slaves < 2、 redis-read endpoints 为空（从库标签丢失）、CronJob 连续失败、NFS 空间。

3. 备份与恢复

3.1 备份策略

• 方式：redis-cli --rdb 经 SYNC 拉取主库全量 RDB（主库 fork 子进程 BGSAVE，不阻塞服务）
• 频率：每天 02:00（北京），文件 redis-YYYYMMDD-HHMMSS.rdb.gz 写入 NFS（redis-backup PVC）
• 保留：7 天自动清理

3.2 手动备份

kubectl -n redis create job --from=cronjob/redis-backup redis-backup-manual-$(date +%s)
kubectl -n redis logs -f job/redis-backup-manual-<TS>

3.3 恢复

# 1. 解压备份并拷入主库 Pod 数据目录
gunzip redis-20260801-051052.rdb.gz
kubectl -n redis cp redis-20260801-051052.rdb <主库Pod>:/data/dump.rdb -c redis

# 2. 重启主库 redis 容器加载 RDB（从库随后全量重同步）
kubectl -n redis delete pod <主库Pod>

# 3. 确认 Sentinel 选主完成、读写服务后端正确
kubectl -n redis get pods -L isMaster; kubectl -n redis get endpoints redis-master redis-read

恢复会触发从库全量重同步（数据量大时有几分钟复制延迟升高），属正常现象。 更低 RPO 需求：缩短备份周期，或在 redis-values.yaml 开启 AOF（注意 NFS 上 fsync 性能）。

4. 故障转移（自动）与人工介入

正常场景无需介入：主库宕机 → Sentinel（quorum=2）~30s 自动提升从库 → labeler 更新 isMaster 标签 → redis-master/redis-read 自动切换 → 旧主恢复后自动降级为从库。

人工确认点：

# 转移后检查
kubectl -n redis get pods -L isMaster              # 新主 true
kubectl -n redis get endpoints redis-master redis-read
kubectl -n redis exec <新主Pod> -c sentinel -- \
  redis-cli -p 26379 -a "$PW" --no-auth-warning SENTINEL master mymaster | grep flags   # 应为 master 无 s_down

例外场景：旧主 Pod 重建后丢失 isMaster=false 标签（不进 redis-read）， redis-label-sync CronJob 5 分钟内自动补打；急用可手动 kubectl -n redis label pod <Pod名> isMaster=false。

强制手动切换（计划内维护主库节点前）：

kubectl -n redis exec <任一Pod> -c sentinel -- \
  redis-cli -p 26379 -a "$PW" --no-auth-warning SENTINEL failover mymaster

5. 扩缩容

# 增加节点（Sentinel 模式 replicaCount=节点总数）
# 修改 redis-values.yaml: replica.replicaCount: 4
helm upgrade redis oci://192.168.122.156:30000/charts/redis \
  --version 21.2.6 --plain-http -n redis -f redis-values.yaml
# 新节点自动作为从库接入；redis-label-sync 会为其补打 isMaster=false

Sentinel 节点数建议保持奇数（3 或 5），quorum=(n/2)+1。

6. 密码管理

• 唯一密码 REDIS_PASSWORD，存于 .secrets.env，注入 chart values 与备份 CronJob（secret redis）
• 轮换：kubectl -n redis edit secret redis 更新 + helm upgrade 同步 values + 滚动重启 StatefulSet； Sentinel 的 auth-pass 由 chart 自动渲染同步

7. 常见问题

现象	原因	处理
redis-read endpoints 为空/缺少某从库	从库 Pod 重建丢 isMaster=false 标签	等 label-sync（5min）或手动 kubectl label pod xxx isMaster=false
redis-master 无后端	主从切换中（label 更新间隙）	数秒自愈；持续缺失检查 labeler sidecar 日志
Sentinel s_down	网络分区/主库过载	查主库负载与节点网络；恢复后自动转回
备份 Job 失败	NFS 抖动/空间不足	看 Job 日志；df -h /mnt/xfs
客户端 NOAUTH/WRONGPASS	密码未同步轮换	确认 secret/values/客户端三处一致
全量重同步频繁失败	NFS IO 慢导致 RDB 传输超时	增大 repl-timeout（values 中 commonConfiguration）

8. 卸载

helm uninstall redis redis-nfs-provisioner -n redis
kubectl -n redis delete -f rw-services.yaml -f backup.yaml
kubectl -n redis delete pvc --all     # 数据随之删除（SC 回收策略 Delete），操作前确认已备份
kubectl delete ns redis