RedisNotes

附录：附录 Redis 速查手册

zjc 于 2026-01-30 发布

这是《Redis 零基础实战指南》的独立章节版。本章从概念、实操和生产排查三个视角展开，代码块保留了原书可直接运行的版本。 这本手册用于日常开发、值班排查和上线前检查。建议打印或放到团队知识库中，并结合自己公司的平台规范补充。

1. 连接与基础命令

1.1 连接

redis-cli -h 127.0.0.1 -p 6379
redis-cli -h 127.0.0.1 -p 6379 -a 'password'
redis-cli -h 127.0.0.1 -p 6379 --tls --cacert ca.crt
redis-cli -h 127.0.0.1 -p 6379 -u redis://user:password@host:6379/0

1.2 服务器状态

PING
ECHO hello
SELECT 0
CLIENT INFO
CLIENT LIST
CLIENT KILL ID 123
INFO server
INFO clients
INFO memory
INFO stats
INFO replication
INFO persistence
CONFIG GET maxmemory
CONFIG GET maxmemory-policy
TIME
DBSIZE
LATENCY HISTORY event
SLOWLOG GET 20

1.3 key 通用操作

EXISTS key
TYPE key
DEL key
UNLINK key
EXPIRE key 60
PEXPIRE key 60000
EXPIREAT key 1787568000
TTL key
PTTL key
PERSIST key
RENAME old new
RANDOMKEY
SCAN 0 MATCH user:* COUNT 100
OBJECT ENCODING key
OBJECT FREQ key
MEMORY USAGE key
MEMORY USAGE key SAMPLES 0

生产禁用：

KEYS *
FLUSHDB
FLUSHALL
SMEMBERS big_set
HGETALL big_hash
ZRANGE big_zset 0 -1

如确需全量扫描，使用 SCAN、SSCAN、HSCAN、ZSCAN 并分批处理。

2. 数据类型命令速查

2.1 String

SET key value
SET key value EX 60
SET key value PX 60000
SET key value NX
SET key value XX
GET key
GETSET key new-value
MSET k1 v1 k2 v2
MGET k1 k2
INCR counter
INCRBY counter 10
INCRBYFLOAT score 1.5
DECR counter
STRLEN key
APPEND key suffix
SETRANGE key 0 hello
GETRANGE key 0 4

典型场景：缓存 JSON、计数器、分布式锁、限流计数。

2.2 Hash

HSET user:1 name Tom age 20
HGET user:1 name
HMGET user:1 name age
HGETALL user:1
HDEL user:1 age
HEXISTS user:1 name
HLEN user:1
HKEYS user:1
HVALS user:1
HINCRBY user:1 login_count 1
HSCAN user:1 0 COUNT 100

典型场景：对象字段、用户资料、购物车。

2.3 List

LPUSH queue a b
RPUSH queue c
LPOP queue
RPOP queue
BLPOP queue 5
BRPOP queue 5
LRANGE queue 0 -1
LLEN queue
LINDEX queue 0
LSET queue 0 new-value
LREM queue 1 value
LTRIM queue 0 99

典型场景：最新列表、简单任务队列。

可靠队列建议使用 Stream，List 没有消费确认和 pending 机制。

2.4 Set

SADD tags a b
SREM tags a
SMEMBERS tags
SISMEMBER tags a
SCARD tags
SINTER set1 set2
SUNION set1 set2
SDIFF set1 set2
SPOP tags
SRANDMEMBER tags 3
SSCAN tags 0 COUNT 100

典型场景：标签、共同关注、去重、抽奖。

2.5 ZSet

ZADD rank 100 user:1 200 user:2
ZSCORE rank user:1
ZINCRBY rank 10 user:1
ZRANK rank user:1
ZREVRANK rank user:1
ZRANGE rank 0 9 WITHSCORES
ZREVRANGE rank 0 9 WITHSCORES
ZRANGEBYSCORE rank 100 200
ZREVRANGEBYSCORE rank 200 100 LIMIT 0 10
ZCOUNT rank 100 200
ZCARD rank
ZREM rank user:1
ZPOPMIN rank
ZPOPMAX rank
ZSCAN rank 0 COUNT 100

