Arthas Spring Boot Starter 实战指南:应用内嵌诊断、Tunnel 远程管理与非 Spring Boot 应用接入

发布时间:2026/11/9 2:47:09

Arthas Spring Boot Starter 实战指南:应用内嵌诊断、Tunnel 远程管理与非 Spring Boot 应用接入 Arthas Spring Boot Starter 实战指南应用内嵌诊断、Tunnel 远程管理与非 Spring Boot 应用接入【免费下载链接】arthasAlibaba Java Diagnostic Tool Arthas/Alibaba Java诊断利器Arthas项目地址: https://gitcode.com/gh_mirrors/ar/arthas本文基于仓库 site/docs/en/doc/spring-boot-starter.md 编写并结合作者仓库源码进行纵深讲解。导读Arthas Spring Boot Starter 是 Arthas 为 Spring Boot 应用提供的零成本接入方案只要在 pom 中引入一个依赖应用启动时 Spring 就会自动拉起 Arthas 并 attach 到自身进程开箱即用地获得在线诊断能力。本文将以 starter 的引入、配置、Endpoint 监控为核心讲解如何在 Spring Boot 2/3 应用中内嵌 Arthas、通过 Tunnel Server 实现远程管理、加载外部命令并给出非 Spring Boot 应用使用ArthasAgent.attach()的等价方案。为什么需要 Arthas Spring Boot Starter传统使用 Arthas 的方式是下载 arthas 包后用as.sh或as.bat连接目标 Java 进程这对于本地开发、测试环境非常方便。但在生产集群、容器化部署或无法人工登录的场景下人工 attach 成本高、难自动化。Spring Boot Starter 则把 attach 动作完全自动化应用启动时Spring 容器初始化 Arthas并 attach 自身进程。这样应用一启动就处于可诊断状态配合 Arthas Properties 中的 Tunnel Server 配置还能把本地 Arthas 注册到远程管理端实现无人值守的远程诊断。::: tip Arthas 3.7.2 及以后版本同时支持 Spring Boot 2 和 Spring Boot 3。仓库源码 pom.xml 中的 profile 也印证了这一点JDK 8~16 时仅集成测试 Spring Boot 2 示例Spring Boot 3 示例的集成测试需要 JDK 17 及以上。 :::快速开始引入 Maven 依赖在 Spring Boot 应用的pom.xml中添加如下依赖dependency groupIdcom.taobao.arthas/groupId artifactIdarthas-spring-boot-starter/artifactId version${arthas.version}/version /dependency其中${arthas.version}需要替换为实际使用的版本号。引入后应用启动时 Spring 会启动 Arthas并 attach 自身进程无需任何额外代码。从源码看starter 本身只做了薄薄一层的 Spring 集成真正干活的组件都在它的依赖里arthas-agent-attach负责把 Arthas agent 挂载到当前 JVMarthas-packaging提供打包好的 arthas 运行资源如arthas-core.jar、arthas-bin.zip。同时starter 以provided/optional方式依赖spring-boot-starter-actuator和spring-boot-starter-web见 pom.xml即不强制你的应用引入 Web/Actuator 能力只有想通过 HTTP Endpoint 查看 Arthas 状态时才需要它们。工作原理从 Spring Bean 到 Arthas AgentStarter 的核心自动化逻辑集中在 ArthasConfiguration.java它通过 Spring Boot 的自动装配完成以下链路条件装配ConditionalOnProperty(name spring.arthas.enabled, matchIfMissing true)默认开启可通过spring.arthas.enabledfalse一键关闭。配置收集ConfigurationProperties(prefix arthas)将所有以arthas.*开头的配置项收集进arthasConfigMap。源码注释特别说明之所以用一个独立的 Map 而不是只依赖ArthasProperties是为了避免某些新版本才支持的配置项在ArthasProperties类里尚未定义。配置归一化StringUtils.removeDashKey()把-风格的配置键如agent-id转成驼峰如agentId详见 StringUtils.java。补全默认值ArthasProperties.updateArthasConfigMapDefaultValue()为未配置的disabledCommands注入默认值stop。注入应用名如果配置中没有appName自动取spring.application.name的值。启动 Agent给所有配置加上arthas.前缀后new ArthasAgent(mapWithPrefix, arthasProperties.getHome(), arthasProperties.isSlientInit(), null)然后调用arthasAgent.init()真正完成 attach。init()的底层实现在 ArthasAgent.java先通过Class.forName(java.arthas.SpyAPI)SpyAPI.isInited()判断 Arthas 是否已在运行避免重复 attach通过ByteBuddyAgent.install()获取当前 JVM 的Instrumentation若未显式指定arthasHome则从 classpath 解压arthas-bin.zip到临时目录加载arthas-core.jar中的com.taobao.arthas.core.server.ArthasBootstrap调用getInstance(inst, configMap)完成初始化检查isBind()端口绑定失败则记录错误信息slientInittrue时只记录错误不抛异常否则抛出IllegalStateException。配置属性详解官方示例通过 Tunnel Server 远程管理application.properties或application.yml中的核心配置示例如下arthas.agent-idhsehdfsfghhwertyfad arthas.tunnel-serverws://47.75.156.201:7777/ws arthas.command-locations/opt/arthas/ext-command.jar,/opt/arthas/ext-commands三个配置项分别解决三个问题配置项作用说明arthas.agent-id设置 agent 的唯一标识用于在 Tunnel Server 端唯一标识该应用实例arthas.tunnel-server指定 Tunnel Server 地址Arthas 启动后通过 WebSocket 连接到该服务端等待远程指令arthas.command-locations指定外部命令的加载路径可配置 jar 文件路径或目录路径多个用逗号分隔Spring Boot 的 relaxed binding 机制同时支持arthas.command-locations和arthas.commandLocations两种写法在 Spring Boot 配置文件中推荐使用arthas.command-locations-风格。全部受支持配置项来自源码Starter 支持的所有配置项完整定义在 ArthasProperties.javaConfigurationProperties(prefix arthas)意味着所有键都以arthas.开头配置键properties 风格字段驼峰类型说明arthas.ipipStringArthas 服务监听 IParthas.telnet-port/arthas.telnetPorttelnetPortintTelnet 端口默认 3658arthas.http-port/arthas.httpPorthttpPortintHTTP 端口默认 8563arthas.tunnel-server/arthas.tunnelServertunnelServerStringTunnel Server 地址arthas.agent-id/arthas.agentIdagentIdStringagent 唯一标识arthas.app-name/arthas.appNameappNameString应用名未配置时自动取spring.application.namearthas.stat-url/arthas.statUrlstatUrlString上报已执行命令的统计地址arthas.session-timeout/arthas.sessionTimeoutsessionTimeoutlong会话超时时间秒arthas.usernameusernameString认证用户名arthas.passwordpasswordString认证密码arthas.homehomeString指定 arthas 安装目录arthas.slient-init/arthas.slientInitslientInitbooleanagent 初始化出错时是否静默默认 false抛异常arthas.disabled-commands/arthas.disabledCommandsdisabledCommandsString禁用的命令列表默认stoparthas.command-locations/arthas.commandLocationscommandLocationsString外部命令加载路径端口与远程管理的细节参考 Arthas Properties 中的说明arthas.telnetPort配置为-1时不监听 telnet 端口arthas.httpPort同理配置为0时随机监听端口随机端口号会记录在~/logs/arthas/arthas.log中如果一台机器上部署多个应用怕端口冲突可以都配置为随机端口或-1然后统一通过 Tunnel Server 使用 Arthas——这正是上面arthas.tunnel-server示例的典型场景。默认禁用 stop 命令::: tip 默认情况下arthas-spring-boot-starter会禁用stop命令。 :::这一行为在源码中有明确实现ArthasProperties中DEFAULT_DISABLEDCOMMANDS stopArthasProperties.javaupdateArthasConfigMapDefaultValue()在用户未配置disabledCommands时写入该默认值。原因是starter 将 Arthas 内嵌在业务应用进程内若允许stop命令等于允许远程/在线把 Arthas 服务停掉从而失去诊断能力。如需调整可以显式配置arthas.disabled-commandsstop,dump关于disabledCommands与外部命令加载的完整说明可参考 Arthas Properties 中的 disable specify commands 与 Load external commands 两节。加载外部命令command-locationsarthas.command-locations用于在 Arthas 启动时加载自定义外部命令arthas.command-locations/opt/arthas/ext-command.jar,/opt/arthas/ext-commands关键约束来自 Arthas Properties每个条目可以是 jar 文件路径或目录路径多个条目用逗号分隔目录条目只扫描当前目录下的*.jar不会递归如果${arthas.home}/commands目录存在Arthas 启动时也会尝试加载其中的*.jar显式配置的commandLocations先加载默认目录后加载外部 jar 需要通过META-INF/services/com.taobao.arthas.core.shell.command.CommandResolver暴露CommandResolver实现Arthas 内置命令优先外部命令与内置命令同名时外部命令被跳过并写入日志。命令行方式等价配置--command-locations /opt/arthas/ext-command.jar,/opt/arthas/ext-commands。仓库还提供了完整的外部命令开发示例arthas-demo-external-command 模块包含DemoExternalCommand.java与DemoExternalCommandResolver.java以及对应的集成测试 arthas-external-command-integration-test详细开发流程参见 Load External Commands。通过 Actuator Endpoint 查看 Arthas 状态Starter 内置了一个 Actuator Endpoint 用于查看 Arthas 的配置与初始化状态。::: tip 使用该 Endpoint 需要应用引入并暴露 Actuator Endpoint。Spring Boot 中可通过management.endpoints.web.exposure.includearthas或*等配置暴露具体以 Spring Boot 官方 Production-ready Features 文档为准。 :::假定应用端口是 8080访问http://localhost:8080/actuator/arthas返回示例{ arthasConfigMap: { agent-id: hsehdfsfghhwertyfad, tunnel-server: ws://47.75.156.201:7777/ws, } }Endpoint 的实现位于 ArthasEndPoint.javaEndpoint(id arthas)定义 Endpoint idReadOperation的invoke()返回arthasConfigMap即实际注入给 Arthas 的配置以及初始化错误信息errorMessage当 agent 初始化失败时装配逻辑在 ArthasEndPointAutoConfiguration.java同样受spring.arthas.enabled开关控制并且仅当 Endpoint 被 Spring Boot 暴露时才创建ConditionalOnAvailableEndpoint。这个 Endpoint 的价值在于应用启动后即可通过 HTTP 确认 Arthas 是否成功挂载、配置是否按预期生效、以及失败时的错误原因非常适合接入监控探活或诊断系统的自检环节。非 Spring Boot 应用的使用方式如果你的应用不是 Spring Boot例如普通 Spring、Servlet、自研框架、甚至非 Spring 的 Java 应用无法使用 starter可以改用arthas-agent-attacharthas-packaging两个依赖在代码里显式调用ArthasAgent.attach()。Maven 依赖dependency groupIdcom.taobao.arthas/groupId artifactIdarthas-agent-attach/artifactId version${arthas.version}/version /dependency dependency groupIdcom.taobao.arthas/groupId artifactIdarthas-packaging/artifactId version${arthas.version}/version /dependency一行代码完成 attachimport com.taobao.arthas.agent.attach.ArthasAgent; public class ArthasAttachExample { public static void main(String[] args) { ArthasAgent.attach(); } }带配置的 attachHashMapString, String configMap new HashMapString, String(); configMap.put(arthas.appName, demo); configMap.put(arthas.tunnelServer, ws://127.0.0.1:7777/ws); ArthasAgent.attach(configMap);::: warning 非 Spring Boot 方式下配置键必须是驼峰风格如appName、tunnelServer这与 Spring Boot 的-风格不同。只有 Spring Boot 应用才同时支持驼峰和-两种风格——因为-到驼峰的转换StringUtils.removeDashKey是由 starter 完成的裸用ArthasAgent时没有这一步。 :::ArthasAgent还提供了其他静态方法attach(String arthasHome)可指定 Arthas 安装目录当 classpath 中没有arthas-bin.zip资源时例如以-javaagent之外的隔离类加载方式运行需要显式指定 arthas 目录详见 ArthasAgent.java。配置风格与优先级小结风格Spring Boot 应用推荐-风格arthas.tunnel-server也兼容驼峰非 Spring Boot 的ArthasAgent.attach(configMap)只能使用驼峰。优先级来自 Arthas Properties命令行参数 System Env System Properties arthas.properties若希望arthas.properties拥有最高优先级可配置arthas.config.overrideAlltrue。开关通过spring.arthas.enabledfalse可整体关闭 starter 的自动 attach 与 Endpoint 装配两个自动配置类都带有ConditionalOnProperty(name spring.arthas.enabled, matchIfMissing true)。参考文档Arthas Properties完整配置项、禁用命令、外部命令加载与配置优先级说明Load External Commands外部命令开发与加载完整示例核心源码ArthasProperties.java、ArthasConfiguration.java、ArthasEndPoint.java、ArthasAgent.java集成测试示例arthas-spring-boot-starter-exampleSpring Boot 2与 arthas-spring-boot3-starter-exampleSpring Boot 3【免费下载链接】arthasAlibaba Java Diagnostic Tool Arthas/Alibaba Java诊断利器Arthas项目地址: https://gitcode.com/gh_mirrors/ar/arthas创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/11/4 10:04:18

