pstack+Claude Code读栈排查Java死锁实战

这周排查一个Java服务周期性卡顿的问题，线上日志一切正常，CPU也没飙得太夸张，但业务线程就是动不动堆成一片，一卡就是十几秒。下午实在没忍住，抓了几次线程栈逐行去读，读到一半眼睛已经花了。后来干脆把pstack采集到的现场栈整文件丢给Claude Code，让它当我的“读栈搭子”，这一试就停不下来了。

这篇文章就是围绕pstack-claude这个工作流的完整复盘：它是什么、怎么搭、能解决什么问题、里面有哪些坑，以及我用它完整排查一次死锁的过程。如果你平时要面对线上进程卡死、线程池打满、CPU突刺这类问题，又不想手动在几十层调用栈里翻找可疑代码，那这套组合值得你花半小时搭起来。我会从工具原理讲到环境构建，再到实战投喂和避坑，尽量让从没碰过Claude Code的人也能照着做。

1. 项目整体拆解：进程栈采集和终端AI为什么能凑到一起

1.1 pstack到底在采集什么信息

pstack命令本质上是对gdb的一层封装，它的核心动作是：attach到目标进程，然后对该进程的每一个线程执行backtrace，把线程当前正在执行的函数调用链给抓出来。每一帧栈信息，就是程序此刻从“当前执行到哪一行”一路回溯到“入口函数”的完整路径。

如果把一次故障比作案发现场，栈就是嫌疑人脚底板上的泥脚印：它记录了这个线程在出事那一刻到底踩过了哪些代码路径。这也是为什么栈信息必须当场抓——它是瞬态的，进程每运行几毫秒，所有线程的栈都会变化，等进程重启了、线程退出了，再想还原当时的执行路径就完全没戏了。

实际使用起来非常简单，多数发行版装好gdb之后就能直接用：

# 抓取PID为12345的进程所有线程的当前函数调用栈 pstack 12345 > /tmp/pstack-12345.txt # 如果没有pstack命令，可以直接用gdb做同样的事 gdb -p 12345 -batch -ex "thread apply all bt" > /tmp/gdb-12345.txt

抓出来的文件通常有几百到几千行，按线程分组，每个线程一个块。这就是我们后面要交给Claude Code处理的原始素材。

1.2 Claude Code在终端工作流里的定位

Claude Code是跑在终端里的AI代理工具，和网页版聊天最大的区别是它能直接处理本地上下文：读文件、执行shell命令、维护跨多轮对话的状态。对我这种习惯了ssh到服务器上解决问题的工程师来说，它的价值在于不用把日志和代码来回复制粘贴，直接在故障现场干活。

在做栈分析这件事上，Claude Code特别适合当“初筛员”。几百行原始栈文件摆在那儿，人工逐行看当然能看懂，但效率低，而且容易漏掉关联线索。Claude Code可以跨文件对照：你给它一个栈文件，同时指给它源码目录，它能一边看栈里出现的类名和方法名，一边去源码里找对应的调用关系，然后把可疑链路整理出来。

它还能连续追问。比如第一次问“这个栈里哪个线程最可疑”，它给出分析后，你可以继续问“那它等待的锁在哪个文件哪个方法里申请”，它不会丢失前文上下文。这种多轮分析能力，正是读栈排查问题最需要的东西。

1.3 组合方案的设计思路

pstack-claude这个工作流的思路其实很朴素，分四步走：采集原始证据、整理现场信息、交给AI做模式识别、由人来下达结论。

第一步，进程故障时第一时间用pstack抓全量线程栈，保住现场。第二步，把栈文件、线程状态、时间点、相关日志片段整理成一份“病例”。第三步，把这份病例连同源码目录一起交给Claude Code，让它按你的提示词去分析锁等待关系、热点调用、可疑代码路径。第四步，工程师对AI给出的结果做复核，去源码里验证，最终拍板修复方案。

整个设计里最关键的约束在于：AI只负责缩小搜索范围，永远不直接改线上代码。我见过不少把AI结论当真理的人，但在栈分析这个场景，模型再聪明也不了解你的业务语义、配置历史、发布节奏，它只是帮你把“哪里要看”这个问题从大海捞针变成定向扫描。人工复核这一环绝对不能省。

1.4 目标场景与适用人群

这套组合最舒服的场景有这么几类：一是死锁和锁竞争，栈里能看到线程互相等待的锁地址；二是线程池耗尽，大量线程卡在同一个任务队列或同一个阻塞点上；三是进程hang住，CPU不高但请求完全不响应，这时栈能直接告诉你所有线程停在哪个调用上；四是高延迟抖动，需要对比卡顿时刻和空闲时刻的栈差异。

