存储管理
存储路径设置
默认存储路径和系统要求
下表列出了 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 支持以下存储路径设置方式：
- 安装时通过修改安装部署时配置的
data_root参数自定义数据路径。 - 部署完成后，用户也可以通过修改部署生成的
kaiwudb_env文件、docker-compose.yml文件或kwbase start命令修改存储路径。
冷热数据分级存储和对象存储
KaiwuDB 支持分级存储管理时序数据，将时间较近的热数据存储在高速介质上，把时间久远、热度较低的数据存储在低成本介质，可以带来如下价值：
- 降低存储成本：时序数据中，冷数据占比大，冷数据迁移至低价存储介质上，可大幅降低存储成本。
- 运维方便：根据数据采集时间，系统自动根据配置实现数据由热—>温—>冷—>S3层级的迁移，无需人工干预。
- SQL 透明：使用统一SQL进行数据查询，对业务透明。
说明
- 时序冷热数据分级存储功能默认关闭，如果节点已经启动，用户完成分级存储目录设置后，需要重启节点才能使配置生效。
- 在分布式集群中，每个节点需要单独配置，未配置的节点将保持分级存储功能关闭。
KaiwuDB 的分级存储既支持本地存储设备，也支持对象存储，将最冷的一批数据保存在更廉价的介质上。数据不管存储在哪一层，都保持SQL透明。
存储目录类型
存储目录分为主存储目录和普通存储目录。
主存储目录：时序数据的默认存储目录，有且仅有一个，默认存储级别为 0 级。
- 时序数据默认与关系数据存储在 KaiwuDB 部署时自定义的数据路径。裸机部署时，时序数据默认存储在
/var/lib/kaiwudb下的tsdb子目录。容器部署时，系统将使用宿主机路径并自动挂载。 - KaiwuDB 同时支持用户通过
--ts-store启动参数自定义时序数据的存储路径，将时序数据与关系数据分开存储。此时，--ts-store参数指定的路径为主存储目录。有关启动参数的配置说明，参见启动参数配置。
- 时序数据默认与关系数据存储在 KaiwuDB 部署时自定义的数据路径。裸机部署时，时序数据默认存储在
普通存储目录：除主存储目录之外的其他存储目录，无默认优先级。用户可通过
ts_tier.cfg配置文件灵活设置目录和存储级别。
存储目录配置
KaiwuDB 启动后，系统将自动在主存储目录创建 ts_tier.cfg 文件，用于管理普通存储目录。用户也可以在启动前在主存储目录手动创建 ts_tier.cfg 文件，提前完成存储目录和冷热级别设置。
ts_tier.cfg 文件采用 CSV 格式，配置格式及示例如下：
# local disks
# <dir_path>, <level>
/data/ts_hot,0
/data1/ts_hot,0
/data/ts_warm,1
/data/ts_cold,2
# S3 archive
s3.enable=true #必填，是否启用 S3 归档，true 代表打开，false 代表关闭
s3.endpoint=http://127.0.0.1:9090 #必填，S3 地址。本地访问不用 HTTPS；如果要公网暴露，必须防火墙限制 + HTTPS 代理
s3.region=us-east-1 #可选，自建 MinIO 不验证 region，随意字符串即可；云厂商需按 bucket 所在区域填写
s3.bucket=kwdb-cold #必填，归档对象所在 bucket
s3.access_key_id=AKxxxx #必填，S3 Access Key ID
s3.secret_access_key=SKxxxx #必填，S3 Secret Access Key
s3.use_path_style=false #可选，bucket 放在 URL path 还是 host 里面，默认 false
s3.verify_ssl=true #可选，S3 服务器HTTPS证书校验开关，默认 true
s3.cache_enable=true #可选，是否启用 S3 页缓存，默认 true
s3.cache_capacity_mb=1024 #可选，S3 缓存总容量，单位 Mib，默认 1024
s3.cache_bypass_mb=8 #可选，单次读达到该大小直接 Range GET，不入缓存；0 代表所有读都可以进入页缓存，默认 8
其中：
dir_path：普通存储目录的具体路径，主存储目录路径无需添加到配置文件中。level：存储目录的冷热级别，支持设置为0、1、2，分别对应“热”、“温”、“冷”级别。**注意：**多级存储本地磁盘不允许跨级配置，只支持0、0,1或0,1,2的组合方式。- S3 配置，经
endpoint+region+path-style组合可对接AWS S3、MinIO、Ceph RGW、阿里云 OSS、腾讯云 COS、华为云 OBS等 S3 兼容对象存储。
KaiwuDB 支持用户在线添加普通存储目录，以应对实际时序写入量的变化。完成目录配置后，需要重启当前节点，配置才能生效。
注意
- 未配置
ts_tier.cfg，分级存储不生效； - 添加 0 级磁盘可以增加磁盘 IO, 提升数据写入和查询性能。由于 1 级和 2 级磁盘的 IO 低于 0 级磁盘，添加过多 1 级和 2 级磁盘可能会影响查询性能。
- 如果同一层级的目录已写满，分布式集群中的该节点将进入宕机状态。
- 目前不支持删除配置文件中已添加的存储目录。如果删除的目录中已写入数据，并且取消了对应设备的挂载，将导致数据丢失。
数据分级管理
用户可以通过以下 SQL 命令定义热、温、冷数据的划分规则：
SET CLUSTER SETTING ts.tier.duration = "<period>,<period>,<period>";
默认设置为 30d,90d,180d，表示:
- 30 天内采集的时序数据为热数据，存储在 0 级存储目录。
- 30 至 90 天内采集的时序数据为温数据，存储在 1 级存储目录。
- 90 至 180 天的数据为冷数据，存储在 2 级存储目录。
- 180天以上的数据将迁移至 S3 对象存储。
时间单位只支持 d (天)。
提示
- 集群参数
ts.tier.duration允许设置两段，也允许设置三段； - 如果仅配置本地分级目录，未配置S3，集群参数
ts.tier.duration设置三段，当本地分级只设置 0 和 1，数据迁移到 1 级存储目录后，将按照数据的生命周期进行保存，直到生命周期结束。本地分级设置 0、1、2，数据迁移到 2 级存储目录后，将按照数据的生命周期进行保存，直到生命周期结束 - 如果配置S3，就会从本地分级最后一层迁移至S3。数据迁移支持:
0 —> S3、0 —> 1 —> S3、0 —> 1 —> 2 —> S3。
数据迁移
KaiwuDB 分级存储数据迁移支持自动迁移和手动迁移两种：
- 自动迁移：迁移通过
scheduled_ts_relocate周期触发迁移，默认每天 00:30 进行，用户可通过show schedules查看当前的迁移周期，也可根据具体情况通过alter schedule修改迁移周期。--示例：将迁移周期修改为每分钟执行一次 alter schedule scheduled_ts_relocate recurring '0 */1 * * * * *' `修改迁移周期。 - 手动迁移：通过
relocate ts databases命令，可进行手动迁移数据，该命令执行后会立即进行迁移任务。
提示
数据需要归档到 S3，只迁移分区数据的 block 数据文件，元数据/索引等文件保留在本地。文档一旦归档到 S3 后，关闭 S3 会因 S3 连接异常而导致数据查询失败。 删除数据包含已归档至 S3 对象存储上的数据，系统会将整个 block 数据文件回拉至本地进行数据删除、重组后在下一个迁移周期迁移至 S3。
数据压缩
KaiwuDB 支持在创建或修改时序表时，为每个数据列单独指定编码算法、压缩算法及压缩级别，针对不同数据特征选择最优压缩策略，在存储空间和系统资源之间灵活权衡。配置修改后仅对新写入数据生效，已有数据不受影响。
编码算法、压缩算法及压缩级别
编码算法
不同数据类型支持的编码算法及默认值如下：
| 数据类型 | 可选编码算法 | 默认值 |
|---|---|---|
| INT2 / INT4 / INT8 | simple8b / disabled | simple8b |
| TIMESTAMP / TIMESTAMPTZ | simple8b / delta-d / disabled | simple8b |
| FLOAT / DOUBLE | chimp / bss / elf / alp / fptrunc / disabled | chimp |
| BOOL | bit-packing / rc / disabled | bit-packing |
| 字符类型 | disabled | disabled |
压缩算法
所有数据类型均支持以下压缩算法，默认使用 lz4：
| 算法 | 压缩率 | 压缩速度 | 解压速度 | CPU 占用 | 内存占用 | 适用场景 |
|---|---|---|---|---|---|---|
lz4 | 低到中（2x-3x） | 极快 | 最快 | 很低 | 很低 | 高频写入、对延迟敏感的场景（默认） |
zstd | 中到高（2.5x-5x+） | 很快 | 极快（与 lz4 同级） | 低到中（取决于等级） | 中等（可调） | 存储空间敏感、兼顾读写性能的场景 |
zlib | 中（2.5x-4x） | 中等 | 快 | 中等 | 中等 | 存储空间敏感、对写入性能要求较低的场景 |
snappy | 低（1.5x-2x） | 极快 | 极快 | 很低 | 很低 | 速度优先、不需要调节压缩级别的场景 |
disabled | — | — | — | — | — | 关闭压缩 |
说明
zstd压缩速度接近lz4，但压缩率更高，解压速度同样极快，是需要兼顾空间与性能时的优先选择。zlib压缩率与zstd相近，但压缩和解压速度均较慢，CPU 和内存消耗更高，在高频大批量写入场景下影响尤为明显，请谨慎评估后使用。bss编码算法仅重排float/double的内存布局已让后续的二级压缩算法更高效，因此需要结合二级压缩才有意义。
压缩级别
支持 low、medium（默认）、high，可简写为 l、m、h。压缩级别越高，压缩率越高，CPU 和内存占用也越多，请根据业务负载合理配置。
说明
snappy 和 lz4 不支持压缩级别设置，对其指定压缩级别不会有实际效果。
压缩配置
各级压缩配置的优先级规则如下：
- 不修改 cluster setting 时：列级自定义配置 > 数据类型默认值 > cluster setting 全局配置
- 已设置 cluster setting 时：列级自定义配置 > 数据类型默认值 = cluster setting 全局配置
建议优先通过 cluster setting 设置全局基准，仅对有特殊需求的列单独指定配置。
全局压缩配置
通过 cluster setting 统一配置全局默认压缩行为，无需逐列指定：
-- 设置压缩模式（0-3）
SET CLUSTER SETTING ts.compress.stage = 3;
-- 设置全局默认压缩算法
SET CLUSTER SETTING ts.compress.algorithm = 'lz4';
-- 设置全局默认压缩级别
SET CLUSTER SETTING ts.compress.level = 'medium';
参数说明：
| 参数 | 说明 | 默认值 | 类型 |
|---|---|---|---|
ts.compress.stage | 控制时序数据的压缩模式： - 0：关闭编码，关闭压缩- 1：开启编码，关闭压缩- 2：关闭编码，开启压缩- 3：开启编码，开启压缩 | 3 | int |
ts.compress.algorithm | 全局默认压缩算法，支持 lz4、zstd、zlib、snappy、disabled。优先级低于列级配置。 | lz4 | string |
ts.compress.level | 全局默认压缩级别，支持 low、medium、high。优先级低于列级配置。 | medium | string |
列级压缩配置
建表时为各列指定编码和压缩配置：
CREATE TABLE test_compress.t1 ( k_timestamp TIMESTAMPTZ ENCODE 'Simple8B' COMPRESS 'lz4' LEVEL 'high' NOT NULL, c1 INT ENCODE 'Simple8B' COMPRESS 'zlib' LEVEL 'high', c2 FLOAT COMPRESS 'zlib' LEVEL 'medium', c3 INT ENCODE 'Simple8B', -- 仅指定编码，压缩使用默认值 c4 BLOB COMPRESS 'disabled', c5 BOOL ENCODE 'disabled', c7 VARCHAR ENCODE 'disabled' COMPRESS 'disabled' ) TAGS ( code1 INT2 NOT NULL ) PRIMARY TAGS (code1);修改已有列的压缩配置：
-- 修改压缩算法和压缩级别 ALTER TABLE t1 ALTER COLUMN c2 COMPRESS 'zstd' LEVEL 'high'; -- 同时修改编码和压缩算法（ENCODE 必须在 COMPRESS 之前） ALTER TABLE t1 ALTER COLUMN c1 ENCODE 'Simple8B' COMPRESS 'zstd' LEVEL 'medium'; -- 关闭列的压缩 ALTER TABLE t1 ALTER COLUMN c4 COMPRESS 'disabled';
数据重组
数据重组是指按照特定规则对原始时序数据进行清理和整理的过程，主要应用于以下场景:
- 删除数据清理：执行 DELETE 或 DROP 操作后，清理被标记删除的数据以释放存储空间
- 过期数据清理：清理通过生命周期管理功能识别出的过期数据
- 数据整理优化：对不连续的 entity 数据进行重组排序，提高查询效率
数据重组可以优化存储空间利用率，提升数据库查询性能和响应速度，改善整体系统效率。
重组方式
KaiwuDB 提供自动重组和手动重组两种数据重组方式：
自动重组
系统定期自动触发重组任务，以分区(Partition)为基本单位，采用单线程串行方式处理，确保操作的稳定性和数据一致性。具体流程如下：
- 任务触发：系统定期自动触发重组任务
- 分区遍历：依次扫描各个分区，对每个分区执行重组操作
- 数据清理：
- 清理过期数据
- 清理被标记删除的数据
- 文件重建：生成优化后的新数据文件，替换原有文件
- 标记清理：清理相关的删除标记记录，完成重组流程
重组操作与合并操作互斥，同一 entity segment 不会同时执行这两种操作。
手动重组
需要立即释放存储空间或优化查询性能时，可以通过立即重组命令 VACUUM TS DATABASES; 手动触发重组操作。
手动重组特别适用于以下场景：
- 删除数据或删除库表后释放空间：执行 DELETE 或 DROP 操作后，立即清理已删除数据，快速释放存储空间
- 批量写入后数据整理：大批量数据写入后，对数据文件进行整理排序，加速后续查询性能
参数说明：
| 参数 | 说明 |
|---|---|
aggregate only | 可选关键字。当使用 aggregate only 关键字时，对所有分区进行预聚合计算，而不进行数据重组，降低数据预聚合处理耗时。 |
手动重组功能与自动重组功能兼容，互不影响，同时具有以下特点：
- 对当前分区数据执行重组操作
- 对不连续的 entity 数据进行重组排序，整理分散的 block 以提高查询效率（无论是否有删除操作）
- 及时检查并清理已删除表的相关数据
- 将内存数据持久化到磁盘，并合并 last 文件
重组配置
- 自动重组：自动数据重组功能默认启用，用户可以通过
ts.auto_vacuum.enabled实时参数选择是否启用或禁用该功能。有关详细信息，参见集群实时参数。 - 手动重组：用户需要通过执行立即重组命令
VACUUM TS DATABASES;手动触发重组操作。
时序分布式日志存储引擎
时序分布式日志存储引擎（RaftLog Store）是专门针对分布式集群时序数据场景的存储优化，通过减少磁盘 IO 压力和优化写入路径，在机械硬盘环境下显著提升数据写入性能。
该功能适用于分布式集群、大量时序数据写入、机械硬盘存储环境且对写入性能要求较高的应用场景。
启用后，系统会在数据目录的时序引擎目录下自动创建 raftlog 子目录，当前文件达到 512 MB 时自动转换为历史文件，每 30 分钟检查一次合并需求。
功能配置
启用时序分布式日志存储引擎需要在节点启动命令中添加 --use-raft-store 参数。
注意
- 该参数必须在数据库首次安装启动时指定，默认为关闭状态。
- 数据库初始化完成后，无法通过修改启动参数切换存储引擎。
启动命令的更多信息和示例，参见kwbase start。