Redis SCAN 为什么像漏键：游标推进、COUNT 误读与去重验收

线上清理一批旧缓存时，脚本打印“本轮扫到 100 个”，但最后留下的键数和预估对不上。先别急着把 Redis 当成漏数据：SCAN 返回的是渐进式游标，COUNT 只是工作量提示，配合 MATCH 后还可能出现空批次；如果脚本把游标当页码，或者遇到重复键就直接计数，结果自然会失真。

SCAN 看起来像漏键，绝大多数时候是游标推进逻辑写反、COUNT 参数被误当成分页大小、没有做结果去重这三类开发侧的误用，不是 Redis 服务端丢数据。

游标不是页码：先把一次遍历跑完整

最基础的 Redis SCAN 调用逻辑只有两步：传入当前游标值，再接住 Redis 返回的新游标继续传。第一次传 0，后续必须原样使用上一次返回的游标值，直到新游标再次变成 0。

SCAN 0 MATCH cache:user:* COUNT 100
SCAN 184 MATCH cache:user:* COUNT 100
SCAN 0 MATCH cache:user:* COUNT 100

这里的 184 只是示意返回值，不是第 184 页。每次返回的键数量可以少于 100，甚至在过滤条件较窄时直接返回空数组；只要游标还没有回到 0，就不能中途停止。

调用方真正要决定的三个参数

COUNT 只控制节奏，不是分页大小

COUNT 是服务端每轮扫描的工作量提示值。调大它，通常能减少客户端和服务端的往返次数，但也会增加单轮命令的执行耗时；调小它，单次返回响应更轻量，却不代表一定能降低服务端整体负载。清理任务应把它当作可调的节流参数，而不是业务分页场景下的固定返回条数。

MATCH 先过滤，数量可能更稀

MATCH cache:user:* 只让最终返回结果符合指定模式，并不会把整个游标空间重新整理成“匹配键专属分页”。所以连续几轮拿到空数组并不等于遍历完成，结束判断仍然只能看返回的游标值。

TYPE 是额外边界，不要替代业务校验

如果只想处理某种数据类型的键，可以在支持该特性的版本里用 TYPE 过滤；但删除前仍建议用业务前缀、键类型和 TTL 再确认一次。一个写错的匹配前缀，往往比一次慢扫描带来的风险大得多。

清理脚本怎么验收：遍历、去重、再确认

把“扫到多少”拆成三个独立统计值：观察总次数、唯一键总数、实际删除成功数。观察次数允许大于唯一键数；实际删除数还可能小于唯一键数，因为键在两次读取之间已经被业务逻辑删掉，或者它已经不再符合预设的 TTL 条件。

cursor = 0
seen = set()
deleted = 0
while True:
    cursor, keys = scan(cursor, match="cache:user:*", count=100)
    for key in keys:
        if key in seen:
            continue
        seen.add(key)
        if should_remove(key):
            deleted += delete(key)
    if cursor == 0:
        break
print("observed", len(seen), "deleted", deleted)

示例里的函数名是伪代码，关键不在具体客户端语法，而在三条验收规则：游标原样回传、键集合全局去重、删除动作可重复执行。生产脚本还应限制单轮最大删除量，记录开始游标、结束时间、匹配模式和异常数量。

四个容易把结果看错的场景

线上不建议用 KEYS * 代替渐进式遍历。它一次性处理整个键空间，短脚本看起来更简单，但在键总量很大或请求繁忙时会把延迟风险全部集中到单个命令上。

相关问题

SCAN 会不会保证每个键只返回一次？

在键空间完全稳定没有变动的前提下，它对完整遍历所有键有明确保证，但应用仍应按“可能出现重复观察”的逻辑设计，尤其是遍历期间发生键增删或集群扩缩容的场景。

COUNT 越大是不是越快？

不一定。它可能减少往返次数，也可能拉长单轮响应耗时并拉高瞬时负载，应结合业务实例的延迟、CPU 占用情况在低峰期压测后调整。

什么时候可以直接结束扫描？

只有 Redis 返回的新游标为 0 才能结束；返回数量少、拿到空数组或未达到预估数量都不是合法的结束信号。

清理任务为什么还要二次复查？

因为键空间可能在扫描期间持续变化。二次复查能发现新增、重复或删除失败的键，把“脚本跑完”变成可以人工核对的确定结果。

把扫描结果变成可核对的结论

Redis SCAN 更像一条可以随时暂停的遍历通道，而不是固定页码的分页接口。把游标生命周期、过滤条件、去重策略和复查窗口写进脚本日志，遇到“漏键”疑问时就能快速区分是尚未扫完、过滤过窄、键已被业务变更，还是删除动作本身没有执行成功。