Redis SCAN 命令详解：安全遍历海量键的利器

ops/2025/3/3 5:07:42/

一、SCAN 命令的核心价值

Redis 的 KEYS * 命令虽然可以遍历所有键，但在生产环境中直接使用可能导致服务阻塞（时间复杂度 O(n)）。SCAN 命令通过游标分批次迭代，实现非阻塞式遍历，成为处理百万级键的安全选择。

二、命令语法与参数解析

1. 基础语法

SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]

2. 参数说明

参数	作用
`cursor`	游标值，首次传入 0，后续使用前次返回的游标
`MATCH`	模式匹配，如 `user:*` 过滤以 “user:” 开头的键
`COUNT`	建议返回数量（默认 10），实际返回可能不同，不影响迭代完整性
`TYPE`	指定键类型（Redis 6.0+），如 `string`、`hash`、`list` 等

三、使用示例

1. 基础迭代

# 第一次迭代
127.0.0.1:6379> SCAN 0
1) "17"            # 下次迭代的游标
2) 1) "user:1001"2) "product:2023"3) "session:abcd"# 基于新游标继续
127.0.0.1:6379> SCAN 17
1) "0"             # 游标归零，迭代完成
2) 1) "order:5678"

2. 结合 MATCH 和 COUNT

# 查找以 "prod" 开头的键，每批最多 50 个
127.0.0.1:6379> SCAN 0 MATCH prod* COUNT 50
1) "23"
2) 1) "prod:100"2) "prod:101"

3. 指定键类型（Redis 6.0+）

# 仅返回 Hash 类型键
127.0.0.1:6379> SCAN 0 TYPE hash
1) "5"
2) 1) "user:profile:1001"2) "product:meta:2023"

四、SCAN 的核心特点

1. 非阻塞迭代

原理：基于字典槽（slot）分批次遍历，每批耗时 O(1)
优势：避免单次操作长时间阻塞主线程

2. 不保证完全一致性

表现：迭代期间新增/删除的键可能被包含或遗漏
原因：采用“快照”机制，但非强一致性视图

3. 可能返回重复键

概率：约 10%-20% 的重复率（取决于数据修改频率）
处理：客户端需自行去重

4. 适用场景

统计键数量、导出匹配模式的键
定期清理过期数据（结合 TTL 检查）
大数据量的键空间分析

五、SCAN 家族命令

命令	作用	示例
`SSCAN`	遍历集合元素	`SSCAN myset 0 MATCH a*`
`HSCAN`	遍历哈希表字段	`HSCAN user:1001 0`
`ZSCAN`	遍历有序集合成员	`ZSCAN rankings 0`

六、注意事项与最佳实践

1. COUNT 参数调优

小值（如 10）：适合网络延迟敏感场景
大值（如 1000）：适合内网低延迟环境
建议：根据平均键大小和网络条件动态调整

2. 客户端去重方案

# Python 示例：使用集合去重
seen = set()
cursor = 0
while True:cursor, keys = redis.scan(cursor, match='user:*', count=100)for key in keys:if key not in seen:process(key)seen.add(key)if cursor == 0:break