Apache TsFile 常用 CLI 命令与工具详解

梳理 Apache TsFile 2.4.0 构建与运行命令：Maven 生命周期、依赖管理、exec:java 运行、java -cp 直跑、包内类检查与 jshell 常量查询，附 JVM 堆验证与报错定位。

Apache TsFileApache TsFile2026/10/12

Apache TsFile 常用 CLI 命令与工具详解

一、定位与准备

TsFile 是文件格式库，官方不提供独立 CLI 可执行程序（区别于 IoTDB 的 start-cli.sh）。因此本章沉淀的是「构建 + 运行 + 检查」三类命令：Maven 全生命周期、java 直跑、以及 jar/字节码级别的检查工具。全部命令实测于 tsfile 2.4.0（OpenJDK 17 + Maven 3.6.3/3.9.16）。

前置工程最小集（沿用 Maven 标准布局）：

mkdir -p /root/tsfile-demo/src/main/java/demo
cd /root/tsfile-demo

pom.xml 中与本章相关的关键片段（完整 pom 见《Ubuntu 22.04 安装 Apache TsFile 指南》4.2 节，两处一致）：

<properties>
    <tsfile.version>2.4.0</tsfile.version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.apache.tsfile</groupId>
        <artifactId>tsfile</artifactId>
        <version>${tsfile.version}</version>
    </dependency>
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-simple</artifactId>
        <version>2.0.17</version>
    </dependency>
</dependencies>

运行示例主类：demo.WriteDemo（写 4000 行生成 demo.tsfile）与 demo.ReadDemo（元数据遍历 + 时间窗口查询），源码见安装指南 4.3/4.4 节。

二、Maven 命令详解

2.1 生命周期命令

（1）编译：

export MAVEN_OPTS="-Xms256m -Xmx512m"
mvn -q compile

实测退出码 0。-q 只输出错误与警告，日常验证用；去掉 -q 可看到完整插件执行清单。

（2）清理 + 打包：

