在线诊断 Arthas Tunnel Server SpringBoot Agent 前言在生产环境中Java应用常部署在内网或多集群环境无法直接远程诊断。Arthas Tunnel 作为官方远程诊断代理方案可完美解决此问题。一、环境准备生产必看服务器LinuxCentOS/Ubuntu 均可推荐 CentOS 7开放端口8080Web控制台、7777Agent注册WebSocket协议JDK1.8与业务应用JDK版本一致避免兼容性问题SpringBoot2.x/3.x 均可本文适配所有版本无额外依赖权限部署时使用非root用户生产规范关键目录日志、Jar包赋予读写权限二、Arthas Tunnel Server 生产配置服务端核心服务端负责接收 Agent 注册、提供 Web 控制台以下配置包含安全认证、日志、健康检查可直接复制部署。2.1 目录结构规范部署先创建统一目录便于管理避免文件混乱# 创建 Arthas Tunnel 部署目录mkdir-p/opt/arthas/tunnel# 创建日志目录mkdir-p/opt/arthas/tunnel/logs# 切换目录cd/opt/arthas/tunnel# 下载 Arthas Tunnel Server Jar 包4.1.8 最新版wgethttps://maven.aliyun.com/repository/public/com/taobao/arthas/arthas-tunnel-server/4.1.8/arthas-tunnel-server-4.1.8-fatjar.jar# 重命名简化后续操作mvarthas-tunnel-server-4.1.8-fatjar.jar arthas-tunnel-server.jar2.2 核心配置文件application-prod.yml创建生产环境配置文件重点配置安全密码、端口、日志避免使用默认配置存在安全风险server:port:8080# Web控制台端口可自定义如8088需开放安全组servlet:context-path:/arthas# 可选添加上下文路径增强安全性arthas:tunnel:server:port:7777# Agent 注册端口WebSocket协议不可随意修改enable-detail-pages:true# 开启 Agent 列表页面便于查看在线Agent生产可开启方便管理allow-agent-ips:192.168.0.0/16,10.0.0.0/8# 限制Agent注册IP段生产必配防止非法注册# 安全配置生产核心必须修改spring:security:user:name:arthas# 登录Web控制台的用户名password:Arthas2026!# 强密码生产务必修改格式字母数字特殊符号generate-password:false# 关闭自动生成密码使用自定义密码# 日志配置生产规范便于排查问题logging:level:root:INFOcom.alibaba.arthas:INFO# Arthas 核心日志级别避免日志冗余file:name:/opt/arthas/tunnel/logs/arthas-tunnel-server.log# 日志路径与前面创建的目录一致pattern:file:%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n# 日志格式logback:rollingpolicy:max-file-size:100MB# 单个日志文件最大100MBmax-history:30# 日志保留30天自动清理# 健康检查生产必配便于监控management:endpoints:web:exposure:include:arthas,health,info# 暴露arthas、健康检查、应用信息接口base-path:/actuator# 监控接口上下文路径endpoint:health:show-details:always# 显示健康检查详细信息arthas:enabled:true# 开启Arthas监控接口2.3 启动脚本start-tunnel.sh创建启动脚本简化启动操作避免每次输入复杂命令#!/bin/bash# Arthas Tunnel Server 启动脚本生产版# 作者CSDN-xxx可替换为自己的昵称# 日期2026-04# 定义变量JAR_NAMEarthas-tunnel-server.jarPROFILEprodLOG_PATH/opt/arthas/tunnel/logsJVM_OPTS-Xms512m -Xmx512m -XX:UseG1GC -XX:MaxGCPauseMillis200# JVM参数根据服务器配置调整# 检查进程是否已启动pid$(ps-ef|grep$JAR_NAME|grep-vgrep|awk{print $2})if[-n$pid];thenechoArthas Tunnel Server 已启动进程ID$pidexit0fi# 启动服务nohupjava$JVM_OPTS-jar$JAR_NAME--spring.profiles.active$PROFILE$LOG_PATH/start.log21# 检查启动结果sleep3pid$(ps-ef|grep$JAR_NAME|grep-vgrep|awk{print $2})if[-n$pid];thenechoArthas Tunnel Server 启动成功进程ID$pidelseechoArthas Tunnel Server 启动失败请查看日志$LOG_PATH/start.logfi给脚本赋予执行权限chmodx start-tunnel.sh2.4 systemd 托管生产高可用必备通过 systemd 托管服务实现开机自启、故障自动重启避免服务意外中断[Unit] DescriptionArthas Tunnel Server (Production) Afternetwork.target # 网络启动后再启动服务 Wantsnetwork.target [Service] Userapp # 非root用户生产规范需提前创建app用户 Groupapp WorkingDirectory/opt/arthas/tunnel # 部署目录 ExecStart/usr/bin/java -Xms512m -Xmx512m -jar arthas-tunnel-server.jar --spring.profiles.activeprod Restartalways # 故障自动重启 RestartSec3 # 重启间隔3秒 LimitNOFILE65535 # 最大文件句柄数避免连接数不足 StandardOutputappend:/opt/arthas/tunnel/logs/systemd.log StandardErrorappend:/opt/arthas/tunnel/logs/systemd.err [Install] WantedBymulti-user.target # 多用户模式下开机自启执行以下命令启用并启动服务# 复制配置文件到 systemd 目录sudocp/opt/arthas/tunnel/arthas-tunnel.service /etc/systemd/system/# 重新加载 systemd 配置sudosystemctl daemon-reload# 设置开机自启sudosystemctlenablearthas-tunnel# 启动服务sudosystemctl start arthas-tunnel# 查看服务状态sudosystemctl status arthas-tunnel常用命令后续维护用# 停止服务sudosystemctl stop arthas-tunnel# 重启服务sudosystemctl restart arthas-tunnel# 查看服务日志sudojournalctl-uarthas-tunnel-f三、SpringBoot Agent 生产配置客户端业务应用集成业务应用集成 Arthas Agent通过配置自动注册到 Tunnel Server无需手动启动 arthas全程无侵入适配 SpringBoot 2.x/3.x。3.1 pom.xml 依赖Maven项目引入 Arthas SpringBoot Starter版本与 Tunnel Server 一致4.1.8!-- Arthas Agent 依赖生产版与 Tunnel Server 版本一致 --dependencygroupIdcom.taobao.arthas/groupIdartifactIdarthas-spring-boot-starter/artifactIdversion4.1.8/version!-- 可选如果应用打包时不需要包含此依赖可设置为provided --!-- scopeprovided/scope --/dependencyGradle 项目依赖补充implementationcom.taobao.arthas:arthas-spring-boot-starter:4.1.83.2 application.yml 核心配置在业务应用的 application.yml或 application-prod.yml中添加以下配置重点保证 AgentId 唯一、关闭本地端口安全# Arthas Agent 配置生产核心arthas:agent-id:${spring.application.name}:${server.port}:${HOSTNAME}# 全局唯一AgentId关键# 说明AgentId 由 应用名端口主机名 组成确保多实例、多集群环境不冲突app-name:${spring.application.name}# 应用名称便于在Tunnel控制台区分tunnel-server:ws://192.168.1.100:7777/ws# 替换为你的 Tunnel Server IP:7777telnet-port:-1# 生产必关关闭本地telnet端口防止本地未授权访问http-port:-1# 生产必关关闭本地http端口防止本地未授权访问ip:0.0.0.0# 允许所有IP访问仅用于Agent注册不影响安全session-timeout:1800# 会话超时时间30分钟超时自动断开增强安全disabled:false# 默认为false开启Agent如需临时关闭改为true# 补充如果应用部署在K8s可修改AgentId为适配K8s环境# agent-id: ${spring.application.name}:${server.port}:${POD_NAME}配置说明tunnel-server替换为实际的 Tunnel Server 公网/内网IP端口固定为7777与服务端配置一致协议必须是 ws://AgentId必须全局唯一推荐格式应用名端口主机名或Pod名避免多实例冲突telnet-port/http-port设置为-1彻底关闭本地访问端口仅通过 Tunnel Server 远程诊断保障生产安全3.3 安全增强配置可选高安全场景如果生产环境安全要求较高可添加以下配置进一步限制 Arthas 使用arthas:# 限制可执行的Arthas命令黑名单禁止高危命令command-blacklist:shutdown,stop# 开启命令执行日志便于审计audit-log:trueaudit-log-path:/opt/app/logs/arthas-audit.log# 审计日志路径# 仅允许指定IP的Tunnel Server连接进一步限制tunnel-server-allow-ips:192.168.1.100# 替换为你的Tunnel Server IP四、生产部署完整流程一步一步来部署 Tunnel Server创建目录 → 下载Jar包 → 编写 application-prod.yml → 编写启动脚本 → systemd 托管开放服务器安全组8080Web控制台、7777Agent注册访问 Web 控制台http://Tunnel Server IP:8080/arthas输入用户名密码配置文件中设置的登录成功即部署完成集成 SpringBoot Agent在业务应用中添加 pom 依赖 → 配置 application.yml 中的 Arthas 相关参数重启业务应用应用启动后会自动注册到 Tunnel Server远程诊断登录 Tunnel Web 控制台输入 AgentId业务应用配置的点击「Connect」进入 Arthas 控制台执行诊断命令dashboard、thread、watch、trace 等完成远程诊断五、生产常见问题排查避坑指南问题1Agent 无法注册到 Tunnel Server排查① 检查 7777 端口是否开放安全组/防火墙② 确认 tunnel-server 配置正确ws://协议、IP/端口正确③ 检查 AgentId 是否唯一④ 查看业务应用日志搜索 arthas是否有注册失败信息。问题2Web 控制台登录失败排查① 核对 spring.security.user.name/password 配置② 检查 8080 端口是否开放③ 查看 Tunnel Server 日志logs/arthas-tunnel-server.log。问题3远程诊断时命令执行失败排查① 确认 Agent 已成功注册Web控制台可看到AgentId② 检查 Arthas 版本是否一致③ 确认业务应用JDK版本与 Tunnel Server JDK版本兼容。问题4服务重启后 Agent 不自动注册排查① 确认 Arthas 依赖已正确引入未被排除② 检查 application.yml 中 arthas.disabled 是否为 false③ 查看应用启动日志是否有 Arthas 启动相关日志。六、补充说明生产优化建议版本选择推荐使用 4.1.8 稳定版避免使用最新快照版保障生产稳定性。备份定期备份 Tunnel Server 日志和配置文件避免配置丢失。监控将 Tunnel Server 的健康检查接口/actuator/health接入监控平台如Prometheus、Grafana实时监控服务状态。密码管理生产环境中密码建议通过配置中心如Nacos、Apollo管理避免硬编码在配置文件中。