valkey

Valkey

由 Linux Foundation 维护的开源、兼容 Redis 的内存数据存储。由 Redis OSS 7.2.4（BSD 3-Clause 许可证）分叉而来。可直接替代 Redis OSS 2.x 至 7.2.x，使用相同的协议、命令和数据格式。

适用场景：缓存、会话存储、速率限制、发布/订阅消息、任务队列、排行榜、分布式锁、实时计数器，或任何需要亚毫秒级键值操作的工作负载。

不适用场景：主要关系型数据存储、大型对象存储（值 >512 MB），或要求在多个键之间实现强 ACID 事务且不使用 Lua 脚本的工作负载。

快速参考

任务	方法	要点
Cache-aside	GET -> 未命中 -> 读取 DB -> SET key val EX ttl	始终设置 TTL，即使设置得很长
会话存储	HSET session:{id} field val + EXPIRE	每次请求时刷新滑动 TTL
速率限制	INCR + EXPIRE（固定窗口）或有序集合（滑动窗口）	需要精确控制时使用有序集合
分布式锁	SET lock:{res} token NX PX 30000	始终设置过期时间以防止死锁
队列（简单）	LPUSH + BRPOP	使用带超时的阻塞式弹出
队列（可靠）	Streams + XGROUP + XACK	使用消费者组实现至少一次投递
发布/订阅	SUBSCRIBE / PUBLISH	即发即弃，不持久化
Streams	XADD + XREADGROUP	持久化、可重放，支持消费者组
排行榜	有序集合：ZADD / ZREVRANGE	O(log N) 排名操作
唯一计数	PFADD + PFCOUNT（HyperLogLog）	约 12 KB 内存，误差 0.81%
淘汰策略	maxmemory-policy allkeys-lru	适用于大多数工作负载的最佳默认设置
Docker 设置	valkey/valkey:8.1-alpine	健康检查：valkey-cli ping
持久化	AOF（appendonly yes）+ RDB 快照	AOF 用于持久性，RDB 用于备份
客户端库	ioredis 或 iovalkey（官方分支）	所有 Redis 客户端均可直接使用
从 Redis 迁移	替换二进制文件，保留数据文件	与 Redis 7.2 的 RDB/AOF 兼容

常见错误

错误	正确做法
在生产环境中使用 KEYS *	使用带游标的 SCAN 进行迭代
缓存键没有 TTL	始终设置 TTL——无界增长会导致 OOM
对大型键使用 DEL，导致服务器阻塞	使用 UNLINK 进行异步删除
使用发布/订阅实现持久消息传递	使用带消费者组的 Streams 实现持久化
所有键使用相同的 TTL（惊群效应）	添加抖动：EX (base + random(0, spread))
生产环境未设置 maxmemory	明确设置 maxmemory 和淘汰策略
使用 MULTI/EXEC 实现锁定	使用 SET ... NX PX 实现分布式锁
存储大型二进制对象（值 >1 MB）	存储引用；保持值较小
Docker Compose 中没有健康检查	添加 valkey-cli ping 健康检查
忽略生产环境中的 requirepass	始终设置身份验证和 ACL

委派

• 发现缓存模式并审查数据模型：使用 Explore Agent
• 规划从 Redis 迁移到 Valkey 的策略：使用 Plan Agent
• 实现完整的缓存层并编写测试：使用 Task Agent

如果有 docker 技能，请将 Compose 网络配置和多阶段构建模式委派给它。 如果有 performance-optimizer 技能，请将应用级缓存策略委派给它。 如果有 database-security 技能，请将 ACL 和 TLS 配置审查委派给它。

参考资料

• 数据结构和命令 —— 字符串、哈希、列表、集合、有序集合、流、HyperLogLog、位图、地理空间
• 缓存模式 —— Cache-aside、直写、TTL 策略、淘汰策略、客户端缓存、失效
• 常见模式 —— 速率限制、分布式锁、队列、会话存储、发布/订阅、流、排行榜
• Docker 和部署 —— Compose 设置、持久化、复制、Sentinel、Cluster、安全性、从 Redis 迁移