用 summarize-database 技能为 StackExchange.Redis 生态中的线上 RESP 数据库做只读采样画像-平芜编程栈

后端
缓存
数据库客户端
消息队列

【免费下载链接】StackExchange.Redis

The Redis client for .NET

项目地址：https://gitcode.com/gh_mirrors/st/StackExchange.Redis

本文介绍如何在 StackExchange.Redis 仓库的 Agent 技能体系中，使用.claude/skills/summarize-database/SKILL.md所定义的"数据库画像"方法，对一个线上（常为生产环境）的 RESP 数据库（Redis、Valkey、Garnet 及 Azure Managed Redis 等）进行只读、采样式的统计分析：识别 key 命名模式、定位数据按数量与按大小的分布重心，并判断值内容的实际类型（计数器、JSON、XML、文本、二进制 blob）。读完本文，你将掌握一套从连接确认、安全约束、采样、探测、模式分词到内容分类与报告输出的完整实战流程，能够在不对生产服务器产生破坏性影响的前提下，快速回答"这个库里到底存了什么、数据集中在哪里"。

技能定位：一次采样回答三个问题

该技能的本质是通过采样一小部分 keyspace，为一个活跃（通常也是生产）的 RESP 数据库建立统计画像。整个画像围绕三个问题展开，对应着最终报告的三块核心内容：

(a) Key 模式—— 将 key 分词，使users:1243:orders与users:543:orders这样的键折叠为users:{id}:orders，并按数据量对模式排序；
(b) 数据在哪里—— 哪些模式/类型承载了主体数据，并且按数量与按大小分别报告（两者经常不一致：可能有很多小键，也可能只有少数巨大键）；
(c) 值是什么—— 数字计数器、JSON、XML、base64/二进制 blob，还是纯文本。

需要强调的是，这是一次只读、采样式的分析：你被指向的是别人的真实数据，"正确性"与"不伤害服务器"比"完整性"更重要。技能在 AGENTS.md 中被定位为仓库内置的两项 Agent 技能之一（另一项是implement-resp-command），其输入输出面向任意支持 Agent 技能的客户端，文件本身与具体工具无关。

硬安全规则：不可逾越的底线

SKILL.md 用一整节篇幅定义了硬性安全规则，任何画像操作都必须在其约束下进行：

