做过线上问题排查的同学应该都有体会，最痛苦的往往不是问题本身，而是定位问题的过程：先登服务器，再jps找进程，接着jstack、jmap一顿操作，碰到方法内部耗时异常还得改代码加日志重新发布。Arthas的出现基本终结了这种低效循环，它能attach到运行中的Java进程，直接查看方法出入参、统计执行耗时，甚至热更新字节码。而SpringBoot Admin作为服务监控面板，如果能把Arthas的Tunnel能力接进来，运维人员只需在浏览器里点几下，就能对注册到Admin的任意实例发起诊断，全程不用碰服务器。本文把整合的完整步骤和常见坑位整理出来，照着做基本一次成功。
一、整合前的整体架构思路
很多文章上来就直接贴依赖，结果读者配置完发现页面能打开但连不上目标应用，问题就出在没搞清楚角色分工。这套整合方案里其实有三个角色：SpringBoot Admin Server负责服务监控与页面展示，Arthas Tunnel Server负责中转所有的Arthas会话，而被监控的业务应用则作为Arthas Client注册到Tunnel。
为什么要引入Tunnel这一层？因为Arthas原生的Web Console只能连接本机或者网络可达的进程，在容器化、多实例部署的环境下，浏览器根本无法直连每个Pod里的Arthas端口。Tunnel Server相当于一个注册中心加消息中转站，所有客户端主动连上来注册，浏览器只需要访问Tunnel Server的ws地址，就能通过agentId定位到任意一个客户端会话。
理解了这个结构，后面的配置就顺理成章：Admin Server需要引入spring-boot-admin依赖并开启对Tunnel页面的代理，业务应用引入arthas-spring-boot-starter并配置tunnel地址。网络规划上要保证业务应用到Tunnel Server的端口（默认7777）是通的，浏览器到Admin Server的端口也是通的，这两个方向缺一不可。
二、Tunnel Server与Admin Server的搭建步骤
先搭Tunnel Server。新建一个普通的SpringBoot工程，JDK建议1.8以上，引入arthas-tunnel-server依赖。这里有个版本细节要特别注意：arthas官方提供的tunnel-server是一个可直接运行的fat jar，但如果你想把它嵌入到自己的SpringBoot工程里，需要使用arthas-tunnel-server的maven依赖方式，版本建议选3.6.x以后的稳定版。
<dependency>
<groupId>com.alibaba.arthas</groupId>
<artifactId>arthas-tunnel-server</artifactId>
<version>3.6.9</version>
</dependency>接着在配置文件里指定Tunnel对外提供websocket服务的端口，以及一个简单的内存存储实现。单机部署用内存方式就够了，如果Tunnel Server本身要做集群，可以换成Redis存储agent注册信息：
server:
port: 8080
arthas:
tunnel:
server:
port: 7777
# 单机模式使用内存存储已注册的agent信息
storage:
type: in-memory然后是Admin Server这一侧。SpringBoot Admin 2.0对应的是2.x的admin依赖，如果SpringBoot版本是2.6以后，还要额外处理路径匹配策略的问题，这个后面坑点部分会细说。Admin Server的搭建本身很常规，关键是把Tunnel的Web Console页面挂载进来。做法是在Admin Server里引入spring-boot-admin-server-ui相关依赖，并通过前端扩展机制把tunnel的页面作为插件注入。如果不想折腾前端插件，更省事的做法是直接把arthas-tunnel-server和spring-boot-admin-server合并在同一个工程里，共用一个端口，页面各自独立访问，集成成本最低。
@SpringBootApplication
@EnableAdminServer
public class AdminTunnelApplication {
public static void main(String[] args) {
SpringApplication.run(AdminTunnelApplication.class, args);
}
}三、业务应用接入Arthas客户端
业务应用这边的接入非常轻量，只需要引入arthas-spring-boot-starter。这个starter内置了SpringBoot的健康检查、配置绑定等能力，Arthas会随应用一起启动，省去了手动attach的步骤：
<dependency>
<groupId>com.taobao.arthas</groupId>
<artifactId>arthas-spring-boot-starter</artifactId>
<version>3.6.9</version>
</dependency>然后在application.yml里告诉客户端Tunnel Server在哪里，并指定本地的telnet和http端口：
arthas:
tunnel-server: ws://192.168.0.10:7777/ws
server:
port: 7778
ip: 192.168.0.20
app-name: order-service这里有几个配置项值得展开。ip这一项在多网卡或者容器环境里尤其重要，不配置的话Arthas会自动探测本机IP，容器里探测出来的往往是内网虚拟网卡地址，导致Tunnel回调失败，所以建议显式指定。app-name会显示在Tunnel的管理列表里，多实例场景下配合agentId可以区分不同实例。tunnel-server地址末尾的/ws路径不能少，少了会导致websocket握手失败。
启动业务应用后，访问Tunnel Server的页面（默认路径是/arthas-tunnel-server.html或者/apps.html，视版本而定），能看到注册上来的agent列表，复制对应的agentId，就可以在Web Console里输入这个id连接到目标进程了。连上之后常用的诊断命令比如dashboard看全局概况、trace com.demo.OrderService createOrder追踪方法调用链耗时、watch观察返回值，都可以直接在浏览器里执行。
四、高频问题汇总与排查
问题1：Tunnel页面能打开，但agent列表是空的。这是出现频率最高的问题。排查思路是先看业务应用的启动日志里有没有arthas tunnel connect相关的报错。常见原因有三个：一是tunnel-server地址写成了http开头，必须是ws协议；二是防火墙没放通7777端口；三是客户端和Tunnel Server版本差异过大，协议不兼容，建议两边使用同一个版本号。
问题2：agent注册成功，Web Console连接后立刻断开。这种情况多数是agentId复制不对，或者连接的瞬间目标应用重启了。另外一个隐蔽原因是Tunnel Server前挂了Nginx做反向代理，但没开启websocket的upgrade转发，需要在location配置里加上proxy_set_header Upgrade $http_upgrade和proxy_set_header Connection "upgrade"这两行。
问题3：SpringBoot 2.6+启动Admin Server直接报错。报错信息通常是PathPattern模式相关的。原因是SpringBoot 2.6把路径匹配策略默认从AntPathMatcher换成了PathPatternParser，而SpringBoot Admin 2.0早期的UI资源映射还依赖旧策略。解决办法是在配置里加一行spring.mvc.pathmatch.matching-strategy=ant-path-matcher，或者直接升级admin到2.6之后的版本。
问题4：生产环境安全顾虑。Arthas的权限非常大，能执行ognl表达式甚至反编译代码，绝对不能裸奔暴露在公网。建议的做法是给Tunnel Server加上认证，比如前面挡一层带basic auth的网关，同时在业务应用里通过arthas.username和arthas.password配置访问凭证，未授权的连接直接拒绝。另外可以把Arthas设置成按需开启，通过配置中心的开关动态决定是否连Tunnel，平时不注册，排查问题时再打开。
五、整合完成后的使用建议
整套环境跑起来之后，建议把几个高频诊断命令固化为团队的标准排查流程。遇到接口变慢先用trace定位耗时分布，遇到异常不知来源就用watch -e捕获异常堆栈，怀疑缓存命中率问题可以用ognl直接查询运行时对象状态。相比传统的加日志重新发布，这种在线诊断方式能把排查时间从小时级压缩到分钟级。
最后提醒一点，Arthas的watch、trace这类命令本身有性能开销，生产环境长时间挂着大范围匹配的监控任务会拖慢业务，排查完记得执行stop或者用shutdown关掉相关任务，养成良好的使用习惯，这套整合方案才能真正发挥价值。
SpringBoot AdminArthasJava诊断修改时间：2026-09-16 13:38:45