Thanos 解决的核心问题是 Prometheus 不存在原生的跨实例全局查询能力。一个多集群环境中，每个 Kubernetes 集群通常部署独立的 Prometheus，用于采集本集群的节点、容器和应用指标。此时如果 Grafana 想同时绘制两个集群的 CPU 使用率总和，需要在一个面板中引入两个不同的数据源，或者借助 Prometheus 的 remote_read 把数据拉到中心实例。前者无法执行真正的跨集群 PromQL 聚合，后者会带来中心化存储和网络压力。Thanos 的 Querier 组件充当无状态的查询网关，通过 gRPC Store API 访问所有数据源，将分散的指标视图合并成一个逻辑全局视图。
下文会围绕 Sidecar、Store Gateway 和 Querier 的部署顺序展开。先解释它们各自在全局查询链路中的角色，再给出可落地的配置和命令，最后说明高可用与性能调优方式。
一、全局查询链路中的组件职责
Thanos 将全局查询拆成三个核心角色。第一个是 Sidecar，它运行在每个 Prometheus 实例旁边，通过 Prometheus HTTP API 读取本地 TSDB 数据，并把数据块上传到对象存储。Sidecar 同时暴露 gRPC Store API，使 Querier 能实时查询最近两小时左右还保留在本地磁盘的数据。对于已经上传到对象存储的历史数据，Sidecar 不再直接提供查询，而是由 Store Gateway 负责。
第二个是 Store Gateway。它不依赖 Prometheus 进程，直接从对象存储读取索引和数据块，响应 Querier 发来的 Store API 请求。Store Gateway 的意义在于解耦历史数据与 Prometheus 实例：即使某个集群的 Prometheus 被重建或短暂不可用，历史指标仍然可以通过 Store Gateway 查询。它还支持内存索引缓存、对象存储分片和按时间分区，能够支撑较大规模的历史数据查询。
第三个是 Querier。它本身不存储数据，只接收 PromQL 查询请求，通过 gRPC 同时向后端所有 Store API 端点发起部分查询，然后合并结果。这里的关键是去重，因为同一个指标可能来自多个副本 Prometheus，也可能同时存在于 Sidecar 和 Store Gateway 中。Querier 通过 replica label 识别相同副本，只保留一份结果，避免聚合结果翻倍。日志、错误处理、超时控制都由 Querier 统一负责。
二、部署 Prometheus Sidecar 并配置对象存储
Sidecar 的部署必须以 Prometheus 数据目录为前提。常见做法是在 Kubernetes 的 Prometheus StatefulSet 或 Deployment 中增加一个容器，与 Prometheus 共享同一数据卷。Sidecar 需要知道本地 TSDB 路径和 Prometheus 的 HTTP 地址，这两个参数对应 --tsdb.path 和 --prometheus.url。如果使用远程对象存储，还需要提供一个对象存储配置文件。
下面是一个对象存储使用 S3 兼容接口的示例。若使用 MinIO 或 Ceph RGW，只需修改 endpoint 和 region，不要求真实 AWS 环境。配置中不要提交明文密钥到仓库，建议使用 Kubernetes Secret 挂载。
type: S3 config: bucket: thanos-metrics endpoint: s3.amazonaws.com region: us-east-1 access_key: replace_with_access_key secret_key: replace_with_secret_key
启动 Prometheus 时还必须设置全局外部标签。外部标签会被写入每个样本，Querier 做全局查询时依赖 cluster 标签区分不同集群，依赖 replica 标签识别同一集群中的多个副本。缺少这两个标签会造成跨集群查询无法定位来源，去重也会失效。Prometheus 配置片段如下。
global:
scrape_interval: 15s
evaluation_interval: 15s
external_labels:
cluster: cluster-a
replica: replica-1
接着启动 Sidecar。Sidecar 的 gRPC 端口默认为 10901，HTTP 端口默认为 10902，后者提供健康检查和基础信息。命令中的反斜杠是 shell 续行符，部署到容器时也可以写成一行或用数组形式传递参数。
prometheus \ --config.file=/etc/prometheus/prometheus.yml \ --storage.tsdb.path=/prometheus \ --web.enable-lifecycle
thanos sidecar \ --tsdb.path=/prometheus \ --prometheus.url=http://127.0.0.1:9090 \ --objstore.config-file=/etc/thanos/object-store.yaml \ --grpc-address=0.0.0.0:10901 \ --http-address=0.0.0.0:10902
这里有一个容易忽略的点：Sidecar 上传数据块到对象存储的周期默认为 2 小时，由 Prometheus 自己压缩 TSDB 块后触发。如果需要在故障切换时更快看到远端数据，可以调小 --tsdb.block-duration 或使用 Prometheus 的 --storage.tsdb.min-block-duration，但参数需要谨慎调整，块太小会增加对象存储中的对象数量。
三、启动 Store Gateway 接入历史数据
Store Gateway 是独立进程，不依赖 Prometheus。它需要访问同一份对象存储配置，并使用本地磁盘缓存索引信息。默认情况下，Store Gateway 会把对象存储中的索引文件下载到本地，以加速重复查询。可以通过 --data-dir 指定本地缓存目录，通过 --index-cache-size 和 --chunk-pool-size 限制内存使用。
下面是一个适用于中小规模集群的启动命令。该命令同时暴露 gRPC 和 HTTP 端口，供 Querier 和监控系统使用。Store Gateway 启动后，Querier 还需要主动配置它的地址，否则不会自动发现。
thanos store \ --data-dir /var/lib/thanos/store \ --objstore.config-file /etc/thanos/object-store.yaml \ --index-cache-size 250MB \ --chunk-pool-size 2GB \ --grpc-address 0.0.0.0:10901 \ --http-address 0.0.0.0:10902
Store Gateway 的作用时间范围通常是从 Prometheus 本地保留期之后开始。Prometheus 默认保留 15 天本地数据，对象存储则可以保存数月甚至数年。因此查询最近 15 天的数据时，Querier 会主要命中 Sidecar；查询更早的数据时，会转向 Store Gateway。这种分层设计减少了对象存储的实时访问压力，也让近期数据的查询延迟更低。
四、部署 Querier 并验证全局查询
Querier 是最终面向 Grafana 或其他 PromQL 客户端的数据源入口。它必须知道所有后端 Store API 的地址，包括各个集群的 Sidecar 以及 Store Gateway。地址可以通过 --store 参数静态指定，也可以使用 DNS SRV 记录动态发现。静态方式更适合初期部署和测试。
下面的启动命令把两个集群的 Sidecar 和一个 Store Gateway 加入查询后端，并指定 --query.replica-label 为 replica。这样当同一集群有两个副本 Prometheus 时，Querier 只会选择一个副本的结果。
thanos query \ --http-address 0.0.0.0:9090 \ --grpc-address 0.0.0.0:10901 \ --query.replica-label replica \ --store 127.0.0.1:10901 \ --store 127.0.0.2:10901 \ --store 127.0.0.3:10901 \ --query.timeout 2m \ --query.max-concurrent 20
验证时，可以先访问 Querier 的 HTTP 端口 http://127.0.0.1:9090/graph，执行一个简单的聚合查询，例如 sum by (cluster) (rate(node_cpu_seconds_total{mode!="idle"}[5m]))。如果返回结果中包含多个 cluster 标签值，说明全局查询已经打通。再执行 count(up{job="node-exporter"})，观察数量是否等于所有集群的目标数之和。
去重是否生效可以通过重复查询验证。启动另一个副本 Prometheus，赋予相同的 cluster 标签但不同的 replica 标签，将其 Sidecar 加入 Querier。若未配置 --query.replica-label，同一个时间序列会出现两条完全相同的样本，导致 sum 结果翻倍。配置后，Querier 会在合并阶段做外部标签匹配，仅保留一个副本的数据。
五、高可用与查询性能调优
Querier 本身无状态，多副本部署不会产生数据冲突。可以在多个节点运行 Querier，前置负载均衡或 Kubernetes Service，Grafana 数据源指向该服务地址。但要注意 Querier 的 store 列表最好使用 DNS SRV 或文件发现，避免某个 Sidecar 地址变化后需要手动重启。
Store Gateway 的性能直接决定历史查询的响应速度。随着对象存储数据量增长，单个 Store Gateway 会成为瓶颈。可以把不同时间范围的数据分片给不同的 Store Gateway，使用 --min-time 和 --max-time 参数限制每个实例负责的时间段，再配置 Querier 访问多个 Store Gateway。这样查询会被并行分发到对应时间段的实例，避免单点扫描全部索引。
Compactor 是另一个必须纳入规划的组件。它负责压缩对象存储中的 TSDB 块，并生成下采样数据。若不部署 Compactor，对象存储中的小块会越来越多，Store Gateway 每次查询都要加载大量索引文件。推荐 Compactor 定时执行，并配置 5 分钟和 1 小时的下采样，让长时间跨度的 PromQL 查询自动使用聚合后的低分辨率数据，显著降低 Store Gateway 的计算和 IO 压力。
常见的部署问题包括 Prometheus 未配置 external_labels 导致查询结果丢失来源信息；Sidecar 与 Prometheus 时钟不同步导致数据块边界异常；对象存储权限不足导致 Sidecar 上传失败但进程不报错。排查时可以查看 Sidecar 的 HTTP 页面，确认 TSDB 上传状态和对象存储连接是否正常。
ThanosPrometheus全局指标查询修改时间：2026-09-28 08:28:16