最近在维护生产环境的Prometheus监控系统时，遇到了一个典型的TSDB存储错误：loading on-disk chunks failed，具体报错是out of sequence m-mapped chunk for series ref 2760916。这个问题折腾了我好几天，今天把完整的排查过程和解决方案整理出来，希望能帮到遇到同样问题的同学。

问题背景：TSDB存储机制

首先需要理解TSDB（Time Series Database）的核心存储设计：

1. 内存映射文件（mmap）机制：TSDB通过mmap将磁盘文件映射到内存，实现高效读写。这也是报错中m-mapped chunk的由来。

2. 数据分块存储：时间序列数据被分成多个chunk存储，每个chunk包含特定时间范围内的数据点。

3. WAL日志：所有写入操作先记录到Write-Ahead Log，确保数据持久性。

错误深度解读

这个out of sequence错误通常发生在以下场景：

1. 磁盘文件损坏：可能是异常关机或存储故障导致
2. 并发写入冲突：多个写入器同时操作同一时间范围
3. 时间戳乱序：新数据点的时间戳早于已存在的数据

核心问题在于TSDB要求每个series的数据必须按时间严格递增，而损坏的文件破坏了这一约束。

解决方案：修复损坏数据

第一步：定位问题文件

通过错误信息中的series ref 2760916，我们可以用tsdb tool检查具体问题：

// 示例：使用Prometheus自带的tsdb工具检查块
package main

import (
    "github.com/prometheus/prometheus/tsdb"
    "github.com/prometheus/prometheus/tsdb/chunks"
)

func inspectBlock(path string) {
    // 加载TSDB块
    block, err := tsdb.OpenBlock(nil, path, nil)
    if err != nil {
        panic(err)
    }
    defer block.Close()

    // 遍历所有series
    indexReader, err := block.Index()
    if err != nil {
        panic(err)
    }
    defer indexReader.Close()

    // 这里可以添加特定series的检查逻辑
}

第二步：修复损坏块

如果确认是单个块损坏，最安全的方法是：

1. 停止Prometheus服务
2. 备份整个data目录
3. 删除损坏的块（位于data目录下类似01HXZ...的文件夹）
4. 重启服务让其从WAL重建

配置优化建议

为了防止问题再次发生，建议调整这些配置：

# prometheus.yml 关键配置
tsdb:
  # 增大head chunk存活时间
  max_block_duration: 2h

  # 启用严格的时序检查
  out_of_order_time_window: 0s

  # 调整WAL设置  
  wal:
    segment_size: 128MB
    truncate_frequency: 2h

生产环境经验

1. 监控TSDB健康状态：定期检查prometheus_tsdb_*指标
2. 避免频繁重启：每次重启都会触发WAL重放
3. 硬件配置：使用SSD并确保足够IOPS
4. 版本升级：较新的Prometheus版本对TSDB稳定性有显著改进

总结

处理这类存储问题的关键是：

1. 理解TSDB的存储原理
2. 善用自带的tsdb工具
3. 建立完善的监控机制
4. 定期进行数据备份

希望这篇实战总结能帮你少走弯路。如果你在TSDB使用过程中遇到过其他有意思的问题，欢迎留言分享！