Arthas 本地开发、构建打包与 Release 发布全流程实战指南

原创2026-09-18 12:37:421,390 阅读
文章标签:开发工具调试器性能剖析可观测性MCP 服务AI 技能运维

Arthas 本地开发、构建打包与 Release 发布全流程实战指南

本篇技术指南以 Arthas 仓库的贡献指南(CONTRIBUTING.md)为核心骨架,系统讲解从「提 Issue 反馈」到「本地一键打包安装」「多版本切换调试」再到「维护者 Release 发布」的完整工程链路。结合仓库中的 as-package.sh、pom.xml、Bootstrap.java 等源码与配置,读者可以掌握 Arthas 开发环境的搭建要求、~/.arthas 本地安装机制、--use-version/--versions 多版本管理,以及全量打包与发布到 Maven Central 的操作细节。

一、参与 Arthas 的三种方式

Arthas 的社区贡献入口非常明确,任何开发者都可以从以下三个层面参与:

层面 内容 指向位置
Issue 反馈 新功能诉求(feedbacks)、炫酷的使用技巧(usage tips)、高效的排查经验(experiences) 仓库 Issue 追踪器
用户文档 中英文用户手册 site/docs/ 目录
在线教程 交互式演练教程 killercoda 分支维护

其中用户文档是改进成本最低、价值最直接的入口:Arthas 的全部命令手册(trace、watch、dashboard、jad、ognl 等)都维护在 site/docs/ 下的 doc/ 子目录中,中文与英文版本一一对应(如 watch.md 与 watch.md)。若发现命令用法描述有误、示例缺失或翻译不准确,直接提交 PR 即可。

二、开发环境要求

CONTRIBUTING.md 对开发 Arthas 的 JDK 与编译环境给出了明确约束,这些约束直接决定了你能不能在本地把代码跑起来:

  • 运行时 JDK 版本:Arthas 运行时支持 JDK6+。需要说明的是,这是 Arthas 3.x 时代的兼容口径;从当前 Bootstrap.java 的类注释可以看到,Arthas 4 明确要求 JDK 8+("Arthas 4 supports JDK 8+"),如需诊断 JDK 6/7 上的应用则应使用 Arthas 3。
  • 编译用 JDK8:仓库明确建议使用 JDK8 编译,使用更高版本会遇到问题。从根 pom.xml 可以看到编译目标锁定在 maven.compiler.target/source = 1.8,这是为了确保产物在低版本 JDK 上可用。CI 相关配置可以参考 .github/workflows 目录。
  • JFR 相关问题的 JDK 选择:如果遇到 JFR 相关问题,建议使用 8u262 及之后的高版本 openjdk8 或 zulu jdk8(OpenJDK 社区在 8u262 中修复了相关缺陷)。
  • JNI 编译环境:Arthas 需要编译 JNI 代码,因此需要 C/C++ 编译环境支持:
    • macOS 需要安装 Xcode;
    • Windows 需要安装 gcc;
    • Linux 需要具备 gcc/g++ 工具链。

三、本地安装:as-package.sh 一键打包并安装到 ~/.arthas

3.1 推荐做法:as-package.sh

本地开发时,最推荐的流程是执行仓库根目录下的 as-package.sh 打包脚本。它会自动完成「构建 → 打包 → 安装到本地」的全过程,核心机制如下:

  1. 版本号生成:脚本调用 Maven Wrapper 读取根 pom.xml 中的 project.version(当前仓库为 4.3.4),再拼接当前时间戳 YYYYMMDDHHMMSS,得到形如 4.3.4.20260918120000 的完整版本号;
  2. 写入版本文件:将版本号写入 core 模块的 src/main/resources/com/taobao/arthas/core/res/version 资源文件(打包完成后脚本会删除该临时文件);
  3. Maven 打包:执行 ./mvnw clean package,跳过测试与 javadoc;
  4. 解压安装:找到 packaging/target/arthas-bin.zip,将其解压到 ~/.arthas/lib/<版本号>/arthas 目录,并打印 ~/.arthas 的磁盘占用。

由于 as.sh 启动时会对 ~/.arthas/lib 下的目录排序并取最新版本,因此本地调试时 Arthas 会自动加载刚安装的最新版本,无需任何额外配置。

3.2 快速迭代:--fast

为了加速本地迭代,脚本提供了 --fast 选项:

./as-package.sh --fast

