Arthas：超详细部署与使用教程

Arthas 是阿里巴巴开源的 Java 在线诊断工具（Diagnostic Tool），可以在不修改业务代码、不重启 JVM 的前提下，对线上运行的 Java 应用进行实时诊断：查看方法调用参数/返回值/异常、定位慢调用、反编译类、查看类加载来源、监控 QPS/RT、生成火焰图等，是 Java 线上问题排查的事实标准工具。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

在生产环境中，开发人员通常面临几个棘手问题：

• 生产网络与本地开发环境隔离，无法用 IDE 远程调试；
• 生产环境开启调试会挂起所有线程，直接导致业务停摆，不可接受；
• 问题难以在测试环境复现，甚至重启后就消失；
• 想加日志定位问题，需要走「测试 → 预发 → 生产」全流程发布，耗时且低效。

Arthas 就是为解决这些问题而生的。它以「观察者」的身份 attach 到目标 JVM 上，不挂起任何业务线程，开发者可以实时排查生产问题：无需重启、无需改代码、无需重新发布。Arthas 脱胎于阿里巴巴内部的 Java 诊断实践，代码基础源于 Greys，已被阿里、支付宝、阿里云、淘宝、工行、顺丰、贝壳、科大讯飞等数百家企业注册使用。

1.2 核心功能

• 类加载排查：查看某个类是否已被加载、从哪个 Jar 包加载，排查 Jar 包冲突、类版本错乱。
• 反编译（jad）：在线反编译已加载的类，确认线上运行的代码是否与预期一致。
• 类加载器统计（classloader）：查看类加载器数量、每个加载器加载的类数、类加载器层级，排查类泄漏。
• 方法调用观测（watch）：查看方法的入参、返回值、抛出的异常。
• 调用栈追踪（stack）：查看指定方法在被调用时的完整调用链，定位「谁调用了这个方法」。
• 慢调用定位（trace）：追踪方法内部每条子调用的耗时，找出最慢的子调用。
• 调用统计（monitor）：按周期统计方法的 QPS、平均响应时间、成功率。
• 时间隧道（tt）：记录方法每次调用的现场，事后可回放、重放历史调用。
• 系统指标监控（dashboard/jvm/thread）：实时面板查看线程状态、CPU、内存、GC、运行时参数。
• 性能剖析（profiler）：内置 async-profiler，一键生成 CPU 火焰图。
• 堆内对象查询（vmtool）：获取堆中指定类的实例对象。
• 交互与远程诊断：命令行交互模式带自动补全；支持 telnet 与 WebSocket（Web Console），可本地/远程/浏览器诊断。
• 多 JDK 支持：4.x 版本支持 JDK 8 及以上，包括 JDK 17、JDK 21、JDK 25。
• 跨平台：支持 Linux / macOS / Windows。

1.3 技术架构

Arthas 的工作原理是：arthas-boot 作为引导程序启动后，列出本机所有 Java 进程，用户选择目标进程（或通过 --select 指定进程），Arthas 以 Java Agent 方式 attach 到目标 JVM，通过 Instrumentation 机制对目标类的字节码进行增强（在方法织入观测逻辑），同时在本机开启 telnet 端口（默认 3658）与 HTTP 端口（默认 8563）供命令行与 Web Console 交互。诊断逻辑对业务线程完全透明，默认不改变方法执行结果。

下图是 Arthas 官方文档中的 Dashboard 实时面板（Thread 线程表、Memory 内存、GC 统计、Runtime 运行时信息）：

二、环境要求

注意：Arthas 诊断的是运行中的 JVM 进程，因此部署机上必须已有一个 Java 应用在运行；Arthas 本身不需要独立数据库、不需要注册中心。

三、部署方式

下面给出五种部署方式：arthas-boot 一行命令（推荐）→ as.sh 安装脚本 → 完整 Release 包离线部署 → Spring Boot Starter 嵌入式集成 → Docker 容器内诊断。

3.1 方式一：arthas-boot 一键启动（官方推荐）

这是最快的上手方式：下载引导 jar，直接用 java -jar 启动，它会自动检测本机 Java 进程并引导你 attach。

# 1. 下载 arthas-boot.jar（官方 CDN）
curl -O https://arthas.aliyun.com/arthas-boot.jar

# 2. 启动，它会列出本机所有 Java 进程让你选择
java -jar arthas-boot.jar

# 打印帮助
java -jar arthas-boot.jar -h

启动后会出现类似如下的进程列表，输入编号回车即可 attach：

[1]: 12345 com.alibaba.demo.Application
[2]: 23456 org.apache.rocketmq.namesrv.NamesrvStartup