适用人群我觉得没有门槛限制，后端开发、运维、SRE、性能优化工程师都能上手。哪怕你对gdb不熟，只要会敲pstack命令、会把文件交给AI，这套流程就能跑起来。真正需要积累的是最后一步——对人判断力的要求，而这恰恰是AI替代不了的部分。

2. 环境准备：从零把Claude Code跑起来

2.1 先解决Windows下的虚拟化平台与WSL

很多人在Windows上装Claude Code时会碰到一个很劝退的报错，大意是Claude的workspace要求Windows开启虚拟化平台能力。这个报错其实不是Claude Code本体不能跑，而是它的沙箱工作区依赖Windows的Virtual Machine Platform功能，也就是WSL2和Hyper-V底层的那个虚拟化基础。

处理办法分三步，顺序不要乱：

第一步，用管理员身份打开PowerShell，执行：

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

顺手把Linux子系统也开上：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

第二步，重启电脑，然后装WSL。如果你的Windows版本比较新，直接执行：

wsl --install

它会默认装Ubuntu。装完启动一次Ubuntu，设置普通用户和密码。

第三步，如果上面两步都做完还报虚拟化错误，去检查BIOS里的虚拟化技术（Intel VT-x / AMD SVM）是不是被关掉了。我自己就踩过这个坑，之前帮同事排查，系统层面全部开启正常，最后发现是生产笔记本BIOS里把虚拟化关了，导致WSL一直起不来。

需要说明的是，Claude Code的跨平台支持情况是：macOS和原生Linux可以直装，Windows这边通过WSL运行是最稳妥的方式。装好WSL之后，后面所有的安装步骤都在WSL的Linux环境里执行，不要再回到Windows的cmd。

2.2 在WSL里安装Node.js和Claude Code

Claude Code是npm包，所以第一步是装Node.js。WSL里如果直接用apt装，版本往往偏老，我建议用nvm来装，后续换版本也方便：

# 安装nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash # 重新加载shell配置 export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # 安装并启用Node.js 20 LTS nvm install 20 nvm use 20

Node装好之后，安装Claude Code就是一条命令的事：

npm install -g @anthropic-ai/claude-code claude --version

看到版本号输出就算装好了。这里我强烈建议用nvm而不是系统apt装Node，原因下一节会详细说，它直接影响自动更新功能能不能正常工作。

Claude Code启动后直接在终端里敲claude就会进入交互界面。首次启动它会要求登录：可以走浏览器授权，也可以直接粘贴API Key。这个环节按官方指引操作即可，环境变量方式我放在2.4节讲。

2.3 npm权限与自动更新失败的解法

我在WSL里第一次运行Claude Code的时候，遇到过这个报错：

auto-update failed: no write permission to npm prefix

这个错误的原因非常典型：npm全局安装目录默认是/usr/lib/node_modules或/usr/local/lib/node_modules，属于系统保护目录，普通用户没有写权限。Claude Code启动时会尝试检查并下载新版本，写入全局目录时被拒，于是报错。

解决思路是让npm的全局目录落到当前用户的home目录下：

npm config set prefix ~/.npm-global

然后在~/.bashrc或~/.zshrc里加一行：

export PATH="$HOME/.npm-global/bin:$PATH"

重新加载配置之后，把Claude Code重新全局安装一次：

npm install -g @anthropic-ai/claude-code

这样自动更新就能往用户目录写文件了。

如果你用的是nvm方案，全局目录天然就在用户目录下（~/.nvm/versions/node/v20.x/lib/node_modules），从一开始就不会碰权限问题，这也是我推荐nvm的根本原因。

2.4 登录认证与模型接口配置

正常使用Claude Code需要认证。交互式环境里，直接运行claude，按提示用浏览器登录或者粘贴API Key就行。如果要在脚本或自动化流程里用，那就设置环境变量：

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"

另一种情况是你有自己可用的模型网关接口，比如企业自建网关或者第三方兼容端点。Claude Code是支持通过环境变量切换接口的：

export ANTHROPIC_BASE_URL="https://your-gateway.example.com/anthropic" export ANTHROPIC_MODEL="your-model-name"

我实测过一些兼容Anthropic接口的模型服务，比如DeepSeek的anthropic兼容端点，把它指向Claude Code后跑栈分析这类偏推理的任务，效果是完全够用的，成本还低不少。这类配置属于开发工具的正常扩展用法：Claude Code本身只是一个客户端壳子，模型可以换，但你要记住，换来的模型分析结论更要谨慎复核，它不代表官方模型的输出质量。

3. 核心实现：把pstack的输出变成AI能读懂的“现场报告”