该选项等价于同时启用以下行为(从 as-package.sh 源码可见):

  • 跳过 clean(保留各模块 target 缓存,避免全量重编译);
  • 跳过 site 模块的文档前端构建(vuepress/yarn 构建较耗时且对本地功能验证无影响);
  • 启用 Maven 并行构建(-T 1C,按 CPU 核数并行)。

如果需要重建文档,则不要使用 --fast,直接执行完整打包即可。

3.3 脚本支持的完整参数

结合脚本源码,as-package.sh 支持的参数整理如下:

参数 作用
--fast 跳过 clean + 跳过 site 前端构建 + Maven 并行构建(-T 1C)
--no-clean 不执行 Maven clean,保留各模块 target 缓存
--skip-site 跳过 site 模块的前端构建(vuepress/yarn),不影响默认打包产物
-T, --threads <arg> 传给 Maven 的并行线程数(如 1C 或 4)
-- 之后的参数原样透传给 Maven(追加到打包命令末尾)
-h, --help 显示脚本帮助

3.4 注意事项:arthas-vmtool 需要手动同步

重要提示:修改 arthas-vmtool 相关代码后,打包结果需要手动复制到本仓库的 lib/ 路径下,不会自动复制。

这是因为 lib/ 目录下的 libArthasJniLibrary-*.so/.dylib/.dll 等动态库文件(对应 arthas-vmtool 模块的 JNI 编译产物)是打包时直接从该目录取用的,而构建流程不会回写。改动 vmtool 后请将新生成的动态库覆盖到 lib/ 下再重新打包。

3.5 手动打包方式

如果不使用 as-package.sh,也可以直接执行:

./mvnw clean package -DskipTests

生成的 zip 位于 packaging/target/ 下。但务必注意:as.sh 启动时加载的是 ~/.arthas/lib 下的版本,因此这种手动打包方式产出的 zip 需要自行解压到 ~/.arthas/lib(或配合下一节的 --use-version 使用),否则 as.sh 不会加载它。

四、多版本管理与启动指定版本

本地开发过程中,~/.arthas/lib 下会积累多个版本,Arthas 提供了两个参数来管理多版本。

4.1 指定版本启动:--use-version

./as.sh --use-version 4.3.4.20260918120000

--use-version 用于在存在多个版本时显式指定要启动的 Arthas 版本。从 Bootstrap.java 源码可以看到 useVersion 字段的定位:它对应 ~/.arthas/lib 下的一个版本目录。

4.2 列出所有版本:--versions

./as.sh --versions

该命令会同时列出本地版本和远程版本:本地版本来自 ~/.arthas/lib 目录下的子目录名;远程版本则通过远程仓库的元数据获取。对应实现是 Bootstrap.java 中的 listVersions() 方法,输出格式为 Local versions: 与 Remote versions: 两段。

4.3 底层机制:ARTHAS_LIB_DIR 与 arthas home 定位

理解 ~/.arthas/lib 的来源有助于排查问题。从 Bootstrap.java 静态代码块可以看到:

  1. 优先读取环境变量 ARTHAS_LIB_DIR 指定的目录(若已设置会打印日志);
  2. 否则使用 ${user.home}/.arthas/lib;
  3. 若目录不可用则回退到 ${java.io.tmpdir}/.arthas/lib。

而 arthas home 的解析顺序则是:先看 --use-version 是否指定 → 再尝试使用 arthas-boot.jar 所在目录 → 最后从远程仓库下载。加载前还会通过 verifyArthasHome()(Bootstrap.java)校验目录内必须存在 arthas-core.jar、arthas-agent.jar、arthas-spy.jar 三个核心 jar,缺一不可。

五、在 IDEA 中调试 Arthas

CONTRIBUTING.md 推荐通过 Debug Arthas In IDEA 的方式在 IDE 中进行断点调试。实践中,可以借助 as-package.sh 先把最新构建安装到本地 ~/.arthas/lib,再在 IDE 中直接运行 Bootstrap.java 的主方法并打上断点,配合 math-game 模块提供的示例应用(demo.MathGame)即可复现 attach 诊断的完整调用链。

六、全量打包(Packaging All)

需要产出完整发行包(含文档站点)时,执行:

./mvnw clean package -DskipTests -P full

full profile 在整个构建链路中承担三件事:

  1. git 提交信息写入:通过 git-commit-id-plugin 在 full profile 下生成 arthas-git.properties 文件(见 pom.xml),方便追溯每个包对应的源码提交;
  2. javadoc 打包:通过 maven-javadoc-plugin 在 package 阶段生成 javadoc jar;
  3. 文档包生成:在 packaging/pom.xml 的 full profile 中,额外执行 assembly-doc.xml 描述符的 assembly 任务,产出 doc.zip 文档包。

