241 lines
7.0 KiB
Markdown
241 lines
7.0 KiB
Markdown
|
---
|
|||
|
|
tags: [redis, scan, keys, traversal, performance]
|
|||
|
|
create time: 2026-06-01 10:30
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# Redis SCAN 遍历命令
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
在生产环境中，你经常需要找到所有符合某个模式的 Key——比如找出所有 `rate:limit:*` 做清理或统计。直觉上会用 `KEYS *pattern*`，但**大库中使用 KEYS 会导致服务雪崩**。`SCAN` 是唯一的正确选择。
|
|||
|
|
|
|||
|
|
这对应你的薄弱点 Q15：为什么用 SCAN 替代 KEYS。
|
|||
|
|
|
|||
|
|
## 一、KEYS vs SCAN：核心对比
|
|||
|
|
|
|||
|
|
### KEYS：简单但危险的阻塞操作
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 一行搞定，但会阻塞整个 Redis
|
|||
|
|
KEYS rate:limit:*
|
|||
|
|
→ user1
|
|||
|
|
→ user2
|
|||
|
|
→ user3
|
|||
|
|
...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**问题：** KEYS 是一次性全量扫描——它会在单个操作中遍历所有 Key，然后一次性全部返回。在这期间：
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
flowchart LR
|
|||
|
|
A["KEYS *pattern* 开始"] --> B["阻塞 Redis 主线程<br/>遍历所有数据库"]
|
|||
|
|
B --> C["如果库中有 1000 万个 Key？<br/>可能耗时数秒到数十秒"]
|
|||
|
|
C --> D["所有其他客户端被阻塞<br/>超时/连接堆积"]
|
|||
|
|
D --> E["生产事故：服务不可用"]
|
|||
|
|
|
|||
|
|
style A fill:#fff3e0
|
|||
|
|
style D fill:#ffebee
|
|||
|
|
style E fill:#b71c1c,color:#fff
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> [!warning]- KEYS 的三个致命问题
|
|||
|
|
>
|
|||
|
|
> 1. **阻塞主线程**：Redis 单线程，KEYS 执行期间所有其他请求都无法处理
|
|||
|
|
> 2. **内存峰值**：结果一次性返回，匹配大量 Key 时可能 OOM
|
|||
|
|
> 3. **无法增量迭代**：一次返回所有结果，中途无法停止
|
|||
|
|
|
|||
|
|
### SCAN：分步游标，永不阻塞
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 第一次调用，cursor = 0
|
|||
|
|
SCAN 0 MATCH rate:limit:* COUNT 100
|
|||
|
|
→ 1) "12345" ← 下一个 cursor
|
|||
|
|
→ 2) 1) "user1"
|
|||
|
|
2) "user2"
|
|||
|
|
...
|
|||
|
|
|
|||
|
|
# 下次用返回的 cursor 继续
|
|||
|
|
SCAN 12345 MATCH rate:limit:* COUNT 100
|
|||
|
|
→ 1) "67890"
|
|||
|
|
→ 2) 1) "user3"
|
|||
|
|
...
|
|||
|
|
|
|||
|
|
# 当 cursor 返回 "0" 时，遍历完成
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**优势：**
|
|||
|
|
- 每次只返回少量结果（由 COUNT 控制）
|
|||
|
|
- 不会阻塞 Redis 主线程
|
|||
|
|
- 可以安全地在生产环境使用
|
|||
|
|
|
|||
|
|
## 二、SCAN 参数详解
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
| 参数 | 含义 | 示例 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `cursor` | 游标，0 表示开始，返回 0 表示结束 | `0`, `12345` |
|
|||
|
|
| `MATCH` | 模式过滤（支持 `* ? []` 通配符） | `rate:limit:*` |
|
|||
|
|
| `COUNT` | 每次迭代的元素数量（默认 10） | `COUNT 100` |
|
|||
|
|
| `TYPE` | 按数据类型过滤（Redis 4.0+） | `TYPE string` |
|
|||
|
|
|
|||
|
|
### COUNT 参数的误区
|
|||
|
|
|
|||
|
|
`COUNT` **不是精确返回数量**，而是告诉 Redis "这一轮大概应该返回多少条"。实际返回数量可能多也可能少。
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
COUNT 越大 → 每次返回越多，总迭代次数越少，但单次延迟略高
|
|||
|
|
COUNT 越小 → 每次返回越少，总迭代次数越多，但单次延迟极低
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**建议值：** 根据数据量和延迟要求调整，通常 100 ~ 500 是 sweet spot。
|
|||
|
|
|
|||
|
|
## 三、Go-Redis 中的使用
|
|||
|
|
|
|||
|
|
### 3.1 基础用法
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
func scanAllKeys(ctx context.Context, rdb *redis.Client, pattern string) ([]string, error) {
|
|||
|
|
var allKeys []string
|
|||
|
|
|
|||
|
|
// Cursor 为 0 时会自动从第一轮开始
|
|||
|
|
cursor := uint64(0)
|
|||
|
|
for {
|
|||
|
|
// KeysByPattern 内部处理了游标迭代
|
|||
|
|
keys, nextCursor, err := rdb.Scan(ctx, cursor, pattern, 100).Result()
|
|||
|
|
if err != nil {
|
|||
|
|
return nil, err
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
allKeys = append(allKeys, keys...)
|
|||
|
|
|
|||
|
|
if nextCursor == 0 {
|
|||
|
|
break // 遍历完成
|
|||
|
|
}
|
|||
|
|
cursor = nextCursor
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
return allKeys, nil
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.2 ⚠️ 快捷方法（不推荐用于大数据量）
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
// rdb.Keys() 底层调用的是 KEYS 命令——会阻塞 Redis！
|
|||
|
|
keys, err := rdb.Keys(ctx, "rate:limit:*").Result()
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> [!note]- Go-Redis 的坑
|
|||
|
|
>
|
|||
|
|
> `rdb.Keys()` 虽然调用方便，但底层仍然是阻塞式的 `KEYS` 命令。**在大数据量场景下务必使用上面的手动 SCAN 循环**（见 3.1 节）。
|
|||
|
|
|
|||
|
|
### 3.3 带 TYPE 过滤的高效扫描
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
// 只找 String 类型的限流 Key
|
|||
|
|
cursor := uint64(0)
|
|||
|
|
for {
|
|||
|
|
iter := rdb.Scan(ctx, cursor, "rate:limit:*", 200)
|
|||
|
|
keys, _ := iter.Result()
|
|||
|
|
|
|||
|
|
for _, key := range keys {
|
|||
|
|
t, _ := rdb.Type(ctx, key).Result()
|
|||
|
|
if t.Err() != nil || t.Val() != "string" {
|
|||
|
|
continue
|
|||
|
|
}
|
|||
|
|
// 处理这个限流 Key...
|
|||
|
|
handleKey(key)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if iter.Cursor() == 0 {
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 四、SCAN 的不一致性保证
|
|||
|
|
|
|||
|
|
这是 SCAN 最容易让人困惑的地方——**它不保证返回的结果是某一时刻的快照**。
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
flowchart TD
|
|||
|
|
A["SCAN 开始遍历"] --> B["过程中有新 Key 插入"]
|
|||
|
|
B --> C{"新 Key 会被返回吗?"}
|
|||
|
|
C -- "不一定" --> D["可能被下一轮 SCAN 返回"]
|
|||
|
|
C -- "也可能错过" --> E["本轮不会看到"]
|
|||
|
|
|
|||
|
|
A --> F["过程中有 Key 被删除"]
|
|||
|
|
F --> G{"已访问过的 Key 被删?"}
|
|||
|
|
G -- "不会重复返回" --> H["正常，因为游标已越过"]
|
|||
|
|
G -- "未访问到的 Key 被删?" --> I["自然跳过，不影响"]
|
|||
|
|
|
|||
|
|
style C fill:#fff3e0
|
|||
|
|
style D fill:#e3f2fd
|
|||
|
|
style E fill:#fff9c4
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**三个一致性保证：**
|
|||
|
|
|
|||
|
|
| 保证 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| ✅ 不会遗漏 | 如果一个 Key 在整个 SCAN 过程中始终存在且没被删除，它至少被返回一次 |
|
|||
|
|
| ⚠️ 可能重复 | 同一个 Key 可能在多次迭代中返回多次（去重即可） |
|
|||
|
|
| ⚠️ 可能遗漏 | 如果在 SCAN 开始前就存在的 Key 中途被删除了，它可能被跳过 |
|
|||
|
|
|
|||
|
|
> [!tip]- 实际影响
|
|||
|
|
>
|
|||
|
|
> 对限流场景来说，SCAN 的一致性模型完全够用——你要做的通常是清理即将过期的 Key 或者统计当前有多少活跃 Key，不需要精确到某一毫秒的快照。只需要在代码中对返回的 Key 集合做 `set` 去重即可。
|
|||
|
|
|
|||
|
|
## 五、Lua 脚本中使用 SCAN
|
|||
|
|
|
|||
|
|
Redis Lua 中也支持 `redis.call('SCAN', ...)`，但有重要限制：
|
|||
|
|
|
|||
|
|
```lua
|
|||
|
|
-- Lua 中可以使用 SCAN
|
|||
|
|
local cursor = 0
|
|||
|
|
repeat
|
|||
|
|
local result = redis.call('SCAN', cursor, 'MATCH', KEYS[1], 'COUNT', 100)
|
|||
|
|
cursor = tonumber(result[1])
|
|||
|
|
local keys = result[2]
|
|||
|
|
-- 处理 keys...
|
|||
|
|
until cursor == 0
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> [!warning]- Lua + SCAN 的性能陷阱
|
|||
|
|
>
|
|||
|
|
> Lua 脚本最长只能运行 5 秒。如果你在 Lua 里用 SCAN 遍历一个包含百万级 Key 的数据库，很可能超时。解决思路：
|
|||
|
|
> - 减少 `COUNT` 参数
|
|||
|
|
> - 把 SCAN 放在 Lua 外部，用 Go 循环控制
|
|||
|
|
> - 使用 `KEYS` 替代仅在开发/小库环境中
|
|||
|
|
|
|||
|
|
## 六、排查场景应用
|
|||
|
|
|
|||
|
|
### 查找僵尸 Key
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
// 找出所有 rate:limit:* 开头的 Key 并检查 TTL
|
|||
|
|
cursor := uint64(0)
|
|||
|
|
for {
|
|||
|
|
keys, next, _ := rdb.Scan(ctx, cursor, "rate:limit:*", 200).Result()
|
|||
|
|
for _, key := range keys {
|
|||
|
|
ttl, _ := rdb.TTL(ctx, key).Result()
|
|||
|
|
if ttl < 0 {
|
|||
|
|
log.Printf("zombie key found: %s (TTL=%d)", key, ttl)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
if next == 0 {
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
cursor = next
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 关联笔记
|
|||
|
|
|
|||
|
|
- [[分布式限流]] — 限流架构中 SCAN 的实际应用场景
|
|||
|
|
- [[内存持续增长排查]] — SCAN 是排查内存问题的必备工具
|
|||
|
|
- [[僵尸Key防护]] — 利用 SCAN 发现和清理僵尸 Key
|