Pinpoint 3.1.1 常用 CLI 命令与工具详解

目标：把 Pinpoint 3.1.1 日常运维会用到的四组命令工具——HBase Shell（存储层检查与维护）、Compose 服务管理（启停与日志）、Agent 侧参数验证（JVM/探针配置落盘）、REST API（curl 查询）——逐一讲清用法、参数与真实回显。所有命令与输出均来自 Ubuntu 22.04.4 LTS 实测环境（Docker Compose 部署形态，部署过程见本专栏《Pinpoint 3.1.1 Docker Compose 部署指南》）。

一、环境信息

操作系统：Ubuntu 22.04.4 LTS（x86_64）
部署形态：Docker Compose（Docker 29.8.1 + Compose v5.5.1），项目名 pinpoint-311-stack，部署目录 /opt/pinpoint
Pinpoint 版本：3.1.1；组件版本：HBase 2.2.6、ZooKeeper 3.4.13、MySQL 8.0.46、Redis 7.0.14
Java 运行时：Web/Collector 为 Java 17；HBase 容器自带 JDK 8（含 jps）；示例应用为 JDK 8 + Tomcat 8
服务端口：8148 → Web 控制台、8149 → HBase Master UI、8150 → 示例应用、8151 → MySQL
统一取证日期：2026-10-23

二、工具概览

Pinpoint 自身不带管理 CLI——它的「命令行工具面」由四层构成，各自解决不同问题：

工具组	载体	解决什么问题	本文章节
HBase Shell	hbase 服务内置（`/opt/hbase/hbase-2.2.6/bin/hbase shell`）	存储层检查：表清单、表结构/TTL、数据抽查、TTL 在线修改	第四章
Compose 服务管理	宿主机 `docker compose`	服务启停、日志、进入、销毁	第五章
Agent 侧验证工具	`ps`/`grep`/`jps` + 启动日志	确认应用挂上了探针、JVM 堆与探针配置落盘是否生效	第六章
REST API	`curl` 指向 Web 控制台 8148	脚本化查询：应用列表、Agent 状态、拓扑 JSON、服务器时间	第七章

💡 说明：Pinpoint 没有类似 pinpointctl 的官方统一 CLI。日常运维的实际形态就是「HBase shell 管存储 + compose 管服务 + curl 查数据」三件套，Web 控制台承担可视化部分。

三、前置条件

已按《Pinpoint 3.1.1 Docker Compose 部署指南》完成部署，全套服务 Up；
链路已贯通（Agent 已注册），验证命令与实测回显：

curl -s http://localhost:8148/api/applications

[{"applicationName":"quickapp","serviceType":"TOMCAT","code":1010}]

以下命令均在部署目录执行（compose 子命令依赖该目录下的 docker-compose.yml）：

cd /opt/pinpoint

四、HBase Shell 工具详解

HBase Shell 是 JRuby 交互式解释器，Pinpoint 的 22 张表、TTL、数据分布都在这一层检查。工具本体在 hbase 服务内：/opt/hbase/hbase-2.2.6/bin/hbase shell。

4.1 进入与退出

docker compose exec pinpoint-hbase /opt/hbase/hbase-2.2.6/bin/hbase shell

进入后实测回显（首尾节选，略去 SLF4J 提示行）：

HBase Shell
Use "help" to get list of supported commands.
Use "exit" to quit this interactive shell.
For Reference, please visit: http://hbase.apache.org/2.0/book.html#shell
Version 2.2.6, r88c9a386176e2c2b5fd9915d0e9d3ce17d0e456e, Tue Sep 15 17:36:14 CST 2020
hbase(main):001:0>

退出：输入 exit 回车；
非交互式（脚本/管道场景）必须加 -T 分配伪终端以外的执行通道，实测形态：

echo 'status
exit' | docker compose exec -T pinpoint-hbase /opt/hbase/hbase-2.2.6/bin/hbase shell

⚠️ 注意：exec 不带 -T 跑管道会因无 TTY 报 stty: 'standard input': Inappropriate ioctl for device，虽然命令仍会执行，但脚本里建议统一 -T。

4.2 version 与 status：确认集群活着