3.1 正确采集线程栈：pstack、gdb、gcore三种姿势

采集现场栈信息不止pstack一种办法，我把三种常用方式整理出来，按需选择：

pstack的输出格式比较固定，每个线程块以Thread开头，后面是线程号，再往下就是栈帧列表。gdb的thread apply all bt输出自由度更高，如果你熟悉GDB的print指令，甚至可以在bt的同时把互斥锁地址、线程状态等一并打出来，这对后面AI分析锁等待关系很有帮助。

gcore则是把整个进程的内存镜像dump下来，生成core文件。它的好处是采集过程对进程影响极小，而且core文件生成后你可以随时再打开分析，不用怕现场丢失。缺点是文件非常大，动辄几个GB，需要磁盘空间撑得住。

采集时有三个细节必须注意：第一，抓栈要趁现场还在的时候抓，进程卡住的时候马上动手；第二，目标进程必须和你的操作账号是同一个用户，否则attach会被拒绝；第三，pstack执行瞬间会让进程短暂挂起，对极端性能敏感的业务要挑可接受的窗口。虽然挂起时间通常只有几毫秒，但在线上环境还是要有这个意识。

3.2 让输出更完整：多线程状态、内核栈与时间线

单一栈快照的信息量其实是很有限的：你只知道那一刻线程停在哪，但不知道它是怎么一步步走到这里的，也不知道其他维度的线索。我的习惯是至少抓两份栈：故障时段一份、恢复或空闲时段一份，并且记录每份的精确时间点。给AI两份栈做对比分析，效果远好于只丢一份“静态照片”。

