存储管理

存储路径设置

默认存储路径和系统要求

下表列出了 KaiwuDB 各类文件的默认存储路径、文件系统和配置信息。

文件	默认路径	大小	文件系统	配置参数
数据文件	/var/lib/kaiwudb	取决于存储数据的大小	- 建议使用 ext4 文件系统。 - 如果存储大于 16 TB 的数据，建议使用 XFS 系统。	- 部署配置文件中的 data_root 参数 - --store 启动参数
日志	/var/lib/kaiwudb/logs	默认 1G，可配置	建议使用 ext4 文件系统。	--log-dir 启动参数
证书	/etc/kaiwudb/certs	N/A	建议使用 ext4 文件系统。	--certs-dir 启动参数
二进制文件	/usr/local/kaiwudb/bin	> 200 M	建议使用 ext4 文件系统。	N/A
动态库文件	/usr/local/kaiwudb/lib	> 100 M	建议使用 ext4 文件系统。	N/A

说明

如果采用 Docker 容器部署，则使用宿主机路径，系统自动进行挂载。

存储路径设置

KaiwuDB 支持以下存储路径设置方式：

• 安装时通过修改 deploy.cfg 文件中的 data_root 参数自定义数据路径。
• 部署完成后，用户也可以通过修改部署生成的 kaiwudb_env 文件、 docker-compose.yml 文件或 kwbase start 命令修改存储路径。

预分配空间管理

KaiwuDB 支持通过 ts.disk_free_space.alert_threshold 实时参数设置时序数据的预分配空间告警阈值，实现存储空间的智能管理。

系统需要创建新的数据段（segment）以存储新写入的时序数据时，会自动检查节点剩余存储空间，并根据设置的阈值决定是否执行预分配操作：

• 如果节点剩余存储空间达到配置的阈值，系统将不进行预分配操作，并返回提示信息。单机版本仍支持数据查询，但数据无法写入或导入。分布式集群下，该节点进入宕机状态。
• 如果用户未配置预分配空间告警阈值，即采用默认值 0 B，表示不启用预分配空间管理功能，此时，如果剩余空间不足，预分配空间操作将执行失败，分布式集群下，该节点将进入宕机状态。

预分配空间告警阈值的设置取决于表的结构特征，具体计算方式如下:

ts.disk_free_space.alert_threshold (B) ≥ (type_a_size * column_number_a + type_b_size * column_number_b + ...) * ts.blocks_per_segment.max_limit * ts.rows_per_block.max_limit

其中：

• type_X_size：各数据类型所占的字节数，参见预估磁盘使用量。
• column_number_X：各数据类型对应的列数。
• ts.blocks_per_segment.max_limit：时序数据分片下每个数据段中可存储的数据块数量，默认值为 1000。
• ts.rows_per_block.max_limit ：每个数据块中可存储的数据行数，默认值为 1000。

例如，INT8 数据类型占用的字节数是 8 字节，对于一个包含 100 列 INT8 类型的表，如果 ts.blocks_per_segment.max_limit 和 ts.rows_per_block.max_limit 均采用默认值 1000，预分配空间告警阈值应不小于：8 * 100 * 1000 * 1000 = 800 MB。

冷热数据分级存储

KaiwuDB 通过分级存储机制智能管理时序数据。系统会根据数据的采集时间，自动将数据存储到热温冷级别的存储目录中，同时支持根据热温数据的保存时长自动将数据迁移到合适的存储层级。

这一机制不仅优化了存储资源的使用，还在保障数据访问性能的同时，有效降低存储成本。

时序冷热数据分级存储功能默认关闭，如果节点已经启动，用户完成分级存储目录设置后，需要重启节点才能使配置生效。在分布式集群中，每个节点需要单独配置，未配置的节点将保持分级存储功能关闭。

存储目录类型

存储目录分为主存储目录和普通存储目录。

• 主存储目录：时序数据的默认存储目录，默认存储级别为 0 级。

  • 时序数据默认与关系数据存储在 KaiwuDB 部署时，deploy.cfg 文件中自定义的数据路径。裸机部署时，时序数据默认存储在 /var/lib/kaiwudb 下的 tsdb 子目录。容器部署时，系统将使用宿主机路径并自动挂载。
  • KaiwuDB 同时支持用户通过 --ts-store 启动参数自定义时序数据的存储路径，将时序数据与关系数据分开存储。此时，--ts-store 参数指定的路径为主存储目录。有关启动参数的配置说明，参见启动参数配置。

• 普通存储目录：除主存储目录之外的其他存储目录，无默认优先级。用户可通过 ts_tier.cfg 配置文件灵活设置目录和存储级别。

存储目录配置

KaiwuDB 启动后，系统将自动在主存储目录创建 ts_tier.cfg 文件，用于管理主存储目录和普通存储目录。用户也可以在启动前在主存储目录手动创建 ts_tier.cfg 文件，提前完成存储目录和冷热级别设置。