OpenClaw记忆系统深度解析:让AI助手真正记住你

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/11/4 12:09:35

Rust 环境搭建指南:从 rustup 到 cargo 的完整实践

1. 为什么我劝你从 rustup 开始,而不是直接装 Rust很多人第一次接触 Rust,看到官网那个rustup的安装命令,心里会犯嘀咕:不就是装个编译器吗,为什么还要多一层工具链管理器?我直接下个rustc的压缩包解压不行…

2026/11/9 2:43:27

隰县电工证报名考试怎么转?郑州报考避坑指南全在这了

隰县电工证报名考试怎么转?郑州报考避坑指南全在这了 之前考的证在外省能不能转过来?这是很多人在报考隰县电工证报名考试时最关心的问题,特别是在河南郑州、信阳浉河区等地从事公路工程的同行,经常遇到证书异地转接的难题。别急,下面我用多年实操经验告…

2026/11/9 2:43:27

南充市电工证焊工证在哪考怎么复审

南充市电工证焊工证在哪考怎么复审 证书过期了不知道怎么复审延期,你是不是也遇到了这种情况?别慌,今天就来聊聊 南充市电工证焊工证在哪考…

2026/11/9 2:43:27

株洲市职工电工证查讯怎么报名学历不高怕报不上名

株洲市职工电工证查讯怎么报名学历不高怕报不上名 你是不是也觉得学历不高,就报不了名?别急,今天咱们就来聊聊【株洲市职工电工证查讯】怎么报名,还有你关心的薪资和职业发展问题。 电工证在手,机会更多 电工证…

