# Redis Mastery

> Redis 7.0 生产级高并发缓存架构、分布式锁与数据安全规范技能。 基于阿里云 Redis 最佳实践、美团高并发缓存一致性与 Salvatore 官方规范。 涵盖规范 Key 命名与强制 TTL 约束、BigKey/HotKey 治理红线与高危禁用命令清单 (禁 KEYS/FLUSHALL)、 缓存三大灾难终结方案 (穿透/击穿/雪崩)、双写一致性标准 (Cache Aside / 延迟双删) 及原子 Lua 分布式锁铁律。

- Skill: `garfield247/redis-mastery` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add garfield247/redis-mastery`
- Raw SKILL.md: https://api.skillmd.com/api/skills/garfield247/redis-mastery/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Garfield247 (https://skillmd.com/u/garfield247)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/garfield247/redis-mastery

---


# Redis 生产级高并发缓存与数据安全规范技能 (Redis Mastery Skill)

## 概述 (Overview)

本技能定义了基于 **Redis 7.0 / 6.x** 进行生产级高并发缓存设计、分布式锁实现、BigKey 治理与双写一致性维护的权威工程标准。
严格对齐《阿里云 Redis 开发规范与最佳实践》及美团高并发缓存生产实践，深刻践行 **“命名层级规范，强控生命周期；杜绝阻塞命令，切碎大键热键；缓存三灾防患，双写一致闭环；原子脚本加锁，守护单线程池”** 的架构哲学。

---

# 1. Key 命名与生命周期管理规范 (Key Standards & TTL)

Redis 内存空间极其昂贵，且单 Reactor 线程对大 Key 或无效冷数据极度敏感。必须从源头规范 Key：

### 1.1 命名空间与多环境隔离规范 (Environment-Aware Key Namespace)

为了兼容**多套环境共用同一 Redis 实例**（如本地联调与测试共用、灰度演练与正式共用）的隔离需求，Redis Key 的命名空间采用分层分段规范：

#### 标准命名格式
```text
{project}:[{env}:]{module}:{object}:{identifier}
```

#### 常见环境标签 (`env`) 枚举与场景
- **`local`**：开发者本地独立调试，共用局域网 Redis 时防止污染共享数据；
- **`dev`**：开发联调集成环境；
- **`test`**：测试环境 / QA 自动化流水线测试；
- **`stage` / `long`**：预发布长期演练环境、灰度发布节点（Canary）；
- **`prod`**：正式生产环境（物理独立集群时 `env` 可选省略）。

#### 标杆范例
- 普通业务缓存：`myproject:prod:order:detail:100821`
- 鉴权凭证缓存：`myproject:prod:user:token:890123`
- 多租户业务缓存：`myproject:prod:account:load:{company_id}:{account_id}`
- 长连接路由映射：`myproject:prod:route:user:{company_id}:{user_id}`

#### 关键约束
1. **控制 Key 长度**：尽量保持在 40~60 字节内，严禁在 Key 中堆砌大段长字符串；
2. **禁止特殊字符**：严禁在 Key 中包含空格、换行符、引号或不可见字符；
3. **工程落地最佳实践（配置化统一注入）**：
   - 严禁在业务代码中到处硬编码环境分支（如 `if env == "dev"`）；
   - 统一在配置中定义 `KeyPrefix: "{project}:{env}:"`，通过统一的构建函数 `BuildKey(module, object, id)` 透明无感组装。

### 1.2 强制 TTL 生命周期铁律 (No Infinite Cold Keys)
- **冷数据严禁无期常驻**：
  - 除系统级不可变的全局全局配置与只读字典外，**所有写入 Redis 的业务数据强制必须设置显式过期时间（TTL）**；
  - 严禁写入永久不带 TTL 的业务临时数据（如用户登录态、验证码、计算中间结果、临时锁），防止内存持续暴涨触发 OOM Eviction（逐出策略击垮业务）。

---

# 2. BigKey / HotKey 治理红线与高危命令禁令 (BigKey & Dangerous Commands)

Redis 是**单线程处理命令请求**，任何耗时超过数毫秒的阻塞性操作都会瞬间导致全实例所有后续请求排队超时，直接造成依赖该 Redis 的整个微服务集群雪崩！

```mermaid
graph TD
    A["单 Reactor 线程处理模型"] --> B["耗时大命令: KEYS * / HGETALL (10万字段)"]
    B --> C["阻塞主线程 50ms~500ms"]
    C --> D["连接池排队占满 -> 全局微服务请求超时熔断"]