ts_tier.cfg 文件采用 CSV 格式，配置格式如下：

<dir_path>, <level>

其中：

• dir_path ：普通存储目录的具体路径，主存储目录路径无需添加到配置文件中。
• level：存储目录的冷热级别，支持设置为 0、1、2，分别对应“热”、“温”、“冷”级别。注意：冷热级别设置只支持 0,1,2 或 0,1 两种组合方式。

配置示例：

/data0/kwdb1,0
/data1/kwdb2,0
/data2/kwdb3,1
/data3/kwdb4,1
/data4/kwdb5,2

KaiwuDB 支持用户在线添加普通存储目录，以应对实际时序写入量的变化。完成目录配置后，需要重启当前节点，配置才能生效。

注意

• 添加 0 级磁盘可以增加磁盘 IO, 提升数据写入和查询性能。由于 1 级和 2 级磁盘的 IO 低于 0 级磁盘，添加过多 1 级和 2 级磁盘可能会影响查询性能。
• 如果同一层级的目录已写满或达到预分配空间设置的告警阈值，分布式集群中的该节点将进入宕机状态。
• 目前不支持删除配置文件中已添加的存储目录。如果删除的目录中已写入数据，并且取消了对应设备的挂载，将导致数据丢失。

数据分级管理

用户可以通过以下 SQL 命令定义热、温、冷数据的划分规则：

SET CLUSTER SETTING ts.tier.duration = "<period>,<period>";

默认设置为 30d,90d，表示:

• 30 天内采集的时序数据为热数据，存储在 0 级存储目录。
• 30 至 90 天内采集的时序数据为温数据，存储在 1 级存储目录。
• 90 天以上的数据为冷数据，存储在 2 级存储目录。

冷数据的存储时长不受时间设置的影响，实际存储时间取决于数据的生命周期。

时间单位只支持 d (天)。 系统将根据时间变化自动由热到温或温到冷迁移数据。

提示

如果仅设置了 0 级和 1 级存储目录，温数据的时间设置将不再生效，数据迁移到 1 级存储目录后，将按照数据的生命周期进行保存，直到生命周期结束。

数据压缩

数据压缩是用更少的空间对原有数据进行编码的过程，其核心在于去除冗余和不必要的数据，同时保持数据的核心信息和完整性。

KaiwuDB 支持对时序数据进行在线周期性压缩与即时压缩，确保用户享受自动压缩便利的同时，可以根据需求进行手动压缩，以灵活优化存储空间和数据管理；具备 5-30 倍的数据压缩能力，有助于降低数据存储成本；系统可以直接挂载压缩数据，无需解压缩即可查询数据。

压缩方式

KaiwuDB 支持周期性压缩与即时压缩两种压缩方式：

周期性压缩

系统根据用户设置的数据活跃时间自动进行的数据压缩。

周期性压缩在后台执行，系统会在每个压缩周期内，自动检测是否有数据超过指定的活跃时间，初次检测到符合条件的数据段会被标记为 InActiveSegment，在下个周期压缩为 squashfs 格式，从而释放存储空间。

时序数据的默认活跃时间为 1 天。用户可通过创建表和修改表语句的 active_duration 参数设置活跃时间或取消周期性数据压缩功能。active_duration 参数更多信息，参见创建表和修改表。

即时压缩

即时压缩为需要快速响应的数据压缩需求设计，不依赖活跃时间设置，可以在任何时间对数据进行快速压缩，适合数据迁移或希望即时释放空间的场景。

用户可根据需要手动执行 COMPRESS 压缩命令，系统将立即对所有符合条件的数据段执行压缩。用户可通过 KaiwuDB 监控平台的语句页面查看压缩语句的开始时间和执行进度，也可以通过 immediate_compression.threads 实时参数设置即时压缩使用的线程数。

压缩完成时间取决于待压缩的数据量，待压缩的数据量越大，所需的时间越长。

有关压缩命令更多信息，参见即时压缩；有关 KaiwuDB 监控平台更多信息，参见 KaiwuDB 监控平台；有关 immediate_compression.threads 实时参数更多信息，参见实时参数。

压缩方式对比

下表列出了周期性压缩和即时压缩的区别：

特性	周期性压缩	即时压缩
触发方式	系统根据数据活跃时间设置自动触发	用户手动触发，即刻执行
压缩条件	根据时序表数据的活跃时间判定，初次检测到符合条件的数据段会标记为 InActiveSegment，到下个周期正式压缩	无需判定活跃时间，直接对目标数据执行压缩
默认活跃时间	1天，支持创建表和修改表时设置活跃时间	无活跃时间要求
适用场景	日常数据库运维和优化	数据迁移或即时释放空间的场景

说明

周期性压缩和即时压缩同时触发时，系统会根据触发顺序自动调整：

• 如果周期性压缩先触发，即时压缩会等待周期性压缩完成后再执行；
• 如果即时压缩先触发，系统将跳过本次周期性压缩。

