Redis SCAN 游标为什么不能当作总进度百分比

Redis SCAN 返回的第一个值是一个用于续读的 cursor，它不是“已经扫描了多少键”的计数器，也不是可以直接除以某个总数的百分比刻度。最可靠的完成判断是：从 cursor 为 0 开始反复调用，直到 Redis 返回的下一个 cursor 再次为 0。

如果页面上需要展示进度，应该把 Redis 的技术状态和业务指标拆开：用“已处理批次数”“已处理键数”“最近一次 cursor”或“已完成/未完成”表达真实状态。只有在业务侧另有一个稳定、可信的总量快照时，才可以计算百分比；不能把 SCAN 的数字本身当作分子或分母。

游标只是续读位置，不是百分比

一次 SCAN 调用可以写成 SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]。调用方把上一次返回的 cursor 原样传给下一次调用，直到返回值为 0。这个 cursor 的职责是让 Redis 和客户端知道“从哪一个迭代状态继续”，而不是告诉客户端 keyspace 中有多少键。

因此，下面这些判断都不成立：

• cursor / 最大 cursor 等于扫描百分比；
• cursor 越大，说明已经处理的键越多；
• cursor 变小了，说明扫描发生了回退；
• 把 cursor 转成整数后，按它的大小绘制线性进度条。

cursor 是 Redis 迭代器的内部位置表示，数值大小没有业务上的单调含义。它可能在两次调用之间变大，也可能变小；即使 cursor 看起来接近某个上限，也不表示遍历接近终点。唯一具有明确完成语义的特殊值是返回 cursor 为 0。

用返回 cursor 为 0 判断一轮结束

一次从 SCAN 0 开始、不断使用上一次返回 cursor、直到再次得到 0 的过程，才叫一次完整遍历。中途返回空数组并不代表结束，因为过滤条件可能让这一批没有匹配项，或者这一轮调用只推进了迭代器位置。

# 中文注释：从 0 开始，把每次返回的 cursor 传给下一次调用
cursor=0
while :; do
  # 中文注释：COUNT 只是工作量提示，不能据此推导总量或百分比
  reply=$(redis-cli --raw SCAN "$cursor" MATCH 'cache:*' COUNT 100)

  # 中文注释：实际脚本应按客户端协议解析 cursor 和键列表
  next_cursor=$(printf '%s\n' "$reply" | sed -n '1p')
  # 中文注释：这里的结束条件只看 Redis 返回的下一个 cursor
  [ "$next_cursor" = "0" ] && break
  cursor="$next_cursor"
done

上面的示例省略了不同客户端对多行返回的解析细节，但保留了最重要的控制关系：开始值是 0，下一次输入来自上一次输出，结束条件是输出 cursor 回到 0。业务代码中不要自行构造“下一个 cursor”，也不要在看到空结果时提前退出。

如果任务需要断点续跑，可以持久化最近一次返回的 cursor，但要把它看成一个短期的迭代状态，而不是可跨任意数据变化使用的进度百分比。恢复时继续使用该 cursor，仍然要以最终回到 0 作为这一轮结束信号。

COUNT 影响每次工作量，不代表返回条数

COUNT 是给 Redis 的工作量提示。它通常会影响一次调用大致推进多少工作，但 Redis 不承诺每次返回固定数量的键，也不承诺一定至少返回一个键。小型内部编码结构可能一次返回全部元素；使用 MATCH 时，过滤发生在扫描取得候选之后，因此很多调用可能返回空的匹配集合。

这也是把 cursor 和返回数量相除会出错的原因：你甚至没有一个稳定的“每次处理多少键”。COUNT 100 不等于本次返回 100 个键，更不等于总共有多少个 100 键的批次。

# 中文注释：COUNT 可以按负载调整，但不能当作固定页大小
redis-cli SCAN 0 MATCH 'order:*' COUNT 100

# 中文注释：下一次必须使用上一次真实返回的 cursor
redis-cli SCAN  MATCH 'order:*' COUNT 200