典型场景：排行榜、延迟队列、时间线、优先级队列。

2.6 Bitmap

SETBIT sign:1001:202608 5 1
GETBIT sign:1001:202608 5
BITCOUNT sign:1001:202608
BITPOS sign:1001:202608 1
BITOP AND result source1 source2
BITOP OR result source1 source2

典型场景：签到、活跃标记、布尔状态。

2.7 HyperLogLog

PFADD uv:page:1001 user1 user2
PFCOUNT uv:page:1001
PFMERGE total uv:page:1 uv:page:2

典型场景：近似 UV 统计。标准误差约 0.81%，不保存元素。

2.8 GEO

GEOADD stores 116.397 39.909 store:1
GEOPOS stores store:1
GEODIST stores store:1 store:2 km
GEOSEARCH stores FROMLONLAT 116.39 39.90 BYRADIUS 3 km ASC COUNT 20

典型场景：附近门店、附近的人。

2.9 Stream

XADD events * type order-created orderId 1001
XRANGE events - +
XREVRANGE events + - COUNT 10
XLEN events
XREAD COUNT 10 STREAMS events 0
XGROUP CREATE events order-group 0
XREADGROUP GROUP order-group consumer-1 COUNT 10 STREAMS events >
XPENDING events order-group
XACK events order-group 1234567890-0
XCLAIM events order-group consumer-2 60000 1234567890-0
XTRIM events MAXLEN 100000

典型场景：轻量事件流、任务队列、消费组处理。

3. 数据结构选型表

需求 推荐结构 原因
整体缓存 JSON String 简单、网络友好
对象局部字段更新 Hash 避免整对象重写
最新 N 条数据 List / ZSet ZSet 更容易按时间分页
去重 Set O(1) 判断存在
排行榜 ZSet 按分数排序和范围查询
签到 Bitmap 内存小
UV 近似统计 HyperLogLog 固定小内存
附近位置 GEO geohash 范围查询
可确认队列 Stream 消费组和 pending
分布式锁 String + Lua NX PX 原子加锁
滑动窗口限流 ZSet 按时间范围清理
固定窗口限流 String / Hash 原子计数
多字段索引 RediSearch 需要模块支持

4. 关键配置速查

4.1 内存与淘汰

maxmemory 8gb
maxmemory-policy allkeys-lfu
maxmemory-samples 10
lfu-log-factor 10
lfu-decay-time 1
lazyfree-lazy-eviction yes
lazyfree-lazy-expire yes
lazyfree-lazy-server-del yes
replica-lazy-flush yes
activedefrag no

常用策略：

策略 行为 适用
noeviction 内存满后写入报错 混存不可丢数据
allkeys-lru 全量近似 LRU 纯缓存
allkeys-lfu 全量近似 LFU 长期热点明显
volatile-lru 只淘汰有 TTL key 混合实例谨慎使用
volatile-ttl 优先淘汰短 TTL 特定缓存分层
allkeys-random 随机淘汰 少用

4.2 持久化

save 3600 1 300 100 60 10000
stop-writes-on-bgsave-error yes
rdbcompression yes
rdb-save-incremental-fsync yes
appendonly yes
appendfilename "appendonly.aof"
appenddirname "appendonlydir"
appendfsync everysec
no-appendfsync-on-rewrite no
auto-aof-rewrite-percentage 100
auto-aof-rewrite-min-size 64mb
aof-use-rdb-preamble yes

4.3 复制与哨兵

replicaof 127.0.0.1 6379
replica-read-only yes
replica-serving-stale-data yes
repl-diskless-sync yes
repl-diskless-sync-delay 5
repl-backlog-size 256mb
repl-backlog-ttl 3600
min-replicas-to-write 1
min-replicas-max-lag 10
replica-priority 100

哨兵配置示例：

port 26379
sentinel monitor mymaster 127.0.0.1 6379 2
sentinel down-after-milliseconds mymaster 5000
sentinel failover-timeout mymaster 60000
sentinel parallel-syncs mymaster 1

4.4 网络与客户端

