线上Java应用又崩了？试试JavaDoc，给你的JVM做一次"全身体检" 🩺
1. 凌晨三点，我又被报警吵醒了
手机在枕边疯狂震动，我的眼睛还没完全睁开，就已经知道发生了什么——线上的 Java 服务又挂了。
翻看监控，CPU 飙到 95%，内存曲线像坐过山车。登录服务器，top、jstat、jstack 一顿操作，屏幕上的数字密密麻麻，但我需要的不是数据，是诊断。
我相信很多 Java 开发者都经历过这种时刻：问题就在眼前，你却不知道该看什么。
更让人头疼的是，现在的应用大多跑在容器里。jmap 要调 PID，jstat 要配参数，cgroup 限制下的内存和宿主机看到的根本不是一回事。你手握一堆命令行工具，却像拿着一把没有刻度的尺子。
这时候，你需要的是一位"Java 医生"。
JavaDoc（谐音 javadoc，但此 Doc 非彼 Doc）—— Java Doctor · Java 医生，一个轻量级容器内 Java 进程诊断工具。
它的核心理念很简单：采集快照 → 规则初筛 → AI 会诊。就像你去医院体检，先抽血化验，再出指标报告，最后医生给你解读——JavaDoc 对 JVM 做的事，一模一样。
2. JavaDoc 的四大核心能力 🔬
很多人把 JavaDoc 理解成"另一个 jstack"，那就太小看它了。v1.0.0 在我眼里已经不是单一工具，而是一套**"采集 + 初筛 + AI 会诊 + 贴心设计"**的完整诊断体系。下面我把它拆成四个能力展开讲。
🩺 能力一：全维体检 —— 看得全，才看得准
JavaDoc 不像传统工具那样让你一个个敲命令。它通过 Attach/JMX + cgroup + /proc 三通道并行采集，一次收集所有关键指标：
| 维度 | 采集内容 | 数据来源 |
|---|---|---|
| JVM 内存 | Heap / OldGen / Eden / Non-Heap / Metaspace / CodeCache | JMX |
| 进程系统指标 | CPU 使用率 / 物理内存 / RSS / Swap / OOM Score | /proc + cgroup |
| GC 与线程 | YGC / FGC 频次与耗时 / 死锁检测 | JMX |
容器化环境下，cgroup 限制的内存和 /proc 看到的宿主机内存往往不一致——比如容器限制 512MB，/proc 却显示宿主机有 64GB 可用，差距能有两个数量级。JavaDoc 会同时采集两组数据并对比展示，让你一眼看出容器限制是否被触及。
举个例子：在一次容器 OOM 复盘中，宿主机
/proc/meminfo显示还剩 30GB，但 cgroup 已经写满，JavaDoc 报告直接标红[↑异常]，定位速度比手动比对快十倍。
报告的"基本信息"区会直接列出 JDK 版本、目标 PID、cgroup 版本、启动命令等关键上下文；"体检指标详情"区则是带状态标识的指标表格——下面是真实报告截图：
可以看到每一项指标都有"标准参考值"和"状态标识"（[正常] / [参考] / [↑异常] / [无数据]），完全是一份能直接发给同事的体检报告格式——这是 JavaDoc 给我最直观的冲击。
🧠 能力二：智能初筛 —— 20+ 规则，四级状态
数据采集完成后，JavaDoc 内置的 20+ 阈值规则会对每一项指标逐一检查。输出不是冷冰冰的原始数值，而是带判断的四级状态：
| 状态标识 | 含义 | 应对动作 |
|---|---|---|
[正常] | 绿灯，指标在安全范围 | 无需处理，继续观察 |
[参考] | 黄灯，处于临界区或需结合上下文 | 持续关注趋势 |
[↑异常] | 红灯，已超出推荐阈值 | 需要立即介入 |
[无数据] | 灰灯，采集失败或该项不适用 | 检查采集通道 |
比如 OldGen 使用率超过 85%，你会直接看到 [↑异常] 标记；Cgroup OOM Kill 次数 > 0 则是 [↑异常]，直接提醒你"这台机器上已经发生过 OOM 了"——不需要自己背阈值表，工具替你做初筛。
🤖 能力三：AI 智能会诊（差异化核心）⭐
这一节是我压轴要讲的。如果说前两个能力是"体检报告"，那 AI 会诊就是医生本人。 它是 JavaDoc 区别于所有传统诊断工具（Arthas、async-profiler、jcmd 套件等）的最大不同。
1）为什么需要 AI 会诊？
传统工具的局限在于：它们告诉你"症状"，但不告诉你"为什么"和"怎么办"。
jstat输出 FGC 频次——但这是问题还是正常？/proc显示 OOM Score=684——这算高吗？高多少算危险？- Heap Dump 几十 GB——里面哪个对象在涨？
JavaDoc 的 AI 会诊做的就是：把上面这些"半成品信息"翻译成可执行的处置建议。它会结合所有指标（JVM 内存 + 容器 cgroup + 系统负载 + 启动参数），由大模型输出一段像资深 SRE 写出来的诊断文字。
2）三家大模型横评
JavaDoc v1.0.0 内置支持 OpenAI / DeepSeek / Ollama 三种大模型，可按场景自由切换：
| 模型 | 推理能力 | 成本 | 隐私性 | 中文理解 | 推荐场景 |
|---|---|---|---|---|---|
| OpenAI（GPT-4o / o1） | ⭐⭐⭐⭐⭐ | 高（美元计费） | ❌ 数据出网 | ⭐⭐⭐ | 复杂内存泄漏、生产事故复盘 |
| DeepSeek | ⭐⭐⭐⭐ | 极低（国内价） | ❌ 数据出网 | ⭐⭐⭐⭐⭐ | 中文语境团队、性价比首选 |
| Ollama（llama3 / qwen2） | ⭐⭐⭐ | 0（本地推理） | ✅ 数据不出内网 | ⭐⭐⭐⭐ | 金融/政企内网、隐私敏感场景 |
我的个人推荐：生产环境日常巡检用 DeepSeek，复杂根因分析用 OpenAI，金融/医疗内网用 Ollama。
3）三段式处方（杀手锏）
JavaDoc 的 AI 输出不是"一段含糊的建议"，而是严格三段式结构——这是它最让我心动的设计：
📋 异常现象：精准定位当下问题
🔍 根因推断：分析可能的成因链
💊 处置建议：给出可执行的命令/参数
下面是一段真实报告里的"AI 调优处方建议"（已脱敏）：
1. 异常现象
- 进程 OOM 评分 684，超过参考阈值 500，但容器内存使用率仅 8%，无 OOM 事件
- JVM 启动参数未显式设置堆大小（-Xms/-Xmx），当前堆最大 838 MiB，但容器内存上限 3350.7 MiB，存在资源浪费
- 非堆内存（55.1 MiB）高于堆内存（34.1 MiB），Metaspace 使用 37.1 MiB，加载类数 8663，可能因未设置 Metaspace 上限
2. 根因推断
- OOM 评分异常：系统默认 OOM 评分调整值（
/proc/1/oom_score_adj=0）导致评分偏高，但实际内存压力较低，无风险- 堆大小未显式配置：JVM 自动根据容器内存上限计算堆最大为 838 MiB，但未设置初始堆，可能导致启动时 GC 频繁或性能波动
- 非堆内存偏高：Metaspace 未设上限（max=N/A），当前使用 37.1 MiB，若类加载持续增加可能触发 Full GC
3. 处置建议
- 调整 JVM 启动参数，显式设置堆大小：
java -Xms512m -Xmx512m -jar /opt/oom-lab/app.jar（根据业务负载调整，建议初始堆与最大堆一致以减少 GC 压力）- 设置 Metaspace 上限，避免类加载失控：
java -XX:MaxMetaspaceSize=256m -jar /opt/oom-lab/app.jar- 合理调整 OOM 评分（仅在关键服务场景）：
echo -500 > /proc/1/oom_score_adj（降低被 OOM Killer 选中的概率）
这份"处方"直接附在 HTML 报告末尾，可以复制命令直接执行，等于把一个资深 SRE 装进了你的工具链。下面是真实报告截图：
4）优雅降级（工程良心）
AI 接入必然要考虑网络不可用的情况。JavaDoc 的设计很克制：
- ✅ LLM API Key 缺失 → 跳过 AI 步骤，本地规则初筛报告照常输出
- ✅ DNS 解析失败 / 连接超时 → 报告里写明失败原因，本地诊断完整
- ✅ HTTP 401（Key 错误）/ 429（限流）/ 5xx（服务端异常）→ 分类提示，原始响应体可查看
- ✅ 网络完全中断 → 离线报告照常生成，AI 字段标注
[未启用]
网络挂掉，JavaDoc 依然能出完整本地报告，绝不让你在排障时掉链子——这是工程上的克制，也是对运维场景的尊重。
📦 能力四：贴心设计 —— 部署、安全、报告
除了"看得准"和"看得懂"，JavaDoc 还有几个让我心动的细节：
① 极简部署：单个 Fat-JAR 仅约 400KB，唯一运行时依赖是 Gson 2.11.0，java -jar 直接运行。不需要 Agent，不需要修改启动参数，不需要重启目标进程。
② 安全脱敏：进程启动命令和失败详情中，password、secret、token、API Key 等敏感字段自动替换为 ***，诊断报告放心分享。
③ 三种报告格式：控制台即时查看、Markdown 存档追踪、单文件 HTML 诊断书直接分享给同事。
④ JDK 全兼容：JDK 8 / 11 / 17 / 21 全部支持，不为不同版本准备不同工具。
一句话总结：采集全维 → 初筛分级 → AI 给处方 → 降级不中断。这不是 jstack 的替代品，是 JVM 诊断的"完整工作流"。
3. 30 秒上手 + 6 个真实排障场景 💊
工具再好，上手成本高也是白搭。JavaDoc 的设计原则就是**"比装一个 IDEA 插件还简单"**——下面我带你 30 秒跑通，再用 6 个真实场景演示它的"实战能力"。
Step 1：下载（30 秒）
# 从 Gitee 克隆
git clone git@gitee.com:zhaowd5/JavaDoc.git
cd JavaDoc
mvn package -DskipTests
# 输出：target/JavaDoc-1.0.0.jar（约 400KB）
嫌克隆慢？直接去 Gitee Release 下载预编译的 JAR 也行。
Step 2：第一次诊断（一行命令）
# 基础诊断 —— 对 PID=1 的 Java 进程做全身体检
java -jar JavaDoc-1.0.0.jar --pid 1
这就是最简形式。不需要配置文件，不需要环境变量，一个 JAR 一个 PID——直接在容器里 kubectl exec 进去都能跑。
Step 3：看报告（控制台 / Markdown / HTML）
控制台会直接输出诊断结果，但你也可以生成可分享的报告文件：
# 输出 HTML 诊断书到指定目录（最推荐）
java -jar JavaDoc-1.0.0.jar --pid 1 \
--output-format html \
--output-dir /opt/reports
生成的 HTML 是单文件、可直接邮件发送、可归档追踪的诊断书——这份报告同时包含本地规则初筛 + AI 智能会诊结论。
6 个真实排障场景（命令速查表）
光跑通基础调用还不够，真实排障时你需要的是"场景化命令"。下面是我整理的 6 个高频场景速查：
| 场景 | 命令 | 适用情况 |
|---|---|---|
| 🩺 场景 1：CPU 飙升排查 | java -jar JavaDoc-1.0.0.jar --pid 1 | 看 CPU 使用率、线程状态、GC 频次 |
| 💧 场景 2：内存泄漏定位 | java -jar JavaDoc-1.0.0.jar --pid 1 --llm deepseek | AI 分析 OldGen/Metaspace 趋势，输出根因推断 |
| 📦 场景 3：容器 OOM 分析 | java -jar JavaDoc-1.0.0.jar --pid 1 | cgroup 内存限制 vs 实际 RSS 对比，OOM Score 评估 |
| 📅 场景 4：日常健康巡检 | java -jar JavaDoc-1.0.0.jar --pid 1 --output-format md | 输出 Markdown 报告存档，形成诊断历史 |
| 🤖 场景 5：AI 智能会诊 | java -jar JavaDoc-1.0.0.jar --pid 1 --llm openai | 复杂内存泄漏分析，三段式处方 |
| 🔒 场景 6：本地模型私有化 | java -jar JavaDoc-1.0.0.jar --pid 1 --llm ollama | 数据不出内网，金融/政企内网首选 |
场景 2 的 AI 结论和处方就是上面截图 2 里展示的样子——一份真实的报告胜过千行文字。
几个贴心的小参数
- 环境变量注入 API Key：
export OPENAI_API_KEY=sk-xxx即可，命令行历史不残留 Key，安全合规。 - 多 PID 批量诊断：未来路线图里有"多实例批量诊断"，v1.0 暂时只支持单 PID。
- 报告归档建议：生产环境建议用 cron 每天定时跑一次，输出 Markdown 报告按日期归档，形成"诊断历史"。
JDK 8、11、17、21 全兼容，不为不同版本准备不同工具。
4. v1.0 只是一个起点 🚀
v1.0.0 是 2026 年 7 月 14 日首发。它已经做到的：
- ✅ 三大通道全维采集（Attach/JMX + cgroup +
/proc） - ✅ 20+ 内置规则 + 四级状态标识
- ✅ OpenAI / DeepSeek / Ollama 三模型支持
- ✅ 控制台 + Markdown + HTML 三种报告格式
- ✅ 敏感信息自动脱敏 + 大模型优雅降级
- ✅ 单 JAR 约 400KB，JDK 8~21 全兼容
但我对 JavaDoc 的想象远不止于此。以下是未来可能的方向：
🕐 持续诊断（定时体检）：不是一次性的快照，而是按 cron 表达式定期采集，形成趋势曲线。内存泄漏不再靠"感觉"，而是靠曲线说话。
📊 多实例批量诊断：一个 K8s 集群跑着几十个 Java Pod，逐个诊断效率太低。批量采集 + 汇总报告，一键看清全集群 JVM 健康度。
🔌 更多 LLM 提供商：国内的通义千问、文心一言，国外的 Claude、Gemini——不同团队有不同偏好，JavaDoc 应该都支持。
📈 诊断历史趋势分析：把每次诊断的 Markdown 报告结构化存储，纵向对比 GC 频率变化、内存增长速率，从单次"体检"升级为长期"健康管理"。
🐳 容器化一键部署：提供 Dockerfile 和 Helm Chart，kubectl exec 进 Pod 直接跑诊断，或作为 Sidecar 定期巡检。
这些方向不是凭空想象的 roadmap，而是我在真实场景中遇到的痛点。JavaDoc 的功能走向，将由社区的真实反馈驱动。
5. 试试看，然后告诉我你的想法 📋
写这篇文章，不是为了推销一个"完美方案"——JavaDoc 远不完美。v1.0 还有很多粗糙的地方，AI 会诊的准确率也取决于模型的推理能力和 prompt 质量。
但我相信方向是对的：让诊断变简单，让排障有章法。
如果你也曾在凌晨三点对着 jstat 的输出发呆，如果你也曾在容器里被 cgroup 限制搞得晕头转向，不妨试试 JavaDoc。
三件事，你可以任选一件来做：
⭐ Star 支持：git@gitee.com:zhaowd5/JavaDoc.git —— 一个 Star 就是一份"这个方向值得做下去"的信号。
🐛 提交 Issue：你在使用时遇到的任何问题——哪怕是报错信息不清晰、文档写得不明白——都值得提出来。Bug 报告、功能需求、使用体验、文档建议，统统欢迎。
🔧 贡献 PR：代码、文档、测试用例，任何形式的贡献都感激不尽。项目用 Maven 管理，结构清晰，很容易上手。
JavaDoc = Java Doctor。给你的 Java 进程约一次体检吧。
首发于 2026 年 7 月 · 稀土掘金
