Thanos —— 给 Prometheus 加上长期存储、全局查询与降采样的分布式套件

分类：01 指标采集与时序存储 适用：已有多套 Prometheus / 多 Kubernetes 集群，需要无限期留存与统一查询视图 一句话：以一组可组合的组件无缝叠加在原生 Prometheus 之上，用对象存储换无限留存、用 Query 扇出换全局视图 官方：https://thanos.io/ ｜ https://github.com/thanos-io/thanos 授权：Apache-2.0（CNCF Incubating 项目）

版本、镜像 tag、二进制资产名均以官方最新稳定版为准（见 releases 页）；各组件 flag 以 thanos <component> --help 为准。

1. 它解决什么问题

不负责：采集与被监控端服务发现（仍由 Prometheus 完成）、对象存储本身、通知渠道落地（交 Alertmanager）。组件多、运维复杂度高于单机方案。

2. 核心概念与架构

关键术语

长期存储 + 全局查询 + 降采样如何解决 Prometheus 单点

  [单点]：Prom(P1) --本地 2h 块--> 本地盘(有限留存)   —— 宕机即丢、无全局视图、长查询慢
  [Thanos]：
   P1 + Sidecar --upload--> ┌──────────── 对象存储(S3/GCS/COS...) ────────────┐
   P2 + Sidecar --upload--> │  raw 块(2h) + 5m/1h 降采样块 + meta.json        │
   Receive --upload-------> │  不可变、可多副本、可版本控制 = 长期存储/备份     │
                            └───┬───────────────┬───────────────┬────────────┘
                                │ Store Gateway │  Compactor(单例：压缩/降采样/保留)
                                v               v
   Grafana --> Query Frontend --> Query <--StoreAPI 扇出--> Sidecar(实时) / Store(历史) / Ruler / Receive
                                | 基于 replica 标签去重、实现 Prometheus HTTP API
   Ruler --规则评估--> Query --告警--> Alertmanager --> 邮件/Slack/Webhook

3. 安装与部署

3.1 环境准备

3.2 多种安装方式

Thanos 是单一二进制（一个 thanos 文件 + 子命令覆盖全部组件），官方不提供 deb/rpm 包。

A. 二进制 + systemd

# 资产名以 releases 页为准（常见命名格式）
curl -LO "https://github.com/thanos-io/thanos/releases/download/<version>/thanos-<version>.linux-amd64.tar.gz"
tar xzf thanos-<version>.linux-amd64.tar.gz
install -m 0755 thanos-<version>.linux-amd64/thanos /usr/local/bin/thanos
thanos --version
useradd -r -s /sbin/nologin thanos && mkdir -p /var/lib/thanos/{store,compact,rule,receive} && chown -R thanos:thanos /var/lib/thanos

# /etc/systemd/system/thanos-query.service（其他组件改 ExecStart 子命令即可）
[Unit]
Description=Thanos Query
After=network-online.target
[Service]
User=thanos
Restart=on-failure
ExecStart=/usr/local/bin/thanos query --http-address=0.0.0.0:10904 --grpc-address=0.0.0.0:10903 --store=<sidecar>:10901 --store=<store>:10905 --query.replica-label=replica
[Install]
WantedBy=multi-user.target

systemctl daemon-reload && systemctl enable --now thanos-query

B. Docker / docker compose

services:
  query:
    image: quay.io/thanos/thanos:<version>
    command: ["query", "--http-address=0.0.0.0:10904", "--grpc-address=0.0.0.0:10903",
              "--store=sidecar:10901", "--store=store:10905", "--query.replica-label=replica"]
    ports: ["10904:10904"]
  store:
    image: quay.io/thanos/thanos:<version>
    volumes: ["./bucket.yml:/etc/thanos/bucket.yml:ro", "./store-data:/data"]
    command: ["store", "--data-dir=/data", "--objstore.config-file=/etc/thanos/bucket.yml",
              "--grpc-address=0.0.0.0:10905", "--http-address=0.0.0.0:10906"]

镜像也可用 Docker Hub 镜像 thanosio/thanos:<version>；生产固定版本 tag，勿用 latest。

C. Kubernetes Helm / Jsonnet

helm repo add bitnami https://charts.bitnami.com/bitnami && helm repo update
helm install thanos bitnami/thanos -n monitoring --create-namespace -f values.yaml

官方另提供 kube-thanos（Jsonnet）用于声明式部署；也可在 kube-prometheus-stack 中启用 Thanos Sidecar。

D. 源码构建

git clone https://github.com/thanos-io/thanos && cd thanos
make build          # 需 Go 工具链，产物在 ./tmp/bin 或 $GOPATH/bin，以官方 Makefile 为准

3.3 首次启动与验证