数据压缩算法

KaiwuDB 支持通过 ts.compression.type 实时参数为时序数据配置以下无损压缩算法：

• GZIP：对于要压缩的文件，GZIP 首先使用 LZ77 算法的一个变种进行压缩，对得到的结果再使用 Huffman 编码的方法进行压缩，压缩率很高，但比较耗时。
• LZ4：属于 LZ77 压缩方案家族，压缩比并不高，但是解码速度极快。
• LZMA：LZMA（Lempel-Ziv-Markov chain Algorithm）是一种 DEFLATE 和 LZ77 算法改良和优化后的压缩算法。它使用类似于 LZ77 的字典编码机制。
• LZO：LZO 是块压缩算法，属于 LZ77 压缩方案家族。该算法旨在快速压缩和解压缩。由于块中可能存放多种类型的数据，整体的压缩效果没有针对某一种数据类型进行压缩的算法好。
• XZ：采用 LZMA2 算法，具有非常高的压缩比，但压缩和解压速度相对较慢。
• ZSTD（Zstandard）：是一种提供高压缩比的快速压缩算法。ZSTD 采用有限状态熵（Finite State Entropy，FSE）编码器，提供非常强大的压缩速度、压缩率的折中方案。

默认情况下，KaiwuDB 采用 GZIP 压缩算法。如需设置其他算法，参见集群实时参数配置。

说明

当 mksquashfs 数据压缩工具或者 mount 挂载工具不支持某种算法时，系统默认采用 GZIP 压缩算法并且以 WARN 日志的形式输出告警信息。

KaiwuDB 依赖支持的数据压缩算法

说明

• mksquashfs、mount 或 squashfuse 必须同时支持某种压缩算法。
• 采用 Docker 部署 KaiwuDB 时，需要添加 -v /boot:/boot 目录映射，或者复制宿主机 /boot/config-$(uname -r) 文件到 Docker 的 /boot 目录下。然后重启 KaiwuDB。否则，系统仅支持 GZIP 压缩算法。

• mksquashfs 压缩工具

  mksquashfs 压缩工具支持以下算法：

  版本	压缩算法
  4.0 及以下版本	GZIP
  4.1	GZIP、LZMA、LZO
  4.2	GZIP、LZMA、LZO、XZ
  4.3	GZIP、LZMA、LZO、XZ、LZ4
  4.4 及以上版本	GZIP、LZMA、LZO、XZ、ZSTD

• mount 挂载工具支持的压缩算法与内核对 squashfs 的压缩算法支持有关。例如，

  • CentOS 7：支持挂载 GZIP、LZO、XZ 压缩的 .sqfs 文件。
  • Ubuntu 20.04/24.04：支持挂载 GZIP、LZO、XZ、LZ4、ZSTD 压缩的 .sqfs 文件。

数据压缩级别

数据的压缩级别与压缩速度和压缩率相关。压缩级别越高，压缩速度越慢，压缩效果越好，压缩后的文件越小。反之，压缩级别越低，压缩速度越快，压缩效果越差，压缩后的文件越大。KaiwuDB 支持通过 ts.compression.level 实时参数配置以下压缩级别：

• low：低压缩级别，通常情况下，压缩率相对较低，压缩速度快。
• middle：中压缩级别，通常情况下，兼顾压缩率及压缩速度。
• high：高压缩级别，通常情况下，压缩率相对较高，压缩速度慢。

下表列出 KaiwuDB 支持的压缩算法与压缩级别之间的关系。

压缩级别	压缩算法
	GZIP	LZO	ZSTD	LZ4	XZ	LZMA
low	有效	有效	有效	有效，等同于 middle	无效	无效
middle	有效	有效	有效	有效	无效	无效
high	有效	有效	有效	有效	无效	无效

数据重组

数据重组是指对原始数据按照特定规则和逻辑进行清理、排序和整合。数据重组依赖于迭代器排序，通过过滤删除的数据、历史数据的数据类型更新以及排序读取等方法，优化存储空间的利用率，提升数据库的查询速度和响应能力，节省存储成本，提高数据库的访问速度和效率。

重组流程

系统在执行数据重组前，会先进行重组评估，检查以下内容：

• 分区内的 segment 版本和数量
• 分区最后修改时间
• 分区内是否有数据删除
• 数据的顺序状态

重组以分区为单位进行。重组开始前，分区会被短暂加锁，设置为不可读写状态，以确定是否需要进行数据重组。

重组开始时，该分区的所有 segment 均会被设置为不可写状态，同时分区解锁，数据读取不受影响。新增数据将被写入新创建的 segment。如果在重组期间发生数据删除或插入，系统会中止该分区的重组，在下次重组任务中重新执行该分区的重组。

重组配置

在 KaiwuDB 中，数据重组功能默认启用，用户可以通过 ts.auto_vacuum.enabled 实时参数选择是否启用或禁用该功能。有关详细信息，参见集群实时参数。