mvn -q clean package
ls target/*.jar

实测回显：

target/tsfile-demo-1.0.0.jar

注意：clean 会删除整个 target 目录，包括此前 dependency:copy-dependencies 生成的 target/dependency（实测踩坑：clean 之后再用旧依赖目录运行 java 会报 NoClassDefFoundError，需重新执行 copy-dependencies）。

2.2 依赖管理命令

（1）解析并下载全部依赖：

mvn -q dependency:resolve

实测：首次执行从 repo1.maven.org 拉取 tsfile-2.4.0 及 common/zstd-jni/snappy-java/lz4-java/xz/slf4j-api/antlr4-runtime，退出码 0。

（2）打印依赖树：

mvn dependency:tree

实测回显：

com.example:tsfile-demo:jar:1.0.0
+- org.apache.tsfile:tsfile:jar:2.4.0:compile
|  +- org.apache.tsfile:common:jar:2.4.0:compile
|  +- com.github.luben:zstd-jni:jar:1.5.6-3:compile
|  +- org.xerial.snappy:snappy-java:jar:1.1.10.5:compile
|  +- at.yawk.lz4:lz4-java:jar:1.10.1:compile
|  +- org.tukaani:xz:jar:1.10:compile
|  +- org.slf4j:slf4j-api:jar:2.0.17:compile
|  \- org.antlr:antlr4-runtime:jar:4.13.2:compile
\- org.slf4j:slf4j-simple:jar:2.0.17:compile

（3）复制运行时依赖到固定目录（配合 java -cp 直跑）：

mvn -q dependency:copy-dependencies -DoutputDirectory=target/dependency
ls target/dependency/

实测回显：

antlr4-runtime-4.13.2.jar
common-2.4.0.jar
lz4-java-1.10.1.jar
slf4j-api-2.0.17.jar
slf4j-simple-2.0.17.jar
snappy-java-1.1.10.5.jar
tsfile-2.4.0.jar
xz-1.10.jar
zstd-jni-1.5.6-3.jar

（4）不改 pom 临时切换版本（多版本排查利器，实测通过）：

mvn -q dependency:resolve -Dtsfile.version=1.1.4

实测退出码 0，~/.m2/repository/org/apache/tsfile/tsfile/1.1.4/ 出现对应 jar。

2.3 运行命令 exec:java

export MAVEN_OPTS="-Xms256m -Xmx512m -Dfile.encoding=UTF-8"
mvn -q compile exec:java -Dexec.mainClass=demo.WriteDemo

实测回显：

写入完成: /root/tsfile-demo/demo.tsfile 大小=9984 字节, 耗时=125ms

要点：

  1. exec:java 在 Maven 自身 JVM 内执行业务代码，因此堆由 MAVEN_OPTS 控制（256–512 MB 档位验证方式见第五章）。
  2. 中文乱码时给 MAVEN_OPTS 追加 -Dfile.encoding=UTF-8（实测 Maven 默认继承平台字符集导致乱码）。
  3. 常用参数：-Dexec.mainClass=完整类名；-Dexec.cleanupDaemonThreads=false 可关闭退出时的线程清理提示。

2.4 其他高频参数

参数作用实测场景
-q静默模式，仅错误输出日常编译验证
-e打印异常栈依赖冲突排查
-DskipTests跳过测试package 加速（本工程无测试用例）
-Dtsfile.version=1.1.4覆盖 pom 属性多版本切换验证

三、java 直跑方式

3.1 目录式 classpath（开发期）

java -Dfile.encoding=UTF-8 -cp 'target/classes:target/dependency/*' demo.ReadDemo

实测回显（节选）：

root.demo.device1 -> temperature : FLOAT
root.demo.device1 -> humidity : DOUBLE
root.demo.device1 -> status : TEXT
== 查询结果（root.demo.device1 temperature/humidity, 3 秒窗口） ==
1700000000000 | FLOAT:20.0 | DOUBLE:45.0
共命中 3 行（本次仅展示 3 行）

3.2 打包 jar 直跑（交付期）

mvn -q dependency:copy-dependencies -DoutputDirectory=target/dependency
java -Dfile.encoding=UTF-8 -cp 'target/tsfile-demo-1.0.0.jar:target/dependency/*' demo.ReadDemo

实测查询结果与 3.1 一致。默认打包不含 Main-Class 清单，java -jar 不可用；如需 -jar 形式，可在 pom 中加入 maven-shade-plugin 并设置 mainClass（属工程侧扩展）。

3.3 classpath 通配符必须加引号（实测坑）

错误写法（实测报错）：

Error: Unable to initialize main class demo.ReadDemo
Caused by: java.lang.NoClassDefFoundError: org/apache/tsfile/read/filter/basic/Filter

原因：-cp a.jar:dir/* 不加引号时，shell 会把 dir/* 展开成多个空格分隔的词，java 只收到第一个词，classpath 被截断。正确写法是把整段 classpath 用单引号包住，交由 JVM 自行展开通配符。

3.4 打包后运行的堆参数

直跑场景堆在命令行指定：

java -Xms256m -Xmx512m -cp 'target/tsfile-demo-1.0.0.jar:target/dependency/*' demo.WriteDemo

验证方式见第五章。

四、文件与包内检查工具

4.1 od 验证文件魔数

TsFile 文件首尾各有一段 TsFile 魔数（首部后跟版本字节，尾部前有 4 字节尾部长度）：

head -c 10 demo.tsfile | od -c | head -2
tail -c 10 demo.tsfile | od -c

实测回显：

0000000   T   s   F   i   l   e 004  \0 002 022
0000000  \0  \0  \0 302   T   s   F   i   l   e

4.2 jar tf 检查类是否在包内

JAR=~/.m2/repository/org/apache/tsfile/tsfile/2.4.0/tsfile-2.4.0.jar
jar tf $JAR | grep -E 'TsFileWriter|TsFileSequenceReader|Tablet.class'

实测回显：

org/apache/tsfile/read/TsFileSequenceReader.class
org/apache/tsfile/write/TsFileWriter.class
org/apache/tsfile/write/record/Tablet.class

排查 NoClassDefFoundError 时，先用该命令确认类所在 jar，再核对 classpath。

4.3 javap 查看 API 签名

javap -cp $JAR org.apache.tsfile.write.TsFileWriter | head -8

实测回显：

public class org.apache.tsfile.write.TsFileWriter implements java.lang.AutoCloseable {
  public org.apache.tsfile.write.TsFileWriter(java.io.File) throws java.io.IOException;
  public org.apache.tsfile.write.TsFileWriter(java.io.File, org.apache.tsfile.encrypt.EncryptParameter) throws java.io.IOException;
  public org.apache.tsfile.write.TsFileWriter(java.io.File, org.apache.tsfile.write.schema.Schema) throws java.io.IOException;
  public org.apache.tsfile.write.TsFileWriter(java.io.File, org.apache.tsfile.write.schema.Schema, org.apache.tsfile.common.conf.TSFileConfig) throws java.io.IOException;

需要私有字段/全部成员时加 -p。升级版本前后对比签名是快速发现 API 变化的办法（如 2.4.0 的 Tablet.setRowSize）。

4.4 jshell 查询常量

不写工程直接查包内常量：

echo 'System.out.println(org.apache.tsfile.common.conf.TSFileConfig.CONFIG_FILE_NAME);' \
  | jshell --class-path $JAR -s -

实测回显：

iotdb-system.properties

同法实测其他常量：MIN_BLOOM_FILTER_ERROR_RATE=0.01、MAX_BLOOM_FILTER_ERROR_RATE=0.1、RLE_MAX_REPEATED_NUM=32767、RLE_MAX_BIT_PACKED_NUM=63。

4.5 strings 提取配置键

cd /tmp && mkdir -p jarx && cd jarx
jar xf $JAR org/apache/tsfile/common/conf/TSFileDescriptor.class
strings org/apache/tsfile/common/conf/TSFileDescriptor.class | grep -E '^[a-z][a-z0-9_.]+$' | sort -u

实测可得 2.4.0 从 iotdb-system.properties 读取的全部键（page_size_in_byte、group_size_in_byte、compressor、float_precision、batch_size、lz4_use_jni、encrypt_type 等），是编写配置文件时最可靠的键名依据。

五、JVM 堆验证

标准动作三件套（程序运行期间在另一会话执行）：

（1）ps 回显（Ubuntu 22.04 + Maven 3.6.3 实测）：

ps -ef | grep [j]ava

root  7582  1 33 12:11 ?  00:00:04 /usr/bin/java -Xms256m -Xmx512m -classpath /usr/share/maven/boot/plexus-classworlds-2.x.jar ... org.codehaus.plexus.classworlds.launcher.Launcher -q exec:java -Dexec.mainClass=demo.HeapHolder

（2）jps -v 回显：

7582 Launcher -Xms256m -Xmx512m -Dclassworlds.conf=/usr/share/maven/bin/m2.conf ...

（3）程序内断言（主类第一行打印后驻留）：

maxMemory=512MB

CentOS 8 + Maven 3.9.16 环境的 ps 回显略有差异（多一个 JDK 17 原生访问开关参数），堆参数同样可见：

root  1625  1 31 12:32 ?  00:00:04 /usr/lib/jvm/java-17-openjdk/bin/java --enable-native-access=ALL-UNNAMED -Xms256m -Xmx512m ...

六、常见问题

Q1：mvn clean package 后 java -cp ... dependency/* 直跑报 NoClassDefFoundError？

A：clean 清掉了 target/dependency。重新执行 mvn dependency:copy-dependencies -DoutputDirectory=target/dependency 后再运行（实测复现）。

Q2：java -jar 提示 target/tsfile-demo-1.0.0.jar 中没有主清单属性？

A：默认 jar 不含 Main-Class。用 -cp 'app.jar:dependency/*' 主类名 直跑，或工程内引入 maven-shade-plugin 指定 mainClass 后再打包。

Q3：exec:java 输出中文乱码？

A：export MAVEN_OPTS="... -Dfile.encoding=UTF-8" 后重跑。

Q4：如何不写代码确认某配置键是否被 2.4.0 支持？

A：按 4.5 节 strings 提取 TSFileDescriptor 字节码键清单；不在清单中的字段（如 bloomFilterErrorRate）只能走代码 setter。

Q5：官方有没有 TsFile 专用 CLI 工具？

A：没有。tsfile 包内也未内置可执行 main 类（实测 jar tf 检索无 Main/Tools 入口），命令行形态就是「Maven 构建 + java 直跑 + jar/javap/jshell 检查」的组合。

七、参考链接