除了用户态栈之外，还可以补充几个维度的数据。比如cat /proc/PID/task/*/stack能看到内核栈，它对应线程在内核里的等待路径，线程阻塞在锁上还是IO上，这里会有线索。再比如把dmesg里相关时间段的内核日志、业务日志里对应时刻的报错片段一起打包，组一条时间线。

打个比方，这就像医生看心电图，从来不是只看一帧，而是看动态变化、看前后波形。AI分析栈也一样，你把“故障时的栈+恢复后的栈+日志时间线”摆在一起，它能给出的判断维度会丰富很多：哪些线程一直都在，哪些是卡顿突然新增的阻塞，哪个锁在整个周期里被反复争夺，这些问题在单一快照里是看不出来的。

3.3 三种投喂方式：交互指令、CLI管道、MCP工具

把栈信息交给Claude Code，我试过三种方式，各有各的适用场景。

第一种是交互式，在Claude Code会话里直接执行：

!pstack 12345 > /tmp/stack.txt

然后：

/read /tmp/stack.txt

接着直接下分析指令。这种方式最灵活，适合临场排查问题，你可以边问边追加上下文。

第二种是CLI管道，适合脚本化批量处理：

claude -p "请分析这个线程栈文件，找出最可疑的线程和锁等待关系" --file /tmp/stack.txt

这种方式可以塞进定时任务或者故障自愈脚本里，一旦抓到栈就自动扔给AI初筛，再把报告推到群里。

第三种是注册一个MCP工具，把pstack封装成Claude Code能直接调用的工具。这种方式最彻底，以后在会话里说一句“抓一下PID 12345的栈并分析”，Claude Code会自己去执行pstack、读文件、做分析，全程不需要你手动切出去敲命令。缺点是搭起来稍微多一点工作量。如果你只是偶尔排查问题，前两种足够了；高频使用再考虑MCP方案。

3.4 提示词工程：让Claude Code做栈分析而不是写诗

给Claude Code投喂栈文件时，提示词的质量直接决定分析质量。我用下来比较有效的一套模板，核心是给它明确的任务边界和输出格式约束：

你是一位资深系统工程师，现在给你一份Java进程在故障时刻的pstack线程栈文件。 请按以下要求分析： 1. 先找出所有处于阻塞、等待状态的线程，列出它们的栈摘要； 2. 识别是否存在锁等待闭环（线程A等待的锁被线程B持有，B等待的锁被C持有，等等），如果有，明确点出循环关系； 3. 找出出现频率最高、疑似热点的方法调用，并说明它可能是由什么机制触发的； 4. 对可疑代码路径，引用栈帧中的具体类名和方法名，必要时去源码目录核对； 输出格式要求： - 先说结论，用三句话以内概括最可能的问题； - 然后逐线程分析，每个线程标出优先级（高/中/低）； - 最后给一份排查动作清单，按建议执行顺序排列； - 严禁推测源码里不存在的逻辑，所有判断必须有栈帧或代码依据。

这套模板的核心思路是：让它做“模式识别工程师”，而不是“小说家”。加上“必须有依据”这一条，能明显减少它编造无关调用的概率。另外，如果你给了它源码目录的访问权限，加上一句“必要时去源码目录核对调用关系”，它给出的分析会精准很多。

4. 实战复盘：一次pstack-claude排查死锁的全过程

4.1 现场症状与第一手采集

实际案例发生在订单服务上：每隔大约二十分钟，服务会出现一次十几秒的卡顿，请求大面积超时，过一会儿又自己恢复。CPU不算高，GC也正常，监控上唯一的异常是线程池活跃线程数瞬间拉满。

当时我的第一反应不是去看日志，而是等下一次卡顿时直接抓栈。卡顿出现时，我立刻执行：

pstack 24102 > /tmp/mall-order-stack.txt

同时记录下当前时间，并抓了一份业务日志里对应时间段的报错片段。等服务恢复之后，又补抓了一份空闲时的栈作为对照组。这两份文件加上日志片段，就是这次排查的全部原始材料。

采集这份栈的动作本身很轻，对线上影响可以忽略。我特意没有等上游反馈，也没有去重启服务，这个“忍住别重启”的决定很关键，因为一旦重启，现场就彻底没了。

4.2 给AI的“病历”与拿到的分析结果

在Claude Code里，我先把首份故障栈和空闲栈的对比信息喂进去，用的提示词就是3.4里那套模板，稍微加了点业务背景：这是一个订单服务，线程池固定大小，请求处理模型是标准的线程池+队列模型。

Claude Code返回的分析报告里，最醒目的是两条判断。第一，它识别出线程池里有三组线程分别在三个不同的lock地址上等待；第二，它顺着栈帧里的方法调用关系，发现了一个很典型的闭环：线程A在等待锁X，而锁X被线程B持有，线程B同时又在等待锁Y，锁Y又被线程C持有，而线程C正等待锁X释放。这正是教科书里循环等待的标准结构，几乎可以断言这就是死锁。

它还做了个额外动作：因为我在提示词里给了源码目录访问权，它去翻了几个相关类的源码，标注出锁X和锁Y分别在哪些方法里被获取，并提示这三个方法之间的调用顺序在不同线程里存在交叉。这个线索对后续人工复核帮助非常大，它把搜索范围从整个服务缩小到了两个方法。

4.3 人工复核：AI结论不能直接上生产

AI给出的结论再清晰，也必须在代码里落地验证。我随后人工去翻了这两个方法的源码，确认了问题本质：方法A按“先锁X再锁Y”的顺序获取锁，方法B却是“先锁Y再锁X”，两个方法在并发时形成了交叉等待，触发概率不高，但每循环一段时间就会撞上。

修复方案也直接：把两个方法的加锁顺序统一，或者在锁竞争点改用带超时的ReentrantLock，让线程拿不到锁时走补偿逻辑而不是无限等。这里我要多说一句，AI虽然把问题定位到了具体方法和锁顺序上，但最终的修复策略还是必须人来拍板，因为涉及业务语义：统一锁顺序会不会影响其他调用链？改成超时锁之后，补偿逻辑是否完备？这些都需要工程判断。

从这个案例可以看到pstack-claude工作流的正确姿势：AI负责把“问题在哪里”从几分钟缩短到几十秒，工程师负责把“怎么改”这个决策做对。两个环节缺一不可。

4.4 常见问题与排查技巧速查表

最后把这轮实践里碰到的高频问题整理成一张速查表，都是真实踩过的：

除了表格里的问题，再分享两个实用习惯。一是抓栈最好连续抓两次，间隔一两秒，两份对比能排除运气成分，能看出线程是不是真的停滞不动。二是给AI投喂时，如果把源码目录也交给它，记得在提示词里说明所有源码路径，避免它猜测代码结构。这些细节叠加起来，能把pstack-claude从“能用”提升到“好用”。

结尾

整套pstack-claude工作流跑下来，我最大的体会不是AI读栈读得多快，而是这套方案逼着我养成了“故障第一时间抓现场”的习惯。以前拿到问题第一反应是翻日志、看监控，栈是最后才看的东西；现在反过来，先抓栈再问AI，等AI圈定可疑范围之后，再去日志和监控里验证。这个顺序调整之后，定位问题的时间缩短了不是一点半点。

最后再分享一个小经验：线上排查不管AI给了多自信的结论，改动之前一定让同事过一遍review，你带上栈文件和分析报告去讲清楚来龙去脉。这个习惯帮我避过了好几个因为依赖模型结论而差点改错方向的坑。pstack负责记录现场，Claude Code负责缩小战场，真正拍板的永远是拿着工具站在故障面前的工程师本人。这套流程只负责把那儿的路照得更亮，脚还得你自己迈。