attach 成功后会出现 $ 命令提示符，即可输入诊断命令。

常用启动参数：

# 直接指定目标进程 ID（非交互）
java -jar arthas-boot.jar --target-pid 12345

# 指定目标进程名（模糊匹配 main class）
java -jar arthas-boot.jar --select demo

# 指定连接的 IP 与端口（多人协作时）
java -jar arthas-boot.jar --target-ip 192.168.1.10 --telnet-port 3658 --http-port 8563

# 首次离线模式（不下载增强库，使用本地已缓存）
java -jar arthas-boot.jar --use-version 4.3.5

3.2 方式二：as.sh 安装脚本

在 Linux / Unix / macOS 上，一条命令安装 Arthas 引导脚本：

curl -L https://arthas.aliyun.com/install.sh | sh

该命令会把引导脚本 as.sh 下载到当前目录，之后：

# 进入交互界面（同样会列出 Java 进程）
./as.sh

# 帮助
./as.sh -h

# 直接 attach 指定进程
./as.sh 12345

可以把 as.sh 移动到 /usr/local/bin 并加入 $PATH，全局可用。Windows 环境请使用方式一的 arthas-boot.jar。

3.3 方式三：完整 Release 包离线部署（生产内网推荐）

在能联网的机器下载完整发布包，传到内网服务器解压使用。Release 页：github.com/alibaba/arthas/releases，文件名形如 arthas-bin.zip（版本对应 arthas-all-4.3.5，以实际 release 为准）。

# 联网机器下载（以 4.3.5 为例）
wget https://github.com/alibaba/arthas/releases/download/arthas-all-4.3.5/arthas-bin.zip

# 传到目标服务器后解压
unzip arthas-bin.zip -d /opt/arthas
cd /opt/arthas

# 启动
java -jar arthas-boot.jar

解压目录结构（官方）：

arthas/
├── arthas-boot.jar      # 引导程序
├── arthas-core.jar       # 核心包
├── arthas-agent.jar     # Agent
├── arthas-spy.jar       # Spy 织入
├── install-local.sh      # 本地安装脚本
├── as.sh                 # Linux/macOS 启动脚本
├── as.bat                # Windows 启动脚本
├── async-profiler/       # profiler 火焰图依赖
└── logs/                 # Arthas 自身日志

3.4 方式四：Spring Boot Starter 嵌入式集成

如果希望 Arthas 随 Spring Boot 应用一起启动（无需手动 attach），可引入官方 starter（以官方文档 spring-boot-starter 页为准）：

<dependency>
    <groupId>com.taobao.arthas</groupId>
    <artifactId>arthas-spring-boot-starter</artifactId>
    <version>4.3.5</version>
</dependency>

Web 环境如需关闭，可引入：

<dependency>
    <groupId>com.taobao.arthas</groupId>
    <artifactId>arthas-spring-boot-starter</artifactId>
    <version>4.3.5</version>
    <exclusions>
        <exclusion>
            <groupId>com.taobao.arthas</groupId>
            <artifactId>arthas-web</artifactId>
        </exclusion>
    </exclusions>
</dependency>

随后通过 application.yml 配置（端口、隧道、鉴权等，具体项以官方文档 spring-boot-starter 章节为准）：

arthas:
  telnet-port: 3658
  http-port: 8563
  ip: 127.0.0.1

这种方式适合把诊断能力内置到业务镜像中，生产环境建议配合鉴权与网络白名单使用。

3.5 方式五：Docker 容器内诊断

应用跑在容器里时，可以把 arthas-boot.jar 拷进容器，或直接在容器内执行：

# 进入容器（容器内需有 JDK/JRE 与 curl）
docker exec -it <container-id> /bin/bash

# 容器内下载并 attach
curl -O https://arthas.aliyun.com/arthas-boot.jar
java -jar arthas-boot.jar

官方文档另有 Docker 镜像使用说明（arthas.aliyun.com/doc/docker），支持把 Arthas 作为 sidecar 或在容器构建时预装。

3.6 验证部署成功

1. 执行 java -jar arthas-boot.jar 后，看到本机 Java 进程列表并成功 attach，提示符变为 $；
2. 输入 dashboard 回车，能实时看到 Thread / Memory / GC / Runtime 面板（见 1.3 节截图）；
3. 输入 version，打印 Arthas 版本号（如 4.3.5）；
4. 浏览器访问 http://127.0.0.1:8563（HTTP 端口默认 8563），能打开 Web Console 并执行命令；
5. telnet 连接验证：