2026/11/9 2:43:27

重庆江北考低压电工证考前押题全攻略,缺证别想上岗!

重庆江北考低压电工证考前押题全攻略,缺证别想上岗! 你是不是正在为找工作发愁?是不是听说现在很多岗位都要求有特种作业证才能上岗?别急,重庆江北考低压电工证,就是你打破就业瓶颈的关键一步!今天咱们不绕弯子,直接给你一套【考前押题】攻略,帮你一…

2026/11/9 2:38:26

当兵回来能考电工证吗 怎么报名全攻略

当兵回来能考电工证吗 怎么报名全攻略 你是不是退伍后担心学历不高考不上电工证?别急,今天就来聊聊当兵回来能考电工证吗,以及怎么报名的问题,让你一目了然,少走弯路。 一、退伍军人考电工证的政策支持 当兵回来能考电工证吗?答案是肯定的。…

2026/11/9 0:37:55

电工证丢失还能补吗?千万别踩坑,丢了证等于失业

电工证丢失还能补吗?千万别踩坑,丢了证等于失业 你正在找工作,但手里的电工证突然丢了,这下怎么办?别急,先别慌, 电工证丢失还能补吗 ?答案是肯定的,但 千万别踩坑 ,补办流程如果不了解,可能会耽误你上岗、甚至影响到你的收入。…

