aredis哨兵模式指南：Redis高可用与自动故障转移配置全解-平芜编程栈

aredis哨兵模式指南：Redis高可用与自动故障转移配置全解

【免费下载链接】aredisredis client for Python asyncio (has support for redis server, sentinel and cluster)项目地址: https://gitcode.com/gh_mirrors/ar/aredis

aredis 哨兵模式（Sentinel）是 Python 异步项目中搭建Redis 高可用架构的关键能力。作为专为 Python asyncio 打造的异步 Redis 客户端，aredis 内置了完整的 Sentinel 支持：自动发现主从节点、故障时自动转移连接、读写分离负载均衡，让业务代码无需感知底层拓扑变化。本指南带你从零看懂并配好这一整套 Redis 高可用方案 🔍

为什么需要 Redis 哨兵模式？

单机 Redis 存在两个致命问题：

主节点宕机：进程挂掉或机器故障，读写请求全部中断；
从节点无法写入：从库只读，主库一倒，应用端拿到的"主地址"就失效了。

Redis Sentinel（哨兵）就是为了解决这个问题：多个哨兵进程持续监控主从节点，一旦判定主节点不可用（ODOWN），就自动选举新主节点并通知客户端。而 aredis 的哨兵模式让客户端自动跟上这次切换——你只配一次哨兵地址，主节点漂移后连接池会重新查询哨兵、断开旧连接、接入新主节点，全程对业务代码透明。

aredis 哨兵模式的核心组成

aredis 的 Sentinel 支持集中在两个模块中，理解它们就理解了整个机制：

组件	文件	作用
`Sentinel`	`aredis/sentinel.py`	哨兵集群入口，负责发现主节点和存活从节点
`SentinelConnectionPool`	`aredis/sentinel.py`	哨兵管理的连接池，主节点变化时自动断开旧连接
`SentinelManagedConnection`	`aredis/sentinel.py`	建立连接前先从哨兵查询目标地址的连接
`SENTINEL`命令封装	`aredis/commands/sentinel.py`	`sentinel_master()`、`sentinel_slaves()`等命令

官方文档对这一机制有更完整的说明，可参考docs/source/sentinel.rst；相关行为在tests/client/test_sentinel.py中有对应的测试覆盖，例如哨兵节点宕机后的自动跳过、从节点轮询等场景。

快速上手：三步接入哨兵集群

假设你已经部署了 1 主、2 从的 Redis，以及一个默认监听26379端口的哨兵实例（服务名为mymaster）。接入 aredis 只需三步：

from aredis.sentinel import Sentinel # 1. 创建哨兵客户端（可以传多个哨兵地址做冗余） sentinel = Sentinel([('10.0.0.1', 26379), ('10.0.0.2', 26379)], stream_timeout=0.1) # 2. 获取主节点客户端 —— 用于写操作 master = sentinel.master_for('mymaster', stream_timeout=0.1) await master.set('foo', 'bar') # 3. 获取从节点客户端 —— 用于读操作 slave = sentinel.slave_for('mymaster', stream_timeout=0.1) print(await slave.get('foo')) # 'bar'

master和slave都是标准的StrictRedis实例，后续调用get、set、hset等 API 与单机模式完全一致。连接建立时，客户端会先查询哨兵拿到真实地址再连接，因此你不需要在代码里硬编码任何 Redis 主从 IP。

💡 小贴士：master_for/slave_for返回的客户端可以复用，内部连接池会自动处理地址变更，无需每次重建。

自动故障转移是如何发生的？

这是哨兵模式最"聪明"的部分，aredis 内部由三个机制协同完成：

1️⃣ 主节点发现与哨兵容错

Sentinel.discover_master()会依次询问每个哨兵节点，如果某个哨兵连接失败或超时，就自动跳过、尝试下一个；找到健康主节点后，还会把这个哨兵挪到列表首位，下次优先查询它，天然实现了哨兵层自身的故障转移。同时会通过min_other_sentinels校验该哨兵是否还"认识"足够的同伴，避免使用脑裂哨兵的过期信息。

2️⃣ 主节点切换时自动重连

当哨兵完成故障转移后，旧主节点被降为从节点。SentinelManagedConnection在读取响应时捕获ReadOnlyError（对"主"节点写入却返回只读错误），会主动断开连接并抛出ConnectionError('The previous master is now a slave')。与此同时SentinelConnectionPool.get_master_address()发现主地址已变化，会断开池中所有旧连接，下一次请求自动向新主节点发起连接——业务层只需对偶发连接异常做一次重试即可。

3️⃣ 从节点轮询与降级兜底

读请求走slave_for时，rotate_slaves()对所有存活从节点做轮询（round-robin），自动分散读压力；如果所有从节点都不可达，会降级回退到主节点连接，保证读操作尽量可用；若连主节点都找不到，则抛出SlaveNotFoundError。

关键配置参数速查表

参数	位置	说明
`sentinels`	`Sentinel`构造	哨兵地址列表，建议传 2~3 个做冗余
`min_other_sentinels`	`Sentinel`构造	要求哨兵感知的最少同伴数，过低可能读到过期拓扑，生产环境建议设为 1 以上
`sentinel_kwargs`	`Sentinel`构造	连接哨兵实例的参数；缺省时复用`socket_*`选项
`connection_kwargs`	`Sentinel`构造	连接 Redis 主从节点时的通用参数（如`db`、`decode_responses`）
`stream_timeout`	构造 /`master_for`	I/O 超时，异步场景务必设置，避免请求永久挂起
`check_connection`	`master_for`/`slave_for`	建连后立即发`PING`校验，可过滤掉"看似活着"的坏连接

常见异常排查

异常	含义	处理建议
`MasterNotFoundError`	所有哨兵都查不到健康主节点（主节点 ODOWN/SDOWN，或服务名写错）	检查哨兵日志与`SENTINEL MASTERS`输出；确认`service_name`拼写正确
`SlaveNotFoundError`	无存活从节点且主节点也不可达	确认从节点复制是否同步；检查网络与安全组
`ReadOnlyError`/`ConnectionError('The previous master is now a slave')`	正在发生主从切换	属预期行为，客户端自动重连；业务侧加一次短重试即可