#使用 valkey-cli 分析大 Key

Valkey Operator 不提供集成的大 Key 检查报告。
当延迟、内存、网络、持久化或 slot 迁移排查需要 key 大小证据时，请直接使用 valkey-cli。

有关服务器镜像中随附 CLI 支持的选项语义，请参阅官方 Valkey CLI documentation。

#运行影响

valkey-cli --bigkeys 会遍历 keyspace，并运行特定类型的大小命令。虽然遍历使用基于游标的扫描，但额外的命令会消耗服务器 CPU 和网络带宽。对大型集合基数的检查也可能非常耗时。

• 请在流量较低时运行，并监控延迟、CPU、内存和网络使用情况。
• 使用专用的最小权限检查账号，仅授予 SCAN 以及 CLI 所需的类型和大小命令。请根据所选服务器版本验证准确的规则；普通只读应用账号可能权限过宽，或者缺少所需的自省命令。
• 不要在命令行或 shell 历史记录中放置密码。
• 如果服务指标恶化，请停止扫描。
• 将结果视为某一时刻的观测；在扫描期间 keyspace 可能发生变化。

#扫描单个 endpoint

valkey-cli -h <host> -p 6379 --user <username> --askpass \
  --bigkeys -i 0.1

使用 --bigkeys 时，-i 0.1 选项会在每 100 次扫描循环后休眠 0.1 秒；它不会在每次循环后都延迟，也不会让该命令完全没有影响。输出可能包含 key 名称，因此请将其视为敏感信息，仅保存排查所需的内容。

使用 TLS：

valkey-cli --tls --cacert <ca-file> \
  --cert <client-certificate-file> --key <client-key-file> \
  -h <host> -p 6379 --user <username> --askpass \
  --bigkeys -i 0.1

#Cluster 覆盖范围

向某个 Cluster node 发起的扫描只会覆盖该 node 的本地 keyspace，而不是所有 primary node。请从高层状态中列出已观察到的 primary Pod：

kubectl -n <namespace> get valkey <name> \
  -o jsonpath='{range .status.nodes[?(@.role=="master")]}{.podName}{"\t"}{.slots}{"\n"}{end}'

针对每个当前的 primary endpoint 运行一次已批准的扫描。拓扑可能在故障切换或重新平衡期间发生变化，因此请在采集前后记录 CLUSTER NODES，并避免在 slot 迁移期间进行扫描。

#解读并采取行动

该命令会报告每种数据类型中观测到的最大 key 以及汇总统计信息。它并不会判断某个统一的安全大小。请结合命令复杂度、访问频率、网络负载、持久化成本、复制以及应用延迟目标来评估结果。

优先采用应用层修复，例如拆分过大的值或集合、限制增长、在语义上正确的情况下设置过期时间，并避免使用在当前基数下复杂度不安全的命令。在验证 ownership、恢复以及应用行为之前，不要删除或重写生产 key。