thanos --version
curl -s http://<query>:10904/-/healthy && echo
curl -sG 'http://<query>:10904/api/v1/query' --data-urlencode 'query=up' | head -c 300
# 校验对象存储可读（无块时返回空属正常）
thanos tools bucket ls --objstore.config-file=/etc/thanos/bucket.yml

浏览器打开 http://<query>:10904 可见类 Prometheus 的查询 UI 与 Store 端点状态。

4. 配置文件详解

主配置：Thanos 没有单一主配置文件，各组件用命令行 flag；唯一共享的关键文件是对象存储配置 --objstore.config-file（或内联 --objstore.config）与 Prometheus 侧的 external_labels。

对象存储关键项（S3 / MinIO，官方 type: S3）

完整可运行最小示例

# /etc/thanos/bucket.yml —— S3 / MinIO 最小配置（至少需 bucket / endpoint / access_key / secret_key）
type: S3
config:
  bucket: "<bucket>"
  endpoint: "<s3-endpoint>"
  access_key: "<ak>"
  secret_key: "<sk>"
  insecure: false
  signature_version2: false

# prometheus.yml —— external_labels 与 lifecycle（Sidecar 依赖后者做热重载）
global:
  scrape_interval: 15s
  external_labels:
    cluster: "cn-east-1"
    replica: "A"

thanos sidecar --tsdb.path=/var/prometheus --prometheus.url=http://localhost:9090 \
  --objstore.config-file=/etc/thanos/bucket.yml \
  --grpc-address=0.0.0.0:10901 --http-address=0.0.0.0:10902
thanos query --http-address=0.0.0.0:10904 --grpc-address=0.0.0.0:10903 \
  --store=localhost:10901 --query.replica-label=replica

5. 核心使用方法（各组件启动参数 / CLI / HTTP API / Web UI）

各组件启动参数（对象存储配置见第 4 章）

