Redis键空间通知实战：轻量级事件订阅转发工具设计解析

oh-my-hermes 这个名字，一眼就能看出是跟 oh-my-zsh 那套命名学的。实际上它也确实是个挺轻量的开源小工具：订阅 Redis 的键空间通知（Keyspace Notifications），把 Redis 内部发生的键写入、删除、过期、淘汰这类事件，像信使一样原样转达给下游系统。我在内部项目里维护这个工具也有大半年了，期间踩了不少坑，也重构过两版，今天干脆把完整的设计思路和落地过程整理出来，包括配置、源码逻辑、参数解释和真实遇到的问题，希望对想走同样路子的人有帮助。

先说它解决的核心痛点：很多业务系统用了 Redis 做缓存或者临时状态存储，但状态一变，业务侧往往只能靠轮询去感知。轮询就是笨办法，延迟高、空转多、代码还丑。Redis 本身提供了 pub/sub 机制来广播键变化事件，但原生能力比较裸，光靠 redis-cli 去订阅只能看到一串频道名，没法过滤、没法转发、也没法管理多个实例。oh-my-hermes 做的事情就是把这一层补上：稳定订阅，按规则过滤，再通过 webhook 或者消息管道把事件推给下游。适合想低成本实现数据变更感知，又不想为了一两个场景直接上消息队列的团队。

1. 这个项目到底解决什么问题

1.1 灵感来源与命名逻辑

先说说名字。“oh-my-”这个前缀，做后端的人应该都不陌生，最有名的就是 oh-my-zsh，一个把 zsh 配置管理做到极致的社区项目。后来社区里各种 “oh-my-xxx” 都有，本质上都是同一个意思：把你的工作流收拾得服服帖帖，开箱即用。Hermes 是希腊神话里的信使神，在技术圈里也不陌生，React Native 用的 JS 引擎就叫 Hermes。搁在这个项目里，Hermes 的意象非常准：Redis 是数据的来源，事件就是它发出的消息，而这个工具就是负责把消息准确送到目的地的那个信使。

这个命名也代表了项目定位。我一开始就没打算把它做成一个重型的消息中间件，目标就三条：轻量、好配、能干活。轻量指的是依赖少、内存占用低；好配指的是一个 yaml 文件搞定所有订阅规则和转发目标；能干活指的是断线重连、消息缓冲、规则过滤这些实际生产中绕不开的问题，必须内置解决。

1.2 Redis 键空间通知的痛点

Redis 的键空间通知机制本身不复杂，核心就两样东西。第一，服务器配置里开启 notify-keyspace-events，告诉 Redis 哪些事件要广播；第二，客户端通过 SUBSCRIBE 或 PSUBSCRIBE 订阅特定频道，接收事件消息。但它有几个很现实的问题，直接用原生接口做生产级服务是撑不住的。

第一个问题：频道格式容易把人绕晕。Redis 事件频道分两类，keyspace@: 这类频道会告诉你“某个键发生了某个操作”，比如keyspace@0:user:10086 上收到一条 set 消息，意思是这个键被 set 了；keyevent@: 这类频道维度是事件类型，比如keyevent@0:expired 上每来一条消息，就意味着有一个键过期了。但不管是哪类，你收到的都只是一个字符串消息，没有结构化字段，实际使用还得自己解析。

第二个问题：键名是直接拼在频道名里的。什么意思？如果你的业务把手机号、身份证这类信息塞进 Redis 键名，那么所有订阅了这个频道的人都能从频道名里看到完整明文。这个在内部系统问题不大，但涉及用户隐私数据时就是个红线，必须提前规范键名。

第三个问题，也是最重要的：pub/sub 是即发即弃（fire-and-forget）的。消费者断线了，消息就丢了；消费者处理慢了，Redis 的发送缓冲区还可能堆积，极端情况下会拖垮 Redis 实例。这些东西用 redis-cli 手动订阅是感受不到的，写成一个常驻服务以后全都会暴露出来。

1.3 适合用的场景和不适合用的场景

