企业官网建设流程全解析

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 部署有本质区别。

选择这种方式，通常出于以下几个考量：

1. 环境限制：目标服务器无法访问Docker仓库，或不允许运行容器。
2. 版本锁定：生产环境要求绝对可控，需要明确每一个依赖库的版本，自行编译能确保二进制产物的纯净性。
3. 深度定制：需要对Pinpoint的源代码进行修改（例如定制采样策略、修改存储逻辑），编译是必经之路。
4. 学习与理解：对于想深入了解Pinpoint架构的新手或架构师而言，手动部署是绝佳的学习路径。

对于Pinpoint 2.3.3这个版本，它发布于2020年初，其依赖的Spring Boot、HBase等组件版本也相对固定，形成了一个稳定的技术栈组合。我们的部署目标，就是复原这个组合。

2.2 基础环境清单与关键要点

部署一套完整的Pinpoint，至少需要以下服务器角色（可以部署在同一台机器，但生产环境建议分离）：

• Collector服务器：负责接收来自被监控应用（Agent）的追踪数据。
• Web服务器：提供图形化查询界面。
• HBase服务器：作为存储后端，存放所有的追踪和指标数据。
• 被监控应用服务器：部署了Pinpoint Agent的业务系统。

以下是具体的环境要求，我会特别强调版本，因为这是成功编译和运行2.3.3版本的关键：

注意：环境准备阶段最易出错的就是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 -DskipTests=true -Dmaven.test.skip=true -Dcheckstyle.skip=true -Dfindbugs.skip=true

参数拆解与避坑指南：

• -DskipTests=true -Dmaven.test.skip=true：跳过单元测试和集成测试。强烈建议跳过，因为测试需要连接真实的HBase和Kafka等中间件，环境配置极其复杂，且对网络有要求，首次编译必定失败。
• -Dcheckstyle.skip=true -Dfindbugs.skip=true：跳过代码风格和缺陷检查。这些插件有时会因规则问题导致构建失败，为了快速得到产物，可以先跳过。
• 为什么不指定-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目录下找到对应的*.war（Web模块）和*.jar（Collector, Agent等）文件时，就成功了。

实操心得：编译机最好有4核CPU和8GB以上内存，否则可能因为内存不足导致Maven构建失败。如果遇到OutOfMemoryError，可以设置环境变量MAVEN_OPTS="-Xmx2048m -XX:MaxPermSize=512m"。另外，建议将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> <name>hbase.rootdir</name> <value>file:///data/hbase</value> <!-- 数据存储目录，请确保有写入权限 --> </property> <property> <name>hbase.zookeeper.property.dataDir</name> <value>/data/zookeeper</value> <!-- ZooKeeper数据目录 --> </property> <property> <name>hbase.unsafe.stream.capability.enforce</name> <value>false</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张表：

• AgentInfo
• AgentLifeCycle
• AgentStatV2
• ApplicationTraceIndex
• TraceV2
• StringMetadata
• SqlMetadataV2
• ApiMetadata

注意事项：初始化脚本只需要在HBase集群中执行一次。如果执行失败，检查网络连通性（能否访问localhost:2181）以及HBase是否正常运行。有时需要等待HBase完全启动后再执行脚本。

5. Collector与Web模块部署详解

5.1 Collector部署与配置

Collector是数据收集中心，需要配置端口、HBase连接等信息。

1. 准备部署目录：在Collector服务器上（假设是192.168.1.100），创建目录，例如/app/pinpoint-collector。
2. 复制产物：将编译好的pinpoint-collector/target/pinpoint-collector-2.3.3-SNAPSHOT.war文件复制到该目录。为了方便，我们将其重命名为collector.war。
3. 准备启动脚本：由于是WAR包，我们需要一个Web容器来运行。这里以常用的Tomcat 8为例（需JDK 8）。
   • 将collector.war放入Tomcat的webapps/目录下。
   • 更优雅的方式是配置Tomcat指向外部WAR包。编辑conf/server.xml，在<Host>标签内添加：

     <Context path="/" docBase="/app/pinpoint-collector/collector.war" />

4. 关键配置：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.host=localhost hbase.client.port=2181 # Collector自身暴露的端口（供Agent连接） collector.tcpListenPort=9994 collector.statListenPort=9995 collector.spanListenPort=9996 # 集群节点标识，单机可设为默认 collector.cluster.listen.ip=192.168.1.100

   • 修改Tomcat的启动脚本（如bin/catalina.sh），在JAVA_OPTS中添加：

     -Dpinpoint.collector.config=/app/pinpoint-collector/config/pinpoint-collector.properties

5. 启动Tomcat：bin/startup.sh。查看日志logs/catalina.out，确认没有错误，并且有看到成功连接HBase和启动Netty服务器的日志。

5.2 Web模块部署与配置

Web模块的部署流程与Collector类似，但配置文件和关注点不同。