version 看版本，status 看集群成员状态。实测回显（shell 内执行）：

hbase(main):001:0> version
Version 2.2.6, r88c9a386176e2c2b5fd9915d0e9d3ce17d0e456e, Tue Sep 15 17:36:14 CST 2020

hbase(main):002:0> status
1 active master, 0 backup masters, 1 servers, 0 dead, 1908.0000 average load

解读：1 active master 一主在位、1 servers, 0 dead 一个 RegionServer 在线无掉线——单机部署的健康形态。若 status 显示 0 servers，说明 HRegionServer 没起来，先看 docker compose logs pinpoint-hbase。

4.3 list：查看 Pinpoint 全部表

hbase(main):003:0> list
TABLE                                                                                      
AgentEvent                                                                                 
AgentId                                                                                    
AgentInfo                                                                                  
AgentLifeCycle                                                                             
ApiMetaData                                                                                
Application                                                                                
ApplicationIndex                                                                           
ApplicationMapStatisticsCallee_Ver2                                                        
ApplicationMapStatisticsCaller_Ver2                                                        
ApplicationMapStatisticsSelf_Ver2                                                          
ApplicationTraceIndex                                                                      
HostApplicationMap_Ver2                                                                    
MapAgentSelf                                                                               
MapAppHost                                                                                 
MapAppIn                                                                                   
MapAppOut                                                                                  
MapAppSelf                                                                                 
SqlMetaData_Ver2                                                                           
SqlUidMetaData                                                                             
StringMetaData                                                                             
TraceIndex                                                                                 
TraceV2                                                                                    
22 row(s)

解读：22 张表即 Pinpoint 3.1.1 全套 schema——TraceV2/TraceIndex 存调用链明细与索引，三张 ApplicationMapStatistics*_Ver2 存拓扑统计，五张 MapApp*/MapAgent* 是 3.1 新增的 ServerMap V3 表，AgentInfo/AgentId 存探针注册信息，Sql/String/ApiMetaData 存元数据。部署完看不到 22 张表说明建表流程没走完（首启 hbase 服务会先等 15 秒再建表）。

4.4 desc：查看表结构与 TTL

hbase(main):004:0> desc 'AgentInfo'
Table AgentInfo is ENABLED
AgentInfo
COLUMN FAMILIES DESCRIPTION
{NAME => 'Info', VERSIONS => '1', EVICT_BLOCKS_ON_CLOSE => 'false', NEW_VERSION_BEHAVIOR => 'false', KEEP_DELETED_CELLS => 'FALSE', CACHE_DATA_ON_WRITE => 'false', DATA_BLOCK_ENCODING => 'PREFIX', TTL => '31536000 SECONDS (365 DAYS)', MIN_VERSIONS => '0', REPLICATION_SCOPE => '0', BLOOMFILTER => 'ROW', CACHE_INDEX_ON_WRITE => 'false', IN_MEMORY => 'false', CACHE_BLOOMS_ON_WRITE => 'false', PREFETCH_BLOCKS_ON_OPEN => 'false', COMPRESSION => 'NONE', BLOCKCACHE => 'true', BLOCKSIZE => '65536'}

⚠️ 注意：表名必须带单引号。实测不带引号直接报错：
hbase(main):005:0> desc AgentInfo
NameError: uninitialized constant AgentInfo
这是 JRuby 把裸词当 Ruby 常量解析导致的，所有 shell 命令的表名都照此处理。

4.5 scan 与 count：数据抽查

scan 抽样看行、count 数行数，验证「数据真的落库了」。实测（Application 表存应用注册信息）：

hbase(main):006:0> scan 'Application', {LIMIT => 3}
ROW                   COLUMN+CELL
 \x00...\x00quickapp\x00...\x03\xF2  column=A:A, timestamp=1792714147372, value=\x00
1 row(s)

hbase(main):007:0> count 'Application'
1 row(s)

解读：行键是二进制拼串（应用名 quickapp 混在其中），行尾的 \x03\xF2 十进制正是 1010 = TOMCAT 的 serviceTypeCode——探针注册类型直接可见。空表返回 0 row(s) 属正常（说明该维度还没数据）。