我自己实际用下来，最适合 oh-my-hermes 的场景有几类。缓存一致性通知：订单服务更新了数据库，顺手把 Redis 里的缓存键删掉或者改写，其他服务通过订阅捕获这个动作，主动刷新本地缓存。临时状态过期提醒：最常见的订单超时未支付自动关闭、优惠券过期提醒、验证码过期清理，直接在键上设置 EXPIRE，由 expired 事件触发下游逻辑。数据变更触发外部动作：比如某个配置键一变，自动通知所有业务节点 reload 配置，省去每台机器跑一遍运维脚本。

不适合的场景也要说清楚。要求严格不丢消息的核心资金链路，别用它，请老老实实上 MQ；需要消息回溯和堆积消费，别用它，pub/sub 没有历史消息；订阅方太多或者消费太慢，也请慎重，Redis 的 pub/sub 性能在大量消费者下会明显下降。它适合的是那些“丢了可以重试、晚一点没关系、但千万别轮询”的场景。

2. 整体设计思路与核心架构

2.1 消息流向：订阅端到输出端

oh-my-hermes 的整体架构非常简单，一条消息从 Redis 出发到下游业务系统，中间只经过四个阶段：订阅接收、格式解析、规则过滤、路由发送。

订阅接收阶段做的事情，是持有到 Redis 的长连接，通过 PSUBSCRIBE 订阅一批频道模式。这里我会用 Redis 的 RESP2 协议的 psubscribe 机制，而不是 subscribe，原因很简单：subscribe 只能订阅固定频道，而键名是动态的，没法提前枚举完；psubscribe 支持通配符，一个keyevent@*:* 就能覆盖所有库、所有事件类型，配置起来省心得多。

格式解析阶段，把 Redis 推送的原始消息拆成结构化字段。一条原始消息大概长这样：

pmessage __keyevent@0__:expired __keyevent@0__:expired order:timeout:298374

前面是匹配到的模式，中间是具体频道名，最后才是消息内容。解析的时候需要从频道名里抠出 db 编号和事件动作，这样后面过滤才有的放矢。

规则过滤是核心，也是和裸订阅最大的区别。配置里写清楚“什么样的消息才值得转发”，比如只看 db 0、只看 expired 事件、键名只关心 order:timeout: 前缀、剩下的全部丢弃。这个阶段会把绝大多数无关消息挡在外面，避免下游被打爆。

路由发送阶段最灵活，也是我觉得这个小工具最实用的地方。默认支持三类输出目标：HTTP Webhook、标准输出（方便调试）、转发到另一个 Redis 的 pub/sub 上。实际用的时候 Webhook 用得最多，把事件 POST 到业务接口，业务侧收到再去做后续处理。

2.2 为什么选择客户端订阅而不是别的方案

设计的时候我对比过三条路。第一条路就是用现成的消息队列，比如 RabbitMQ、Kafka、Redis Stream，业务系统把变更事件主动发到队列里。这条路可靠性强，功能全，但它要求业务系统主动发消息，侵入性强，很多老系统改不起。第二条路是定时轮询 Redis 键，用 SCAN 扫描出所有匹配前缀的键，再比对状态。这条路对现有代码零侵入，但延迟完全取决于轮询间隔，而且扫描大 keyspace 对 Redis 本身有负担，当你有几十万上百万个键时根本扛不住。第三条路就是 oh-my-hermes 选择的客户端订阅方案，既不侵入业务代码，又能做到准实时，延迟基本在毫秒到百毫秒级别。

订阅方案最大的优势是“旁观者清”。你的业务代码不需要知道有一个信使在监听 Redis，Redis 本身也不需要改动任何数据流逻辑，只是额外发一些通知出来。对于那种“我只想知道某个键过期了没”的诉求，这几乎是当前成本最低的做法。

2.3 关键模块拆解

三个模块我认为最值得分享：连接管理、事件管线、发送缓冲。

连接管理解决的是可靠性问题。正常运行时维护一条到 Redis 的长连接，一旦检测到连接断开，按指数退避策略重连，重连成功后重新执行 psubscribe。这里有个细节特别容易踩坑：Redis 的 pub/sub 连接如果长时间空闲，可能被中间的网络设备断开，但 TCP 层不会立刻感知，所以必须启用应用层的心跳。我的做法是每隔 30 秒发一条 PING，如果连续三次没有 PONG，就主动断开重连。