bind 0.0.0.0
protected-mode yes
port 6379
tcp-backlog 511
timeout 300
tcp-keepalive 300
maxclients 10000
client-output-buffer-limit normal 0 0 0
client-output-buffer-limit replica 256mb 64mb 60
client-output-buffer-limit pubsub 32mb 8mb 60
io-threads 4
io-threads-do-reads no

4.5 安全

requirepass strong-password
aclfile /etc/redis/users.acl
rename-command KEYS ""
rename-command FLUSHALL ""
tls-port 6380
tls-cert-file /etc/redis/tls/redis.crt
tls-key-file /etc/redis/tls/redis.key
tls-ca-cert-file /etc/redis/tls/ca.crt

生产上建议网络隔离 + ACL + TLS，而不是只依赖密码。rename-command 在部分版本和云环境中受限，优先使用 ACL。

ACL 示例：

ACL SETUSER app_user on >strong-password ~app:* +GET +SET +DEL +EXPIRE +PING
ACL LIST
ACL WHOAMI
ACL CAT

5. 关键 INFO 指标

5.1 server

指标 含义
redis_version 当前版本
process_id 进程 ID
uptime_in_seconds 运行时长
config_file 配置文件

5.2 clients

指标 含义
connected_clients 当前客户端连接数
blocked_clients 阻塞命令等待数
maxclients 最大连接数
cluster_connections 集群连接

告警关注：连接数持续上涨、blocked_clients 异常。

5.3 memory

指标 含义
used_memory Redis 分配器使用内存
used_memory_rss 操作系统视角 RSS
used_memory_peak 历史峰值
maxmemory 最大内存限制
maxmemory_policy 淘汰策略
mem_fragmentation_ratio RSS / used_memory
total_system_memory 系统总内存

常见判断：

used_memory / maxmemory > 80%：容量预警
mem_fragmentation_ratio > 1.5：观察碎片
mem_fragmentation_ratio < 1：可能使用 swap，严重风险

5.4 stats

指标 含义
total_commands_processed 累计命令数
instantaneous_ops_per_sec 当前 QPS
hit_ratio 键空间命中率
expired_keys 累计过期删除
evicted_keys 因内存淘汰的 key
keyspace_hits 命中次数
keyspace_misses 未命中次数
rejected_connections 拒绝连接数

缓存命中率：

keyspace_hits / (keyspace_hits + keyspace_misses)

5.5 persistence

指标 含义
rdb_bgsave_in_progress 是否正在 bgsave
rdb_last_save_time 上次 RDB 时间
rdb_last_bgsave_status 上次 bgsave 状态
aof_enabled 是否开启 AOF
aof_rewrite_in_progress 是否正在重写
aof_last_write_status 上次 AOF 写状态
aof_current_size 当前 AOF 大小
loading 是否正在加载数据

5.6 replication

指标 含义
role master 或 replica
connected_slaves 已连接从节点数
master_replid 主节点复制 ID
master_repl_offset 主节点复制偏移
slave_repl_offset 从节点复制偏移
slave_read_repl_offset 从节点读偏移
master_link_status 从节点连接主节点状态
master_last_io_seconds_ago 距上次主从 IO 秒数

复制延迟观察：

master_repl_offset - slave_repl_offset

5.7 cluster

CLUSTER INFO
CLUSTER NODES
CLUSTER SLOTS
CLUSTER COUNTKEYSINSLOT 1234
CLUSTER KEYSLOT key
CLUSTER CHECK 127.0.0.1:7001

重点指标：

指标 含义
cluster_state ok 或 fail
cluster_slots_assigned 已分配槽
cluster_slots_ok 正常槽
cluster_slots_pfail 疑似故障槽
cluster_slots_fail 故障槽
cluster_known_nodes 已知节点
cluster_size 至少一个槽的 master 数

6. 故障排查命令

6.1 延迟升高

redis-cli slowlog get 50
redis-cli latency latest
redis-cli latency history event
redis-cli info commandstats
redis-cli info clients
redis-cli info memory
redis-cli --latency -h host -p port
redis-cli --intrinsic-latency 30
redis-cli --bigkeys
redis-cli --memkeys

排查顺序：

慢命令 -> 大 key -> 客户端连接 -> 内存和 swap -> fork/AOF -> 网络 -> 主从/集群事件