4.6 alter：TTL 在线修改（实测含语法陷阱）

Pinpoint 各表的 TTL 由 compose 环境变量在建表时写定；首启后要改保留期，用 alter 在线改。实测先踩到的陷阱——不带列族名会被静默忽略：

hbase(main):008:0> alter 'AgentEvent', {TTL => '6048000'}
Unknown argument ignored: TTL
Updating all regions with the new schema...
1/1 regions updated.
Done.
Took 2.5537 seconds

命令"成功"返回，但 desc 'AgentEvent' 复查 TTL 仍是 5184000 SECONDS (60 DAYS)——Unknown argument ignored: TTL 这行才是真相。正确写法必须带 NAME => '列族'：

hbase(main):009:0> alter 'AgentEvent', {NAME => 'E', TTL => '6048000'}
Updating all regions with the new schema...
1/1 regions updated.
Done.
Took 2.1043 seconds

hbase(main):010:0> desc 'AgentEvent'
Table AgentEvent is ENABLED
AgentEvent
COLUMN FAMILIES DESCRIPTION
{NAME => 'E', VERSIONS => '1', EVICT_BLOCKS_ON_CLOSE => 'false', NEW_VERSION_BEHAVIOR => 'false', KEEP_DELETED_CELLS => 'FALSE', CACHE_DATA_ON_WRITE => 'false', DATA_BLOCK_ENCODING => 'PREFIX', TTL => '6048000 SECONDS (70 DAYS)', MIN_VERSIONS => '0', REPLICATION_SCOPE => '0', BLOOMFILTER => 'ROW', CACHE_INDEX_ON_WRITE => 'false', IN_MEMORY => 'false', CACHE_BLOOMS_ON_WRITE => 'false', PREFETCH_BLOCKS_ON_OPEN => 'false', COMPRESSION => 'NONE', BLOCKCACHE => 'true', BLOCKSIZE => '65536'}

TTL => '6048000 SECONDS (70 DAYS)' 修改生效。各表列族名先 desc 查（实测：AgentInfo 列族 Info、AgentEvent 列族 E、TraceV2 列族 S）。

4.7 建表脚本：TTL 的源头

compose 里的 *_TTL 环境变量由 hbase 服务的 configure-hbase.sh sed 进建表脚本，脚本实测位于 /opt/hbase/hbase-create.hbase（36 行）与 /opt/hbase/hbase-update-ttl.hbase（36 行）。抽查内容实测：

docker compose exec pinpoint-hbase sh -c "grep -n \"create 'AgentInfo'\|create 'TraceV2'\" /opt/hbase/hbase-create.hbase"

实测回显：

1:create 'AgentInfo', { NAME => 'Info', TTL => 31536000, DATA_BLOCK_ENCODING => 'PREFIX' }
13:create 'TraceV2', { NAME => 'S', TTL => 5184000, DATA_BLOCK_ENCODING => 'PREFIX' }, {NUMREGIONS => 256, SPLITALGO => 'UniformSplit'}

解读：TTL 值（31536000/5184000）就是环境变量替换的结果；TraceV2 预分 256 个 region（NUMREGIONS => 256）——这是写入压力最大的表，别手抖重建它。首启时 check-table.sh 用 exists 'AgentId' 判断表是否已建，不存在才执行这个脚本。

五、Compose 服务管理命令

5.1 状态与日志

docker compose ps

实测回显（节选，STATUS 列全部 Up）：

NAME                      IMAGE                                       COMMAND                   SERVICE              CREATED         STATUS         PORTS
pinpoint-311-agent        pinpointdocker/pinpoint-agent:3.1.1         "/usr/local/bin/conf…"   pinpoint-agent        5 minutes ago   Up 5 minutes
pinpoint-311-collector    pinpointdocker/pinpoint-collector:3.1.1     "java -cp @/app/jib-…"   pinpoint-collector    5 minutes ago   Up 5 minutes
pinpoint-311-hbase        pinpointdocker/pinpoint-hbase:3.1.1         "/bin/sh -c '/usr/lo…"   pinpoint-hbase        5 minutes ago   Up 5 minutes   0.0.0.0:8149->16010/tcp, [::]:8149->16010/tcp
pinpoint-311-web          pinpointdocker/pinpoint-web:3.1.1           "java -cp @/app/jib-…"   pinpoint-web          5 minutes ago   Up 5 minutes   0.0.0.0:8148->8080/tcp, [::]:8148->8080/tcp