telnet 127.0.0.1 3658
# 连接成功后输入 version 回车

四、使用方法

4.1 基础用法

attach 成功后进入交互式命令行，支持 Tab 自动补全。常用退出方式：

# 断开当前会话（目标进程继续运行，不影响业务）
quit

# 完全退出 Arthas（卸载字节码增强，恢复现场）
stop

4.2 常用命令（带示例）

dashboard —— 实时总览面板

dashboard

每隔 5 秒刷新一次线程、内存、GC、运行时信息，按 q 退出。

thread —— 查看线程

# 列出所有线程
thread

# 找出 CPU 占用最高的 3 个线程并打印栈
thread -n 3

# 查看指定状态的线程（如 BLOCKED）
thread -b

# 查看指定线程 ID 的栈
thread 12

官方示例（找出最耗 CPU 的线程）：

$ thread -n 3
"as-command-execute-daemon" Id=29 cpuUsage=75% RUNNABLE
    at sun.management.ThreadImpl.dumpThreads0(Native Method)
    ...

jad —— 反编译类

# 反编译接口/类，确认线上实际运行代码
jad javax.servlet.Servlet

# 只反编译某个方法
import com.alibaba.demo.service.UserService;
jad com.alibaba.demo.service.UserService getById

sc / sm —— 查找已加载的类/方法

# 搜索已加载的类，并显示类从哪个 jar 加载
sc -d org.springframework.web.context.support.XmlWebApplicationContext

# 列出类的所有方法
sm -d com.alibaba.demo.service.UserService

watch —— 观测方法入参/返回值/异常

# 查看方法的第一个参数、返回值、抛出异常
watch com.alibaba.demo.service.UserService getById "{params, returnObj, throwExp}"

# 只在抛异常时观测
watch com.alibaba.demo.service.UserService getById "{params[0], throwExp}" -e

# 带条件：入参 id > 100 才观测
watch com.alibaba.demo.service.UserService getById "{params, returnObj}" "params[0] > 100"

trace —— 定位慢子调用

# 追踪方法内部每条子调用耗时
trace com.alibaba.demo.service.UserService getById

# 只看耗时超过 100ms 的调用
trace com.alibaba.demo.controller.UserController list '#cost > 100'

下图是官方 trace 命令输出示例（每条子调用的耗时一目了然）：

stack —— 查看调用栈

# 谁在调用这个方法？打印完整调用链
stack com.alibaba.demo.service.UserService getById

monitor —— 周期统计

# 每 5 秒统计一次方法的 total/success/fail/avg-rt/fail-rate
monitor -c 5 com.alibaba.demo.service.UserService getById

tt —— 时间隧道（记录并回放）

# 记录每次调用现场
tt -t com.alibaba.demo.service.UserService getById

# 查看记录列表
tt -l

# 回放某次历史调用（INDEX 从列表里取）
tt -i 1000 -p

profiler —— 生成火焰图

profiler start          # 开始 CPU 采样
profiler stop           # 停止，输出 html 火焰图到 arthas-output 目录
# 输出示例：/tmp/demo/arthas-output/20211207-111550.html

用浏览器打开生成的 .html 即可看到火焰图。

其他常用命令

jvm            # 查看 JVM 信息（堆、线程、类加载、编译参数）
sysprop        # 查看/修改系统属性
sysenv         # 查看环境变量
vmtool         # 获取堆中对象实例：vmtool --action getInstances --className com.xxx.User --limit 10
classloader    # 类加载器统计
help           # 查看所有命令
session        # 查看当前会话

4.3 进阶功能

• Web Console：浏览器打开 http://127.0.0.1:8563，在网页里执行同样的命令，适合远程/无 SSH 环境。
• ** Tunnel 服务（arthas-tunnel-server）**：把多个机器上的 Arthas 会话汇聚到一个中心服务器，集中管理大规模机器的诊断（部署方式见官方文档 tunnel 章节）。
• 热更新（mc + retransform）：mc 在内存中把 .java 编译成 .class，再用 retransform 加载到运行中的 JVM，实现临时热修复：

mc /tmp/Test.java
retransform /tmp/Test.class

• ognl 执行表达式：通过 ognl 动态查看 Spring 上下文里的 Bean、调用静态方法等。
• 条件表达式与耗时过滤：watch/trace/stack 都支持 #cost、条件表达式，精准过滤噪声。

4.4 适用场景