packaging 模块(packaging/pom.xml)是整个发布产物的汇聚点:

  • 默认执行 assembly.xml 描述符,产出 arthas-bin.zip(二进制发行包),并将该 zip 一并打入 arthas-packaging-<version>.jar;
  • 内置 deb profile(-P deb)通过 jdeb 生成 deb 安装包(安装到 /usr/share/arthas,as.sh 链接到 /usr/bin,并附带 man 手册 arthas.1);
  • 内置 rpm profile(激活条件为 Linux 且传入 -Drpm)通过 rpm-maven-plugin 生成 rpm 包。

七、Release 发布流程(面向仓库维护者)

CONTRIBUTING.md 给出了完整的发版 checklist,这是仓库维护者执行 Arthas 新版本发布的标准流程,包含源码同步、Maven 发布、文档与镜像更新三大阶段:

7.1 源码与构建准备

  1. 同步 vmtool 动态库:若 arthas-vmtool 有更新,先手动触发 build-vmtool 的 CI,构建后把新的动态库提交到 lib/ 目录;
  2. 统一版本号:修改 as.sh(仓库 README 中提到的启动脚本)、Bootstrap.java 中的版本、最后修改日期,以及 Dockerfile 中的版本;
  3. 配置 Maven settings:修改本地 settings.xml,配置发布所需的中央仓库认证信息;
  4. 预热 gpg 后台进程:执行一次 gpg --sign /tmp/2.txt 让 gpg 守护进程启动,否则打包可能失败(对应 pom.xml 中 release profile 的 maven-gpg-plugin 签名步骤,它配置了 --pinentry-mode loopback)。

7.2 Maven Central 发布

  1. 执行发布命令:
mvn clean deploy -DskipTests -P full -P release

-P release 激活根 pom.xml 中的 release profile,该 profile 在 verify 阶段对构件做 GPG 签名,并通过 central-publishing-maven-plugin(publishingServerId=central)对接 Sonatype Central 门户; 6. 门户发布:到 central.sonatype.com/publishing/deployments 发布自己的 Deployment; 7. 验证同步:在 repo1.maven.org/maven2/com/taobao/arthas/arthas-packaging/ 下确认构件是否已同步; 8. 检查阿里云仓库:Maven Central 发布完成后,还需到阿里云公共仓库检查同步情况(可能存在延时),例如:

https://maven.aliyun.com/repository/public/com/taobao/arthas/arthas-packaging/<版本>/arthas-packaging-<版本>-bin.zip

版本号元数据地址为 https://maven.aliyun.com/repository/public/com/taobao/arthas/arthas-packaging/maven-metadata.xml。

7.3 代码、文档与镜像更新

  1. 打 tag:为本次发布打上 tag 并 push 到仓库;
  2. 更新 gh-pages:更新分支下的 arthas-boot.jar、math-game.jar、as.sh,下载 doc.zip 解压覆盖文档,可通过 update-doc 的 GitHub Action 自动完成;
  3. 更新 Docker 镜像:推送新的 tag 到 Docker Hub,可通过 push-docker 的 GitHub Action 完成(注意:这里会用到当前仓库根目录下的 Dockerfile,其内部构建流程会拉取发行包制作镜像);
  4. 更新 README:如新增了命令,需要在 README.md 中补充说明并更新相关链接;
  5. 更新 Release 页面:整理 release 页面的 issue 信息与修改说明;
  6. 更新 latest_version API:更新 arthas.aliyun.com/api/latest_version 接口返回的最新版本;
  7. 更新内部版本:同步更新组织内部依赖的 Arthas 版本号。

八、结语

从本地开发者的 as-package.sh --fast 快速迭代,到需要同时维护多个本地版本时的 --use-version/--versions,再到维护者视角的 -P full 全量打包与 -P release 中央仓库发布,CONTRIBUTING.md 所描述的是一条被源码充分印证、可完整落地的工程链路。对想要深入 Arthas 内部实现的开发者而言,建议以此为起点,结合 as-package.sh、Bootstrap.java、packaging/pom.xml 三处关键文件反复对照研读,即可快速打通「改代码 → 打包 → 本地调试 → 发布」的完整闭环。

登录后查看全文
arthas