日志命令（-f 跟踪、--tail 限定行数），实测（collector 的 gRPC 配置回显）：

docker compose logs --tail 200 pinpoint-collector 2>&1 | grep -m4 'collector.receiver.grpc'

pinpoint-311-collector  |  ::                    collector.receiver.grpc.agent.enable ::                                true
pinpoint-311-collector  |  ::            collector.receiver.grpc.agent.bindaddress.ip ::                             0.0.0.0
pinpoint-311-collector  |  ::           collector.receiver.grpc.agent.bindaddress.port ::                                 9991
pinpoint-311-collector  |  ::           collector.receiver.grpc.agent.ssl.enable ::                                false

5.2 单服务启停

停 web（实测回显）：

docker compose stop pinpoint-web

 Container pinpoint-311-web Stopping
 Container pinpoint-311-web Stopped

启 web（实测回显）：

docker compose start pinpoint-web

 Container pinpoint-311-web Starting
 Container pinpoint-311-web Started

确认状态：

docker ps --format '{{.Names}} {{.Status}}' | grep pinpoint-311-web

pinpoint-311-web Up 3 seconds

重启单个服务用 docker compose restart <服务名>。

5.3 整体启停与销毁

docker compose stop      # 全部停止，保留数据卷
docker compose start     # 全部启动
docker compose down      # 删除容器与网络，保留数据卷（数据还在）
docker compose down -v   # 连数据卷一起删（链路数据清零，慎用）

down -v 实测回显（尾部节选）：

 Container pinpoint-311-zoo1 Removed
 Container pinpoint-311-zoo3 Removed
 Container pinpoint-311-zoo2 Removed
 Volume pinpoint-311-stack_data-volume Removing
 Volume pinpoint-311-stack_mysql_data Removing
 Volume pinpoint-311-stack_hbase_data Removing
 Network pinpoint-311-net Removing
 Volume pinpoint-311-stack_data-volume Removed
 Volume pinpoint-311-stack_mysql_data Removed
 Network pinpoint-311-net Removed
 Volume pinpoint-311-stack_hbase_data Removed

⚠️ 注意：HBase/collector 每次冷启动都要 Warmup 与建表检查，从 stop 到整链路再次可用约 3–5 分钟，期间 Web 报「HBase 连接失败」属正常。

5.4 exec：进入容器执行工具

本文所有「容器内命令」都走这一通道，两种形态：

# 交互式进入（人操作）
docker compose exec pinpoint-hbase /opt/hbase/hbase-2.2.6/bin/hbase shell

# 一次性执行（脚本/管道用，加 -T）
docker compose exec -T pinpoint-hbase /opt/hbase/hbase-2.2.6/bin/hbase version

另有一个文件通道 docker compose cp，用于把容器内配置文件拷出修改（目标目录要先 mkdir，详见《Pinpoint 3.1.1 配置参数详解》3.3 节实测说明）。

六、Agent 侧参数与验证工具

Agent 是「不跑业务的探针目录 + 应用侧 JVM 参数」的组合，验证手段集中在「参数有没有落到应用进程上」。

6.1 应用侧启动参数

compose 里示例应用通过 JAVA_OPTS 注入完整探针参数（实测值）：

    environment:
      JAVA_OPTS: "-Xms256m -Xmx512m -javaagent:/pinpoint-agent/pinpoint-bootstrap.jar -Dpinpoint.agentId=app-in-docker -Dpinpoint.applicationName=quickapp -Dpinpoint.profiler.profiles.active=release"

参数逐项说明：