事件管线是单线程还是多线程，我纠结了很久。第一版用的是每个 Webhook 目标一个线程，后来发现回调变慢时线程越积越多，反而把 CPU 耗在上下文切换上。第二版改成 asyncio 事件循环，Redis 订阅协程只负责把消息解析后丢进 asyncio.Queue，后面由独立的发送 worker 从队列取消息，再异步发 HTTP 请求。这样订阅和发送彻底解耦，Redis 侧的消息读取永远不被下游拖慢。

发送缓冲是实际生产环境教会我的。Webhook 接口可能响应慢，如果发送速度跟不上接收速度，消息就会堆积。缓冲队列撑不住的时候怎么办？我的策略是：队列长度超过阈值后，新消息直接记录到本地日志文件，等队列有空间了再重放。毕竟这类事件消息的实时性要求没那么苛刻，晚几十秒也能接受，但不能丢。

3. 从零配置一个可用实例

3.1 Redis 端必须先做的配置

任何客户端工具都只是半成品，Redis 那一半配置不弄好，一切都白搭。先确认 Redis 版本，最好是 5.0 以上，老版本对部分事件类型支持不完整。然后设置 notify-keyspace-events，方式有两种，临时生效用命令：

redis-cli config set notify-keyspace-events KEA

永久生效就改 redis.conf 里的同名配置项，然后重启 Redis。

这个参数值是一串字母，每个字母代表一类事件。实际生产我建议直接开 KEA，K 代表 keyspace 事件，也就是频道名里带具体键名的那类；E 代表 keyevent 事件，也就是按事件类型分类的那类；A 是“所有事件类型”的别名，展开后等价于 g$lshzxe，覆盖字符串、列表、集合、哈希、有序集合、过期、淘汰等等。

注意一点：配置成 KEA 之后，每个键的每次操作可能产生多条事件消息，消息量会比默认状态大不少。如果有环境是压测或者敏感集群，要评估一下网络开销。但对我们常规业务量来说，这点开销完全可以接受，换来的是完整的可观测性。

3.2 安装 oh-my-hermes 与最小启动

项目用 Python 写的，依赖非常克制，核心就是 redis-py 和 httpx，都走 asyncio。安装直接用 pip：

pip install oh-my-hermes

装完之后先验证版本：

oh-my-hermes --version

最小配置只需要一个 hermes.yaml，放在当前目录或者通过 --config 指定路径。最基础的内容长这样：

redis: host: 127.0.0.1 port: 6379 db: 0 subscribe: - "__keyevent@*__:expired" - "__keyevent@*__:set" - "__keyevent@*__:del" rules: - name: debug-print event: "*" key_prefix: "*" output: stdout

然后直接跑：

oh-my-hermes run --config hermes.yaml

看到日志输出 “subscribed to 3 patterns” 就算启动成功。先订阅全部事件再打印到 stdout，目的是确认 Redis 的事件本身通没通。

3.3 配置一个订单超时提醒的完整例子

确认基础链路没问题后，再来配一个真实的业务场景。假设我们有一个电商订单系统，订单创建后往 Redis 写一个短生命周期的键，键名规则是 order:timeout:{orderId}，存活时间 30 分钟。过期之后，我们希望下游的订单关闭服务收到通知，执行关单操作。

Redis 侧保持 notify-keyspace-events KEA 不变。配置改成只关心 db 0 的 expired 事件，并且键名前缀限死到 order:timeout:：

redis: host: 127.0.0.1 port: 6379 db: 0 subscribe: - "__keyevent@0__:expired" rules: - name: order-timeout event: expired key_prefix: "order:timeout:" output: webhook webhook_url: "http://localhost:8080/api/orders/close-timeout" webhook_template: | {"order_id": "{{ key | replace('order:timeout:', '') }}", "source": "redis-keyspace"}

