作者： 景丹 镜舟科技 DBA 团队负责人 Peter Pang, StarRocks Contributor
在生产环境排查线上问题，真正的经验往往都是踩坑踩出来的。
比如，有经验的工程师看到 FE Report 时间戳没更新，第一反应就是 LockManager 死锁；看到 Routine Load 导入超时，大概率知道是线程池满了；遇到 Compaction 变慢，会想到可能是 DataCache 自动扩缩容触发了底层存储行为的变化。
这些排障经验非常管用，但也非常容易丢。它们平时就散落在 Slack 的聊天记录、故障复盘报告、个人的备忘录里，或者干脆只记在上周刚值完班的同事脑子里。
我们就在想：能不能把这些零散的经验固化下来，直接喂给 AI 助手去用？我们要的不是那种长篇大论、没人爱看的文档，而是基于真实故障、能让 AI 直接照着跑的结构化排障流程。
这一尝试促成了 starrocks-debug-skills 的诞生，这是一个包含 StarRocks 故障排查技能、案例和诊断命令的开源集合。
沉淀排障经验，难在哪？
每个工程团队都会通过故障事件积累运维知识。时间久了，有经验的工程师能摸清哪些症状是关键的，哪些信号具有误导性，应该首先检查哪些日志，以及在压力下尝试哪些修复措施是安全的。
但这些经验很少能好好沉淀下来。它们散落在 Slack 讨论链、事后分析报告、内部文档、个人笔记中，以及那些在下一次故障发生时可能醒着也可能没醒的工程师的记忆里。
其后果是可想而知的：
-
**重复排查：**新手工程师搞了好几个小时，最后发现这个问题有人三个月前就解过，有现成的解法，就是没人告诉他。
-
响应质量参差不齐： 同一个报错，有人 10 分钟搞定，有人查两个小时，全看当班的是谁。
-
知识流失： 当工程师离职、轮岗或不再参与值班工作时，他们的调试直觉通常也会随之流失。
-
升级瓶颈： 复杂问题会汇聚到一小群专家那里，在面临高压故障时形成单点故障。
文档当然有用，但静态的运行手册（runbooks）有其局限性。它们可能会过时、遗漏重要的上下文，或者无法适应你所面临的具体症状。值班工程师通常需要的不仅仅是一页操作指南，而是一条引导路径：从症状到假设，从假设到诊断命令，再从新证据到下一个最佳步骤。
AI 排障需要什么样的知识库？
通用的 AI 聊天机器人能帮你查文档，但排查生产故障靠的不是“查文档”，而是一套逐步推进的逻辑：
症状 → 假设 → 诊断命令 → 结果解读 → 下一步
这就是为什么我们把知识库分成三层来组织，而不是堆成一大坨 Markdown：
-
Skills (技能)： 针对每个问题领域（查询排查、导入失败、Compaction 调优以及另外 9 个类别）的系统性排查指南。每项技能都提供带有决策树的逐步诊断流程。
-
Cases (真实案例)： 真实的故障事件报告，经过匿名化处理并提炼成以下模式：症状 → 排查过程 → 根本原因 → 解决方案 → 经验教训。包含超过 25 个案例，涵盖了存算一体（shared-nothing）和存算分离（shared-data）部署架构中的生产故障。
-
Tools (诊断命令)： 可直接复制粘贴的诊断命令参考：日志搜索模式、Profile 收集、堆栈跟踪捕获、网络诊断以及
information_schema查询。
这三层加在一起，给了 AI 真正能用的上下文：知道该走哪条排查路径、能跟真实故障做模式匹配、每一步都有现成的命令可以跑。入口文件 SKILL.md 会根据你的症状把你引到正确的排查路径，直接给你需要的命令。
排障实战：AI 怎么顺藤摸瓜？
下面三个真实场景，看看这套技能怎么把一个模糊的报错，变成一条可以直接跑的排查路径。
场景 1：排查导入持续超时
把报错贴进去：Reached timeout=30000ms。
普通 AI 可能给你一页通用文档，但这个技能直接判断这是写入路径的瓶颈，带着你逐层检查线程池是不是被打满了：brpc → async_delta_writer → memtable_flush → segment_replicate
每一层都有现成的命令，直接跑就行。
-- 通过 BE HTTP API 检查线程池饱和度
-- 寻找 active ≈ total 且 queue 非零的线程池
curl -s http://<be_ip>:<be_http_port>/metrics | grep "thread_pool"
# 关键线程池: async_delta_writer, memtable_flush, segment_replicate_sync
接着，它还会让你在超时节点检查 BE 日志，看有没有自动抓到 Profile（v3.4+ 支持）
# 在超时时搜索自动诊断的 profile
grep "profile=" be.WARNING
# 示例: tablet writer add chunk timeout. txn_id=1691, cost=16728ms, timeout=16500ms
如果 segment_replicate_sync 是瓶颈（Case-017 里见过这个模式），Skills 会建议把 flush_thread_num_per_store 从默认的 2 调到 4-6，并告诉你为什么：高并发 Routine Load 会把副本同步线程打满，最终触发 30 秒的 BRPC 超时。
场景 2：定位“Version Does Not Exist”报错
Version Does Not Exist 这个报错很容易把人带偏，大多数人第一反应是去查 BE 存储或 tablet 健康状况，结果越查越懵。
这个 Skill 能把它识别为典型的 FE 死锁信号（Case-003），直接让你去查 FE Report 的时间戳：
# 捕获 FE 堆栈跟踪 — 抓取多个快照
jstack <fe_pid> > /tmp/fe_jstack_$(date +%s).log
grep -A 30 "ReportHandler" /tmp/fe_jstack_*.log
如果 ReportHandler 线程卡在 LockManager.lock 上的 TIMED_WAITING 状态，死锁基本坐实了。接下来：多抓几个 jstack dump 留给工程分析，然后重启 FE 恢复服务。整个过程几分钟就能定位，而不是在错误方向上绕一个小时。
场景 3：解决存算分离下 Compaction 积压
存算分离集群里 Compaction 跟不上摄入进度，原因可能有很多。该 Skill 的排查流程首先检查一个不那么明显的因素：DataCache 自动扩缩容（autoscaling）。在Case-013 的真实场景中，在一个包含 120 个摄入 BE、80 个查询 BE 和 10 个 compaction BE 的存算分离集群中，P99 延迟出现飙升：
# 检查与 compaction 飙升相关的 DataCache 自动扩缩容事件
grep "autoscaling" be.WARNING
规律很明显：磁盘用到 80% 之后，DataCache 开始缩容并驱逐数据，Compaction 只能直接从 S3 读，速度一慢，Compaction Score 就一路往上涨。
这个技能能帮你识别出这是 DataCache 自动扩缩容的副作用，并给出具体建议：在独立 Warehouse 架构里把自动扩缩容关掉，同时推荐你把 num_partitioned_prefix 设成 100，另外别开全局 Profile 收集。
如何接入 AI 工具？
想要上手体验？只要你用的 AI 工具支持自定义指令（Instructions）、规则（Rules）或技能（Skills），就可以直接接入我们的代码仓库。
Claude Code (终端)
先克隆仓库，将其作为技能目录：
git clone https://github.com/StarRocks/starrocks-debug-skills.git
然后，在 .claude/settings.json 中配置路径，或直接在系统提示词中引用。
Cursor / Windsurf
将 SKILL.md 的内容设为自定义指令或规则文件。Cursor 用户请放入 .cursor/rules/ 目录；Windsurf 用户直接添加至工作区规则即可。
Claude Desktop (Cowork 模式)
直接作为插件安装。遇到 StarRocks 集群问题时直接提问，技能会自动触发，无需手动调用。
通用方法
将 SKILL.md 的内容复制到任何 AI 助手的系统提示词或对话窗口中。这个文件包含了完整的排查流程、诊断命令和常见错误对照表。如果需要深挖特定场景，可以去 cases/ 目录找相关案例文件喂给 AI。
沉淀下来的排查经验长什么样？
盘点过往的排查经验，我们发现了一套清晰的规律：最有价值的排查知识往往是高度可复用的。每一次真实的故障、诊断过程、根本原因和修复方案，都沉淀成了现在的知识库。
目前，仓库已经整理了 12 个诊断模块，涵盖 25 个以上的真实故障案例，覆盖范围如下：
为了方便 AI 精准匹配你遇到的问题，每个案例都采用了标准模板：包括运行环境、故障现象、带日志的排查步骤、根本原因、解决方案以及经验总结。
此外，tools/ 目录下还备好了常用的 information_schema 查询脚本，帮你快速执行负载监控、Tablet 分析、线程池检查和数据倾斜检测。
欢迎提 PR：把你的踩坑经验加进来
这个 AI 技能的智力源于它学习过的真实案例。我们希望它不仅记录问题，更能还原现场：你看到了什么现象？哪些关键信号指明了方向？排查时避开了哪些坑？最终是怎么解决的？
仓库里的 CONTRIBUTING.md 提供了贡献模板。只需遵循以下简单的结构即可提交新案例：
## Symptom
[What the user sees]
## Investigation
[Step-by-step with commands and log patterns]
## Root Cause
[What actually broke and why]
## Resolution
[Short-term mitigation + long-term fix]
提交前，请务必脱敏客户数据，尽量用英文编写，并亲自跑通里面的命令和 SQL。我们的目标不只是“记一笔账”，而是要沉淀下真正能帮人解决问题的“破案思路”。
当然，没有任何知识库能 100% 覆盖所有故障。遇到没见过的问题、特定版本的 Bug 或不太常见的集群配置，依然需要工程师人工上阵。但这正是我们呼吁社区共建的原因：每一次踩坑，都能为知识库补充新的线索和排查路径，让下一位值班的同学少走弯路。
让排障经验不再只活在人脑子里
最大的启发是，当我们把资深专家的排查套路（已知故障、诊断命令、历史案例、排查路径）赋能给 AI 时，它能在运维场景中发挥巨大的价值。
我们不是要用 AI 替代工程师，而是为了让这些宝贵的排查经验更容易被复用、传承和迭代。
如果你正在运维 StarRocks，强烈建议你试试开源的 starrocks-debug-skills 仓库，也欢迎把你踩过的坑贡献进来。即便你在用其他系统，这套方法论依然适用，别让宝贵的经验流失在历史聊天记录里。
下次遇到故障时，不妨用它试试手，并把你的新发现分享出来：github.com/StarRocks/starrocks-debug-skills。
欢迎加入 StarRocks Community Slack，和我们一起把团队内部的隐性经验，转化为整个社区的共享智慧！