Redis作为高性能的内存数据库，在生产环境中往往承载着数以百万计的键。当运维人员需要排查特定前缀的键，或者开发人员需要实现数据清理任务时，遍历键空间成为一项高频操作。然而许多开发者习惯性地使用KEYS命令，这个命令在执行时会阻塞Redis主线程，直到所有匹配的键被扫描完毕。在键数量庞大的场景下，这种阻塞可能长达数秒，直接导致线上服务出现请求超时甚至雪崩。SCAN命令正是为解决这一痛点而生，它通过游标机制将全量遍历拆分为多次小规模请求，每次只扫描一小部分哈希桶，从而将对主线程的影响降到最低。
SCAN命令的底层原理与游标机制
SCAN命令的完整签名为SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]，它返回一个包含两个元素的数组：第一个元素是下一次迭代需要使用的新游标，第二个元素是本次扫描到的键列表。当返回的游标为0时，表示全量遍历结束。理解SCAN的核心在于理解游标的工作机制。Redis内部使用两张哈希表（ht[0]和ht[1]）来实现字典结构，当负载因子达到阈值时触发rehash操作。SCAN的游标实际上是一个哈希桶的索引，它通过特定的位运算算法来计算下一个游标，确保在rehash过程中既能遍历到旧表中的桶，也能遍历到新表中的桶，从而保证不遗漏任何键。
具体来说，SCAN在遍历时会从当前游标指向的哈希桶开始，将该桶中的键收集起来，同时跳过连续的空桶。当遇到rehash时，如果当前游标指向的桶在旧表中已经迁移到新表，SCAN会同时扫描旧表和新表中对应位置的桶。这种设计巧妙地利用了哈希表扩容时桶数量翻倍的特性，通过高位比特位的遍历来覆盖新增的桶空间。需要注意的是，SCAN并不保证不返回重复的键。在rehash进行中，同一个键可能在不同轮次的扫描中被多次返回，这是因为键的物理位置在迁移过程中发生了变化，业务代码必须做好幂等处理。
从源码层面来看，SCAN的核心逻辑位于Redis的dictScan函数中。该函数首先判断当前字典是否正在进行rehash，如果没有rehash，直接从游标指向的桶开始向后扫描；如果正在rehash，则需要同时考虑两张哈希表。游标的计算采用了反转比特位（reverse binary bits）的策略，这种策略保证了在哈希表大小从N扩展到2N时，原来索引为i的桶中的键要么留在原位，要么迁移到索引为i+N的桶中，而反转比特位后的遍历顺序恰好能覆盖这两个位置。
COUNT参数的实际行为与性能影响
许多开发者对COUNT参数存在误解，认为设置COUNT为100就一定会返回100个键。实际上COUNT只是一个提示值，告诉Redis每次扫描时大概应该处理多少个元素。Redis在底层实现中，会从当前游标开始扫描，将遇到的非空哈希桶中的键收集起来。如果某个桶中恰好有大量键（例如是一个大的字典或跳表结构），那么即使COUNT设为10，实际返回的键数量也可能远超10个。反之，如果连续遇到多个空桶，返回的键数量可能少于COUNT值。
这种设计是出于性能考虑的。如果严格限制每次返回的键数量，Redis就需要在收集到指定数量后立即停止扫描并记录当前位置，这会增加额外的状态维护开销。实际开发中，建议根据网络延迟和键的平均大小来调整COUNT。在局域网环境下，COUNT设置为100到500通常能在单次请求延迟和总遍历轮次之间取得较好的平衡。如果键的值比较大，或者网络延迟较高，可以适当降低COUNT以避免单次响应数据量过大导致超时。同时要注意，每次SCAN调用都是O(1)时间复杂度的操作，但总的时间复杂度仍然是O(N)，只是将N分散到了多次请求中。
除了COUNT参数外，SCAN还支持MATCH和TYPE两个可选参数。MATCH参数用于按模式匹配键名，但需要注意的是，过滤是在收集键之后进行的，也就是说SCAN仍然会扫描所有桶中的键，只是在返回前过滤掉不匹配的键。这意味着如果匹配模式过于严格，可能需要多轮扫描才能收集到足够数量的键。TYPE参数则允许按数据类型过滤，这在只需要遍历特定类型键的场景下非常有用，比如只扫描所有Hash类型的键。
生产环境中的避坑指南与代码实现
在生产环境中使用SCAN时，最常见的问题是网络超时和重复键处理。由于SCAN需要多次往返请求，如果单次请求间隔过长，可能触发客户端的超时机制。建议在代码中实现重试逻辑，当遇到网络异常时使用上一次的游标重新发起请求。对于重复键的问题，可以在客户端维护一个已处理键的集合，每次收到SCAN返回的键列表后先进行去重。如果业务场景对准确性要求极高，可以在SCAN遍历完成后再做一次补偿扫描，或者结合TYPE和TTL等命令对结果进行二次过滤。
下面是一个使用Python redis-py库实现的安全遍历示例，包含了重试机制和去重逻辑：
import redis
import time
def safe_scan_keys(r, pattern='*', count=100, max_retries=3):
"""
安全遍历Redis键空间，包含重试和去重逻辑
"""
cursor = 0
seen_keys = set()
while True:
retries = 0
success = False
# 重试机制：网络异常时使用上一次游标重试
while retries < max_retries and not success:
try:
cursor, keys = r.scan(
cursor=cursor,
match=pattern,
count=count
)
success = True
except redis.ConnectionError as e:
retries += 1
if retries >= max_retries:
raise e
time.sleep(0.1 * retries)
# 去重处理：跳过已处理的键
for key in keys:
if key not in seen_keys:
seen_keys.add(key)
yield key
# 游标为0表示遍历结束
if cursor == 0:
break
# 使用示例
r = redis.Redis(host='127.0.0.1', port=6379, decode_responses=True)
for key in safe_scan_keys(r, pattern='user:*', count=200):
print(f'处理键: {key}')
除了基本的遍历逻辑，还需要注意SCAN在集群模式下的行为差异。在Redis Cluster中，每个节点只维护一部分槽位的数据，因此需要在所有主节点上分别执行SCAN命令并合并结果。大多数客户端库都提供了集群感知的SCAN封装，但底层仍然是逐节点遍历。如果业务允许，建议在遍历前先通过CLUSTER NODES命令获取所有主节点地址，然后并行执行SCAN以缩短总耗时。最后要强调的是，SCAN虽然不会阻塞主线程，但大量SCAN请求仍然会消耗CPU资源，建议在业务低峰期执行大规模遍历操作，或者通过读写分离将遍历请求发送到从节点上执行。
Redis SCAN游标遍历键空间修改时间：2026-08-25 23:51:08