Redis 批量清理 Key 实战：SCAN 游标、限速 UNLINK 与可回退工作流

缓存前缀改过几次，Redis 里留下了成片的 cache:legacy:*。这类清理最怕两件事：一次取回太多键把主线程卡住，删错范围后又没有随时停手的机会。更稳妥的做法不是找一条「万能删除命令」，而是把任务拆成取样、游标扫描、限速释放和结果复查四段。

先划清 Redis 清理任务的边界

KEYS cache:legacy:* 在小型测试库里看着省事，放到生产实例上很可能因为全量遍历引发实例抖动。批量清理的目标要定得很具体：只处理已经确认过的业务前缀、每一批处理数量有限、任务可以随时暂停、删完后能查到完整处理结果。

这里别急着直接把模式写死成 *。先从一条完整键名倒推：比如旧版商品详情缓存是 cache:legacy:product:981，匹配模式就限定为 cache:legacy:product:*。如果一个前缀下同时存了会话、计数器和普通业务缓存，先拆成范围更窄的独立任务再跑。

把清理拆成四个可停下的阶段

可控的清理任务从样本确认开始：先只扫一批，打印前20个键，人工确认命名空间完全符合预期之后，再启动完整的游标循环。每轮拿到的键先计数，再按固定节奏提交 UNLINK；如果出现Redis延迟升高、业务告警或者样本异常的情况，停止开关要能让下一轮遍历直接终止。

这四段没有刻意合并。如果把扫描和删除混在一条难以观测的脚本里，出问题时只能整体强制停掉；拆开之后，cursor 卡在什么位置、哪一批返回异常、删除速度是否过高，所有状态都能从日志里明确看出来。

最小可用的 Go 清理器

下面的示例用 go-redis/v9 演示一个单节点清理器。它不把 COUNT 当成精确批大小，只将其作为 Redis 侧的遍历建议值；每批拿到的键都先走限速器校验，再用 UNLINK 提交释放。

package main

import (
    "context"
    "fmt"
    "time"

    "github.com/redis/go-redis/v9"
    "golang.org/x/time/rate"
)

func main() {
    ctx := context.Background()
    rdb := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})
    pattern := "cache:legacy:product:*"
    limiter := rate.NewLimiter(rate.Every(100*time.Millisecond), 1)

    var cursor uint64
    var seen, removed int
    for {
        keys, next, err := rdb.Scan(ctx, cursor, pattern, 200).Result()
        if err != nil {
            panic(err)
        }
        cursor = next
        seen += len(keys)

        if len(keys) > 0 {
            if err := limiter.Wait(ctx); err != nil {
                panic(err)
            }
            n, err := rdb.Unlink(ctx, keys...).Result()
            if err != nil {
                panic(err)
            }
            removed += int(n)
        }
        if cursor == 0 {
            break
        }
    }
    fmt.Printf("seen=%d removed=%d\n", seen, removed)
}

试跑时可以先把 Unlink 那几行替换成打印键名的逻辑，只保留扫描和样本日志。这样能先核对模式是否误扫到测试键、预发布键或者仍在使用的新版本键，确认范围完全没问题之后再启用删除，风险会低很多。

限速与停止开关要写进程序

COUNT 200 不等于每轮一定返回200个键，Redis 会按内部负载状态返回对应数量的结果。真正需要控制的是提交删除的节奏。上面的示例每100毫秒最多提交一批；如果单个键的 value 很大、实例正处于业务高峰或者网络延迟已经出现波动，把间隔拉到300至500毫秒会更稳妥。

生产任务还应该给循环加三个外部信号：一个上下文取消信号、一个最大处理上限、一个每N批写出的进度日志。最大上限不是为了追求精确统计，而是为了让误匹配问题在造成更大影响前自动停下。这时候别直接判定结果正常，尤其当 removed 明显小于 seen 时，有可能是扫描重复、键被其他业务提前清掉，也可能是权限或者网络问题导致的丢数。

为什么更倾向于 UNLINK

针对纯缓存键，UNLINK 会把释放工作交给后台线程处理，减少删除大对象对主线程命令处理的影响。它也不是零代价操作：后台释放同样会消耗CPU，所以连续清理大量大 value 键的时候，仍要同步观察实例的延迟、CPU和内存曲线。

什么时候必须用 DEL

需要同步删除语义，或者下游逻辑必须在当前命令返回时确认键已经不可见，才考虑 DEL。即便这种场景，也要优先控制单批的对象大小和总数，不要把数万个键塞进一次 DEL 调用里。

清理前后各做一次短检查

任务开始前保存匹配模式、样本键、预计运行时段和停止条件；运行中实时记录 cursor、批次数和错误信息；结束后重新扫描同一模式并做抽样检查。下面这份清单比单看一条「删除成功」的日志更可靠。

• 样本键是否都属于预期业务前缀，没有混入生产环境里仍在使用的新版本键。
• Redis 延迟、慢日志和命中率有没有在清理窗口内出现异常波动。
• seen 与 removed 的差异有没有可解释的原因。
• 暂停任务后，是否还能从上次记录的 cursor 重新取样，再决定要不要继续跑后续流程。

如果只是要缩短键的生命周期，优先考虑在写入侧调整TTL，不要反复做大范围的清理操作。批量清理更适合处理错误前缀、一次性历史数据或者已经正式下线的缓存版本。

相关问题

SCAN 会不会漏掉键？

遍历期间键空间持续变化时，SCAN 可能重复返回同一个键，也可能看不到刚写入或者刚删除的键。清理旧的下线前缀时通常可以接受这种弱一致性；如果要求操作范围绝对不能遗漏，应该改成停写窗口或者用业务侧清单驱动删除。

能否在 Redis Cluster 上直接跑这段代码？

可以使用集群客户端，但扫描与统计要按单节点维度理解。不要把单节点的 cursor 和总数解释为整个集群的精确全局进度，先在一个无关紧要的测试前缀上验证完行为再上生产。

UNLINK 后内存为什么没有立刻下降？

内存释放在后台异步完成，内存指标还会受到碎片、持久化和其他正常写入操作的影响。应该结合一段时间内的 used_memory、延迟和 CPU 变化趋势做判断，不要只看某一个瞬时数值下结论。

删除任务中途停掉，已经处理的键怎么办？

已经提交的删除不会自动恢复，因此样本确认和收窄匹配范围是最关键的前置步骤。中途停止后先复查已经处理的范围，再用新的样本决定要不要从头扫描；这类清理任务本身就支持重复运行。

收尾：把一次性清理变成可复查的操作

Redis 批量清理本身技术门槛不高，难的是让它在业务高峰、命名混乱和临时需求突发的场景下仍然可控。用 SCAN 缩小单轮遍历的压力，用 UNLINK 降低对象释放的干扰，用限速、日志和停止条件留出回旋余地。下次遇到历史缓存堆积的场景，先做样本确认，再让程序按节奏慢慢处理，通常比直接敲一条重命令要可靠得多。