Spring Boot系列之使用Arthas Tunnel Server 进行远程调试实践

SmileNicky

发布于 2025-04-17 12:37:28

16900

代码可运行

文章被收录于专栏：Nicky's blogNicky's blog

运行总次数：0

代码可运行

Spring Boot系列之使用Arthas Tunnel Server 进行远程调试实践

前言

在开发和运维 Java 应用的过程中，远程诊断和调试是一个不可或缺的需求。尤其是当生产环境出现问题时，能够快速定位并解决这些问题至关重要。Arthas 是阿里巴巴开源的一款强大的 Java 诊断工具，它可以在不修改代码、不重启应用的情况下，实时诊断和分析 Java 应用的运行状态。而 Arthas Tunnel Server 则为远程连接提供了支持，使得我们可以通过 Web 管理页面远程连接到目标应用的 Arthas Agent，进行实时诊断。本文将详细介绍如何通过 Arthas Tunnel Server 实现 Spring Boot 应用的远程诊断，并提供详细的操作步骤和使用示例。

一、环境准备

1.1 工具与版本

JDK：1.8 或更高版本
Spring Boot：2.3.0 或更高版本
Arthas Tunnel Server：4.0.5 版本
操作系统：Linux 或 Windows（推荐使用 Linux）

1.2 下载 Arthas Tunnel Server

从 GitHub Releases 下载 arthas-tunnel-server-4.0.5-fatjar.jar，并将其放置在服务器的指定目录（如 /home/arthas）。

二、启动 Arthas Tunnel Server

2.1 配置启动参数

在启动 Arthas Tunnel Server 时，可以通过命令行参数配置服务的端口和管理页面的访问权限。以下是推荐的启动命令：

java -jar arthas-tunnel-server-4.0.5-fatjar.jar \
  --server.port=8080 \                # Web 管理页面的端口
  --arthas.server.port=7777 \         # 与 Arthas Agent 通信的端口
  --arthas.enable-detail-pages=true  # 启用管理页面

--server.port：Web 管理页面的端口，默认为 8080。
--arthas.server.port：与 Arthas Agent 通信的端口，默认为 7777。
--arthas.enable-detail-pages：是否启用管理页面，默认为 false。

如果要后台启动并保存一下运行日志：

nohup java -jar arthas-tunnel-server-4.0.5-fatjar.jar --arthas.enable-detail-pages=true --server.port=8080 --arthas.server.port=7777 > /opt/logs/arthas.log 2>&1 &

2.2 访问管理页面

启动后，访问 http://<服务器IP>:8080/，即可查看已连接的 Arthas Agent 列表。管理页面提供了以下功能：

Agent 列表：显示所有已连接的 Arthas Agent，包括 Agent ID、连接状态、连接时间等信息。
连接操作：可以对每个 Agent 进行连接、断开连接等操作。
实时监控：查看 Agent 的实时监控数据，如 CPU 使用率、线程状态等。

三、Spring Boot 应用集成 Arthas

3.1 添加 Arthas 依赖

在 Spring Boot 项目的 pom.xml 文件中添加 Arthas 的 Spring Boot Starter：

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

3.2 配置 Arthas

在 application.yml 文件中配置 Arthas 的隧道服务器地址：

arthas:
  telnetPort: -1
  httpPort: -1
  ip: 127.0.0.1
  appName: arthas_test
  agent-id: your_agent_id           # 唯一标识，用于区分不同的 Agent
  tunnel-server: ws://<tunnel-server-ip>:7777/ws  # Tunnel Server 的 WebSocket 地址

telnetPort：telnetPort为 -1 ，则不listen telnet端口，为 0 ，则随机telnet端口
httpPort：httpPort为 -1 ，则不listen telnet端口，为 0 ，则随机telnet端口
ip：127.0.0.1，本地访问，0.0.0.0，网络访问
appName：应用名称
agent-id：唯一标识，用于区分不同的 Agent，可以自定义。默认情况下，会生成随机ID，如果 arthas agent配置了 appName，则生成的agentId会带上appName的前缀。
tunnel-server：Tunnel Server 的 WebSocket 地址，格式为 ws://<tunnel-server-ip>:<tunnel-server-port>/ws。

3.3 启动 Spring Boot 应用

启动应用后，Arthas Agent 会自动连接到指定的 Tunnel Server。如果连接成功，你可以在 Tunnel Server 的管理页面中看到该 Agent 的信息。

四、远程诊断示例

4.1 登录管理页面

在浏览器中访问 http://<服务器IP>:8080/，查看已连接的 Arthas Agent。

如果要查看actuator，访问http://127.0.0.1:8080/actuator/arthas，账号名是arthas，密码需要在启动日志里找，返回：

{"clientConnections":{"VDYNUIRO0A7Q1QQCKZE7":{"host":"192.168.61.109","port":64113}},"version":"4.0.5","properties":{"server":{"host":"0.0.0.0","port":7777,"ssl":false,"path":"/ws","clientConnectHost":"192.168.62.78"},"embeddedRedis":null,"enableDetailPages":true,"enableIframeSupport":true},"agents":{"e9a2d4f3b8c7":{"host":"192.168.61.109","port":64020,"arthasVersion":"3.6.7"}}}

4.2 连接到目标 Agent

选择需要诊断的 Agent，点击“连接”按钮，即可进入 Arthas 的命令行界面。在命令行界面中，你可以执行各种 Arthas 命令来诊断应用。

4.3 执行诊断命令

以下是一些常用的 Arthas 命令示例：

4.3.1 查看线程状态

thread

该命令可以查看当前应用的所有线程状态，包括线程 ID、线程名称、线程状态（如 RUNNABLE、WAITING 等）、CPU 使用率等信息。通过该命令，你可以快速定位到占用 CPU 过高的线程，或者处于等待状态的线程。

4.3.2 查看方法执行情况

trace com.example.demo.controller.HelloController sayHello

该命令可以跟踪指定方法的执行情况，包括方法的调用次数、执行时间、参数值、返回值等信息。通过该命令，你可以分析方法的性能瓶颈，或者查看方法的调用链路。

4.3.3 查看类加载信息

sc com.example.demo.model.User

该命令可以查看指定类的加载信息，包括类加载器、类的路径、类的加载状态等信息。通过该命令，你可以排查类加载问题，或者查看类的加载路径。

五、常见问题与解决方法

5.1 无法连接到 Tunnel Server

原因：网络连接问题或防火墙限制。
解决方法：检查网络连通性，确保 Tunnel Server 的端口未被防火墙阻止。可以使用 telnet <tunnel-server-ip> <tunnel-server-port> 命令测试网络连通性。

5.2 管理页面无法访问

原因：未启用 --arthas.enable-detail-pages 参数或端口被占用。
解决方法：确保启动命令中包含 --arthas.enable-detail-pages=true，并检查端口是否被占用。可以使用 netstat -an | grep <port> 命令查看端口占用情况。