Sentinal Redis

通过任意消息通道监控 Redis 服务器健康状态、BullMQ 队列、内存使用及性能表现。使用自然语言提问，即可获得可操作的诊断结果。

适用场景

✅ 在以下情况下使用该能力：

• 用户询问 Redis 服务器健康状态、运行状态或基本信息
• 用户希望检查内存使用情况或诊断 OOM（内存溢出）问题
• 用户询问 BullMQ 队列长度、失败任务或卡住的 Worker
• 用户希望检查慢查询或延迟问题
• 用户询问 Redis 响应缓慢或无响应的原因
• 用户提及队列积压、死信队列（dead letter queue）或任务失败
• 用户希望快速获取 Redis 实例的健康概览

不适用场景

❌ 请勿在以下情况下使用该能力：

• 用户需要管理 PostgreSQL、MySQL 或其他非 Redis 数据库
• 用户需要管理 Kafka、RabbitMQ 或 SQS 队列（非 BullMQ）
• 用户需要帮助编写使用 Redis 的应用程序代码
• 用户希望从零开始搭建 Redis（请参考官方 Redis 文档）

安全规则

⚠️ 关键提示：本能力为只读（READ-ONLY）模式，无任何例外。

• 禁止执行任何破坏性命令（如 FLUSHDB、FLUSHALL、DEL、UNLINK、SET、EXPIRE），即使用户明确要求。需解释原因，并建议用户手动执行。
• 禁止修改 Redis 配置（如 CONFIG SET），应引导用户自行操作。
• 禁止在输出中打印或暴露完整 REDIS_URL —— 其中可能包含密码。显示前必须对凭据进行掩码处理。
• 如有疑虑，应先展示待执行命令，并请求用户确认后再执行。

连接方式

若已设置 REDIS_URL 环境变量，则所有命令均使用该 URL：

redis-cli -u "$REDIS_URL" 

若未设置 REDIS_URL，则默认连接本地实例：

redis-cli 

对于未通过 REDIS_URL 配置但启用了密码认证的实例：

redis-cli -h  -p  -a  

执行任何操作前，请始终先测试连通性：

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" ping

服务器健康状态

快速状态检查

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" ping

完整服务器信息

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info server

已连接客户端

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info clients

运行时长与版本信息

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info server | grep -E "redis_version|uptime_in_days|uptime_in_seconds|connected_clients"

内存分析

内存概览

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info memory

关键内存指标

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info memory | grep -E "used_memory_human|used_memory_peak_human|used_memory_rss_human|mem_fragmentation_ratio|maxmemory_human|maxmemory_policy"

内存医生（仅 Redis 4.0+ 支持）

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" memory doctor

指定 Key 的内存占用

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" memory usage 

查找大 Key（基于 scan，适用于生产环境）

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" --bigkeys

内存结果解读

• mem_fragmentation_ratio > 1.5 → 内存碎片率过高，建议重启 Redis
• mem_fragmentation_ratio < 1.0 → Redis 正在交换到磁盘，属严重问题
• used_memory 接近 maxmemory → 将依据 maxmemory_policy 开始驱逐数据
• memory doctor 返回 “Sam, I have no memory problems” → 当前无内存问题

慢查询与性能分析

查看慢日志

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" slowlog get 10

慢日志条目总数

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" slowlog len

当前慢日志阈值

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" config get slowlog-log-slower-than

延迟检测

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" --latency -c 10

延迟历史记录

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" --latency-history -i 1 -c 5

键空间统计

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info keyspace

命令调用统计（调用最频繁的命令）

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info commandstats

客户端监控

列出已连接客户端

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" client list

客户端数量与摘要

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" info clients | grep -E "connected_clients|blocked_clients|tracking_clients"

查找空闲客户端（idle > 300 秒）

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" client list | awk -F' ' '{for(i=1;i<=NF;i++) if($i ~ /^idle=/) print $0}' | grep -E 'idle=[3-9][0-9]{2,}|idle=[0-9]{4,}'

BullMQ 队列监控

BullMQ 使用 Redis 作为后端存储。队列键名遵循模式：bull::。

发现全部队列

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" scan 0 match "bull:*:meta" count 100

队列深度（各状态）

对于名为 的队列：

echo "=== Queue:  ==="
echo -n "Waiting: "; redis-cli -u "${REDIS_URL:-redis://localhost:6379}" llen "bull::wait"
echo -n "Active: "; redis-cli -u "${REDIS_URL:-redis://localhost:6379}" llen "bull::active"
echo -n "Delayed: "; redis-cli -u "${REDIS_URL:-redis://localhost:6379}" zcard "bull::delayed"
echo -n "Failed: "; redis-cli -u "${REDIS_URL:-redis://localhost:6379}" zcard "bull::failed"
echo -n "Completed: "; redis-cli -u "${REDIS_URL:-redis://localhost:6379}" zcard "bull::completed"
echo -n "Paused: "; redis-cli -u "${REDIS_URL:-redis://localhost:6379}" llen "bull::paused"

