# 时序数据三重视界：IoTDB数据目录、TsFile与资源文件查看方法论
**运维一个跑了两年的IoTDB集群，最怕的不是磁盘快满，而是不知道谁占了磁盘**。某风电企业曾因时序数据量突增导致节点宕机，复盘时发现：**根源是某张测试表忘记设TTL，三年前的风机模拟数据至今仍躺在TsFile里**。
IoTDB的文件体系并非黑盒。**数据目录、TsFile本体、资源索引文件——这三层载体分别对应运维视角、数据视角、索引视角**。掌握它们的查看方法，就能在磁盘报警之前把病灶挖出来。
## 一、数据目录：用工具“透视”文件分布
IoTDB的物理文件集中在`data/`下，分为三个子目录：**`data/data`存TsFile，`data/system`存元数据，`data/wal`存写前日志**。想知道每个存储组、每个时间分区实际占多少磁盘，靠`du -sh`一层层找太原始。
官方提供了专用脚本`print-iotdb-data-dir.sh`，位于`tools/tsfile/`目录下。执行后直接输出**数据目录的整体概览**，包括各层级文件数量与大小分布。
```bash
# 打印IoTDB数据目录全景视图
bash $IOTDB_HOME/tools/tsfile/print-iotdb-data-dir.sh
```
该命令底层调用`IoTDBDataDirViewer`类，**无需进入CLI即可快速定位“哪个存储组写最多”**，是容量规划的第一道防线。
## 二、TsFile Viewer：不用启库，直接读文件
**生产环境偶发数据查不到，第一反应是“服务挂了”？不一定——可能只是单个TsFile文件损坏**。此时若依赖IoTDB进程诊断，无异于用抽水机修水龙头。
**TsFile Viewer**是Apache官方提供的独立工具，**能在不启动数据库、不依赖任何服务的情况下，直接打开.tsfile文件，读取内部时序数据与Schema**。
**部署与使用**（需JDK 8+ & Maven）：
```bash
git clone https://github.com/apache/iotdb-tsfile-viewer.git
cd iotdb-tsfile-viewer
mvn clean package -Dmaven.test.skip=true
java -jar target/iotdb-tsfile-viewer-*.jar -path /path/to/file.tsfile
```
<"n7.p5k3.org.cn"><"w9.p5k3.org.cn"><"g2.p5k3.org.cn">
启动后自动打印**设备列表、测点类型、时间范围、数据样本**，**疑似文件损坏或格式异常时，这是最直接的验尸工具**。
**进阶用法**：通过API集成至巡检平台，定时扫描异常TsFile。
```java
try (TsFileSequenceReader reader = new TsFileSequenceReader("file.tsfile")) {
ReadOnlyTsFile roTsFile = reader.asReadOnlyTsFile();
// 遍历数据点...
}
```
**适用场景**：**离线分析、故障排查、教学演示**。某车企曾用此工具在10分钟内定位出某台边缘节点的TsFile时间戳错乱问题，而不用把文件拷回中心库。
## 三、资源文件：被忽略的“索引地图”
每个TsFile同目录下都有一个`.tsfile.resource`文件，**体积远小于TsFile，却包含该文件的时间范围、统计信息、测点索引**。它是IoTDB快速定位“哪个文件包含某段时间数据”的关键。
**查看方法**：目前暂无专用可视化工具，但可通过以下方式间接观察：
1. **CLI执行`flush`**，强制内存数据落盘，同时生成/更新resource文件；
2. **直接使用文本工具打开**（非编辑），确认文件完整性；
3. **依赖JMX MBean**：连接JConsole，在`org.apache.iotdb.service.MBeans`中查看`DataSizeInByte`、`TotalOpenFileNum`等指标，间接判断资源文件加载状态。
```bash
# resource文件与tsfile成对出现
-rw-r--r-- 16923456 1678901234567-1-0.tsfile
-rw-r--r-- 24576 1678901234567-1-0.tsfile.resource
```
<"q5.p5k3.org.cn"><"t1.p5k3.org.cn"><"i8.p5k3.org.cn">
**若resource文件丢失，启动时会自动重建，但大文件重建耗时显著，切勿在生产高峰手动删除**。
## 四、写在目录树之外：被误读的“隐藏文件”
除上述三类核心文件，IoTDB目录中还有几个**常被误删但实则重要的角色**：
**`mlog.bin`**：位于`data/system/schema/`，记录所有元数据操作日志。**没有它，重启后设备层级结构全失**。某团队误将此文件当作日志清理，导致整套时序模型必须从备份恢复。
**`tlog.txt`**：存储时序的标签与属性。默认每个时序占用约700字节，若标签滥用（如每个测点都挂长文本），此文件可能膨胀至GB级。
**`Version-{version}`**：空文件，文件名即版本号。**不是bug，是设计**——IoTDB用文件名记录最大版本号，删掉会导致版本号回退、数据写入错乱。
## 五、三条经验：什么该看，什么不该动
**第一，磁盘报警时先看数据目录，别急着加节点**。用`print-iotdb-data-dir.sh`找出“写最多却没设TTL”的存储组，`SET TTL TO root.ln.** 86400000` 一小时后磁盘自动释放。
**第二，TsFile Viewer是只读工具，放心用**。它不会修改文件，**即使误操作也最多抛出异常，不会破坏源文件**。适合集成进巡检脚本，每日扫描异常TsFile。
**第三，resource文件与wal目录禁止手工删除**。前者影响启动速度，后者导致已写入但未刷盘的数据丢失。**实在要清理空间，用`DELETE DATABASE`或`UNSET TTL`走SQL通道**，让IoTDB自己收拾残局。
**IoTDB的文件视图不是秘密，只是少有人系统性梳理**。数据目录给运维看容量，TsFile Viewer给开发查细节，resource文件给内核做索引——**三层工具对应三层诉求，用对场景，每个文件都在说话**。