TSDB利器：TStorage本地存储引擎实战指南

TStorage是一款轻量级嵌入式时间序列数据库（Time-Series Database，TSDB），专为高效存储和查询按时间戳有序记录的metrics数据（时间序列数据）设计。作为嵌入式解决方案，它无需独立部署服务，可直接集成到应用程序中，提供毫秒级数据写入性能和低资源占用特性，特别适合边缘计算、物联网设备等资源受限场景。

如何理解TStorage的核心架构？

TStorage采用分层架构设计，各核心模块协同工作实现高效数据处理：

存储引擎层

• 磁盘分区（disk_partition.go）：负责数据持久化存储，采用列式存储优化时间序列数据读写效率
• 内存分区（memory_partition.go）：提供内存级数据缓存，降低磁盘IO开销
• 预写日志（wal.go）：确保数据写入的原子性和持久性，防止意外宕机导致数据丢失

辅助功能层

• 编码模块（encoding/）：提供高效的时间序列数据压缩算法（int.go实现整数编码）
• 系统调用封装（syscall/）：跨平台内存映射（mmap）实现，优化大文件操作性能
• 定时任务池（timerpool/）：管理数据过期清理、文件轮转等后台任务

接口抽象层

• 存储接口（storage.go）：定义核心数据操作API，屏蔽底层实现细节
• 标签系统（label.go）：支持多维度数据标签，实现灵活的查询过滤

如何快速上手TStorage？

环境准备

1. 安装依赖

# 克隆项目代码
git clone https://gitcode.com/gh_mirrors/ts/tstorage
cd tstorage

# 安装依赖包
go mod download

2. 基本使用示例

package main

import (
    "log"
    "github.com/ts/tstorage"
)

func main() {
    // 创建存储引擎实例
    storage, err := tstorage.NewStorage(
        tstorage.WithDataPath("/var/lib/tstorage"),  // 数据存储路径
        tstorage.WithRetention(30*24*time.Hour),     // 数据保留30天
    )
    if err != nil {
        log.Fatalf("初始化存储引擎失败: %v", err)
    }
    defer storage.Close()
    
    // 写入时间序列数据
    err = storage.InsertRows([]tstorage.Row{
        {
            Metric: "cpu_usage",
            Labels: []tstorage.Label{{Name: "host", Value: "server1"}},
            DataPoints: []tstorage.DataPoint{
                {Timestamp: time.Now().Unix(), Value: 0.75},
            },
        },
    })
    // ...查询和其他操作
}

配置参数如何优化？

TStorage提供灵活的配置选项，以下是核心参数的默认值与推荐配置对比：

参数	类型	默认值	推荐配置	最佳实践
data_path	string	"./data"	"/var/lib/tstorage"	选择独立磁盘分区，避免IO竞争
max_file_size	int	100MB	256MB	设置为磁盘块大小的整数倍（通常4KB的倍数）
retention_period	time.Duration	7天	30天	根据业务需求调整，不宜过长导致存储膨胀
wal_enabled	bool	true	true	生产环境必须开启，保障数据安全
mmap_enabled	bool	true	true	大文件场景建议开启，提升读写性能

配置示例：

storage, err := tstorage.NewStorage(
    tstorage.WithDataPath("/var/lib/tstorage"),
    tstorage.WithMaxFileSize(256*1024*1024),  // 256MB
    tstorage.WithRetention(30*24*time.Hour),
)

常见问题解答

Q: TStorage支持哪些数据查询方式？

A: 支持按指标名、标签过滤、时间范围等多维度查询，提供Query和QueryRange两种主要接口，分别用于单点查询和范围查询。

Q: 如何处理数据备份与迁移？

A: TStorage数据以文件形式存储，直接拷贝data_path目录即可完成备份。迁移时需注意目标环境的架构兼容性（32位/64位）。

Q: 高并发写入场景下如何优化性能？

A: 建议使用批量写入接口（InsertRows）代替单条写入，批量大小控制在100-1000条为宜；同时可调整内存分区大小（WithMemoryPartitionSize）提升缓存效率。

Q: TStorage与InfluxDB、Prometheus有何差异？

A: TStorage作为嵌入式数据库，无需独立部署，资源占用更小；适合单机应用或边缘设备，而InfluxDB/Prometheus更适合分布式监控系统。

核心源码文件解析

存储引擎核心实现（storage.go）

// NewStorage 创建存储引擎实例
func NewStorage(opts ...Option) (*Storage, error) {
    cfg := defaultConfig()
    for _, opt := range opts {
        opt(&cfg)
    }
    
    // 初始化分区管理器
    pm := newPartitionManager(cfg)
    // ...省略初始化逻辑
    
    return &Storage{
        partitions: pm,
        config:     cfg,
        // ...
    }, nil
}

// InsertRows 批量插入时间序列数据
func (s *Storage) InsertRows(rows []Row) error {
    // 按时间戳和标签路由到相应分区
    for _, row := range rows {
        partition := s.partitions.GetPartition(row.Metric, row.Labels)
        if err := partition.Write(row); err != nil {
            return err
        }
    }
    return nil
}

磁盘存储实现（disk_partition.go）

// Write 将数据写入磁盘分区
func (p *diskPartition) Write(row Row) error {
    // 1. 写入预写日志(WAL)
    if err := p.wal.Write(row); err != nil {
        return err
    }
    
    // 2. 写入内存缓冲区
    p.memoryBuffer.Add(row)
    
    // 3. 当缓冲区达到阈值时刷盘
    if p.memoryBuffer.Len() >= p.config.BufferSize {
        return p.Flush()
    }
    return nil
}

通过以上内容，您已掌握TStorage的核心概念、快速使用方法和优化配置技巧。作为轻量级嵌入式时间序列数据库，TStorage在资源受限环境中展现出优异的性能和可靠性，是边缘计算、物联网设备等场景的理想选择。如需深入了解高级特性，可参考项目中的测试用例（如storage_test.go）和示例代码。