6.2 CPU 高

redis-cli info commandstats
redis-cli --hotkeys
redis-cli cluster nodes
perf top -p $(pidof redis-server)

常见原因：

  1. 单分片热点 key；
  2. QPS 真实超过单节点容量；
  3. 大量序列化或大 value；
  4. 过期删除和淘汰集中；
  5. AOF/RDB fork；
  6. 客户端频繁重连；
  7. 系统进程干扰。

6.3 内存高

redis-cli info memory
redis-cli dbsize
redis-cli --bigkeys
redis-cli --memkeys
redis-cli scan 0 match 'prefix:*' count 100

处理：

  1. 拆分大 key；
  2. 缩短 TTL；
  3. 清理冷数据；
  4. 拆分实例；
  5. 扩容；
  6. 检查淘汰策略是否符合数据价值。

6.4 连接异常

redis-cli client list
redis-cli info clients
redis-cli config get maxclients
ss -antp | grep 6379

关注：

字段 含义
age 连接存活时间
idle 空闲时间
cmd 最近命令
qbuf 输入缓冲区
qbuf-free 输入缓冲区剩余
oll 输出列表长度
omem 输出缓冲区内存

6.5 主从复制异常

redis-cli -p 6379 info replication
redis-cli -p 6380 info replication
redis-cli -p 6380 role
redis-cli -p 6379 client list | grep replica

处理顺序：

  1. 网络连通性和带宽；
  2. master_link_status；
  3. 复制偏移差；
  4. backlog 是否过小；
  5. 主节点写压力和 RDB 生成状态；
  6. 是否频繁全量同步。

6.6 数据丢失排查

1. 确认写入是否到达 Redis：TTL、WAIT、客户端确认、命令日志
2. 确认是否发生故障切换：sentinel/cluster 日志
3. 检查复制确认程度：min-replicas-to-write
4. 检查 AOF/RDB 状态和丢失窗口
5. 检查是否内存淘汰：evicted_keys
6. 检查是否过期：expired_keys
7. 检查是否误删：DEL/UNLINK/SCAN 脚本
8. 检查是否有其他客户端写入：CLIENT LIST、ACL 审计

7. 性能黄金清单

上线前逐项确认：

  1. 所有 key 有前缀规范和 TTL；
  2. value 平均大小和 P99 大小已评估；
  3. 单 key 建议小于 10KB，超过需要评审；
  4. 集合类元素数量有上限；
  5. 禁用 KEYS 和全量大集合命令；
  6. pipeline 批量大小控制在几百条；
  7. Lua 脚本短小、幂等、确定耗时；
  8. 连接池最大连接数和超时已配置；
  9. 命令 P99 延迟有监控；
  10. 慢日志和 latency monitor 开启；
  11. maxmemory 有预警；
  12. 淘汰策略符合数据价值；
  13. RDB/AOF 配置满足 RPO；
  14. 备份恢复已演练；
  15. 哨兵或 Cluster 已演练故障切换；
  16. 应用能处理连接抖动和重试；
  17. 重试有退避和上限；
  18. 热点 key 有识别手段；
  19. 回源数据库有限流；
  20. 有明确降级预案。

8. 安全黄金清单

  1. Redis 不暴露公网；
  2. 使用 VPC、安全组或防火墙限制来源；
  3. 开启 protected-mode；
  4. 使用 ACL 替代共享密码；
  5. 每个应用独立用户；
  6. 只授予必要 key 前缀和命令；
  7. 禁止普通应用执行 CONFIG、DEBUG、FLUSH、SHUTDOWN；
  8. 敏感传输使用 TLS；
  9. 密码和证书使用密钥管理系统；
  10. 定期轮换凭据；
  11. 开启操作审计；
  12. 及时升级安全版本；
  13. 备份文件加密并限制访问；
  14. 生产命令入口审批；
  15. 定期演练权限误配置后的影响。

9. 客户端配置建议

9.1 Java 常用参数

参数 建议
connect timeout 500ms 到 2s
command timeout 50ms 到 500ms，按业务 SLA
max idle 接近 max total
max total 根据实例 QPS 和连接上限计算
min idle 保持少量预热连接
test while idle 谨慎开启
retry 只重试幂等命令
circuit breaker 必须具备

