跳到主要内容
锦木信息 JINMU INFO
Redis 博客
Redis · 遍历键

别用 KEYS *

SCAN 怎么用游标安全地遍历亿级键

线上要找出所有 session:* 的键,顺手敲了句 KEYS session:*——几千万键的实例,这一下可能卡死整个服务几秒钟。正确做法是 SCAN:用一个游标,把"遍历全库"切成许多小步,谁都不卡。

▲ KEYS:一次扫全库,阻塞;SCAN:游标分批,每步只扫一点KEYS vs SCAN
KEYS session:* —— 一口气扫全库 ⚠ 执行期间,其它所有请求全部阻塞干等 ⏳ 其它客户端:等…等…等…(可能好几秒) SCAN 0 → SCAN 17 → SCAN 42 → … → SCAN 0 —— 游标分批 批1 →cur 17 批2 →cur 42 批3 →cur 96 批4 →… 末批 →cur 0 ✓ ↔↔ 每批之间,事件循环照常服务别的请求 → 不卡
01 · 祸根

KEYS 为什么是生产禁忌

问题出在两点叠加。一是 O(N):KEYS pattern 会遍历整个键空间逐个匹配,键越多越慢。二是单线程:Redis 命令串行执行,KEYS 跑的这几秒里,其它所有客户端全被堵在后面。两者相乘,就是一次自酿的"服务抖动"甚至雪崩。

KEYS session:* # ✗ 千万级键上可能阻塞数秒,生产禁用 # 文档明确:KEYS 应只用于调试、或小数据集的手工排查
打个比方

像让唯一的一个店员当众把仓库里每一件货都翻出来念一遍名字——这期间,排队结账的所有顾客都只能干等。SCAN 则是让他"每次只翻一小格,翻完招呼下一位,再回来接着翻",队伍不会堵死。

02 · 游标

SCAN 怎么用:游标接力

SCAN 是游标式的:你从游标 0 开始,每次调用返回"这一小批键 + 下一个游标";把返回的游标再传进去接着扫,直到游标回到 0,遍历结束。每一步只做一点点活,中间事件循环能喘口气服务别人。

SCAN 0 # → 返回 [cursor=17, [key1, key2, ...]] SCAN 17 # → 返回 [cursor=42, [...]] SCAN 42 # → 返回 [cursor=0, [...]] 游标=0 → 结束 # Python 示意 cursor = 0 while True: cursor, batch = r.scan(cursor, match='session:*', count=500) handle(batch) if cursor == 0: break # 唯一的结束条件
!

三个新手必踩的坑:① 判断结束只看游标是否为 0,不能看"这批是不是空"——某一批返回 0 个键是完全正常的,不代表结束。② 游标是不透明的,别去解析或自己改。③ 别并发复用同一个游标,一条遍历链路要串行接力。

03 · 保证

它保证什么,不保证什么

SCAN 的精妙,在于它给了一组"弱但够用"的保证——即使遍历期间字典在扩容/缩容(rehash),它也不漏掉"全程都在"的键:

✓ 保证
  • 全程存在的键,至少返回一次(从遍历开始到结束一直在的)
  • 不返回幽灵键:全程都不存在的键,绝不会冒出来
✗ 不保证
  • 可能重复:同一个键可能被返回多次 → 处理要幂等或自己去重
  • 遍历期间增删的键:可能返回,也可能不返回,行为未定义
  • 每批的数量:不固定,甚至为 0

实现上靠的是"反向二进制"游标——它从高位开始进位,使得哈希表在遍历途中 rehash(桶数量翻倍/减半)时,已扫和未扫的边界依然清晰,从而不丢键。你不必懂细节,只需知道:它在并发写入下仍能完整遍历,这正是它取代 KEYS 的底气。

04 · 选项

MATCH、COUNT、TYPE

选项作用 / 注意
MATCH patternglob 过滤。注意:是"先取回一批、再过滤"——所以某批可能一个都不匹配,这正常。
COUNT n每批大约做多少工作的提示(默认 10),不是精确条数。想减少往返就调大(如 500~1000)。
TYPE t只返回指定类型的键(string/list/set/zset…),6.0+。
i

一个容易困惑的组合:MATCH 很窄 + COUNT 很小时,很多批会"颗粒无收"。因为过滤发生在取回之后——这更说明结束判断只能看游标。想让带 MATCH 的遍历少跑几趟,就把 COUNT 调大。

05 · 一家子

不只扫键:HSCAN / SSCAN / ZSCAN

同样的游标思想,也用来安全地遍历一个大集合内部。当某个 Hash / Set / Zset 本身有几百万成员,直接 HGETALL/SMEMBERS 一把取回,同样会阻塞——这时用对应的 SCAN 家族:

SCAN遍历整个键空间(所有 key)
HSCAN key遍历一个 Hash 的字段-值;NOVALUES 可只返回字段名
SSCAN key遍历一个 Set 的成员
ZSCAN key遍历一个 Zset 的成员-分数
HSCAN bighash 0 COUNT 500 # 分批遍历大 Hash,替代 HGETALL HSCAN bighash 0 NOVALUES # 只要字段名,不要值 SSCAN bigset 0 MATCH vip:* # 分批遍历大 Set

口径一致:都是游标式、都能带 MATCH/COUNT、都用游标=0 判结束。记住:凡是"一次性全量取回"的命令,在大数据量上都该换成对应的 SCAN。

收尾 · 一句话

把"一口闷",改成小口喝

单线程下,KEYS * 这类 O(N) 全量命令会把整个实例卡住。SCAN 用一个反向二进制游标把遍历切成许多小批,中间不阻塞别人,还保证"全程存在的键至少返回一次"(代价是可能重复、需幂等)。同理 HGETALL/SMEMBERS 在大集合上换成 HSCAN/SSCAN。

KEYS=O(N)+单线程→生产禁用 · SCAN 游标:0 开始,游标回 0 结束(空批正常,游标不透明) · 保证"全程在的键至少一次"/不返回幽灵键;不保证不重复(要幂等) · MATCH 取回后过滤·COUNT 是提示·TYPE · 大集合用 HSCAN/SSCAN/ZSCAN

内容依据 Redis 官方文档整理 · redis.io/docs · SCAN

示例为说明性示意;游标语义与选项以对应 Redis 版本为准。

聊聊您的数据难题

告诉我们业务现状,资深技术顾问一对一给出选型与实施建议,咨询免费。