这个配置的语义是：从键空间通知里接收所有 db 0 的 expired 事件，但只有消息内容是 order:timeout: 开头的键名，才会被 POST 到本地 8080 端口的接口。模板里做了个简单的字符串替换，把 orderId 从键名里提取出来，下游接口只管收 order_id 字段，不用关心 Redis 的键名规则。

为了验证，我用一个临时接口打印请求体，然后手动造一个过期键：

redis-cli -n 0 set order:timeout:10086 "abc" EX 30

30 秒后，接口就会收到类似这样的 POST 请求：

{"order_id": "10086", "source": "redis-keyspace"}

整个过程不需要改任何业务代码，纯粹在 Redis 和 oh-my-hermes 之间搭了一条线。

3.4 事件解析后的字段说明

解析结构是模板和规则过滤的基础，我先列一下每条消息解析后到底有哪些字段。

这几个字段看起来简单，但在配置里用处极大。db 字段可以用在规则里限定某些库不处理；key 字段用来匹配键名前缀；event 字段用来区分动作类型。如果还想拿到键对应的值，就得在 Webhook 规则里配置一个额外的 lookup_keys 选项，工具收到事件后主动从 Redis 里读一次这个键的值再拼到请求体里。不过要注意，对 expired 事件来说，键已经没了，是读不到值的，所以这个功能只建议用于 set、rename 这类事件。

4. 核心代码与关键配置参数解读

4.1 订阅与解析部分的核心逻辑

我摘一段核心的订阅循环代码，做了简化但保留了主干逻辑：

import asyncio import redis.asyncio as aioredis from dataclasses import dataclass @dataclass class RedisEvent: db: str event: str key: str channel: str pattern: str async def listen(rd: aioredis.Redis, patterns: list[str]): pubsub = rd.pubsub() await pubsub.psubscribe(*patterns) async for message in pubsub.listen(): if message["type"] != "pmessage": continue pattern = message["channel"].decode() if isinstance(message["channel"], bytes) else message["channel"] data = message["data"].decode() if isinstance(message["data"], bytes) else message["data"] # 频道格式: __keyevent@{db}__:{event} 或 __keyspace@{db}__:{key} meta, _, right = pattern.rpartition(":") if meta.startswith("__keyevent@"): db = meta.split("@")[1].split("__")[0] ev = right key = data yield RedisEvent(db=db, event=ev, key=key, channel=pattern, pattern=pattern) else: # keyspace 类型需要再从频道名里抠键名 # 形如 __keyspace@0__:order:timeout:10086 left, _, _ = pattern.partition(":") meta = left[len("__keyspace@"):] db = meta.split("__")[0] ev = data key = pattern.split(":", 1)[1] yield RedisEvent(db=db, event=ev, key=key, channel=pattern, pattern=pattern)

这个循环本身不做事，只做“接住事件、拍平字段”的工作。注意我特意区分了 keyevent 和 keyspace 两种频道的解析规则，因为它们的事件内容语义完全不同：keyevent 频道的消息体是键名，keyspace 频道的消息体是动作。第一次写代码时没看清文档，在这上面浪费了不少时间。

4.2 规则过滤的匹配逻辑

有了结构化字段之后，过滤规则就很好写了。核心的匹配逻辑我用的是“简单优先、命中即止”的策略：配置里每条规则有 event、key_prefix、db 三个可选的匹配条件，消息进来后逐条规则判断，只要有一条全部匹配，就用这条规则的输出配置，不再继续往下匹配。

event 的匹配支持精确值和通配符，例如 expired、set、del，或者直接写 * 匹配所有。key_prefix 做的是字符串前缀匹配，所以配置成 order:timeout: 能同时覆盖 order:timeout:10086 和 order:timeout:99999。db 字段默认不设置等于匹配所有库，但一旦设置就必须精确相等。

这个设计的取舍在于：把复杂度放在规则上，代码保持简单。如果后面需要更复杂的正则匹配，我预留了 key_pattern 字段，用 re.search 做正则匹配，优先级高于 key_prefix。但用下来的感觉是，之前配置的几十条规则里，用到正则的不超过三条，前缀匹配已经覆盖了绝大部分场景。

