📚 课程目录第4章 Prometheus高可用与联邦集群故障

4. Prometheus 高可用与联邦集群故障：Thanos/Cortex 架构下数据不一致、查询超时、Store Gateway 不可达的排查思路

在生产环境中，Prometheus 的单机架构无法满足大规模、长周期、高可用的监控需求。Thanos 和 Cortex 作为主流的 Prometheus 高可用与联邦集群方案，引入了 Sidecar、Store Gateway、Compactor、Querier 等组件，但也带来了新的故障场景。本章聚焦于数据不一致、查询超时、Store Gateway 不可达三类核心故障，提供系统化的排查路径。

4.1 架构概览与故障分类

Thanos 与 Cortex 虽然实现细节不同，但逻辑架构高度相似：数据从 Prometheus 实例采集后，通过 Sidecar 或 Distributor 上传至对象存储（如 S3、GCS），再由 Querier 或 Store Gateway 提供全局查询视图。故障通常集中在以下三个层面：

故障类别	典型现象	影响范围
数据不一致	同一时间序列在不同 Querier 返回不同值；Grafana 图表出现跳变或空洞	局部或全局
查询超时	Grafana 面板加载缓慢或报 504；PromQL 查询返回 `context deadline exceeded`	全局
Store Gateway 不可达	Querier 日志出现 `connection refused` 或 `no such host`；查询结果缺失部分数据	局部

排查原则： 先确认故障范围（全局 vs 局部），再定位组件层级（存储层 vs 查询层 vs 网络层），最后检查配置与版本兼容性。

4.2 数据不一致的排查思路

数据不一致通常由时间戳对齐问题、Compactor 合并异常、Sidecar 上传延迟或对象存储的最终一致性引起。排查步骤如下：

检查时间戳对齐：使用 rate() 或 delta() 函数时，确保所有 Prometheus 实例的 scrape_interval 和 evaluation_interval 一致。不一致会导致聚合结果偏差。
验证 Compactor 日志：查看 Compactor 是否因 downsampling 或 deduplication 规则冲突而跳过某些 block。关键日志关键字：compaction failed、block already exists。
检查 Sidecar 上传状态：通过 Sidecar 的 HTTP 端点 /metrics 监控 thanos_sidecar_uploads_total 和 thanos_sidecar_upload_failures_total。上传失败通常伴随网络抖动或对象存储限流。
确认对象存储一致性：对于 S3 等最终一致性存储，Thanos 默认使用 --consistency-delay 参数（默认 30 分钟）来等待数据可见。如果查询时间范围小于该延迟，可能出现数据空洞。

快速诊断命令：

# 检查 Thanos Store Gateway 的 block 列表
thanos tools bucket inspect --objstore.config-file=objstore.yml

# 对比两个 Querier 的同一时间序列
curl "http://querier1:9090/api/v1/query?query=up{job=\"node\"}"
curl "http://querier2:9090/api/v1/query?query=up{job=\"node\"}"

4.3 查询超时的排查思路

查询超时是 Thanos/Cortex 集群中最常见的性能故障，根源往往在 Querier 的并发能力、Store Gateway 的响应速度或 PromQL 的复杂度。排查路径如下：

排查步骤	检查对象	关键指标/日志
1. 检查 Querier 负载	Querier 实例	`thanos_querier_queries_in_flight`、`thanos_querier_queries_duration_seconds`
2. 检查 Store Gateway 延迟	Store Gateway 实例	`thanos_store_gateway_data_requests_duration_seconds`、`thanos_store_gateway_series_fetched`
3. 检查对象存储 IO	对象存储（S3/GCS）	API 延迟、限流错误（如 `SlowDown`、`RequestTimeout`）
4. 检查 PromQL 复杂度	查询语句	避免 `avg(rate(...))` 嵌套聚合；使用 `topk` 限制返回序列数

常见陷阱： 当 Querier 的 --timeout 参数（默认 2 分钟）小于 Store Gateway 的 --data-timeout 时，会导致查询提前终止。务必保持 Querier 的超时时间大于 Store Gateway 的超时时间。

以下 SVG 展示了查询超时场景下的请求链路与故障点：

4.4 Store Gateway 不可达的排查思路

Store Gateway 不可达通常表现为 Querier 日志中出现 connection refused 或 no such host，导致查询结果缺失部分数据。排查需从网络、服务发现、健康检查三个维度展开：

网络层：使用 telnet 或 nc -zv 测试 Store Gateway 的 gRPC 端口（默认 10901）是否可达。检查防火墙规则和 Kubernetes Service 的 Endpoint 列表。
服务发现层：Thanos Querier 通过 --store 参数或 DNS SRV 记录发现 Store Gateway。执行 dig SRV _grpc._tcp.store-gateway.example.com 验证 DNS 解析是否正确。
健康检查层：Store Gateway 暴露 /-/healthy 和 /metrics 端点。检查 thanos_store_gateway_healthy 指标是否为 1。如果为 0，说明 Store Gateway 内部状态异常（如对象存储连接失败）。

典型排查命令：

# 测试 Store Gateway gRPC 端口
nc -zv store-gateway-0 10901

# 查看 Querier 已连接的 Store 列表
curl http://querier:9090/api/v1/stores

# 检查 Store Gateway 自身健康状态
curl http://store-gateway:10902/-/healthy

4.5 综合故障排查流程

以下 SVG 总结了从故障发现到根因定位的完整流程：

4.6 预防与最佳实践

为避免上述故障在生产环境中反复出现，建议在部署和运维阶段落实以下措施：

配置一致性检查：使用配置管理工具（如 Ansible、Helm）确保所有 Prometheus 实例的 scrape_interval、evaluation_interval 和 external_labels 一致。
超时参数调优：Querier 的 --timeout 建议设置为 Store Gateway --data-timeout 的 1.5 倍；Store Gateway 的 --data-timeout 建议大于对象存储的 P99 延迟。
健康检查与告警：为 Store Gateway 和 Querier 配置存活探针（Liveness Probe）和就绪探针（Readiness Probe），并设置 Prometheus 告警规则监控 thanos_store_gateway_healthy 和 thanos_querier_queries_in_flight。
版本兼容性：Thanos 和 Cortex 的 Sidecar、Store Gateway、Compactor 等组件必须使用相同的大版本，避免因 gRPC API 变更导致通信失败。

推荐工具： 使用 thanos tools bucket verify 定期检查对象存储中 block 的完整性；使用 cortex-tools 的 analyse 命令分析查询性能瓶颈。