结论:应使用 aioredis.Redis 的 subscribe + listen 配合 asyncio.create_task 启动后台监听任务;pubsub 对象无自动重连、不属连接池、难与 FastAPI 生命周期协同,易断连且无法优雅关闭。

直接说结论:用 aioredis.Redis 的 subscribe + listen 配合后台任务(BackgroundTasks 或 asyncio.create_task)才能稳定收消息;别用 pubsub 对象长期 hold 住连接,它不自动重连、不兼容 FastAPI 生命周期管理。
为什么 pubsub 对象在 FastAPI 里容易断连又难恢复
aioredis 的 pubsub 实例本质是单次绑定的监听器,不是长生命周期连接池资源。它内部没有重连逻辑,一旦 Redis 临时抖动或连接超时,listen() 就会抛出 ConnectionClosedError 并退出循环,后续消息彻底丢失。
-
pubsub不属于aioredis.Redis客户端池,不能被app.state.redis统一管理 - 手动在
startup里启动listen()会阻塞事件循环,必须用asyncio.create_task脱离主线程 - FastAPI 的
shutdown事件里无法优雅取消正在listen()的协程,容易残留僵尸 task
aioredis.Redis 原生 subscribe 是更稳妥的选择
从 aioredis v2.0 起,Redis 实例本身支持 subscribe 方法,返回一个可 await 的 PubSub 对象,并且能复用底层连接池——这意味着它能受益于连接池的自动重连、超时控制和编码配置(如 decode_responses=True)。
- 必须显式调用
await pubsub.subscribe("channel_name"),不能只传字符串 - 监听需用
async for message in pubsub.listen():,不是await pubsub.listen() - 每个 channel 需单独
subscribe,批量订阅写成await pubsub.subscribe("ch1", "ch2") - 务必在
try/except中捕获aioredis.ConnectionError和asyncio.CancelledError
如何在 FastAPI 启动时安全挂载订阅任务
推荐用 asyncio.create_task 启动独立监听协程,并在 shutdown 时主动 cancel()。不要依赖 BackgroundTasks,它只保证请求生命周期内执行,不适用于常驻后台任务。
- 把订阅逻辑封装成独立 async 函数,例如
async def listen_to_events(redis: aioredis.Redis): - 在
@app.on_event("startup")中用app.state.pubsub_task = asyncio.create_task(listen_to_events(app.state.redis)) - 在
@app.on_event("shutdown")中先app.state.pubsub_task.cancel(),再await asyncio.gather(..., return_exceptions=True) - 监听循环内每收到一条
message,建议用asyncio.to_thread或发到线程安全队列处理耗时逻辑,避免阻塞 event loop
实际消息结构与常见误判点
收到的 message 是 dict,类型字段为 type(注意不是 Python 的 type()),值可能是 "message"、"pmessage" 或 "subscribe"。只有 type == "message" 才是真实业务数据。
-
message["data"]类型取决于初始化时是否设了decode_responses=True:开启则为str,否则为bytes - 用通配符订阅(
psubscribe)需调用pubsub.psubscribe("log.*"),对应消息type是"pmessage" - 不要在
listen()循环里直接调redis.set()等操作——这会触发连接复用竞争,应改用await redis.execute_command("PUBLISH", ...)避免混用
真正麻烦的不是怎么收消息,而是怎么让这个监听过程在进程重启、Redis 故障、Uvicorn worker reload 时不丢状态也不狂刷错误日志——关键在于把重试逻辑、连接健康检查、消息去重都收进那个 listen_to_events 函数里,而不是指望框架自动兜底。



