thanos sidecar --tsdb.path=/var/prometheus --prometheus.url=http://localhost:9090 --objstore.config-file=/etc/thanos/bucket.yml --grpc-address=0.0.0.0:10901 --http-address=0.0.0.0:10902
thanos store --data-dir=/var/lib/thanos/store --objstore.config-file=/etc/thanos/bucket.yml --grpc-address=0.0.0.0:10905 --http-address=0.0.0.0:10906 --index-cache-size=2GB --chunk-pool-size=2GB
thanos query --http-address=0.0.0.0:10904 --grpc-address=0.0.0.0:10903 --store=<sidecar>:10901 --store=<store>:10905 --store=dnssrv+_grpc._tcp.thanos-store.monitoring.svc --query.replica-label=replica
thanos query-frontend --http-address=0.0.0.0:10913 --query-frontend.downstream-url=http://<query>:10904 --query-range.split-interval=24h
thanos compact --data-dir=/var/lib/thanos/compact --objstore.config-file=/etc/thanos/bucket.yml --http-address=0.0.0.0:10912 --compact.concurrency=1 --downsample.concurrency=1 --retention.resolution-raw=30d --retention.resolution-5m=180d --retention.resolution-1h=0d
thanos rule --data-dir=/var/lib/thanos/rule --rule-file=/etc/thanos/rules/*.yml --query=<query>:10904 --alertmanagers.url=http://<am>:9093 --objstore.config-file=/etc/thanos/bucket.yml --label=replica='"A"' --grpc-address=0.0.0.0:10910 --http-address=0.0.0.0:10911 --eval-interval=30s
thanos receive --tsdb.path=/var/lib/thanos/receive --objstore.config-file=/etc/thanos/bucket.yml --label=receive_replica='"0"' --remote-write.address=0.0.0.0:10908 --grpc-address=0.0.0.0:10907 --http-address=0.0.0.0:10909 --receive.replication-factor=1
thanos tools bucket verify --objstore.config-file=/etc/thanos/bucket.yml
thanos tools bucket ls --objstore.config-file=/etc/thanos/bucket.yml
thanos tools bucket inspect --objstore.config-file=/etc/thanos/bucket.yml
thanos tools bucket web --objstore.config-file=/etc/thanos/bucket.yml --http-address=0.0.0.0:10914

端口取官方 getting-started 的单机多组件布局建议（10901~10913）；组件自身默认 --grpc-address=0.0.0.0:10901、--http-address=0.0.0.0:10902，多组件同机须显式错开，以 thanos <component> --help 为准。

HTTP API 与 Web UI（Query 兼容 Prometheus v1 API）

curl -s http://<query>:10904/-/healthy
curl -sG 'http://<query>:10904/api/v1/query' --data-urlencode 'query=up'
curl -sG 'http://<query>:10904/api/v1/query_range' --data-urlencode 'query=rate(http_requests_total[5m])' --data-urlencode 'start=<unix_s>' --data-urlencode 'end=<unix_s>' --data-urlencode 'step=3600s'
curl -sG 'http://<query>:10904/api/v1/label/cluster/values'
curl -s http://<store>:10906/metrics | grep thanos_store
curl -s http://<compact>:10912/metrics | grep thanos_compact
curl -s -X POST http://<rule>:10911/-/reload
curl -s http://<rule>:10911/api/v1/rules

Web UI：http://<query>:10904（类 Prometheus UI，含 Stores 页查看已发现端点与健康状态）；thanos tools bucket web 提供 bucket 块浏览。以上共 25+ 条可用命令。

6. 告警与通知

链路：Ruler（基于全局 Query 评估规则）→ Alertmanager（分组/抑制/静默/路由）→ 邮件 / Slack / Webhook。

# /etc/thanos/rules/alert.yml（语法同 Prometheus rule YAML）
groups:
  - name: global
    rules:
      - alert: PrometheusDown
        expr: up{job="prometheus"} == 0
        for: 5m
        labels: {severity: critical}
        annotations: {summary: "{{ $labels.cluster }} Prometheus 掉线"}
      - record: cluster:up:sum
        expr: sum by (cluster) (up)

thanos rule --data-dir=/var/lib/thanos/rule --rule-file=/etc/thanos/rules/*.yml \
  --query=<query>:10904 --alertmanagers.url=http://<am>:9093 \
  --objstore.config-file=/etc/thanos/bucket.yml --eval-interval=30s \
  --grpc-address=0.0.0.0:10910 --http-address=0.0.0.0:10911

7. 实战场景

场景一：把现有 Prometheus 数据平滑接入 / 迁移到 Thanos（零停机）

目标：不动现有抓取，逐步把历史块上传对象存储并建立全局查询，随时可回退。

# ① 建 bucket 并写 /etc/thanos/bucket.yml（第 4 章），校验连通
thanos tools bucket ls --objstore.config-file=/etc/thanos/bucket.yml
# ② 给源 Prometheus 补 external_labels 并启用 lifecycle（改配置后 reload，勿重启）
curl -s -X POST http://<prom>:9090/-/reload
# ③ 同机启动 Sidecar：先只做查询代理，再开启上传
thanos sidecar --tsdb.path=/var/prometheus --prometheus.url=http://localhost:9090 \
  --grpc-address=0.0.0.0:10901 --http-address=0.0.0.0:10902
thanos sidecar --tsdb.path=/var/prometheus --prometheus.url=http://localhost:9090 \
  --objstore.config-file=/etc/thanos/bucket.yml \
  --grpc-address=0.0.0.0:10901 --http-address=0.0.0.0:10902
# ④ 启动 Store Gateway + Query（历史 + 实时一起查）
thanos store --data-dir=/var/lib/thanos/store --objstore.config-file=/etc/thanos/bucket.yml --grpc-address=0.0.0.0:10905 --http-address=0.0.0.0:10906
thanos query --http-address=0.0.0.0:10904 --grpc-address=0.0.0.0:10903 --store=<sidecar>:10901 --store=<store>:10905 --query.replica-label=replica
# ⑤ 双端对比后把 Grafana 数据源由 Prometheus 切到 http://<query>:10904
curl -sG 'http://<prom>:9090/api/v1/query' --data-urlencode 'query=count(up)'
curl -sG 'http://<query>:10904/api/v1/query' --data-urlencode 'query=count(up)'

# prometheus.yml 追加/修改
global:
  external_labels:
    cluster: "cn-east-1"
    replica: "A"

⚠️ 若 bucket 为空且本地已有大量历史块，可对首次接入的 Sidecar 加 --shipper.upload-compacted 上传已压缩块；若该 bucket 已有其它 Sidecar 上传过块，不要使用，否则产生重叠块冲突（需人工清理）。 验证：Query 的 Stores 页全部端点健康；thanos tools bucket ls 出现新块；count(up) 与源一致；隔日查询仍能命中历史。 回滚：停 Sidecar / Store / Query，Grafana 数据源改回原 Prometheus；bucket 中已上传块保留不删，可随时重接。源 Prometheus 本地 TSDB 全程未动。

场景二：多集群全局查询 + HA 副本去重

目标：两个集群各跑一对 HA Prometheus，Query 出一份不重复的全局视图。

# 集群 A 的 prometheus.yml（B 把 cluster 改 us-west-1，两副本分别 replica: A / B）
global:
  external_labels:
    cluster: "cn-east-1"
    replica: "A"

thanos query --http-address=0.0.0.0:10904 --grpc-address=0.0.0.0:10903 \
  --store=<cn-a1>:10901 --store=<cn-a2>:10901 \
  --store=<us-b1>:10901 --store=<us-b2>:10901 \
  --store=<store>:10905 --query.replica-label=replica --query.auto-downsampling=true
# 验证：同一时刻每序列只返回一份
curl -sG 'http://<query>:10904/api/v1/query' --data-urlencode 'query=count(up) by (cluster)'

验证：count by (cluster) 不随副本数翻倍；Query UI 的 Stores 页 4 个 Sidecar 均 UP。 回滚：去掉 --query.replica-label 即恢复原始多副本视图（会出现重复），或临时把 Grafana 指回单集群 Prometheus。

场景三：Receiver 接管 remote write + Compactor 降采样长期保留

目标：Prometheus 不落本地长期数据，remote write 直接进 Thanos，按分辨率分级留存。

# prometheus.yml
remote_write:
  - url: http://<receive>:10908/api/v1/receive
    queue_config:
      max_samples_per_send: 10000

thanos receive --tsdb.path=/var/lib/thanos/receive --objstore.config-file=/etc/thanos/bucket.yml \
  --label=receive_replica='"0"' --remote-write.address=0.0.0.0:10908 \
  --grpc-address=0.0.0.0:10907 --http-address=0.0.0.0:10909 --receive.replication-factor=1
thanos compact --data-dir=/var/lib/thanos/compact --objstore.config-file=/etc/thanos/bucket.yml \
  --http-address=0.0.0.0:10912 --retention.resolution-raw=30d \
  --retention.resolution-5m=180d --retention.resolution-1h=2y
thanos tools bucket verify --objstore.config-file=/etc/thanos/bucket.yml

验证：curl -s http://<receive>:10909/metrics | grep thanos_receive 写入计数增长；bucket 出现块；长范围查询走 5m/1h 降采样（Query 日志/耗时明显下降）。 回滚：remote_write 改回原目标或删除并 reload Prometheus；停 Receive / Compactor，bucket 数据保留；⚠️ 勿同时启第二个写同一 bucket 的 Compactor。

8. 日常运维与故障排查

systemctl status thanos-query thanos-store thanos-compact thanos-sidecar
journalctl -u thanos-query -f --since "10 min ago"
docker logs -f thanos-store 2>&1 | grep -iE 'error|warn'
curl -s http://<query>:10904/-/healthy
curl -s http://<query>:10904/metrics | grep thanos_query
thanos tools bucket verify --objstore.config-file=/etc/thanos/bucket.yml
thanos tools bucket ls --objstore.config-file=/etc/thanos/bucket.yml

9. 性能、容量与高可用

• 高可用：对象存储自身多副本即数据 HA；Sidecar 与每个 Prometheus 同生命周期；Query / Store / Ruler / Receive 多副本无状态扩展；Compactor 必须单例（⚠️ 同一 bucket 只能一个写入者）。
• 多租户：可用 prefix 隔离多套 Thanos、或 Receive 的 hashring + --label 做软租户。
• 降采样 / 对象存储：Compactor 生成 5m/1h 块并执行 raw/5m/1h 分级保留；GCS / S3 / Azure / Swift / 腾讯 COS / 阿里 OSS / OCI 等后端，MinIO 等 S3 兼容存储用 type: S3。
• 自监控：每个组件 --http-address 暴露 /metrics（thanos_* 前缀），由独立 Prometheus 抓取；官方仓库提供 alerts/rules 示例与 Grafana dashboard，务必单独监控对象存储与 Compactor 滞后。

10. 安全加固、备份与升级

# 升级前：校验块完整性并留存配置
thanos tools bucket verify --objstore.config-file=/etc/thanos/bucket.yml
cp /etc/thanos/bucket.yml /etc/thanos/bucket.yml.bak
# 逐组件滚动（以 Query 为例）
systemctl stop thanos-query && install -m 0755 thanos /usr/local/bin/thanos && systemctl start thanos-query
curl -s http://<query>:10904/-/healthy

11. 常见坑

12. 速查表

13. 选型建议与同类对比

何时选：已有多套 Prometheus / 多集群、必须保留原生架构并叠加无限留存与全局视图；需要对象存储级异地备份与降采样；团队能承担组件化运维。 何时不选：只有一两套 Prometheus 且规模小（原生 Prometheus 或单节点 VictoriaMetrics 更省）；不愿引入对象存储；追求最少组件与最低运维成本；核心诉求是日志/链路追踪。

14. 参考链接

• 官网：https://thanos.io/
• 入门（含官方端口布局）：https://thanos.io/tip/thanos/getting-started.md/
• 对象存储配置：https://thanos.io/tip/thanos/storage.md/
• GitHub 仓库：https://github.com/thanos-io/thanos
• Releases（下载与版本）：https://github.com/thanos-io/thanos/releases
• 官方镜像：https://quay.io/thanos/thanos
• kube-thanos（Jsonnet）：https://github.com/thanos-io/kube-thanos
• Bitnami Helm Charts：https://github.com/bitnami/charts