参数	实测值	约束	说明
-javaagent	/pinpoint-agent/pinpoint-bootstrap.jar	路径必须可达	探针入口（共享卷挂载）
-Dpinpoint.agentId	app-in-docker	≤24 字符，同应用内唯一	实例 ID
-Dpinpoint.applicationName	quickapp	2.x ≤24 字符；3.1 加 `-Dpinpoint.modules.uid.version=v3` 可至 254	应用名（拓扑聚合维度）
-Dpinpoint.profiler.profiles.active	release	local/release	探针配置集

生产接入真实应用时，把同一组参数加到应用的启动命令即可（应用需能访问 collector 的 9991/9992/9993 端口）。

6.2 JVM 参数验证

验证应用进程参数（ps aux 截取，能看到完整 java 启动行）：

docker compose exec pinpoint-quickstart ps aux | grep [j]ava

/opt/java/openjdk/bin/java -Djava.util.logging.config.file=/usr/local/tomcat/conf/logging.properties -Xms256m -Xmx512m -javaagent:/pinpoint-agent/pinpoint-bootstrap.jar -Dpinpoint.agentId=app-in-docker -Dpinpoint.applicationName=quickapp -Dpinpoint.profiler.profiles.active=release ... org.apache.catalina.startup.Bootstrap start

验证 web/collector 堆：两服务用 JAVA_TOOL_OPTIONS 注入堆（-Xms256m -Xmx512m），启动日志开头实测：

pinpoint-311-collector  | Picked up JAVA_TOOL_OPTIONS: -Xms256m -Xmx512m

docker compose logs pinpoint-collector 2>&1 | grep -m1 'Picked up'

验证 HBase 堆（hbase 容器自带 JDK 8 的 jps，实测）：

docker compose exec pinpoint-hbase jps -v

164 HRegionServer -Dproc_regionserver -XX:OnOutOfMemoryError=kill -9 %p -Xmx512m -XX:+UseConcMarkSweepGC -XX:PermSize=128m -XX:MaxPermSize=128m -Dhbase.log.dir=/opt/hbase/hbase-2.2.6/logs -Dhbase.log.file=hbase--regionserver-81e9a8749ae7.log -Dhbase.home.dir=/opt/hbase/hbase-2.2.6 -Dhbase.id.str= -Dhbase.root.logger=INFO,RFA -Dhbase.security.logger=INFO,RFAS
88 HMaster -Dproc_master -XX:OnOutOfMemoryError=kill -9 %p -Xmx512m -XX:+UseConcMarkSweepGC -XX:PermSize=128m -XX:MaxPermSize=128m -Dhbase.log.dir=/opt/hbase/hbase-2.2.6/logs -Dhbase.log.file=hbase--master-81e9a8749ae7.log -Dhbase.home.dir=/opt/hbase/hbase-2.2.6 -Dhbase.id.str= -Dhbase.root.logger=INFO,RFA -Dhbase.security.logger=INFO,RFAS
15224 Jps -Dapplication.home=/usr/local/openjdk-8 -Xms8m

HMaster 与 HRegionServer 均 -Xmx512m（由 HBASE_HEAPSIZE=512m 换算）。

6.3 探针配置落盘检查

agent 服务的入口脚本把环境变量 sed 进探针配置文件。改完采样等参数后，用 grep 核对落盘值（经共享卷从挂载探针的应用侧读取，实测）：

docker compose exec pinpoint-quickstart grep -E '^profiler\.transport\.grpc\.(agent|metadata|stat|span)\.collector\.port' /pinpoint-agent/pinpoint-root.config

profiler.transport.grpc.agent.collector.port=9991
profiler.transport.grpc.metadata.collector.port=9991
profiler.transport.grpc.stat.collector.port=9992
profiler.transport.grpc.span.collector.port=9993

docker compose exec pinpoint-quickstart grep -nE '^profiler\.(transport\.module|sampling\.(type|counting\.sampling-rate|percent\.sampling-rate|new\.throughput|continue\.throughput))' /pinpoint-agent/profiles/release/pinpoint.config

19:profiler.transport.module=GRPC
56:profiler.sampling.type=COUNTING
62:profiler.sampling.counting.sampling-rate=1
69:profiler.sampling.percent.sampling-rate=100
73:profiler.sampling.new.throughput=0
75:profiler.sampling.continue.throughput=0