9.2 重试原则

可以重试：

GET、MGET、EXISTS、PING
明确的连接建立失败
幂等写且业务有唯一键

不要盲目重试：

INCR/DECR
SET NX 分布式锁
LPUSH/RPUSH
非幂等业务写
超时原因不明的命令

超时原因不明时，命令可能已经执行，盲目重试会造成重复写入。

10. 常见故障与处理

现象 优先检查 常见原因
突然超时 慢日志、latency、大 key 慢命令、fork、网络抖动
CPU 100% commandstats、hotkeys 热点 key、QPS 超限
内存持续增长 TTL、bigkeys、业务增长 冷数据、无 TTL、淘汰策略错误
大量写入报错 maxmemory、noeviction 内存满、淘汰不可用
命中率下降 业务访问模式、key 过期 TTL 到期、key 被误删
数据库压力升高 miss 指标 穿透、击穿、雪崩
主从断连 网络、复制缓冲、带宽 网络故障、backlog 不足
频繁全量同步 offset、replid、backlog 断线过久、拓扑切换
Cluster 状态 fail cluster info/nodes 槽未覆盖、节点故障
客户端连接耗尽 client list、应用池 连接泄漏、池配置过小

11. 日常巡检表

每日：

1. used_memory 和 maxmemory
2. QPS 和命令 P99
3. 慢查询数量
4. 连接数
5. 主从复制状态
6. 集群状态
7. 备份状态
8. evicted_keys 和 expired_keys

每周：

1. 大 key Top 100
2. 热点 key Top 100
3. key 前缀内存分布
4. 命中率变化
5. 慢命令分类
6. 主从延迟峰值
7. 安全组和 ACL 变更

每月：

1. 容量趋势预测
2. 备份恢复演练
3. 故障切换演练
4. 版本安全公告
5. key 规范治理
6. 值班 Runbook 更新

12. 常用脚本模板

12.1 加锁

SET lock:order:1001 unique-token NX PX 10000

12.2 释放锁

if redis.call('GET', KEYS[1]) == ARGV[1] then
    return redis.call('DEL', KEYS[1])
else
    return 0
end

12.3 秒杀扣减

local stock = tonumber(redis.call('GET', KEYS[1]) or '0')
if stock <= 0 then
    return 0
end
redis.call('DECR', KEYS[1])
return 1

12.4 滑动窗口限流

local key = KEYS[1]
local now = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local limit = tonumber(ARGV[3])
local member = ARGV[4]

redis.call('ZREMRANGEBYSCORE', key, 0, now - window)
if redis.call('ZCARD', key) >= limit then
    return 0
end
redis.call('ZADD', key, now, member)
redis.call('PEXPIRE', key, window)
return 1

12.5 分批 SCAN 删除

redis-cli --scan --pattern 'tmp:*' | head -n 1000 | xargs -r redis-cli unlink

删除前必须确认前缀、预估 key 数量、评估对业务影响，并保留回滚或重建方案。

13. 学习资源

官方：

Redis docs:    https://redis.io/docs/latest/
Redis commands: https://redis.io/docs/latest/commands/
Redis GitHub:  https://github.com/redis/redis
Redis release: https://github.com/redis/redis/releases

推荐顺序：

  1. 官方数据类型文档；
  2. 官方配置说明；
  3. INFO 指标解释；
  4. 持久化、复制、哨兵、Cluster 文档；
  5. 官方性能和延迟文档；
  6. 发布说明；
  7. 源码注释；
  8. 社区 issue 与讨论。

14. 最后检查

每次上线 Redis 相关功能前，问十个问题：

  1. 这个数据能丢吗？
  2. 内存满了会发生什么？
  3. key 的生命周期是什么？
  4. value 最大多大？
  5. Redis 故障时业务返回什么？
  6. 数据库能承受多少回源？
  7. 缓存不一致如何发现和修正？
  8. 主从切换时客户端如何恢复？
  9. 如何确认这次变更是安全的？
  10. 出问题后第一处理动作是什么？

能清楚回答这十个问题，说明这个 Redis 方案已经具备进入生产的基本条件。