Redis SCAN 命令使用指南（华为云Redis版）

一、命令含义

SCAN 是 Redis 提供的基于游标的增量式键遍历命令 ，用于逐步迭代当前数据库中的所有键，是 KEYS 命令的生产环境友好替代方案。

家族命令

SCAN 有三个相关命令，用于不同数据类型的遍历：

• SCAN：遍历数据库中的所有键

• SSCAN：遍历 Set 类型的元素

• HSCAN：遍历 Hash 类型的字段和值

• ZSCAN：遍历 Sorted Set 类型的元素和分数

核心优势

✅ 非阻塞 ：每次调用只返回少量元素，不会像 KEYS * 那样在大库下导致Redis阻塞数秒✅ 游标式迭代 ：支持断点续传，迭代过程中服务端仅保存游标状态，内存开销极低✅ 灵活过滤：支持模式匹配、按类型过滤、自定义返回数量等参数

---

二、使用场景

1. 动态Key获取

适用情况：当业务中的Key是动态生成的，无法预先知道具体的Key名称，需要批量获取或扫描符合条件的Key
示例 ：用户会话Key（session:{user_id}:{random}）、临时缓存Key（temp:{business}:{timestamp}）等

2. 批量数据处理

• 批量删除符合某类模式的过期Key

• 批量统计某类业务Key的数量

• 批量迁移指定类型的数据

3. 生产环境键空间巡检

• 检查是否存在异常大Key

• 统计各业务Key的分布情况

• 清理无用的历史Key

---

三、华为云Redis Web CLI 实操指南

基础语法

SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]

参数说明

参数	说明	示例
cursor	游标值，首次调用填0，后续使用上一次返回的游标值	0
MATCH pattern	可选，只返回匹配指定模式的键	MATCH user:*
COUNT count	可选，提示服务端本次返回的元素数量（默认10，仅为参考值）	COUNT 100
TYPE type	可选，只返回指定类型的键（Redis 6.0+支持）	TYPE string

完整使用步骤

步骤1：首次迭代（游标填0）

> SCAN 0
1) "17"  # 下一次迭代的游标值
2)  1) "user:1001"
    2) "product:2001"
    3) "order:3001"
    4) "session:abc123"
    5) "temp:20260313:xxx"
    # ... 省略其他返回的键

步骤2：后续迭代（使用上一步返回的游标）

> SCAN 17
1) "0"  # 返回游标0表示迭代完成
2)  1) "user:1002"
    2) "product:2002"
    3) "order:3002"
    # ... 省略其他返回的键

✅ 当返回的游标值为0时，表示全量迭代完成

常用场景示例

🔍 场景1：扫描所有user:开头的键

SCAN 0 MATCH user:* COUNT 200

提示：华为云Redis建议COUNT值不要超过1000，避免单次返回过多数据影响性能

🔍 场景2：只扫描String类型的键

SCAN 0 TYPE string

🔍 场景3：扫描所有temp:开头的临时键（用于清理）

SCAN 0 MATCH temp:* COUNT 500

---

四、华为云Redis使用注意事项

1. 性能相关

• ⚠️ 禁止在业务高峰时段进行全库扫描，建议在低峰期操作

• ⚠️ COUNT值建议控制在100-1000之间，单次请求不要返回过多数据

• ⚠️ 大实例（>100万Key）扫描建议增加间隔，避免占用过多CPU

2. 结果准确性

• ⚠️ SCAN不保证单次返回的数量严格等于COUNT，仅作为服务端的参考提示

• ⚠️ 迭代过程中如果有Key新增或删除，可能会出现重复返回或遗漏的情况：

  • 迭代开始就存在且迭代结束仍存在的Key，一定会被返回

  • 迭代过程中删除的Key，可能不会被返回

  • 迭代过程中新增的Key，可能会被返回

• ⚠️ 业务需要自行处理重复Key的情况（可以用Set存储结果去重）

3. 集群版特殊说明

• 华为云Redis集群版使用SCAN时，需要遍历所有分片，建议直接使用控制台的【键分析】功能进行全库扫描，效率更高

• 如果在客户端使用SCAN遍历集群，需要自行处理哈希槽路由逻辑

4. 与KEYS命令的对比

对比项	SCAN	KEYS *
性能	非阻塞，O(1)每次调用，全量O(N)	阻塞，大库下可能阻塞数秒
生产环境可用性	✅ 推荐使用	❌ 禁止在生产环境使用
结果准确性	可能重复/遗漏	完全准确（当前时间点快照）
内存开销	极低（仅保存游标）	高（返回所有Key）

---