检查失败任务

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" zrange "bull::failed" 0 9

获取任务详情

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" hgetall "bull::"

检查任务负载与错误信息

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" hmget "bull::" data failedReason stacktrace attemptsMade timestamp processedOn finishedOn

查找陈旧的活跃任务

长时间未更新的活跃任务可能存在卡住风险：

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" lrange "bull::active" 0 -1

随后对每个任务 ID 检查 processedOn 时间戳：

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" hmget "bull::" processedOn name

若 processedOn 超过 10 分钟且任务仍处于活跃状态，则可能已卡住。

检查队列 Worker（通过事件流）

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" xinfo groups "bull::events" 2>/dev/null || echo "No event stream found"

BullMQ 定期任务

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" zrange "bull::repeat" 0 -1

Key 检查

按模式查找 Key

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" scan 0 match "" count 100

Key 类型与 TTL

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" type 
redis-cli -u "${REDIS_URL:-redis://localhost:6379}" ttl 

Key 编码方式（用于评估内存效率）

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" object encoding 
redis-cli -u "${REDIS_URL:-redis://localhost:6379}" object idletime 

按前缀统计 Key 数量（适用于审计场景）

redis-cli -u "${REDIS_URL:-redis://localhost:6379}" eval "local count = 0; local cursor = '0'; repeat local result = redis.call('SCAN', cursor, 'MATCH', ARGV[1], 'COUNT', 1000); cursor = result[1]; count = count + #result[2]; until cursor == '0'; return count" 0 "*"

诊断 —— 全面健康检查

运行健康检查脚本以获取综合概览：

bash scripts/redis-health.sh "${REDIS_URL:-redis://localhost:6379}"

该脚本输出内容包括：

• 连通性状态
• 服务器版本与运行时长
• 内存使用量与碎片率
• 已连接客户端数与阻塞客户端数
• 慢查询数量
• 全部 BullMQ 队列深度
• 检测到的任何异常警告

故障排查决策树

Redis 响应缓慢

1. 检查延迟：redis-cli --latency -c 10
2. 若延迟 > 1ms → 检查慢日志：slowlog get 10
3. 若慢日志中存在对大型集合执行的 KEYS/SMEMBERS/HGETALL → 建议改用对应 SCAN 变体
4. 检查内存碎片率 → 若 > 1.5，建议重启 Redis
5. 检查 connected_clients → 若 > 1000，需排查连接池配置
6. 检查 blocked_clients → 若 > 0，需检查 BLPOP/BRPOP 消费者

Redis OOM / 内存占用过高

1. 运行 info memory → 对比 used_memory 与 maxmemory
2. 运行 --bigkeys → 查找最大 Key
3. 检查 maxmemory_policy → 是否已启用驱逐策略？
4. 运行 memory doctor → 遵循其建议
5. 检查 Key 是否缺失 TTL：对大 Key 执行 scan 并逐一检查 ttl

BullMQ 任务卡住 / 无法处理

1. 检查队列深度 → 是否大量任务堆积在 wait 状态？
2. 检查 active 列表 → 是否存在长期处于活跃状态的任务？
3. 检查陈旧活跃任务 → processedOn 时间戳是否过旧？
4. 检查事件流 → 使用 xinfo groups 验证 Worker 是否已正确连接
5. 检查 failed 集合 → 读取 failedReason 和 stacktrace
6. 检查 Redis 连通性 → Worker 是否能正常访问 Redis？

BullMQ 失败率过高

1. 获取近期失败任务：zrange bull::failed -10 -1
2. 对每项任务读取 failedReason 和 stacktrace
3. 按错误类型分组 → 是单一重复错误，还是多种错误混杂？
4. 检查 attemptsMade → 是否已耗尽重试次数？
5. 检查任务 data → 负载内容是否格式异常？

注意事项

• 所有命令在未设置 REDIS_URL 时，默认使用 redis://localhost:6379
• scan 命令适用于生产环境（非阻塞），而 keys 命令严禁在生产环境中使用
• BullMQ 键名模式默认采用前缀 bull:；若使用了自定义前缀，请相应替换 bull:
• 对于 Redis Cluster，请在 redis-cli 命令中添加 -c 参数
• 对于 Redis Sentinel，请先连接 Sentinel 实例以自动发现主节点