Arthas 本地开发、构建打包与 Release 发布全流程实战指南
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 打包脚本。它会自动完成「构建 → 打包 → 安装到本地」的全过程,核心机制如下:
- 版本号生成:脚本调用 Maven Wrapper 读取根 pom.xml 中的
project.version(当前仓库为4.3.4),再拼接当前时间戳YYYYMMDDHHMMSS,得到形如4.3.4.20260918120000的完整版本号; - 写入版本文件:将版本号写入 core 模块的
src/main/resources/com/taobao/arthas/core/res/version资源文件(打包完成后脚本会删除该临时文件); - Maven 打包:执行
./mvnw clean package,跳过测试与 javadoc; - 解压安装:找到
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 静态代码块可以看到:
- 优先读取环境变量
ARTHAS_LIB_DIR指定的目录(若已设置会打印日志); - 否则使用
${user.home}/.arthas/lib; - 若目录不可用则回退到
${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 在整个构建链路中承担三件事:
- git 提交信息写入:通过
git-commit-id-plugin在fullprofile 下生成arthas-git.properties文件(见 pom.xml),方便追溯每个包对应的源码提交; - javadoc 打包:通过
maven-javadoc-plugin在 package 阶段生成 javadoc jar; - 文档包生成:在 packaging/pom.xml 的
fullprofile 中,额外执行assembly-doc.xml描述符的 assembly 任务,产出 doc.zip 文档包。
packaging 模块(packaging/pom.xml)是整个发布产物的汇聚点:
- 默认执行
assembly.xml描述符,产出arthas-bin.zip(二进制发行包),并将该 zip 一并打入arthas-packaging-<version>.jar; - 内置
debprofile(-P deb)通过 jdeb 生成 deb 安装包(安装到/usr/share/arthas,as.sh链接到/usr/bin,并附带 man 手册 arthas.1); - 内置
rpmprofile(激活条件为 Linux 且传入-Drpm)通过 rpm-maven-plugin 生成 rpm 包。
七、Release 发布流程(面向仓库维护者)
CONTRIBUTING.md 给出了完整的发版 checklist,这是仓库维护者执行 Arthas 新版本发布的标准流程,包含源码同步、Maven 发布、文档与镜像更新三大阶段:
7.1 源码与构建准备
- 同步 vmtool 动态库:若 arthas-vmtool 有更新,先手动触发 build-vmtool 的 CI,构建后把新的动态库提交到 lib/ 目录;
- 统一版本号:修改 as.sh(仓库 README 中提到的启动脚本)、Bootstrap.java 中的版本、最后修改日期,以及 Dockerfile 中的版本;
- 配置 Maven settings:修改本地
settings.xml,配置发布所需的中央仓库认证信息; - 预热 gpg 后台进程:执行一次
gpg --sign /tmp/2.txt让 gpg 守护进程启动,否则打包可能失败(对应 pom.xml 中releaseprofile 的maven-gpg-plugin签名步骤,它配置了--pinentry-mode loopback)。
7.2 Maven Central 发布
- 执行发布命令:
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 代码、文档与镜像更新
- 打 tag:为本次发布打上 tag 并 push 到仓库;
- 更新 gh-pages:更新分支下的
arthas-boot.jar、math-game.jar、as.sh,下载 doc.zip 解压覆盖文档,可通过 update-doc 的 GitHub Action 自动完成; - 更新 Docker 镜像:推送新的 tag 到 Docker Hub,可通过 push-docker 的 GitHub Action 完成(注意:这里会用到当前仓库根目录下的 Dockerfile,其内部构建流程会拉取发行包制作镜像);
- 更新 README:如新增了命令,需要在 README.md 中补充说明并更新相关链接;
- 更新 Release 页面:整理 release 页面的 issue 信息与修改说明;
- 更新 latest_version API:更新
arthas.aliyun.com/api/latest_version接口返回的最新版本; - 更新内部版本:同步更新组织内部依赖的 Arthas 版本号。
八、结语
从本地开发者的 as-package.sh --fast 快速迭代,到需要同时维护多个本地版本时的 --use-version/--versions,再到维护者视角的 -P full 全量打包与 -P release 中央仓库发布,CONTRIBUTING.md 所描述的是一条被源码充分印证、可完整落地的工程链路。对想要深入 Arthas 内部实现的开发者而言,建议以此为起点,结合 as-package.sh、Bootstrap.java、packaging/pom.xml 三处关键文件反复对照研读,即可快速打通「改代码 → 打包 → 本地调试 → 发布」的完整闭环。