opentsdb 依赖 hbase，必须先部署并启动 hbase；它仅是 hbase 上层时序查询引擎，不存储数据；需确保 zookeeper 连通、时间同步、java 与 hbase 客户端版本兼容、timestamp 为秒级整数，且配置项如 zookeeper.quorum 和 table.name 准确无误。
OpenTSDB 依赖 HBase，必须先装好 HBase 且确保其正常运行
OpenTSDB 本身不存储数据，它只是 HBase 的上层时序查询引擎。如果 HBase 没跑起来，tsdb 启动会卡在 Failed to connect to HBase 或直接报 No route to host —— 这不是 OpenTSDB 的错，是底层连不上。
实操建议：
- HBase 必须启用
hbase.regionserver.thrift.framed（默认 false），否则 OpenTSDB 的 async client 无法通信；修改hbase-site.xml后重启 RegionServer - 确认
hbase.zookeeper.quorum指向的是 ZooKeeper 集群地址（不是 localhost），且所有节点时间同步（ntpd或chronyd） - 用
echo "status" | hbase shell -n检查 HBase 是否 ready；再用echo "list" | hbase shell -n看能否列出表（哪怕空） - OpenTSDB 不支持 HBase 3.x（截至 2.4.1），推荐搭配 HBase 2.4.x 或 2.3.x；HBase 2.5+ 需要 patch
AsyncTable兼容性代码
编译或下载 tsdb 二进制时，注意 Java 版本和 HBase 客户端 ABI 兼容性
OpenTSDB 2.4.x 编译依赖 Java 8/11，但运行时若 HBase 是用 Java 11 编译的，而你用 Java 8 启动 tsdb，大概率遇到 NoClassDefFoundError: org/apache/hadoop/hbase/client/AsyncConnectionBuilder —— 这是 HBase 客户端 API 在不同 Java 版本下二进制不兼容。
实操建议：
- 优先下载官方预编译包（如
opentsdb-2.4.1.tar.gz），而非自己用 Maven 打包；官网包已绑定对应 HBase 2.4.9 客户端 - 检查
tsdb启动脚本中的JAVA_HOME和HBASE_HOME，确保指向同一套 Java + HBase 环境 - 若需自定义编译，务必在
pom.xml中锁定hbase-client版本（例如2.4.9），并用mvn clean package -DskipTests -Dhbase.version=2.4.9 - 启动前执行
./build/tsdb mkmetric --force sys.cpu.user测试写入通路；失败时看日志里是否含Unsupported major.minor version（Java 版本错）或ClassNotFoundException（jar 包缺失）
tsdb.conf 配置中，zookeeper.quorum 和 table.name 是最常配错的两个参数
tsdb.conf 里看似简单，但只要 zookeeper.quorum 少写一个 IP，或 table.name 和实际 HBase 表名不一致（比如忘了加 namespace），tsdb 就会静默失败——不报错、不监听端口、netstat -tlnp | grep 4242 看不到进程。
实操建议：
-
zookeeper.quorum必须和hbase-site.xml中的hbase.zookeeper.quorum完全一致，包括端口（默认2181）；不能写成localhost，得是集群真实 IP 列表，如zk1:2181,zk2:2181,zk3:2181 -
table.name默认是tsdb，但如果你用 HBase namespace（如prod:tsdb），这里必须写全，且确保该 namespace 已通过create_namespace 'prod'创建 - 不要删掉
tsd.core.auto_create_metrics = true，否则写入未定义 metric 会直接 400；调试阶段可临时设为false观察日志中 metric 是否被拒绝 - 改完配置后，用
./build/tsdb tsd --debug --config=tsdb.conf启动，观察控制台是否输出Starting up TSD...和Bound to port 4242；没有就回头查 ZooKeeper 连接日志
写入数据时 timestamp 必须是秒级 Unix 时间戳，且不能早于 HBase 表创建时间
OpenTSDB 要求所有写入的 timestamp 是整数秒（非毫秒），单位是自 1970-01-01 的秒数。如果传了毫秒值（比如 JS 的 Date.now()），数据会写进 HBase 但查询永远返回空——因为 OpenTSDB 内部按秒对齐 rowkey，毫秒值导致 key 错位。
实操建议：
- HTTP 写入时，
put请求体中的timestamp字段必须是1672531200这样的整数，不是"1672531200"字符串，更不能是1672531200123 - 用
curl -X POST -d '{"metric":"sys.cpu.nice","timestamp":1672531200,"value":18,"tags":{"host":"web01"}}测试，成功返回空响应（204）才表示写入成功 - 如果写入后查不到，先执行
echo "scan 'tsdb'" | hbase shell -n | head -20，看 HBase 表里有没有生成类似0000016725312000000000000000000000000000的 rowkey（前 12 位是秒级时间的 hex） - 注意：HBase 表一旦创建，OpenTSDB 不会自动清理过期数据；长期运行需配合 TTL 设置（
HColumnDescriptor.setTimeToLive(86400 * 30)）或外部 compaction 脚本
OpenTSDB 的部署难点不在安装命令，而在 HBase 生态链路上的隐式约束：ZooKeeper 连接状态、HBase 客户端 ABI、时间戳单位、rowkey 构造逻辑，这些地方一错，它就不响、不写、不查，还几乎不报错。盯着 tsdb.log 里 “Connected to ZooKeeper” 和 “Created connection to HBase” 这两行，比反复重装快得多。
