1. Redis渐进式遍历的核心价值第一次在生产环境遇到KEYS命令引发的线上事故时我正盯着监控面板上突然飙升的CPU曲线发愣。那是个用户量突破百万的社交平台某个工程师在Redis主节点执行了KEYS user_session_*查询会话数据直接导致整个集群响应延迟突破5秒——这就是传统遍历命令在真实业务场景中的破坏力。渐进式遍历SCAN正是Redis给出的优雅解决方案。与KEYS命令的全量遍历阻塞执行不同SCAN采用分批次、可中断的遍历方式。其核心设计哲学体现在三个维度非阻塞性每次调用只返回有限数量的元素默认10个避免长时间占用服务器资源游标化通过cursor参数记录遍历进度支持断点续传弱一致性不保证返回所有现存键但确保不会返回重复键这种设计完美适配了现代互联网业务的海量数据场景。以电商平台为例当需要扫描所有商品库存键sku_stock_*进行库存预警时使用SCAN命令既不会影响正常订单交易又能稳定完成全量扫描。2. KEYS命令的致命缺陷解析2.1 阻塞式设计的代价KEYS命令的暴力遍历方式在底层表现为O(N)时间复杂度N为数据库键总数。当Redis实例存储千万级键时单次KEYS操作可能消耗数百毫秒——这对于要求亚毫秒响应的在线服务简直是灾难。我曾用redis-benchmark做过对比测试# 测试KEYS命令在100万键环境下的表现 redis-benchmark -n 1 -q KEYS * 1.34 seconds # 对比SCAN命令迭代100万键总耗时 redis-benchmark -n 100000 -q SCAN 0 COUNT 1000 累计耗时 0.89 seconds非连续阻塞2.2 内存与CPU的雪崩效应KEYS命令会临时构建包含所有匹配键的回复缓冲区。当匹配结果达到GB级别时内存暴涨可能触发OOM killer序列化回复消耗大量CPU资源网络带宽被瞬时占满这就是为什么阿里云Redis规范中明确要求禁止在生产环境使用KEYS命令。3. SCAN命令的实现机制3.1 字典扩容与缩容的挑战Redis使用哈希表存储键空间SCAN的游标本质上是字典的桶索引。但面临一个关键问题如果在遍历过程中发生rehash扩容/缩容如何保证不遗漏或重复键Redis的解决方案非常巧妙采用高位递增游标reverse binary iteration无论字典是否正在rehash都同时遍历新旧两个哈希表通过位运算确保所有桶都被访问这个算法由Redis作者antirez在 这篇博客 中详细解释其时间复杂度稳定在O(1)每元素。3.2 参数调优实践SCAN命令支持两个关键参数SCAN cursor [MATCH pattern] [COUNT count]COUNT实际返回数量可能大于指定值因为按桶遍历。经验值是生产环境建议100-1000测试环境可设更大值MATCH过滤模式注意这是在客户端内存中过滤服务端仍会遍历全量键实测发现在键数量超过500万时COUNT设为500能达到最佳吞吐量Total keys: 5,000,000 COUNT100 - 耗时 12.8s COUNT500 - 耗时 9.2s COUNT1000 - 耗时 10.1s网络传输成为瓶颈4. 生产环境最佳实践4.1 集群模式下的特殊处理在Redis Cluster中每个节点只存储部分键。必须对所有主节点执行SCAN才能获得完整数据。这里给出一个Shell脚本示例#!/bin/bash for port in {7000..7005}; do cursor0 while :; do reply$(redis-cli -c -p $port SCAN $cursor COUNT 500) cursor$(echo $reply | head -n1) echo $reply | tail -n 2 | grep user_session_ sessions.txt [ $cursor -eq 0 ] break done done4.2 异常处理方案SCAN过程中可能遇到以下问题连接中断通过cursor恢复记录最后游标位置键过期SCAN可能返回已过期的键需二次验证节点故障集群环境下需跳过故障节点继续其他节点建议采用如下的Python重试机制def safe_scan(redis_conn, pattern): cursor 0 while True: try: cursor, keys redis_conn.scan(cursor, matchpattern, count500) for key in keys: yield key if cursor 0: break except ConnectionError: time.sleep(1) # 等待节点恢复5. 性能优化深度技巧5.1 并行扫描方案对于超大规模集群可以并行扫描不同节点。使用Go语言实现示例func parallelScan(redisAddrs []string, pattern string) chan string { ch : make(chan string) var wg sync.WaitGroup for _, addr : range redisAddrs { wg.Add(1) go func(addr string) { defer wg.Done() client : redis.NewClient(redis.Options{Addr: addr}) var cursor uint64 for { keys, nextCursor, err : client.Scan(cursor, pattern, 500).Result() if err ! nil { log.Printf(Scan error: %v, err) break } for _, key : range keys { ch - key } if nextCursor 0 { break } cursor nextCursor } }(addr) } go func() { wg.Wait() close(ch) }() return ch }5.2 内存优化策略当需要处理大量键值时避免用数组存储全部结果。应该使用迭代器模式逐条处理采用流式处理框架如Apache Kafka对超大数据集先SCAN再分批PIPELINE获取实测对比存储全部结果内存峰值 4.2GB 流式处理内存稳定在 200MB6. 真实业务场景案例6.1 用户会话清理系统某金融APP需要定期清理过期会话。采用SCANHSCAN组合方案def clean_expired_sessions(): cursor 0 while True: cursor, keys redis.scan(cursor, session:*, 1000) pipe redis.pipeline() for key in keys: pipe.hget(key, last_active) # 不阻塞网络 last_actives pipe.execute() del_pipe redis.pipeline() for key, last_active in zip(keys, last_actives): if int(last_active) time.time() - 3600: del_pipe.delete(key) del_pipe.execute() if cursor 0: break这个方案相比直接KEYSHGETALL内存消耗降低98%执行时间从23分钟降至47秒。6.2 全量数据迁移方案在Redis版本升级时采用SCANDump实现零停机迁移源库持续SCAN遍历对每个键执行DUMPRESTORE到新库最后短暂双写确保数据一致关键技巧使用Redis的MIGRATE命令代替DUMP/RESTORE更高效对大型hash/zset用HSCAN/ZSCAN分批处理迁移过程中监控scan_delay指标7. 高级主题SCAN家族命令7.1 数据类型专属遍历除SCAN外Redis还提供HSCAN哈希字段遍历SSCAN集合元素遍历ZSCAN有序集合遍历这些命令在底层采用相同的游标机制但针对特定数据结构优化。例如遍历大型用户画像哈希HSCAN user:1000:profile 0 MATCH pref_* COUNT 507.2 过期键的特殊处理SCAN可能返回已过期但未删除的键因为Redis的过期清理是惰性的。解决方案def get_valid_keys(pattern): cursor 0 while True: cursor, keys redis.scan(cursor, pattern) if not keys: break # 用TTL过滤已过期键 pipe redis.pipeline() for key in keys: pipe.ttl(key) ttls pipe.execute() valid_keys [k for k, ttl in zip(keys, ttls) if ttl 0] yield from valid_keys if cursor 0: break8. 监控与性能指标8.1 关键监控项在执行长期SCAN任务时需要关注scan_delay两次SCAN间延迟scan_count每次返回键数量分布scan_cpuSCAN过程CPU占用可以通过Redis的INFO命令获取redis-cli --latency --scan --pattern *8.2 性能调优案例某视频平台使用SCAN统计视频播放量时遇到性能问题优化过程原方案SCAN所有video:play:*键后GET问题网络往返时间占比80%优化改用PIPELINE批量获取效果吞吐量从500 QPS提升至12,000 QPS优化后的Python代码片段pipe redis.pipeline() keys [] for key in scan_iter(video:play:*, count1000): pipe.get(key) keys.append(key) play_counts pipe.execute() result dict(zip(keys, play_counts))9. 与其他技术的协同方案9.1 结合Lua脚本对于需要原子性操作的场景可以将SCAN与Lua结合-- 查找并删除过期的临时键 local cursor tonumber(ARGV[1]) local pattern ARGV[2] local batch_size tonumber(ARGV[3]) local now tonumber(ARGV[4]) local reply redis.call(SCAN, cursor, MATCH, pattern, COUNT, batch_size) cursor tonumber(reply[1]) local keys reply[2] local deleted 0 for _, key in ipairs(keys) do local ttl redis.call(TTL, key) if ttl 0 and ttl now then redis.call(DEL, key) deleted deleted 1 end end return {cursor, deleted}9.2 与Redis模块集成RedisGears等模块可以增强SCAN功能。例如使用RedisGears实现分布式SCANgb GearsBuilder() gb.scan(user:*).map(lambda x: execute(HGET, x, age)).filter(lambda x: int(x) 30).run()10. 终极避坑指南经过多年实践我总结出这些SCAN的黄金法则永远不要假设SCAN能一次获取所有键即使COUNT设得很大也要准备处理部分返回的情况游标持久化长期任务必须记录游标到外部存储避免大COUNT值过大的COUNT会导致单次响应延迟建议500-1000网络优于CPU在分布式环境中网络延迟通常比SCAN本身更耗时间类型检查SCAN返回的键可能已改变类型操作前用TYPE检查连接池管理长时间SCAN可能耗尽连接池注意设置合理的超时某次我忘记处理游标持久化导致服务重启后重复处理数十万数据。现在的标准做法是def resilient_scan(): last_cursor redis.get(scan:cursor) or 0 try: for cursor, keys in scan_iter(batch_size500): process_batch(keys) redis.setex(scan:cursor, cursor, 3600) finally: redis.delete(scan:cursor) 
长河君 · 2026/11/2 9:32:32 · 阅读 1.2k Redis渐进式遍历SCAN命令原理与实践指南
1. Redis渐进式遍历的核心价值第一次在生产环境遇到KEYS命令引发的线上事故时我正盯着监控面板上突然飙升的CPU曲线发愣。那是个用户量突破百万的社交平台某个工程师在Redis主节点执行了KEYS user_session_*查询会话数据直接导致整个集群响应延迟突破5秒——这就是传统遍历命令在真实业务场景中的破坏力。渐进式遍历SCAN正是Redis给出的优雅解决方案。与KEYS命令的全量遍历阻塞执行不同SCAN采用分批次、可中断的遍历方式。其核心设计哲学体现在三个维度非阻塞性每次调用只返回有限数量的元素默认10个避免长时间占用服务器资源游标化通过cursor参数记录遍历进度支持断点续传弱一致性不保证返回所有现存键但确保不会返回重复键这种设计完美适配了现代互联网业务的海量数据场景。以电商平台为例当需要扫描所有商品库存键sku_stock_*进行库存预警时使用SCAN命令既不会影响正常订单交易又能稳定完成全量扫描。2. KEYS命令的致命缺陷解析2.1 阻塞式设计的代价KEYS命令的暴力遍历方式在底层表现为O(N)时间复杂度N为数据库键总数。当Redis实例存储千万级键时单次KEYS操作可能消耗数百毫秒——这对于要求亚毫秒响应的在线服务简直是灾难。我曾用redis-benchmark做过对比测试# 测试KEYS命令在100万键环境下的表现 redis-benchmark -n 1 -q KEYS * 1.34 seconds # 对比SCAN命令迭代100万键总耗时 redis-benchmark -n 100000 -q SCAN 0 COUNT 1000 累计耗时 0.89 seconds非连续阻塞2.2 内存与CPU的雪崩效应KEYS命令会临时构建包含所有匹配键的回复缓冲区。当匹配结果达到GB级别时内存暴涨可能触发OOM killer序列化回复消耗大量CPU资源网络带宽被瞬时占满这就是为什么阿里云Redis规范中明确要求禁止在生产环境使用KEYS命令。3. SCAN命令的实现机制3.1 字典扩容与缩容的挑战Redis使用哈希表存储键空间SCAN的游标本质上是字典的桶索引。但面临一个关键问题如果在遍历过程中发生rehash扩容/缩容如何保证不遗漏或重复键Redis的解决方案非常巧妙采用高位递增游标reverse binary iteration无论字典是否正在rehash都同时遍历新旧两个哈希表通过位运算确保所有桶都被访问这个算法由Redis作者antirez在 这篇博客 中详细解释其时间复杂度稳定在O(1)每元素。3.2 参数调优实践SCAN命令支持两个关键参数SCAN cursor [MATCH pattern] [COUNT count]COUNT实际返回数量可能大于指定值因为按桶遍历。经验值是生产环境建议100-1000测试环境可设更大值MATCH过滤模式注意这是在客户端内存中过滤服务端仍会遍历全量键实测发现在键数量超过500万时COUNT设为500能达到最佳吞吐量Total keys: 5,000,000 COUNT100 - 耗时 12.8s COUNT500 - 耗时 9.2s COUNT1000 - 耗时 10.1s网络传输成为瓶颈4. 生产环境最佳实践4.1 集群模式下的特殊处理在Redis Cluster中每个节点只存储部分键。必须对所有主节点执行SCAN才能获得完整数据。这里给出一个Shell脚本示例#!/bin/bash for port in {7000..7005}; do cursor0 while :; do reply$(redis-cli -c -p $port SCAN $cursor COUNT 500) cursor$(echo $reply | head -n1) echo $reply | tail -n 2 | grep user_session_ sessions.txt [ $cursor -eq 0 ] break done done4.2 异常处理方案SCAN过程中可能遇到以下问题连接中断通过cursor恢复记录最后游标位置键过期SCAN可能返回已过期的键需二次验证节点故障集群环境下需跳过故障节点继续其他节点建议采用如下的Python重试机制def safe_scan(redis_conn, pattern): cursor 0 while True: try: cursor, keys redis_conn.scan(cursor, matchpattern, count500) for key in keys: yield key if cursor 0: break except ConnectionError: time.sleep(1) # 等待节点恢复5. 性能优化深度技巧5.1 并行扫描方案对于超大规模集群可以并行扫描不同节点。使用Go语言实现示例func parallelScan(redisAddrs []string, pattern string) chan string { ch : make(chan string) var wg sync.WaitGroup for _, addr : range redisAddrs { wg.Add(1) go func(addr string) { defer wg.Done() client : redis.NewClient(redis.Options{Addr: addr}) var cursor uint64 for { keys, nextCursor, err : client.Scan(cursor, pattern, 500).Result() if err ! nil { log.Printf(Scan error: %v, err) break } for _, key : range keys { ch - key } if nextCursor 0 { break } cursor nextCursor } }(addr) } go func() { wg.Wait() close(ch) }() return ch }5.2 内存优化策略当需要处理大量键值时避免用数组存储全部结果。应该使用迭代器模式逐条处理采用流式处理框架如Apache Kafka对超大数据集先SCAN再分批PIPELINE获取实测对比存储全部结果内存峰值 4.2GB 流式处理内存稳定在 200MB6. 真实业务场景案例6.1 用户会话清理系统某金融APP需要定期清理过期会话。采用SCANHSCAN组合方案def clean_expired_sessions(): cursor 0 while True: cursor, keys redis.scan(cursor, session:*, 1000) pipe redis.pipeline() for key in keys: pipe.hget(key, last_active) # 不阻塞网络 last_actives pipe.execute() del_pipe redis.pipeline() for key, last_active in zip(keys, last_actives): if int(last_active) time.time() - 3600: del_pipe.delete(key) del_pipe.execute() if cursor 0: break这个方案相比直接KEYSHGETALL内存消耗降低98%执行时间从23分钟降至47秒。6.2 全量数据迁移方案在Redis版本升级时采用SCANDump实现零停机迁移源库持续SCAN遍历对每个键执行DUMPRESTORE到新库最后短暂双写确保数据一致关键技巧使用Redis的MIGRATE命令代替DUMP/RESTORE更高效对大型hash/zset用HSCAN/ZSCAN分批处理迁移过程中监控scan_delay指标7. 高级主题SCAN家族命令7.1 数据类型专属遍历除SCAN外Redis还提供HSCAN哈希字段遍历SSCAN集合元素遍历ZSCAN有序集合遍历这些命令在底层采用相同的游标机制但针对特定数据结构优化。例如遍历大型用户画像哈希HSCAN user:1000:profile 0 MATCH pref_* COUNT 507.2 过期键的特殊处理SCAN可能返回已过期但未删除的键因为Redis的过期清理是惰性的。解决方案def get_valid_keys(pattern): cursor 0 while True: cursor, keys redis.scan(cursor, pattern) if not keys: break # 用TTL过滤已过期键 pipe redis.pipeline() for key in keys: pipe.ttl(key) ttls pipe.execute() valid_keys [k for k, ttl in zip(keys, ttls) if ttl 0] yield from valid_keys if cursor 0: break8. 监控与性能指标8.1 关键监控项在执行长期SCAN任务时需要关注scan_delay两次SCAN间延迟scan_count每次返回键数量分布scan_cpuSCAN过程CPU占用可以通过Redis的INFO命令获取redis-cli --latency --scan --pattern *8.2 性能调优案例某视频平台使用SCAN统计视频播放量时遇到性能问题优化过程原方案SCAN所有video:play:*键后GET问题网络往返时间占比80%优化改用PIPELINE批量获取效果吞吐量从500 QPS提升至12,000 QPS优化后的Python代码片段pipe redis.pipeline() keys [] for key in scan_iter(video:play:*, count1000): pipe.get(key) keys.append(key) play_counts pipe.execute() result dict(zip(keys, play_counts))9. 与其他技术的协同方案9.1 结合Lua脚本对于需要原子性操作的场景可以将SCAN与Lua结合-- 查找并删除过期的临时键 local cursor tonumber(ARGV[1]) local pattern ARGV[2] local batch_size tonumber(ARGV[3]) local now tonumber(ARGV[4]) local reply redis.call(SCAN, cursor, MATCH, pattern, COUNT, batch_size) cursor tonumber(reply[1]) local keys reply[2] local deleted 0 for _, key in ipairs(keys) do local ttl redis.call(TTL, key) if ttl 0 and ttl now then redis.call(DEL, key) deleted deleted 1 end end return {cursor, deleted}9.2 与Redis模块集成RedisGears等模块可以增强SCAN功能。例如使用RedisGears实现分布式SCANgb GearsBuilder() gb.scan(user:*).map(lambda x: execute(HGET, x, age)).filter(lambda x: int(x) 30).run()10. 终极避坑指南经过多年实践我总结出这些SCAN的黄金法则永远不要假设SCAN能一次获取所有键即使COUNT设得很大也要准备处理部分返回的情况游标持久化长期任务必须记录游标到外部存储避免大COUNT值过大的COUNT会导致单次响应延迟建议500-1000网络优于CPU在分布式环境中网络延迟通常比SCAN本身更耗时间类型检查SCAN返回的键可能已改变类型操作前用TYPE检查连接池管理长时间SCAN可能耗尽连接池注意设置合理的超时某次我忘记处理游标持久化导致服务重启后重复处理数十万数据。现在的标准做法是def resilient_scan(): last_cursor redis.get(scan:cursor) or 0 try: for cursor, keys in scan_iter(batch_size500): process_batch(keys) redis.setex(scan:cursor, cursor, 3600) finally: redis.delete(scan:cursor)