```

### 2.1 BigKey 阈值红线与拆分策略
- **生产级 BigKey 判决红线**：
  - **String 类型**：单个 Value 超过 **10 KB** 必须治理；超过 50 KB 属于严重事故隐患；
  - **集合类型 (Hash / List / Set / ZSet)**：元素总数量超过 **5000 个**，或总体积超过 **10 MB**，严禁作为单一 Key 存储！
- **BigKey 危害**：内存分配不均、主从复制阻塞、网络带宽打满、集群数据倾斜、删除时阻塞（未开启 Lazy Free 时触发同步释放）。
- **拆分重构方案**：
  1. **Hash 分片存储 (Sharding Hash)**：
     - 将原本拥有数十万字段的大 Hash `user_profile`，按 `user_id % 100` 拆分成 100 个子 Hash：`user_profile:00`, `user_profile:01`, ..., `user_profile:99`；
  2. **List / Set 按时间周期拆分**：
     - 消息队列或日志列表按天归档：`task:queue:20260918`，处理完毕后自动过期清理。

### 2.2 生产环境高危禁用命令清单 (Dangerous Commands Blacklist)
以下命令在生产环境严禁直接执行，必须在 `redis.conf` 中重命名或完全禁用：

| 高危禁用命令 | 严重危害 | 正确替代方案 |
| :--- | :--- | :--- |
| **`KEYS *`** | 遍历全库亿级键，阻塞主线程数秒到数十秒，全站雪崩 | **`SCAN`** 游标式增量迭代扫描 |
| **`FLUSHALL` / `FLUSHDB`** | 瞬间清空全库所有数据（灾难性破坏） | 禁止直接执行，必须双人复核并由自动化脚本受控执行 |
| **`HGETALL`** (针对大 Hash) | 一次性将数万字段拉回网络，打满带宽并阻塞主线程 | **`HMGET`** 精确按需获取特定字段，或 **`HSCAN`** 分批迭代 |
| **`SMEMBERS`** (针对大 Set) | 一次性返回全部集合元素，存在阻塞风险 | **`SSCAN`** 分批迭代，或改用有界数据结构 |
| **`DEL`** (针对大型集合 BigKey) | 同步释放百万级内存指针，阻塞主线程数秒 | Redis 4.0+ 必须使用 **`UNLINK`** (异步释放)，并在配置中开启 `lazyfree-lazy-server-del` |

---

# 3. 缓存三大灾难终结方案 (Cache Disasters Prevention)

高并发场景下，缓存层承受着 90% 以上的读流量，一旦失效，流量将直接打爆底层数据库：

```mermaid
flowchart TD
    subgraph 缓存穿透 (查不存在的数据)
        P1["请求不存在的 ID (-1)"] --> P2["缓存未命中"] --> P3["数据库未命中"]
        P4["终结方案: 布隆过滤器 (Bloom Filter) OR 缓存空对象 (空值 + 短随机 TTL)"]
    end
    subgraph 缓存击穿 (热点单一 Key 突然失效)
        B1["超高并发热点 Key 到期"] --> B2["数十万请求瞬间打爆 DB"]
        B3["终结方案: 互斥分布式锁重建 OR 逻辑过期异步后台更新"]
    end
    subgraph 缓存雪崩 (大批 Key 集中同一秒失效)
        S1["整批 Key 设置了相同的 1小时 TTL"] --> S2["某一刻同时过期，全量穿透到 DB"]
        S3["终结方案: 基础过期时间 + 随机扰动因子: base_ttl + rand(1, 300)s"]
    end