• 线上接口慢、偶发超时，需要快速定位是哪条子调用慢；
• 线上报异常，需要看实时的入参和异常对象；
• Jar 包冲突、类版本错乱，需要确认类到底从哪个 jar 加载；
• 怀疑方法没被调用/被谁调用，需要看调用链；
• CPU 突然飙高，需要定位热点线程/生成火焰图；
• 不想重启服务临时验证一段修复代码（mc + retransform）；
• 无 SSH/无日志的容器环境，用 Web Console 远程诊断。

五、常见问题排查（FAQ）

Q1：执行 java -jar arthas-boot.jar 后看不到我的 Java 进程 - 原因：arthas-boot 与目标进程用户不一致；或目标进程是容器内进程；或 JDK 版本过低。 - 解决：用与目标进程相同的用户执行（root 可看到所有进程）；确认目标 java -version 为 8+；容器内需 docker exec 进入后再执行。

Q2：attach 时报 Can not find arthas version 或下载失败 - 原因：首次启动需从网络下载对应版本的 arthas 增强库，内网不通。 - 解决：使用方式三的完整离线包；或用 --use-version 4.3.5 指定本地已缓存版本；提前配置代理。

Q3：watch/trace 后提示 Affect(class-cnt:0, method-cnt:0) - 原因：类名/方法名写错，或目标类尚未被类加载器加载（懒加载）。 - 解决：先用 sc -d 全限定类名 确认类已加载、类加载器 Hash 正确；方法名写全；必要时用 --classloader 指定 classloader hash。

Q4：诊断过程中目标应用变慢或卡住 - 原因：对超大方法/高频方法织入过多观测，或 monitor 周期太短。 - 解决：缩小观测范围（精确到方法）；用完及时 stop 退出；避免对 QPS 极高的方法长期 watch。

Q5：Web Console（8563）打不开 - 原因：端口被占用、防火墙未放行、或启动时用 --http-port -1 关闭了 HTTP 端口。 - 解决：java -jar arthas-boot.jar --http-port 8563 指定；检查 ss -lntp | grep 8563；云服务器需放行安全组（生产建议只监听 127.0.0.1）。

Q6：quit 后再进入，之前 watch 的命令没了 - 原因：quit 只是断开会话，会话结束后增强默认恢复；stop 才是彻底卸载。 - 解决：需要保持观测时不要 stop；可在新会话中重新发起命令。

Q7：JDK 17+ 下 attach 报模块访问错误 - 原因：高版本 JDK 强模块封装。 - 解决：使用 Arthas 4.x（官方明确支持 JDK 17/21/25），旧版 3.x 在新 JDK 上会失败。

Q8：多个同事同时连同一台机器互相干扰 - 原因：默认 telnet 端口共享。 - 解决：不同人用不同端口启动，或使用官方 tunnel-server 统一管理会话。

六、部署注意事项与最佳实践

1. 生产环境用完即退：诊断结束及时 stop，避免长期保留字节码增强带来的额外开销。
2. 不要在公网暴露 3658/8563：Arthas 端口可执行任意命令，务必绑定内网/本机，或通过 tunnel-server + 鉴权访问。
3. 最小权限观测：先 sc 确认类加载，再精确到方法级 watch/trace，避免对全类或高频大方法织入。
4. 版本对齐：被诊断的 JDK 越高，越要用 Arthas 4.x；高版本 JDK 别用旧版 3.x。
5. 离线环境预置：生产内网提前下载完整 arthas-bin.zip 并纳入运维工具库，不要依赖在线下载。
6. 容器诊断：优先把 arthas-boot.jar 打进镜像，或用官方 docker 方案，避免容器里没有 curl。
7. 火焰图采样控制时长：profiler 采样 30~120 秒即可，过长会产生巨大采样数据。
8. 热修复要谨慎：retransform 热更新不保证所有类都能成功（如已被 JIT 内联的方法），临时修复后仍要走正常发布流程。

七、参考资料

• GitHub 仓库：https://github.com/alibaba/arthas
• 官方文档（中文）：https://arthas.aliyun.com/doc/
• 快速开始：https://arthas.aliyun.com/doc/quick-start
• 安装说明：https://arthas.aliyun.com/doc/install-detail.html
• 命令列表：https://arthas.aliyun.com/doc/commands.html
• Web Console：https://arthas.aliyun.com/doc/web-console.html
• Docker：https://arthas.aliyun.com/doc/docker.html
• Spring Boot Starter：https://arthas.aliyun.com/doc/spring-boot-starter.html
• Profiler/火焰图：https://arthas.aliyun.com/doc/profiler
• FAQ：https://arthas.aliyun.com/doc/faq
• Release 下载：https://github.com/alibaba/arthas/releases
• 一键引导下载：https://arthas.aliyun.com/arthas-boot.jar