服务器Pinpoint教程：零基础部署APM监控与排错

Pinpoint 是一套开源的 APM 监控工具，用来追踪 Java 应用之间的调用链路、响应时间和异常。
它适合排查微服务里的慢请求，也适合观察单个应用的方法级耗时。
下面按零基础能照做的顺序，讲清在 Linux 服务器上部署 Pinpoint 并接入一个 Java 应用的完整过程。

先确认环境与要装哪些组件

Pinpoint 由三部分组成：Collector 接收 Agent 上报的数据，Web 提供查询界面，HBase 负责存储链路数据。
本文用 Docker 部署 HBase 和 Pinpoint 服务，因为这种方式对系统依赖少，升级也方便。

准备条件：

• 一台 Linux 服务器，建议 4 核 8G 以上，磁盘预留 20G 以上，HBase 比较吃内存。
• 已安装 Docker 和 Docker Compose。用 docker version 和 docker compose version 确认命令可用。
• 一个待监控的 Java 应用，且能修改它的启动参数。
• 服务器安全组或防火墙放行 Web 端口（默认 8080）和 Collector 的 gRPC 端口（常用 9991、9992、9993）。

如果服务器内存不足 4G，HBase 容易启动后自动退出。
可以先执行 free -h 查看可用内存，不够时先扩容或改用外部 HBase。

部署 HBase 存储

Pinpoint 的数据最终写入 HBase，所以先把它跑起来。

1. 创建目录并进入：

mkdir -p /opt/pinpoint && cd /opt/pinpoint

1. 新建 docker-compose-hbase.yml，内容如下：

version: '3'
services:
  hbase:
    image: pinpointdocker/pinpoint-hbase:2.5.0
    container_name: pinpoint-hbase
    ports:
      - "2181:2181"
      - "16010:16010"
    volumes:
      - ./hbase-data:/home/pinpoint/hbase
    restart: unless-stopped

1. 启动并检查：

docker compose -f docker-compose-hbase.yml up -d
docker logs -f pinpoint-hbase

当日志不再报错、出现 HBase 启动完成的信息后，用浏览器访问 http://服务器IP:16010，能看到 HBase 管理页说明存储正常。
若页面打不开，先查安全组，再用 ss -tlnp | grep 16010 确认端口已监听。

启动 Collector 与 Web 界面

HBase 就绪后，再启动 Pinpoint 的服务端。

1. 在同一个目录新建 docker-compose-pinpoint.yml：

version: '3'
services:
  pinpoint-collector:
    image: pinpointdocker/pinpoint-collector:2.5.0
    container_name: pinpoint-collector
    ports:
      - "9991:9991"
      - "9992:9992"
      - "9993:9993"
    environment:
      - HBASE_HOST=pinpoint-hbase
    depends_on:
      - hbase
    restart: unless-stopped

  pinpoint-web:
    image: pinpointdocker/pinpoint-web:2.5.0
    container_name: pinpoint-web
    ports:
      - "8080:8080"
    environment:
      - HBASE_HOST=pinpoint-hbase
    depends_on:
      - hbase
    restart: unless-stopped

1. 启动：

docker compose -f docker-compose-pinpoint.yml up -d
docker ps

1. 访问 http://服务器IP:8080，能看到 Pinpoint Web 首页即成功。首次打开可能没有数据，属于正常现象，需要等 Agent 上报。

给 Java 应用接入 Agent

服务端跑起来后，还要让业务应用把数据上报给 Collector。

1. 下载 Agent 包，解压到应用服务器上，例如 /opt/pinpoint-agent。
2. 编辑 pinpoint-root.config，重点改这几项：

profiler.collector.ip=Collector服务器IP
profiler.collector.grpc.port=9991
profiler.transport.grpc.collector.ip=Collector服务器IP

1. 在 Java 启动命令中加入 Agent 参数：

java -javaagent:/opt/pinpoint-agent/pinpoint-bootstrap-2.5.0.jar \
     -Dpinpoint.agentId=my-app-01 \
     -Dpinpoint.applicationName=my-app \
     -jar my-app.jar

agentId 要保证唯一，多个实例不要重复；applicationName 相同表示属于同一个应用，在 Web 上会聚合展示。

1. 重启应用，等一两分钟后回到 Web 界面，在应用列表里应能看到 my-app，点进去能看到调用链和响应时间。

常见报错怎么排查

接入过程中最容易卡在连接和端口上，按下面顺序查通常能定位。

• Agent 启动了但 Web 没数据：先看应用日志有没有 Agent 初始化信息，再确认 profiler.collector.ip 填的是 Collector 可达的 IP，不是 127.0.0.1。
• 报连接超时：在应用服务器上执行 telnet CollectorIP 9991，不通就检查防火墙、安全组和 Collector 容器是否在运行。
• HBase 反复重启：多半是内存不够，用 docker logs pinpoint-hbase 看具体错误，必要时增加服务器内存或限制容器内存。
• Web 打开空白或报错：确认 HBASE_HOST 环境变量指向 HBase 容器名，且两个 compose 文件在同一个 Docker 网络下，否则容器之间无法解析主机名。

涉及删除数据、重启容器或改动防火墙规则前，先确认这些操作不会影响同服务器上的其他业务，并保留一份配置备份。

验证监控是否真正生效

判断部署成功不能只看 Web 能不能打开，还要看数据是否持续写入。

• 在 Web 的应用列表里能看到自己注册的 applicationName。
• 点进应用后，Server Map 上出现节点，调用链里有请求记录。
• 访问一次业务接口，刷新 Web，响应时间图表有新增数据点。
• 用 docker stats 观察 HBase 和 Collector 容器，CPU 和内存没有持续飙高。

如果以上都满足，说明 Pinpoint 已经在正常采集。
后续可以根据业务量调整 Agent 采样率，避免高并发下产生过多链路数据。

Pinpoint 的部署难点主要不在安装命令，而在端口连通和内存分配。
先把 HBase 跑稳，再确认 Agent 到 Collector 的网络可达，最后用 Web 里的实时数据做验证，基本就能顺利完成这套服务器 Pinpoint 教程的落地。