参数含义与修改路径见《Pinpoint 3.1.1 配置参数详解》5.4 节。

七、REST API 工具（curl）

Web 控制台 8148 端口同时暴露一套无认证的查询 API（默认部署形态），curl 即可脚本化查询。时间参数统一为 epoch 毫秒，窗口受 serverMapPeriodMax=2（天）约束。

7.1 应用列表：/api/applications

curl -s http://localhost:8148/api/applications

[{"applicationName":"quickapp","serviceType":"TOMCAT","code":1010}]

这是所有查询的起点：后续任何 API 的 serviceType 参数都必须以这里的返回为准（不能臆测 SPRING_BOOT）。

7.2 Agent 状态：/api/v1/agents

FROM=$((($(date +%s)-600)*1000)); TO=$(date +%s)000
curl -s "http://localhost:8148/api/v1/agents?applicationName=quickapp&from=${FROM}&to=${TO}"

实测回显（节选格式化）：

[{"agentId":"app-in-docker","agentStartTime":1792716268585,"agentName":"app-in-docker","state":{"code":100,"desc":"Running"},"currentState":{"code":100,"desc":"Running"},"currentStateTimestamp":1792716580099,"applicationName":"quickapp","serviceTypeCode":1010,"serviceTypeName":"TOMCAT"}]

state.code=100（Running）即探针在线；重启过 collector 的场景用它确认 Agent 已自动重连。

7.3 拓扑数据：/api/servermap/serverMap

FROM=$((($(date +%s)-3600)*1000)); TO=$(date +%s)000
curl -s "http://localhost:8148/api/servermap/serverMap?serviceName=DEFAULT&applicationName=quickapp&serviceTypeName=TOMCAT&serviceTypeCode=1010&from=${FROM}&to=${TO}&callerRange=1&calleeRange=1&bidirectional=false&wasOnly=false"

实测返回结构（解析后节选）：

{"applicationMapData": {"timestamp": [1792713480000, 1792713540000, ...共 61 个毫秒时间槽...],
  "nodeDataArray": [
    {"applicationName":"USER","serviceType":"USER", ...},
    {"applicationName":"quickapp","serviceType":"TOMCAT", ...}],
  "linkDataArray": [
    {"from":"quickapp_TOMCAT^USER","to":"quickapp^TOMCAT","key":"quickapp_TOMCAT^USER~quickapp^TOMCAT", ...}]}}

解读：两个节点（USER 来源 + quickapp 应用）、一条链路（USER→quickapp）；响应体约数十 KB，脚本化处理建议先落文件再用 python3 -m json.tool 或 jq 解析。

⚠️ 注意：老路径 GET /api/servermap 在 3.1.x 已不存在，实测返回 404（No static resource），必须用 /api/servermap/serverMap。

7.4 serviceMap 与 filterServerMap

/api/servermap/serviceMap（新版服务地图）与 /api/servermap/filterServerMap（按条件过滤的拓扑）端点存在于路由表，但 serviceMap 在默认 compose 镜像未启用，实测直接抛异常：

[AOP] ERROR MapController.getServiceMapData execution time:0ms param:[ApplicationForm{serviceName='DEFAULT', applicationName='quickapp', ...}] error:Service map is not enabled
java.lang.UnsupportedOperationException: Service map is not enabled

filterServerMap 可用，参数在 serverMap 基础上增加过滤条件（如 filter 传节点串）。

7.5 其他常用端点

实测可用的端点清单（均 GET，http://localhost:8148 前缀）：

端点	用途
/api/serverTime	服务器时间（对时用，实测返回 `{"currentServerTime":1792717123411}`）
/api/getScatterData	散点图数据（响应时间分布）
/api/transaction/trace、/api/transactionmetadata	单笔事务调用栈与元数据
/api/inspector/agentStat/chart	Agent JVM 统计（内存/GC/CPU）
/api/getAgentEvents、/api/getAgentStatusTimeline	Agent 事件与状态时间线
/api/getDetailedAgentInfo、/api/agents/overview、/api/agents/statistics	Agent 明细/总览/统计
/api/user、/api/userGroup、/api/alarmRule、/api/configuration	用户/用户组/告警规则/配置管理
/api/heatmap/applicationData、/api/otlp/metricData	热力图与 OTLP 指标查询