只读优先：绝不执行任何写入、删除、过期或重配置类命令，明确禁止FLUSHALL/FLUSHDB、DEL、SET、CONFIG SET、DEBUG RELOAD等。
绝不用KEYS（或KEYS *）：在大 keyspace 上KEYS会阻塞服务器整个扫描过程。应当用RANDOMKEY采样；只有确实需要覆盖面时才用带游标与COUNT的SCAN，绝不使用KEYS。这一警告在仓库文档中同样存在：docs/KeysScan.md 明确指出KEYS/SCAN都是服务器级命令，且两者都会扫遍整个 keyspace，"应避免在生产服务器上使用，或至少将目标指向副本"。
优先把分析负载放到副本上：先执行INFO replication读取拓扑：
- 若连接的是带副本的主节点（role:master、connected_slaves > 0，且有slaveN:ip=…,port=…行），建议用户把目标改指向其中一个副本，让SCAN/MEMORY USAGE/值读取落到副本而非生产主节点；
- 若已在副本上（role:slave/replica），留在原地，不要建议切回其主节点——即使master_host/master_port可见。向"上"移动会把负载推回生产环境，与目标背道而驰（副本可能略有延迟，需在报告中注明画像反映的是接近当前而非实时的状态）。
绝不盲目读取未知大小的值：先执行大小命令，再用GETRANGE key 0 N窥探，绝不对未知 key 直接GET。
约束高开销调用：MEMORY USAGE key SAMPLES <small>，并遵守下文采样上限。
连接前确认目标：向用户回显 host/port/db（以及是否为副本），让用户能阻止你连错服务器；同时确认你被授权查询这个（可能是生产的）系统——而不只是地址正确。
值内容属于机密，读取前必须获得明确同意：key名是模式分析的基础，属于必要读取、可以呈现；但值不是——内容分类阶段（第 4 步）会把真实数据拉入 Agent 上下文，这些数据会离开机器（发送给模型、可能被记录），可能包含 PII、密钥或令牌。必须在运行第 4 步前征得同意。若用户拒绝，则只产出仅结构摘要（第 0–3 步加第 5 步：模式、类型、大小、TTL），跳过值采样。即使获得同意，也不要采样明显敏感的命令空间（匹配*token*/*secret*/*password*/*session*的 key），除非用户专门针对这些开启选择。

工具链：resp-cli 优先，redis-cli 兜底

技能推荐优先使用resp-cli（用户自有的工具，对线上协议透明），仅在缺失或缺少某条命令时回退到redis-cli——并且要明说切换了工具，而不是静默替换。resp-cli在 AGENTS.md 中被描述为"一个 dotnet 全局工具，功能上类似于redis-cli（同样的基本参数：-p、-a、-n、--tls、-3）"，是仓库本地用户探测测试服务器的常用工具。

关键事实如下：

resp-cli [cmd args] -h <host> -p <port> [-a <pass>] [-n <db>] [--tls] [-3]每个进程只运行一条命令。-r N可把一条命令重复 N 次——因此resp-cli -r 200 randomkey就是一个干净利落的随机采样器。
resp-cli没有--scan/--bigkeys/--memkeys模式；redis-cli有，并且支持 stdin管道化，这在探测阶段很重要（见下文性能小节）。
绝不要把密码放在命令行上：-a <pass>会通过进程列表（ps，其他本地用户可见）、shell 历史以及本次对话记录泄露。应改用认证环境变量——RESPCLI_AUTH（resp-cli）/REDISCLI_AUTH（redis-cli）——并用--user <name>指定 ACL 用户名。传输加密用--tls；绝不要为了连上而关闭证书校验（--insecure/--trust）。

服务器兼容性：先识别"真身"，再优雅降级

目标可能是 RESP 兼容服务器而非原生 Redis（本库明确支持 Garnet、Valkey 等）。Garnet 尤其典型：它会通过HELLO对外宣称一个 Redis 版本（例如redis_version:7.4.3），但暴露garnet_version字段且并未实现全部命令。因此要尽早用HELLO识别真实服务器，不能只信redis_version字符串——redis_mode/版本看起来可能像 Redis，但命令却缺失。

在 Garnet 2.0.1 上实际观察到的情况（应"适配而非失败"）：

RANDOMKEY不可用（ERR unknown command）——默认采样器失效，需回退到**SCAN（带游标、COUNT）采样。对小 keyspace，完整SCAN枚举是精确、廉价且优于采样的——做全量枚举并报告 100% 覆盖率，而不是外推。在大** keyspace 上若RANDOMKEY缺失且全量枚举不可行，则没有廉价的无偏采样器：提前终止的部分SCAN按哈希桶顺序返回 key，会引入偏差。要么跑完整游标的SCAN（限制的是每个 key 的探测开销而非扫描本身）并从收集结果中抽样，要么接受部分SCAN的样本并在报告中声明偏差。
OBJECT ENCODING（及OBJECT HELP）不可用——无法报告内部编码，省略该列并注明不可用。
INFO keyspace可能为空，即使DBSIZE> 0——key 数量以DBSIZE为准。
仍可用且照常使用：SCAN、TYPE、MEMORY USAGE、TTL、O(1) 大小命令（HLEN/SCARD/…）以及用于内容读取的HGETALL/HRANDFIELD/LRANGE等。

"先检测、再优雅降级并说明哪些探测不可用"这一策略同样适用于任何命令集实现不全的 RESP 服务器。

六步流程

第 0 步：范围与连接

先执行HELLO（识别真实服务器——留意garnet_version或其他非 Redis 标志，见上节），然后依次执行INFO server、INFO keyspace、INFO memory、INFO replication与DBSIZE。记录服务器/RESP 版本、总 key 数量、已用内存，以及是否有可用副本。

集群模式：若INFO/CLUSTER INFO显示集群模式，则DBSIZE/RANDOMKEY/SCAN都是按节点生效的。要么遍历每个主节点（分别采样再汇总），要么明确说明该摘要只针对你连接的单个节点。绝不能把一个节点的数字当作整个集群的结论。

第 1 步：选择样本大小

默认样本 =min(5% ×DBSIZE，上限)，其中上限默认为约 2,000 个 key。比例与上限都可由用户覆盖——可接受如"采样 10%"、"最多 20000 个 key"或"精确采样 500 个"这样的指令。报告必须写明实际样本大小及其占库的百分比，因为所有外推都依赖这两个数字。

取 key 用resp-cli -r <N> randomkey。RANDOMKEY是放回式采样，因此要对抽到的 key 去重（重复率高说明 keyspace 小或分布偏斜）。

第 2 步：探测每个采样 key

对每个去重后的采样 key 收集：

TYPE key—— string / hash / list / set / zset / stream；
OBJECT ENCODING key—— 内部表示（int、embstr、raw、listpack、intset、hashtable、skiplist、quicklist、stream等），揭示小/大内部布局；
元素大小，按类型各有一个 O(1) 命令：STRLEN（string）、HLEN（hash）、LLEN（list）、SCARD（set）、ZCARD（zset）、XLEN（stream）；
内存：MEMORY USAGE key SAMPLES 5—— 真实字节数（含开销），与元素计数是互补信息（两者回答不同的问题）；若命令被禁用则优雅回退；
TTL key—— 用于报告易失与持久 key 的占比。

性能：小样本下每个命令一个resp-cli进程没问题，但上千样本时就太慢了。样本较大时应构造探测命令并通过redis-cli管道化执行（printf '...\n' | redis-cli ...），resp-cli保留给范围确定/交互式步骤。样本上限正是让这一切可控的约束——务必遵守。

第 3 步：key 模式分词

把每个 key 按:（Redis 惯例）和/切成段，把可变段替换为带类型的占位符，再按分词后的模式分组并统计成员数。

某段看起来像标识符时就折叠它。按大致优先级（最可能优先），但要撒更大的网而不只限于这些：

整数 →{int}
UUID / GUID →{uuid}
十六进制串（如 ≥8 个 hex 字符）→{hex}
ULID / base62 / base64 类 token、长的随机样字符串 →{id}
epoch 时间戳 / 日期样段 →{ts}/{date}
高基数兜底：某段在样本中取值极多（相对其兄弟段而言）几乎可以断定是 id，即使它不匹配以上任何形态——折叠为{var}。

低基数、稳定的段保持字面量（users、orders、cache、session）。报告模式时给出估计的全库计数（样本计数 ÷ 样本占比），并标注它们是估计值。

第 4 步：内容分类

此步会读取真实值——只能在用户同意后运行（见硬安全规则）。未获同意则跳过，交付仅结构摘要。

字符串：先用STRLEN，再用GETRANGE key 0 200窥探（绝不在大/未知值上裸GET）。分类规则：整数计数器（^-?\d+$且/或OBJECT ENCODING=int）、JSON（{/[且可解析）、XML（<…>）、base64/二进制 blob、或纯文本。同时记录近似值大小分布。
聚合类型：采样少数成员，而不是读整个结构。避免对未知大小的聚合使用HGETALL/SMEMBERS/LRANGE key 0 -1——它们是无限界的，大 key 上很慢，还会把远超需要的数据拉进上下文。先做大小门控（HLEN/SCARD/LLEN），再用随机/区间采样器：HRANDFIELD key 5 WITHVALUES、SRANDMEMBER key 5、ZRANDMEMBER key 5 WITHSCORES、LRANGE key 0 4、XRANGE key - + COUNT 5——字段名/元素内容按同样的规则分类。

第 5 步：报告

产出一份精炼摘要：

连接与范围：目标（host/port/db、是否副本）、DBSIZE、已用内存、RESP 版本、集群说明；样本大小与占比；
Key 模式：分词模式 → 估计计数、主导类型、主导编码、示例原始 key 的表格；
数据在哪里：按数量与按估计总大小（单 keyMEMORY USAGE× 外推）分别列出的主导模式/类型，并指出数量与大小的分歧点；
内容：每个主要模式下值是什么（计数器 / JSON / XML / blob / 文本），给出示例形态（示例中隐去明显的密钥/PII）；
注意事项：采样误差、放回式重复、按节点还是按集群、哪些命令不可用。

与 StackExchange.Redis 仓库的印证

该技能并非空中楼阁，它植根于本仓库对 RESP 服务器的既有认知：

命令的服务器级语义：docs/KeysScan.md 明确列出KEYS/SCAN、FLUSHDB/FLUSHALL、RANDOMKEY等都是针对单台服务器的命令，RANDOMKEY只选取当前服务器上的 key；StackExchange.Redis 在IDatabaseAPI 上"伪装"实现了RANDOMKEY——随机挑一台目标服务器，但其余命令无法这样做。这正是技能坚持"按节点采样、不跨节点外推"的底层原因。
Keys的 SCAN/KEYS 自动选择：IServer.cs 中Keys(int database, RedisValue pattern, int pageSize, long cursor, int pageOffset, CommandFlags flags)的注释说明：会根据服务器能力自动选择KEYS或SCAN，且可通过IScanningCursor恢复游标迭代；当SCAN不可用时回退到KEYS——这与技能中"绝不KEYS、优先SCAN或RANDOMKEY"的安全取舍一脉相承（KEYS会阻塞服务器且扫遍全库）。
测试印证：tests/StackExchange.Redis.Tests/KeyTests.cs 的FlushFetchRandomKey与 tests/StackExchange.Redis.Tests/ClusterTests.cs 的AccessRandomKeys分别验证了单机与集群场景下RANDOMKEY的可用性与语义，印证"RANDOMKEY是服务器级、集群中按节点生效"的行为描述。

注意事项

这里的一切都是基于样本的估计——报告时必须说明，并给出样本占比与外推数字。
redis-cli --bigkeys/--memkeys是回答"大小"问题的互补内置工具，但它们不做模式分词与内容分类——本技能的价值恰在"模式 + 内容"，内置工具只作为交叉校验使用。
更多关于resp-cli优先于redis-cli的偏好与项目全局背景，见仓库根目录的 AGENTS.md。