4.3 Webhook 发送器为什么必须带缓冲

接收和发送如果不解耦，整个工具会变成一根脆弱的链条：下游接口慢，订阅协程就卡住，Redis 的发送缓冲区会膨胀，甚至触发 Redis 的 client output buffer limit，把订阅连接断开。这个坑我在联调阶段真实遇到过，现象是运行一小时后 Redis 日志里出现 “Client closed connection” 还有 “output buffer limit reached” 的报错。

后来设计发送模块时，我加了一个固定大小的 asyncio.Queue 作为缓冲，发送 worker 从队列里取消息发 HTTP。队列满的时候采用丢弃且落盘的策略，而不是阻塞生产端。

async def send_worker(queue: asyncio.Queue, client: httpx.AsyncClient): while True: item = await queue.get() try: resp = await client.post(item["url"], json=item["payload"], timeout=5) if resp.status_code >= 500: # 服务端5xx，重试一次 await asyncio.sleep(1) await client.post(item["url"], json=item["payload"], timeout=5) except Exception as exc: log_message_to_disk(item, exc)

每次发送超时控制到 5 秒，避免某个慢接口拖死整个 worker。下游服务如果持续抖动，消息会落在本地磁盘上，至少比全丢强。

4.4 几个容易忽略的配置细节

第一个细节是 db 编号。Redis 键空间通知的频道里带 db 编号，比如 db 0 就是keyevent@0:expired，db 1 就是keyevent@1:expired。用通配符 * 能覆盖所有库，但通配符订阅会让解析逻辑多一层判断，性能略有下降。如果业务明确只用 db 0，直接订阅keyevent@0:* 是更稳的选择。

第二个细节是 rename 事件会导致事件顺序变化。Redis 的 RENAME 命令会触发 rename_from 和 rename_to 两个独立事件，而且两个事件的发布顺序在不同 Redis 版本里不一定保持一致。如果你的下游逻辑对“哪个键先通知”有顺序要求，尽量绕开 rename，或者在下游做状态收敛。

第三个细节是 expired 事件的实际触发时机。很多人以为 EXPIRE 到了就立刻收到 expired 事件，实际不是。Redis 对过期键的删除是惰性的，只有在键被访问或者专门的过期扫描线程跑到时才真正删除，所以 expired 事件可能比预期延迟几十秒。这个不是 bug，是 Redis 的设计。对毫秒级精确过期有要求的场景，等这个事件是不现实的。

5. 常见问题与排查实录

5.1 明明配置了规则，为什么收不到事件

这是被问得最多的一个问题。我排查时按顺序检查四件事。

第一，Redis 的 notify-keyspace-events 到底有没有生效。用 CONFIG GET notify-keyspace-events 看一下，如果返回空字符串，说明配置没落上，事件永远发不出来。配置文件改了要重启，CONFIG SET 只对当前运行期生效，重启后会丢。

第二，psubscribe 的 pattern 和实际频道对没对上。比如业务用的是 db 1，你订阅的是keyevent@0:expired，那就永远收不到。用 redis-cli 手动 psubscribekeyevent@1:* 验证一下，如果手动能收到，说明 Redis 端没问题，问题在配置的 db 号。

第三，检查事件类型缩写。Redis 的 notify-keyspace-events 有一个特别容易踩的坑：A 参数是 g$lshzxe 的别名，但不包含 m（键未命中）和 n（新键）。如果你需要 new key 事件，必须显式加上 n，不能指望 A 帮你覆盖。

第四，检查客户端是不是老版本导致订阅后连接被自动断开。老版本的 redis-py 对 pubsub 的 keepalive 处理有 bug，长时间空闲会被网络设备掐断。升级到最新版本，并在配置里把 socket_keepalive 打开。

5.2 expired 事件延迟特别高，正常吗

正常，但需要判断延迟是来自 Redis 还是来自工具本身。Redis 键过期后，删除动作依赖惰性删除和周期性扫描的配合：周期扫描默认每秒跑 10 次，每次取一部分过期键删除，所以延迟理论上在百毫秒级到秒级波动，极端情况下如果你的键一直不被访问，可能有几十秒的差距。