2026/11/9 0:03:09

建设厅的特种工有哪些含金量高?别交完钱考不过

建设厅的特种工有哪些含金量高?别交完钱考不过 怕考不过白交培训费?别急,先搞清楚建设厅的特种工有哪些含金量高的证,再决定是不是值得投入时间和金钱。 建设厅的特种工证是建筑行业里最基础、也最实用的证书之一,涉及多个作业类别,每种证的 含金量…

2026/11/9 0:03:09

荆门市电工证报名怎么考才靠谱 全国通用证别交冤枉钱

荆门市电工证报名怎么考才靠谱 全国通用证别交冤枉钱 怕考不过白交培训费?荆门市电工证报名前必须知道这些避坑指南。别看网上一堆培训机构广告,真要报个电工证,很多人被坑得一塌糊涂。特别是那些打着“包过”旗号的,最后不是考试不过,就是证不是全国通…

2026/11/9 0:03:09

高空电工作业过程通过率揭秘:怎么选靠谱机构不被坑

高空电工作业过程通过率揭秘:怎么选靠谱机构不被坑 不知道去哪报名怕被中介坑?你不是一个人。现在特种作业证报名渠道五花八门,从线下培训机构到线上代理,真假难辨。尤其是像高空电工作业这类高风险、高门槛的作业类型,证书含金量和考试通过率直接影响你…

2026/11/7 14:54:47

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/7 14:50:12

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