```

### 3.1 缓存穿透（查询根本不存在的数据）
- **根因**：黑客攻击或非法请求查询系统中不存在的 ID，导致请求每次穿透缓存直达数据库；
- **标准方案 A：缓存空对象 (Cache Null Object)**
  - 数据库查询结果为空时，在 Redis 中写入一个特定标记空值（如 `""` 或 `{}`），并设置**短过期时间（如 30~60 秒）**；
- **标准方案 B：布隆过滤器 (Bloom Filter)**
  - 在请求到达 Redis 之前，先经由布隆过滤器判断 Key 是否可能存在，100% 不存在的数据直接在最外层拦截阻断。

### 3.2 缓存击穿（热点 Key 过期瞬间的高并发穿透）
- **根因**：单一秒杀商品或超级热搜 Key 在到期失效瞬间，数万并发请求同时涌向数据库重建缓存；
- **标准方案 A：互斥锁 (Mutex Lock)**
  - 缓存未命中时，仅允许第一个抢到互斥锁的协程去查 DB 重建缓存，其他并发协程休眠等待后重试；
- **标准方案 B：逻辑过期 (Logical Expiration - 永远不真正过期)**
  - Value 中包含一个 `expire_at` 业务字段；
  - 外部读取时若发现当前时间超过 `expire_at`，当前请求直接返回陈旧旧数据，同时异步派生一个 Worker 协程去加锁查询 DB 并刷新缓存。

### 3.3 缓存雪崩（海量 Key 集中在同一秒批量失效）
- **根因**：由于批处理任务，将数万个 Key 统一设置了相同的 TTL（如 1 小时），导致 1 小时后这批 Key 集中集体失效；
- **终结铁律**：**所有缓存的 TTL 强制增加随机抖动扰动因子**：
  $$	ext{Actual TTL} = 	ext{Base TTL} + 	ext{Random}(1, 	ext{JitterSeconds})$$
  例如基准 TTL 为 3600 秒，随机增加 1~300 秒，彻底打散过期时间点。

---

# 4. 双写一致性与延迟双删标准 (Cache Consistency)

在“数据库更新”与“缓存更新”之间，严禁盲目直接修改缓存（会导致读写交错引发脏数据常驻）：

### 4.1 工业级通用主流模式：Cache Aside Pattern (旁路缓存)
- **读取模式**：先查缓存；命中直接返回；未命中查数据库，写入缓存并返回。
- **更新模式**：**先更新数据库，再删除缓存 (Delete Cache)**。
  - **为什么删缓存而不是更新缓存？**
    1. 更新缓存可能耗费大量计算资源，且被更新的数据可能后续根本不被读取；
    2. 并发写时，先更新缓存容易出现“事务 A 后写 DB 但先写缓存，事务 B 先写 DB 但后写缓存”的逆序脏写。

### 4.2 强一致场景：延迟双删标准规范 (Delayed Double Deletion)
在高并发且存在从库读写分离的主从复制延迟场景下，采用标准延迟双删算法：

```mermaid
sequenceDiagram
    autonumber
    actor Dev as 业务更新线程
    participant Redis as Redis 缓存
    participant DB as MySQL 主库
    participant Slave as MySQL 从库

    Dev->>Redis: 1. 先删除缓存 (淘汰旧值)
    Dev->>DB: 2. 更新数据库主库
    Note over Dev: 3. 休眠 N 毫秒 (等待从库同步完成)
    Dev->>Redis: 4. 再次删除缓存 (清除休眠期间可能产生的回写脏缓存)
```

```python
import time

def delayed_double_delete(key: str, update_db_func, delay_ms: int = 500) -> None:
    # 1. 先删缓存
    redis_client.delete(key)
    # 2. 执行数据库业务更新
    update_db_func()
    # 3. 休眠等待从库同步完成与并发读结束
    time.sleep(delay_ms / 1000.0)
    # 4. 再次删除缓存
    redis_client.delete(key)
```

---

# 5. 生产级分布式锁安全五大铁律 (Distributed Locking)

分布式锁必须保证互斥性、防死锁、防误删与续期能力：

```mermaid
graph TD
    A["Redis 分布式锁五大铁律"] --> B["1. 命名规范: {project}:[{env}:]lock:{biz}:{id}"]
    A --> C["2. 独占加锁: SET key uuid NX PX 30000 (原子完成)"]
    A --> D["3. 唯一持有者: Value 必须为唯一 RequestID / UUID"]
    A --> E["4. 原子释放: 必须使用 Lua 脚本校验 Value 相等才允许 DEL"]
    A --> F["5. 严禁裸 DEL: 绝对禁止直接删除 Key (防误删他人锁)"]
```

### 5.1 分布式锁 Key 命名与环境隔离特别警示
- **Lock Key 标准格式**：`{project}:[{env}:]lock:{business}:{unique_id}`；
- 🚨 **环境隔离致命红线**：若测试/灰度与共享环境共用 Redis 实例，分布式锁**必须携带环境前缀**，否则测试环境加锁会直接死锁线上生产业务实体！

### 5.1 释放锁标准原子 Lua 脚本 (防止误删他人的锁)
- **致命场景**：线程 A 获取锁（超时 10s），业务执行了 15s；锁自动到期被线程 B 抢到；此时线程 A 执行完毕直接 `DEL key`，将线程 B 正在持有的锁给删除了！
- **标准释放 Lua 脚本**：
  ```lua
  -- 只有当 key 的当前值与传入的持有者标识 (ARGV[1]) 完全一致时，才执行 DEL
  if redis.call("get", KEYS[1]) == ARGV[1] then
      return redis.call("del", KEYS[1])
  else
      return 0
  end
  ```

---

# 6. Redis 规范审查 Checklist

- [ ] **Key 命名结构**：是否统一使用冒号层级分割？Key 长度是否克制？
- [ ] **强制 TTL**：写入的 Key 是否均设置了显式过期时间？
- [ ] **BigKey 排查**：String 是否小于 10KB？Hash/List/Set 元素是否严格控制在 5000 以内？
- [ ] **禁用命令**：生产代码中是否彻底消除了 `KEYS *`、`FLUSHALL`、`HGETALL`？
- [ ] **雪崩防范**：大批同类 Key 的 TTL 是否均已增加随机扰动因子？
- [ ] **双写一致性**：是否遵循 Cache Aside 模式（先更 DB，再删缓存）？
- [ ] **分布式锁**：是否使用了 `SET NX PX` + 唯一随机 Value + Lua 脚本原子校验释放？