当前位置：首页 > 文章列表 > 数据库 > Redis > Redis HSCAN 如何渐进清理大 Hash：COUNT 提示、游标归零与删除风险

Redis HSCAN 如何渐进清理大 Hash：COUNT 提示、游标归零与删除风险

来源：17golang原创 2026-08-30 04:24:29 0浏览收藏

线上缓存里有一个持续变大的 Hash，直接执行 HGETALL 会把整份字段和值一次性搬到客户端，清理任务很容易把 Redis 延迟和应用内存一起推高。更稳妥的做法是让 HSCAN 按游标渐进遍历，每次只拿一小批候选字段，再用 HDEL 删除已经确认过期的字段。

HSCAN 的 COUNT 只是本轮返回数量的提示，不是严格分页大小；真正的结束标志是 Redis 返回的游标变回 0。清理时应按批收集字段、核对业务条件后调用 HDEL，不要把一次扫描结果当成全量快照。

要点速览

游标从 0 开始，返回 0 才表示一轮遍历结束。
COUNT 100 是工作量提示，实际返回数量可能不同。
MATCH cache:* 先缩小候选字段，但不会改变扫描的渐进特性。
HDEL 返回实际删除字段数，Hash 为空后 Redis 会删除这个键。

为什么大 Hash 不该用 HGETALL 清理

假设订单摘要被放在 order:summary 这个 Hash 中，字段名是订单号，值里保存状态和更新时间。HGETALL order:summary 会把所有字段和值都返回；Hash 越大，单次响应越重，客户端还要额外分配一份结果空间。

HSCAN order:summary 0 COUNT 100 返回两部分：新的游标和本轮字段列表。它适合把一次长任务拆成多次短调用。这里的“渐进”不等于严格快照，扫描期间如果业务继续写入，清理器必须接受集合会发生变化。

HSCAN 的游标、MATCH 与 COUNT 怎么配合

下面这段 Redis CLI 片段只做遍历，不直接删除字段。先观察返回格式，再决定清理条件，能避免把误命中的字段直接删掉。

HSCAN order:summary 0 MATCH order:* COUNT 100
HSCAN order:summary 18432 MATCH order:* COUNT 100
HSCAN order:summary 0 MATCH order:* COUNT 100

第二个位置是游标，下一次调用要原样带上 Redis 返回的值。最后一次返回游标 0，也就是图中的“游标0”，才说明本轮从头到尾走完。即使 COUNT 100 写得很明确，Redis 也可能返回少于或多于这个数量，因此程序不能用“返回数量小于100”判断结束。

HSCAN 从 order:summary 读取游标、筛选 order:* 字段并把候选交给 HDEL 的数据路径

用 MATCH 缩小候选，不要把它当成索引

MATCH order:* 是对扫描结果做模式过滤，不会把 Hash 变成按字段名定位的索引。字段命名稳定时它很有用，但清理任务仍然要完整走完游标；如果只扫描一次，留下的字段可能正好在后续游标范围里。

按批确认过期字段，再调用 HDEL

真正的删除边界在业务判断，而不是 HSCAN 本身。下面示例约定 Hash 值保存 JSON，清理器先解析 expires_at，只把已经过期的字段放入 expired_fields，然后分批调用 HDEL。

cursor = "0"
while True:
    cursor, pairs = redis.hscan(
        "order:summary", cursor=cursor, match="order:*", count=100
    )
    expired_fields = []
    for field, value in pairs.items():
        if is_expired(value):
            expired_fields.append(field)
    if expired_fields:
        redis.hdel("order:summary", *expired_fields)
    if cursor == "0":
        break

这里有两个容易漏掉的点：第一，cursor 必须来自本次响应，不能自行递增；第二，HDEL 的返回值是实际删除的字段数量，不存在的字段不会计数。清理器可以记录“发现数量”和“删除数量”两个指标，二者不相等时再检查并发写入或重复扫描。