1. 准备目录：在Web服务器上（假设是192.168.1.101），创建/app/pinpoint-web。
2. 复制产物：复制pinpoint-web/target/pinpoint-web-2.3.3-SNAPSHOT.war并重命名为web.war。
3. Tomcat部署：同样放入Tomcat的webapps/或通过Context指向。
4. 关键配置：Web模块需要知道Collector的地址和HBase的地址。
   • 解压默认配置：jar -xf web.war WEB-INF/classes/pinpoint-web.properties
   • 编辑外部配置文件/app/pinpoint-web/config/pinpoint-web.properties：

     # HBase配置（与Collector一致） hbase.client.host=localhost hbase.client.port=2181 # Collector集群地址，Web端会从这些Collector拉取配置和少量数据 cluster.zookeeper.address=192.168.1.100:2181 # 如果是多Collector，这里填ZooKeeper地址；单机且Collector与Web分开，也可直接配Collector地址 # 另一种简单配置：直接指定Collector地址（适用于简单环境） # cluster.tcp.port=9994 # cluster.address=192.168.1.100 # Web界面配置 admin.password=admin # 默认管理员密码，务必修改！

   • 在Tomcat的JAVA_OPTS中添加：

     -Dpinpoint.web.config=/app/pinpoint-web/config/pinpoint-web.properties

5. 启动与访问：启动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.applicationservertype=TOMCAT profiler.appname=MY_APPLICATION # 你的应用名，如“订单服务” profiler.agentid=host01-app-01 # 此实例的ID，通常用“主机名-序号” # Collector的地址和端口（TCP） profiler.collector.ip=192.168.1.100 profiler.collector.tcp.port=9994 profiler.collector.stat.port=9995 profiler.collector.span.port=9996 # 采样率，10000表示100%采样，生产环境可根据负载调整（如1000=10%） profiler.sampling.rate=10000

6.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.agentId=host01-app-01 -Dpinpoint.applicationName=MY_APPLICATION"

注意：这里通过-D参数覆盖了配置文件中的agentId和applicationName，这样做更灵活，可以为同一份Agent文件部署的不同实例指定不同名称。

对于Spring Boot的JAR包：

java -javaagent:/opt/pinpoint-agent/pinpoint-bootstrap-2.3.3-SNAPSHOT.jar \ -Dpinpoint.agentId=host01-app-01 \ -Dpinpoint.applicationName=MY_APPLICATION \ -jar your-application.jar

6.4 启动验证

1. 启动你的业务应用。
2. 检查Agent目录下的logs/pinpoint.log，看是否有错误。成功的日志会显示“Agent initialization completed”以及连接到Collector的信息。
3. 在Pinpoint Web界面的左侧应用列表中，稍等片刻（1-2分钟），应该能看到你配置的MY_APPLICATION应用出现。
4. 对应用发起一些请求（访问几个API），然后在Web界面上选择该应用，点击“调用链”查看，应该能看到追踪数据。

7. 常见问题与排查技巧实录

即使按照步骤操作，也难免会遇到问题。这里记录几个我当年部署2.3.3时遇到的典型问题及解决方法。

7.1 Collector/Web启动报错：HBase连接失败

现象：Tomcat日志中大量出现Could not connect to ZooKeeper或HBase connection exception。排查：

1. 网络与端口：在Collector/Web服务器上，使用telnet <hbase_host> 2181检查是否能连通HBase的ZooKeeper端口。
2. HBase状态：确认HBase已正常启动，jps命令能看到HMaster和HRegionServer进程。
3. 防火墙：检查服务器防火墙是否放行了2181端口。
4. 配置一致性：确认pinpoint-collector.properties和pinpoint-web.properties中的hbase.client.host和port配置正确，且与HBase实际配置的ZooKeeper地址一致（查看HBase的hbase-site.xml中的hbase.zookeeper.quorum）。

7.2 Web界面能看到应用，但无调用链数据

现象：应用列表中有你的应用，状态显示为“正常”，但点击进入后，调用链、统计图表全是空的。排查：

1. Agent日志：首先查看应用服务器的pinpoint-agent/logs/pinpoint.log，确认Agent是否成功发送数据。查找是否有“Send x spans to collector”之类的日志。如果没有，可能是Agent到Collector的网络不通。
2. Collector日志：查看Collector服务器的Tomcat日志（catalina.out或localhost.log），看是否有接收到来自该Agent的数据。搜索Agent的ID或IP。
3. 端口确认：Agent配置中的三个端口（9994, 9995, 9996）必须与Collector配置中监听的端口完全一致。并且这些端口在Collector服务器上是否被防火墙阻挡。
4. 采样率：检查pinpoint.config中的profiler.sampling.rate。如果设置得太低（如100表示1%采样），在低流量下可能很长时间都采不到一个请求。测试时可以暂时设为10000（100%采样）。

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界面操作响应慢，查询调用链耗时很长。排查与优化：

1. HBase性能：单机版HBase仅适用于测试。生产环境数据量稍大，性能瓶颈就在HBase。考虑部署HBase分布式集群。
2. 表预分区：Pinpoint初始化创建的HBase表默认只有一个Region。当数据量增长后，所有读写都集中在一个RegionServer上。需要根据数据量预估，对核心表（如TraceV2）进行预分区。这需要在初始化HBase表之前，修改hbase-create.hbase脚本中的建表语句，添加SPLITS参数。
3. Web JVM参数：给运行Pinpoint Web的Tomcat分配合适的堆内存（-Xmx4g -Xms4g），因为查询和聚合数据比较消耗内存。

部署完成后，一个健康的Pinpoint监控系统，其数据流应该是：应用Agent -> Collector -> HBase <- Web UI。你可以通过观察各组件日志、Web界面数据刷新情况以及系统资源监控，来持续验证其运行状态。这套2.3.3的“传统”部署方式，虽然步骤繁琐，但能让你对APM系统的每一个环节都了如指掌，在后续的问题排查和性能调优中，这种深入的理解会带来巨大的回报。