⚠️ 注意：/api/v2/agents 是 v2 表接口，缺 serviceType 参数直接 400，实测回显：
{"type":"about:blank","title":"Bad Request","status":400,"detail":"Invalid serviceType. ServiceType is required for v2 table","instance":"/api/v2/agents","method":"GET","parameters":{"applicationName":["quickapp"],"from":["1792713523000"],"to":["1792717123000"]}, ...}
日常查询用 /api/v1/agents 即可，不踩这个坑。

八、注意事项

HBase Shell 表名一律带单引号：desc AgentInfo 报 NameError（JRuby 常量解析），desc 'AgentInfo' 才对（见 4.4 实测）；
管道调 hbase shell 必须加 -T：echo 'cmd' | docker compose exec -T pinpoint-hbase …/hbase shell，否则有 TTY 告警；
alter TTL 必须带列族名：{TTL => …} 会被 Unknown argument ignored 静默忽略，{NAME => '列族', TTL => …} 才生效（见 4.6 实测）；
serviceType 以 API 返回为准：拓扑、Agent、散点查询的 serviceType 参数都来自 /api/applications，臆测类型只会查到空数据；
查询窗口 ≤2 天：拓扑窗口上限由 serverMapPeriodMax 控制（实测 2 天），API 直调同样受限，更久远的数据分段查；
down -v 清数据：链路明细全部在 pinpoint-311-stack_hbase_data 卷里，销毁前先确认不再需要；
collector 就绪要约 8 分钟：Warmup + gRPC bind 完成前 Agent 上报全部落空并刷 Connection refused，Agent 会自动重试，别急着重启；
API 无认证：默认 compose 形态下 8148 的 REST API 与控制台都没有登录拦截（实测登录开关不生效），生产前置反向代理做认证后再暴露。

九、常见问题

Q1：curl -I http://localhost:8150/index.html 返回 405？ 该镜像对 HEAD 请求不开放（Allow: GET）。实测换 GET 形式即 200：curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8150/index.html。验活一律用 GET。

Q2：拓扑 API 返回空 nodeDataArray？ 时间窗内没有数据落库。先制造流量（curl http://localhost:8150/sleep3.pinpoint，实测约 3 秒返回 200），等 1–2 分钟再查；仍为空则按第七章 7.1 核对 serviceType。

Q3：hbase shell 里命令敲错退格乱码？ 交互式进入时分配了 TTY 一般正常；若乱码，改用 docker compose exec -it 或改走管道 -T 形态逐条执行。

Q4：scan 输出一堆 \x00 十六进制看不懂？ Pinpoint 行键是二进制拼串（应用名/AgentId/时间倒排混合），属正常存储设计。定位数据是否存在看行数（count）与行内可读片段（如应用名、serviceTypeCode）即可。

Q5：/api/servermap/serviceMap 想启用怎么办？ 该功能需要专门的数据链路与开关支撑，默认 compose 镜像未提供（实测 UnsupportedOperationException）。常规拓扑用 /api/servermap/serverMap 完全覆盖。

Q6：改了 compose 环境变量，Agent 侧 grep 出来的还是旧值？ configure-agent.sh 只在 agent 服务启动时写探针文件，改完要 docker compose up -d pinpoint-agent 重建，再重启挂载探针的应用（示例应用场景一起重启），然后用 6.3 的 grep 复查。

十、参考链接

本站系列：《Pinpoint 3.1.1 介绍与选型指南》（定位、架构、新特性与选型对比）
本站系列：《Pinpoint 3.1.1 Docker Compose 部署指南》（从零部署、数据持久化与等价 docker run）
本站系列：《Pinpoint 3.1.1 配置参数详解》（参数位置、默认值与生产模板）
主仓库：https://github.com/pinpoint-apm/pinpoint
官方文档站：https://pinpoint-apm.gitbook.io/pinpoint
HBase 2.2 Book（shell 命令参考）：https://hbase.apache.org/2.0/book.html