工具这一侧的延迟，我压测过，从 Redis 发布事件到 Webhook 发出请求，p99 在 50 毫秒以内。所以如果你测出几分钟甚至更久的延迟，先别怀疑工具，先用 redis-cli psubscribe 手动订阅确认 Redis 的动作。如果手动订阅也收得晚，那就是 Redis 自己的行为。要解决精确性问题，只能改造业务侧，比如创建键的时候同时写入一个延迟队列，让队列在指定时间之后主动触发。

5.3 高并发下消息会不会丢，重复怎么办

会丢的是极端情况：发送队列满了之后，新消息会落盘而不是阻塞。如果落盘也失败，那就是真的丢。但正常情况下，只要磁盘可写，消息最多是延迟处理，而不是消失。

重复是另一种情况，需要特别注意。pub/sub 本身没有消息确认机制，客户端重连后重新订阅，不会自动补发之前的消息；但这不代表下游不会收到重复事件。比如 Redis 主从切换后，客户端重连到新的主节点，旧连接上的消息可能重发一次；再比如下游业务接口超时之后又重试了一次，也会造成重复。所以下游处理事件时一定要保证幂等：订单关闭接口收到两次相同 orderId 的请求，第二次应该直接返回成功，不应再次改变订单状态。我在工具文档里专门加了一节幂等建议，这是生产环境必须养成的习惯。

5.4 常见问题速查表

6. 一些真实使用体会和扩展方向

6.1 怎么把它接进已有的缓存链路

如果你已经在用缓存 + 数据库的模式，接入这个工具不需要大改。最常见的接法是这样：业务更新数据库成功后，删除或更新 Redis 缓存键。同时 Redis 的键事件会推给 oh-my-hermes，下游服务收到 DEL 事件后，主动清理自己的 JVM 本地缓存。整个过程业务代码只加了原来删除缓存那一行，其他完全不用动。

另外一个可以扩展的方向是“缓存预热”。比如运营后台改了一批配置项，写入 Redis 后触发 set 事件，oh-my-hermes 把事件广播到所有业务节点，每个节点收到后主动重新读取配置。这个比定时刷新实时得多，也比每次请求都穿透去数据库查要省很多。

6.2 和消息队列的边界在哪里

这是很多同事问过的问题：有了 oh-my-hermes，是不是可以不用 Kafka 了？我的答案一直是：不能，它替代不了 MQ。消息队列的核心能力是持久化、回溯消费、堆积削峰、多消费者组，这些 oh-my-hermes 都不具备。它适合的永远是“轻量、准实时、可容忍偶发丢失”的场景。

但有时候两者可以互补。比如 upstream 系统负责推送数据变更到 Kafka，下游系统消费 Kafka 做数据同步；这里面如果还牵扯到 Redis 状态变更，理论上也可以用 oh-my-hermes 做一条旁路通知，专门给需要快速响应的模块用。这种“MQ 做主链路、事件通知做旁路”的组合，在实践中比把一切都堆到 MQ 上更好维护。

6.3 关于工具边界和个人体会

用这个工具大半年，最大的感受是：Redis 键空间通知是一把被低估的利器，但它有非常明确的适用边界。它擅长的场景是让已有系统以极低的改造成本获得变更感知能力，它不擅长的场景是要求强一致、强可靠的任何链路。

我个人现在定制了一个小习惯：所有新服务的 Redis 键名统一加上业务前缀，并且在文档里写清楚哪些前缀会被事件订阅监听、哪些前缀涉及敏感信息不能裸放。同时把 oh-my-hermes 的 Webhook 地址统一收敛到一个网关入口，下游接口变更时只需要网关转发，不需要挨个改配置。这些习惯比工具本身的代码更重要，因为工具只是把消息送到你面前，最终怎么用、用在哪里，还是要靠你自己对业务边界的理解。如果你也在为“Redis 状态变化如何低成本通知下游”发愁，可以先拿它跑一版试试，动手验证过，才知道这套方案适不适合你。