1. 项目概述一次“复古”的Pinpoint部署之旅最近在整理技术资产时翻到了一个老项目的监控需求目标环境比较特殊要求使用Pinpoint 2.3.3这个相对早期的版本并且明确要求通过“传统方式”进行部署。这让我想起了几年前当容器化和Kubernetes还未像今天这样普及时我们是如何一步步手动搭建起这套分布式追踪系统的。对于很多维护历史系统、或是在特定受限环境如某些内网、无外网或严格版本管控的环境中工作的朋友来说这种“传统”的编译部署方式依然是必须掌握的技能。它不像用Docker Compose一键拉起那么简单直观但深入其中你能更透彻地理解Pinpoint的组件构成、依赖关系和工作原理。今天我就以Pinpoint 2.3.3为例带你完整走一遍从零开始的安装部署流程过程中会穿插大量当时踩坑后总结的经验希望能帮你绕过那些“暗礁”。2. 环境准备与核心思路解析2.1 为什么选择“传统方式”在动手之前我们先明确一下“传统方式”指的是什么。它通常意味着从官方GitHub仓库拉取指定版本的源代码在本地或构建服务器上使用Maven或Gradle进行编译打包生成可执行的JAR包或WAR包然后手动配置每一台服务器上的环境变量、启动脚本和配置文件最后按顺序启动各个组件。这与使用Docker镜像或 Helm Chart 部署有本质区别。选择这种方式通常出于以下几个考量环境限制目标服务器无法访问Docker仓库或不允许运行容器。版本锁定生产环境要求绝对可控需要明确每一个依赖库的版本自行编译能确保二进制产物的纯净性。深度定制需要对Pinpoint的源代码进行修改例如定制采样策略、修改存储逻辑编译是必经之路。学习与理解对于想深入了解Pinpoint架构的新手或架构师而言手动部署是绝佳的学习路径。对于Pinpoint 2.3.3这个版本它发布于2020年初其依赖的Spring Boot、HBase等组件版本也相对固定形成了一个稳定的技术栈组合。我们的部署目标就是复原这个组合。2.2 基础环境清单与关键要点部署一套完整的Pinpoint至少需要以下服务器角色可以部署在同一台机器但生产环境建议分离Collector服务器负责接收来自被监控应用Agent的追踪数据。Web服务器提供图形化查询界面。HBase服务器作为存储后端存放所有的追踪和指标数据。被监控应用服务器部署了Pinpoint Agent的业务系统。以下是具体的环境要求我会特别强调版本因为这是成功编译和运行2.3.3版本的关键组件要求版本说明与注意事项JDKOracle JDK 8或OpenJDK 8必须使用JDK 8。Pinpoint 2.3.3的代码语法和部分依赖库如HBase Client与JDK 11存在兼容性问题。建议使用1.8.0_212或之后的更新版本。Maven3.2.x 或 3.5.x版本要求不严格但建议使用3.5.x以获取更好的稳定性。需要配置好阿里云等国内镜像以加速构建。Git最新稳定版即可用于克隆源代码。HBase1.2.x或1.4.x强烈推荐使用 HBase 1.4.10。这是经过大量实践验证与Pinpoint 2.3.3兼容性最好的版本。2.x版本API变化较大需要修改Pinpoint代码不推荐。存储至少100GB可用空间HBase数据目录需要充足空间具体取决于应用数量和采样率。注意环境准备阶段最易出错的就是JDK版本。我曾因为服务器默认是JDK 11而浪费了半天时间排查各种诡异的NoSuchMethodError和ClassNotFoundException。务必在所有目标服务器上统一使用JDK 8并通过java -version和javac -version双重确认。3. 源码获取与编译构建3.1 克隆与切换指定版本首先找一台用于编译的机器可以是你本地开发机也可以是内网的构建服务器确保JDK 8和Maven已正确安装。# 1. 克隆Pinpoint官方仓库如果网络慢可以考虑使用Gitee的镜像 git clone https://github.com/pinpoint-apm/pinpoint.git cd pinpoint # 2. 切换到 2.3.3 这个tag git checkout tags/v2.3.3这里有个关键操作检查一下pom.xml根目录下的hbase.version属性。在v2.3.3标签下它通常定义为1.2.6或一个可配置的属性。我们计划使用HBase 1.4.10但官方pom可能未显式支持。不过没关系Pinpoint的模块化做得很好我们可以在编译时通过参数覆盖。3.2 Maven编译命令与参数详解进入pinpoint根目录执行编译命令。这是整个过程中最耗时且最容易出错的环节。# 在pinpoint目录下执行 mvn clean install -DskipTeststrue -Dmaven.test.skiptrue -Dcheckstyle.skiptrue -Dfindbugs.skiptrue参数拆解与避坑指南-DskipTeststrue -Dmaven.test.skiptrue跳过单元测试和集成测试。强烈建议跳过因为测试需要连接真实的HBase和Kafka等中间件环境配置极其复杂且对网络有要求首次编译必定失败。-Dcheckstyle.skiptrue -Dfindbugs.skiptrue跳过代码风格和缺陷检查。这些插件有时会因规则问题导致构建失败为了快速得到产物可以先跳过。为什么不指定-Phbase-1.4Profile在Pinpoint 2.3.x版本中对HBase 1.4的支持可能还不是通过标准的Maven Profile来切换而是通过依赖版本号控制。更稳妥的做法是编译时不指定特殊Profile如果运行时出现HBase API不兼容我们再考虑单独替换hbase-client等依赖jar包。实际上Pinpoint Collector和Web对HBase Client的调用封装得较好1.2.x和1.4.x的兼容性在2.3.3版本上通常可以工作。编译过程会下载大量依赖耗时可能在30分钟到2小时不等取决于网络。如果遇到某个依赖下载失败可以尝试多次执行命令或者检查Maven的settings.xml是否配置了速度更快的国内镜像。编译成功标志当你看到大量的[INFO] BUILD SUCCESS输出并且在各模块的target目录下找到对应的*.warWeb模块和*.jarCollector, Agent等文件时就成功了。实操心得编译机最好有4核CPU和8GB以上内存否则可能因为内存不足导致Maven构建失败。如果遇到OutOfMemoryError可以设置环境变量MAVEN_OPTS-Xmx2048m -XX:MaxPermSize512m。另外建议将Maven本地仓库.m2/repository备份起来以后在其他环境部署时可以直接复用节省大量下载时间。4. 部署HBase存储层Pinpoint的数据存储依赖于HBase。在部署Collector和Web之前必须先让HBase运行起来。4.1 HBase 1.4.10单机模式部署对于测试或小规模环境单机模式足够。这里以Linux系统为例。# 1. 下载并解压 wget https://archive.apache.org/dist/hbase/1.4.10/hbase-1.4.10-bin.tar.gz tar -zxvf hbase-1.4.10-bin.tar.gz -C /opt/ cd /opt/hbase-1.4.10 # 2. 配置JAVA_HOME编辑 conf/hbase-env.sh echo export JAVA_HOME/usr/lib/jvm/java-8-openjdk-amd64 conf/hbase-env.sh # 请将路径替换为你实际的JDK 8安装路径 # 3. 配置单机模式编辑 conf/hbase-site.xml在conf/hbase-site.xml的configuration标签内添加property namehbase.rootdir/name valuefile:///data/hbase/value !-- 数据存储目录请确保有写入权限 -- /property property namehbase.zookeeper.property.dataDir/name value/data/zookeeper/value !-- ZooKeeper数据目录 -- /property property namehbase.unsafe.stream.capability.enforce/name valuefalse/value !-- 避免本地文件系统兼容性警告 -- /property# 4. 启动HBase bin/start-hbase.sh # 5. 验证 bin/hbase shell hbase(main):001:0 list # 应该能看到类似下面的表但初始时空表 TABLE 0 row(s)4.2 初始化Pinpoint所需的HBase表Pinpoint需要特定的HBase表来存储数据。官方提供了创建脚本。我们需要使用刚编译好的Pinpoint工具包或者直接从GitHub仓库获取对应版本的脚本。更推荐的做法使用我们刚才编译产物中的tools模块。# 进入编译输出的tools目录 cd pinpoint/tools/target/pinpoint-tools-2.3.3-SNAPSHOT/ # 执行初始化脚本指定HBase的ZooKeeper地址单机模式默认是localhost:2181 java -jar pinpoint-hbase-init-2.3.3-SNAPSHOT.jar -zk localhost:2181执行成功后再次进入hbase shell执行list命令你应该能看到创建好的4张表AgentInfoAgentLifeCycleAgentStatV2ApplicationTraceIndexTraceV2StringMetadataSqlMetadataV2ApiMetadata注意事项初始化脚本只需要在HBase集群中执行一次。如果执行失败检查网络连通性能否访问localhost:2181以及HBase是否正常运行。有时需要等待HBase完全启动后再执行脚本。5. Collector与Web模块部署详解5.1 Collector部署与配置Collector是数据收集中心需要配置端口、HBase连接等信息。准备部署目录在Collector服务器上假设是192.168.1.100创建目录例如/app/pinpoint-collector。复制产物将编译好的pinpoint-collector/target/pinpoint-collector-2.3.3-SNAPSHOT.war文件复制到该目录。为了方便我们将其重命名为collector.war。准备启动脚本由于是WAR包我们需要一个Web容器来运行。这里以常用的Tomcat 8为例需JDK 8。将collector.war放入Tomcat的webapps/目录下。更优雅的方式是配置Tomcat指向外部WAR包。编辑conf/server.xml在Host标签内添加Context path/ docBase/app/pinpoint-collector/collector.war /关键配置Pinpoint的配置主要通过外部配置文件或JVM参数覆盖。最重要的配置文件是WEB-INF/classes/pinpoint-collector.properties。但WAR包内的文件不便修改我们可以在Tomcat的启动参数中指定外部配置文件位置。创建外部配置目录/app/pinpoint-collector/config/从WAR包中解压出默认配置文件作为模板jar -xf collector.war WEB-INF/classes/pinpoint-collector.properties cp WEB-INF/classes/pinpoint-collector.properties /app/pinpoint-collector/config/编辑/app/pinpoint-collector/config/pinpoint-collector.properties修改核心项# HBase ZooKeeper地址 hbase.client.hostlocalhost hbase.client.port2181 # Collector自身暴露的端口供Agent连接 collector.tcpListenPort9994 collector.statListenPort9995 collector.spanListenPort9996 # 集群节点标识单机可设为默认 collector.cluster.listen.ip192.168.1.100修改Tomcat的启动脚本如bin/catalina.sh在JAVA_OPTS中添加-Dpinpoint.collector.config/app/pinpoint-collector/config/pinpoint-collector.properties启动Tomcatbin/startup.sh。查看日志logs/catalina.out确认没有错误并且有看到成功连接HBase和启动Netty服务器的日志。5.2 Web模块部署与配置Web模块的部署流程与Collector类似但配置文件和关注点不同。准备目录在Web服务器上假设是192.168.1.101创建/app/pinpoint-web。复制产物复制pinpoint-web/target/pinpoint-web-2.3.3-SNAPSHOT.war并重命名为web.war。Tomcat部署同样放入Tomcat的webapps/或通过Context指向。关键配置Web模块需要知道Collector的地址和HBase的地址。解压默认配置jar -xf web.war WEB-INF/classes/pinpoint-web.properties编辑外部配置文件/app/pinpoint-web/config/pinpoint-web.properties# HBase配置与Collector一致 hbase.client.hostlocalhost hbase.client.port2181 # Collector集群地址Web端会从这些Collector拉取配置和少量数据 cluster.zookeeper.address192.168.1.100:2181 # 如果是多Collector这里填ZooKeeper地址单机且Collector与Web分开也可直接配Collector地址 # 另一种简单配置直接指定Collector地址适用于简单环境 # cluster.tcp.port9994 # cluster.address192.168.1.100 # Web界面配置 admin.passwordadmin # 默认管理员密码务必修改在Tomcat的JAVA_OPTS中添加-Dpinpoint.web.config/app/pinpoint-web/config/pinpoint-web.properties启动与访问启动Tomcat后访问http://192.168.1.101:8080假设Tomcat端口8080应该能看到Pinpoint Web的登录界面。使用用户名admin和配置文件中设置的密码登录。6. Agent配置与应用集成这是将你的业务应用接入Pinpoint监控的最后一步也是最常出问题的一步。6.1 Agent文件准备编译后在pinpoint-agent/target/目录下你会找到一个类似pinpoint-agent-2.3.3-SNAPSHOT.tar.gz的压缩包。将其解压到应用服务器上的某个目录例如/opt/pinpoint-agent。目录结构应包含/opt/pinpoint-agent/ ├── boot/ ├── lib/ ├── plugin/ ├── logs/ (启动后生成) ├── pinpoint-bootstrap-2.3.3-SNAPSHOT.jar ├── pinpoint.config └── ...6.2 配置Agent核心配置文件是pinpoint.config。你需要修改以下几个关键项# Agent标识全局唯一用于在Web界面区分不同应用实例 profiler.applicationservertypeTOMCAT profiler.appnameMY_APPLICATION # 你的应用名如“订单服务” profiler.agentidhost01-app-01 # 此实例的ID通常用“主机名-序号” # Collector的地址和端口TCP profiler.collector.ip192.168.1.100 profiler.collector.tcp.port9994 profiler.collector.stat.port9995 profiler.collector.span.port9996 # 采样率10000表示100%采样生产环境可根据负载调整如100010% profiler.sampling.rate100006.3 集成到Java应用启动命令这是最关键的一步。你需要修改你的Java应用启动脚本例如Tomcat的catalina.sh、Spring Boot的java -jar命令添加Pinpoint Agent作为Java Agent。对于Tomcat修改bin/catalina.sh找到JAVA_OPTS或CATALINA_OPTS的设置位置添加JAVA_OPTS$JAVA_OPTS -javaagent:/opt/pinpoint-agent/pinpoint-bootstrap-2.3.3-SNAPSHOT.jar JAVA_OPTS$JAVA_OPTS -Dpinpoint.agentIdhost01-app-01 -Dpinpoint.applicationNameMY_APPLICATION注意这里通过-D参数覆盖了配置文件中的agentId和applicationName这样做更灵活可以为同一份Agent文件部署的不同实例指定不同名称。对于Spring Boot的JAR包java -javaagent:/opt/pinpoint-agent/pinpoint-bootstrap-2.3.3-SNAPSHOT.jar \ -Dpinpoint.agentIdhost01-app-01 \ -Dpinpoint.applicationNameMY_APPLICATION \ -jar your-application.jar6.4 启动验证启动你的业务应用。检查Agent目录下的logs/pinpoint.log看是否有错误。成功的日志会显示“Agent initialization completed”以及连接到Collector的信息。在Pinpoint Web界面的左侧应用列表中稍等片刻1-2分钟应该能看到你配置的MY_APPLICATION应用出现。对应用发起一些请求访问几个API然后在Web界面上选择该应用点击“调用链”查看应该能看到追踪数据。7. 常见问题与排查技巧实录即使按照步骤操作也难免会遇到问题。这里记录几个我当年部署2.3.3时遇到的典型问题及解决方法。7.1 Collector/Web启动报错HBase连接失败现象Tomcat日志中大量出现Could not connect to ZooKeeper或HBase connection exception。排查网络与端口在Collector/Web服务器上使用telnet hbase_host 2181检查是否能连通HBase的ZooKeeper端口。HBase状态确认HBase已正常启动jps命令能看到HMaster和HRegionServer进程。防火墙检查服务器防火墙是否放行了2181端口。配置一致性确认pinpoint-collector.properties和pinpoint-web.properties中的hbase.client.host和port配置正确且与HBase实际配置的ZooKeeper地址一致查看HBase的hbase-site.xml中的hbase.zookeeper.quorum。7.2 Web界面能看到应用但无调用链数据现象应用列表中有你的应用状态显示为“正常”但点击进入后调用链、统计图表全是空的。排查Agent日志首先查看应用服务器的pinpoint-agent/logs/pinpoint.log确认Agent是否成功发送数据。查找是否有“Send x spans to collector”之类的日志。如果没有可能是Agent到Collector的网络不通。Collector日志查看Collector服务器的Tomcat日志catalina.out或localhost.log看是否有接收到来自该Agent的数据。搜索Agent的ID或IP。端口确认Agent配置中的三个端口9994, 9995, 9996必须与Collector配置中监听的端口完全一致。并且这些端口在Collector服务器上是否被防火墙阻挡。采样率检查pinpoint.config中的profiler.sampling.rate。如果设置得太低如100表示1%采样在低流量下可能很长时间都采不到一个请求。测试时可以暂时设为10000100%采样。7.3 应用启动时抛出“Unsupported major.minor version”错误现象在添加-javaagent参数启动应用时直接报错终止。原因这几乎可以肯定是JDK版本不匹配。Pinpoint Agent 2.3.3是使用JDK 8编译的。如果你的业务应用使用更高版本的JDK如11或17运行就会因字节码版本不兼容而报错。解决必须将整个环境统一到JDK 8。包括运行HBase、Collector、Web、业务应用的JVM都必须使用JDK 8。7.4 数据查询缓慢或Web界面卡顿现象Web界面操作响应慢查询调用链耗时很长。排查与优化HBase性能单机版HBase仅适用于测试。生产环境数据量稍大性能瓶颈就在HBase。考虑部署HBase分布式集群。表预分区Pinpoint初始化创建的HBase表默认只有一个Region。当数据量增长后所有读写都集中在一个RegionServer上。需要根据数据量预估对核心表如TraceV2进行预分区。这需要在初始化HBase表之前修改hbase-create.hbase脚本中的建表语句添加SPLITS参数。Web JVM参数给运行Pinpoint Web的Tomcat分配合适的堆内存-Xmx4g -Xms4g因为查询和聚合数据比较消耗内存。部署完成后一个健康的Pinpoint监控系统其数据流应该是应用Agent - Collector - HBase - Web UI。你可以通过观察各组件日志、Web界面数据刷新情况以及系统资源监控来持续验证其运行状态。这套2.3.3的“传统”部署方式虽然步骤繁琐但能让你对APM系统的每一个环节都了如指掌在后续的问题排查和性能调优中这种深入的理解会带来巨大的回报。