# 中文注释：即使本次没有匹配键，也要继续，直到返回 cursor 为 0

如果任务更关心 Redis 的负载，可以记录每次调用耗时、返回条数和处理耗时；如果任务更关心业务处理，可以记录成功处理数量和失败数量。它们都是观察指标，但都不能反过来改变 SCAN cursor 的语义。

把技术状态和业务进度分开

一个可维护的遍历任务至少有三层状态：

例如，后台任务可以显示“已处理 12,430 个匹配键，已完成 37 个批次，当前仍在扫描”，而不是显示“SCAN 进度 63%”。前者说明了已经发生的工作，后者暗示存在一个 Redis 并未提供的稳定总量。

如果产品必须显示百分比，先在业务侧定义分母。例如先生成一份稳定的待处理 ID 清单，再让 SCAN 只负责找出 Redis 中的键；或者把任务范围固定为某个时间点之前的键，并由业务系统维护这份快照。百分比来自稳定范围与处理计数的关系，而不是来自 cursor。

重复返回和变化中的 keyspace 要提前处理

SCAN 为了保持低状态、渐进式遍历，允许同一个元素在一轮中被返回多次。元素在完整遍历期间被新增、删除或持续变化时，是否被返回还要看它在迭代期间的存在状态。也就是说，不能把“收到一次键”直接等同于“这个业务对象只会被处理一次”。

因此，处理器最好满足幂等条件。常见做法是用业务唯一键记录处理结果，或者让重复执行只产生同一个最终状态。若必须统计“独立键数”，还要在业务侧去重；返回批次数和返回元素数只能表示调用工作量，不能直接代表唯一对象数量。

# 中文注释：示例只表达控制逻辑，实际 Redis 客户端的返回结构可能不同
cursor = 0
seen_batches = 0
processed = 0

while True:
    # 中文注释：COUNT 是提示，不假设本次一定返回固定条数
    cursor, keys = redis.scan(cursor=cursor, match="cache:*", count=100)
    seen_batches += 1

    for key in keys:
        # 中文注释：处理动作要能重复执行，避免 SCAN 重复返回造成副作用
        if process_idempotently(key):
            processed += 1

    # 中文注释：只把 cursor=0 作为一轮遍历完成，不按 cursor 大小判断
    if cursor == 0:
        break

print(f"批次={seen_batches}, 已处理={processed}, 完成=True")

如果 keyspace 一直增长，SCAN 不一定能在有限时间内完成一轮完整遍历。生产任务通常要额外设置最大运行时长、固定扫描范围、任务代次或停止边界；这样做是业务调度策略，不是把 cursor 强行解释成百分比。

最小判断清单

1. 是否从 cursor 0 开始，并把 Redis 返回值原样传给下一次调用？
2. 是否只有在返回 cursor 为 0 时才标记一轮完成？
3. 是否接受单次返回 0 个、少量或多于 COUNT 的元素？
4. 是否按幂等方式处理可能重复返回的键？
5. 是否把批次数、处理数和业务完成状态与 cursor 分开存储？
6. 如果 keyspace 持续变化，是否有固定范围、超时或任务代次边界？

记住一句话：Redis SCAN 的 cursor 解决的是“下一次从哪里继续”，不是“总共完成了多少”。游标回到 0 才说明这一轮 full iteration 结束；真正的业务进度，需要由任务自己的计数和范围定义来表达。

相关问题

SCAN 返回空数组时是不是已经遍历完了？

不是。只要返回的 cursor 还不是 0，就应继续；MATCH 过滤或本次调用推进量都可能造成空批次。

把 COUNT 调大能不能让百分比更准确？

不能。COUNT 只影响 Redis 每次调用大致做多少工作，不能提供总键数，也不会把 cursor 变成线性进度。

SCAN 能保证每个键只返回一次吗？

不能。Redis 文档明确允许重复返回，处理逻辑应能安全地重复执行；动态变化的键还可能被返回或不被返回。