Thanos 0.42.4 常用 CLI 命令与工具详解
Thanos 0.42.4 常用 CLI 命令与工具详解：sidecar/query/store/compact/rule/receive/query-frontend 启动命令、tools bucket 桶运维（ls/inspect/verify/web/upload-blocks/mark/cleanup）与 rules-check 实测。
Thanos 0.42.4 常用 CLI 命令与工具详解
目标：系统梳理 Thanos 0.42.4 单二进制的全部子命令与关键旗标，覆盖六组件启动命令、
tools bucket桶运维工具与tools rules-check规则校验，所有命令与回显均在 Ubuntu 22.04（x86_64）实测记录。
一、环境信息
- 操作系统：Ubuntu 22.04 LTS（x86_64）
- Thanos：0.42.4（2026-07-30 发布；版本查询日期 2026-10-20）
- Prometheus：3.15.0（sidecar 数据源）
- 对象存储：FILESYSTEM 后端（
type: FILESYSTEM，本地目录模拟桶；命令用法对 S3 型后端完全一致） - 实验拓扑：单机跑通 Prometheus → sidecar → 桶 → store → query 全链路，另有 rule / receive / query-frontend / bucket web 实测实例
二、thanos 命令总览
Thanos 全部能力收敛在一个静态二进制中，通过子命令区分组件角色：
thanos --version
thanos, version 0.42.4 (branch: HEAD, revision: 45c4f39487e1653e606307d3952a6259fb96acae)
build user: root@cbb5ace98a03
build date: 20260730-13:18:49
go version: go1.26.5
platform: linux/amd64
tags: netgo,slicelabels
thanos --help 2>&1 | grep -E '^\s+(sidecar|store|query|rule|compact|receive|query-frontend)'
sidecar Sidecar for Prometheus server.
store Store node providing access to their blocks stored in object storage.
query Query node exposing PromQL API with Thanos features.
rule Ruler evaluating alert and recording rules against Thanos nodes.
compact Continuously compacts the historical blocks in the object storage.
receive Accept Prometheus remote write API requests and write to local tsdb.
query-frontend Query frontend node implementing Thanos APIs.
tools Tools for maintaining Thanos (bucket verify, rewrite, replicate etc.).
七个子命令 + 一个 tools 工具集。所有组件共享一组全局旗标（--log.level、--log.format=logfmt|json|journald、--http-address、--grpc-address 等），日志格式可用 --log.format=json 切换为 JSON 便于采集。
三、组件启动命令详解
3.1 sidecar —— Prometheus 的贴身代理
thanos sidecar \
--tsdb.path=/var/lib/prometheus \
--prometheus.url=http://localhost:9090 \
--objstore.config-file=/etc/thanos/objstore.yml \
--grpc-address=0.0.0.0:10901 \
--http-address=0.0.0.0:10903
关键日志（启动成功后）：
ts=2026-10-19T19:51:37.86302903Z caller=sidecar.go:259 level=info msg="successfully loaded prometheus external labels" external_labels="{cluster=\"lab-cluster\", environment=\"lab\", replica=\"A\"}"
ts=2026-10-19T19:51:37.863060678Z caller=intrumentation.go:60 level=info msg="changing probe status" status=ready
ts=2026-10-19T19:51:37.863156295Z caller=grpc.go:162 level=info service=gRPC/server component=sidecar msg="listening for serving gRPC" address=0.0.0.0:10901
首批块上传成功日志：
ts=2026-10-19T20:03:19.301443329Z caller=shipper.go:479 level=info msg="upload new block" id=01M5AW53K2913AD282X8CNZWGT
要点：
--tsdb.path必须与 Prometheus--storage.tsdb.path同目录；- ⚠️ 0.42.x 已移除
--min-block-duration旗标，sidecar 自动从 Prometheus/api/v1/status/config感知块时长（老版本教程里的thanos sidecar --min-block-duration=2h在 0.42 会报 unknown long flag）； - 前置条件：Prometheus 必须配置
--storage.tsdb.min-block-duration=2h --storage.tsdb.max-block-duration=2h，否则 sidecar 校验失败：found that TSDB Max time is 1d12h and Min time is 2h. Compaction needs to be disabled。
3.2 query —— 全局查询
端点发现文件写法（/etc/thanos/endpoints.yml，0.42.x schema 为 endpoints[].address）：
endpoints:
- address: localhost:10901
- address: localhost:10905
启动：
thanos query \
--http-address=0.0.0.0:8128 \
--grpc-address=0.0.0.0:10904 \
--endpoint.sd-config-file=/etc/thanos/endpoints.yml \
--query.replica-label=replica
验证数据源注册：
curl -s http://localhost:8128/api/v1/stores | python3 -m json.tool
{
"status": "success",
"data": {
"sidecar": [
{
"name": "localhost:10901",
"lastCheck": "2026-10-19T19:56:36.909980229Z",
"lastError": null,
"labelSets": [
{
"cluster": "lab-cluster",
"environment": "lab",
"replica": "A"
}
]
}
],
"store": [
{
"name": "localhost:10905",
"lastCheck": "2026-10-19T19:56:36.909980229Z",
"lastError": null,
"labelSets": []
}
]
}
}
要点：
--endpoint.sd-config-file是 0.42.x 推荐写法；旧的重复旗标--endpoint=localhost:10901 --endpoint=localhost:10905仍可用但已废弃；- ⚠️ 若端点文件误写为旧版
targets字段，日志会持续刷invalid target address "": missing address，/api/v1/stores返回空——这是 0.4x 升级后最典型的坑； --query.replica-label=replica：多副本去重标签；- 端点文件默认每 5 分钟自动重载（
--endpoint.sd-config-reload-interval），改完不必立刻重启。
3.3 store —— 历史块网关（Store Gateway）
thanos store \
--data-dir=/var/lib/thanos/store \
--objstore.config-file=/etc/thanos/objstore.yml \
--grpc-address=0.0.0.0:10905 \
--http-address=0.0.0.0:8129
启动即同步桶内块元数据：
ts=2026-10-19T20:08:37.597900138Z caller=fetcher.go:337 level=info msg="successfully synchronized block metadata" component=store cached=2 returned=2 partial=0
cached=2 returned=2 表示桶内 2 个块已纳入索引缓存。要点：
--data-dir是索引缓存目录，重启不重扫全桶；- 块元数据每 3 分钟自动重同步（
--sync-block-interval）。
3.4 compact —— 桶内压实与降采样
thanos compact \
--data-dir=/var/lib/thanos/compact \
--objstore.config-file=/etc/thanos/objstore.yml \
--http-address=0.0.0.0:8131 \
--retention.resolution-raw=30d \
--retention.resolution-5m=90d \
--retention.resolution-1h=0d \
--wait
关键日志：
ts=2026-10-19T20:08:52.301818255Z caller=fetcher.go:337 level=info msg="successfully synchronized block metadata" component=compact cached=2 returned=2 partial=0
ts=2026-10-19T20:08:52.306476175Z caller=sync.go:134 level=info msg="start of GC" component=compact
ts=2026-10-19T20:08:52.307735027Z caller=compact.go:663 level=info msg="compaction iterations done, aborting." component=compact
要点：
- ⚠️ 0.42.x 保留期旗标为点号分隔：
--retention.resolution-raw（写成连字符--retention-resolution-raw会报unknown long flag）； --wait：处理完存量后常驻等待新块；一次性模式去掉--wait即跑完退出；- ⚠️ 同一桶只能运行一个 compact 实例；
- 压实动作只在凑满压实窗口的块数时触发（如 2h 块 ×2 合并为 4h? 实际按 2h→12h→24h 层级），刚部署无块可压属正常。
3.5 rule —— 规则评估
规则文件 /etc/thanos/rules.yml 示例：
groups:
- name: lab-alerts
interval: 10s
rules:
- record: job:up:sum
expr: sum by (job) (up)
- alert: InstanceDown
expr: up == 0
for: 1m
labels:
severity: critical
annotations:
summary: "Instance {{ $labels.instance }} down"
description: "{{ $labels.instance }} of job {{ $labels.job }} has been down for more than 1 minute."
启动（挂接 Query 全局视图，结果写自有 TSDB 并上传桶）：
thanos rule \
--data-dir=/var/lib/thanos/rule \
--query=localhost:10904 \
--grpc-address=0.0.0.0:10906 \
--http-address=0.0.0.0:8132 \
--rule-file=/etc/thanos/rules.yml \
--objstore.config-file=/etc/thanos/objstore.yml
查看已加载规则：
curl -s http://localhost:8132/api/v1/rules | python3 -c "import json,sys; d=json.load(sys.stdin)['data']['groups']; print(d[0]['name'], [r['name'] for r in d[0]['rules']])"
lab-alerts ['job:up:sum', 'InstanceDown']
要点：--query 可重复多次连接多个 query 实例；--alertmanagers.url 指定告警接收方（可多个）；rule 产出的记录/告警序列以块形式上传桶，从而也能被长期保留。
3.6 receive —— 远程写入接收端
分片配置 /etc/thanos/hashrings.json：
[
{
"hashring": "ring0",
"endpoints": ["localhost:10907"]
}
]
启动：
thanos receive \
--http-address=0.0.0.0:8137 \
--grpc-address=0.0.0.0:10907 \
--remote-write.address=0.0.0.0:10908 \
--tsdb.path=/var/lib/thanos/receive-tsdb \
--label='receive_replica="r0"' \
--receive.hashrings-file=/etc/thanos/hashrings.json \
--receive.local-endpoint=localhost:10907 \
--objstore.config-file=/etc/thanos/objstore.yml
启动日志确认运行模式：
ts=2026-10-19T20:08:22.406918562Z caller=intrumentation.go:60 level=info msg="changing probe status" status=ready
配合 Prometheus 数据源把样本远程写入 receive（/etc/prometheus/prometheus.yml 追加）：
remote_write:
- url: http://localhost:10908/api/v1/receive
reload 后数据落盘验证：
curl -X POST http://localhost:8136/-/reload
sleep 20
ls /var/lib/thanos/receive-tsdb/default-tenant/
chunks_head lock thanos.shipper.json wal
要点：
--label='receive_replica="r0"'：receive 给接收到的序列强制附加的标签，值必须带引号（漏引号报parse error: label value must be quoted）；- ⚠️
--receive.local-endpoint必须与 hashring 里的本机端点一致：实测缺省时 receive 以mode=RouterOnly启动，只转发不落盘，remote_write 持续context deadline exceeded；补齐后变为mode=RouterIngestor才正常写入； - 常用旗标速查：
--receive.hashrings-file（0.42.x 的分片文件旗标，旧名--hashrings-file已废弃）、--receive.replication-factor=3（多副本）。
3.7 query-frontend —— 查询缓存网关
thanos query-frontend \
--http-address=0.0.0.0:8134 \
--query-frontend.downstream-url=http://localhost:8128
curl -s http://localhost:8134/-/ready
OK
经前端查询与直连 query 等价（响应体多 analysis 缓存分析字段）：
curl -s 'http://localhost:8134/api/v1/query?query=up'
{"status":"success","data":{"resultType":"vector","result":[{"metric":{"__name__":"up","cluster":"lab-cluster","environment":"lab","instance":"localhost:10903","job":"thanos-sidecar"},"value":[1792440880.739,"1"]},...],"analysis":{}}}
要点：Grafana 大盘直接指向 query-frontend（8134）而非 query 本体，可显著降低重复查询压力；--query-range.split-interval=24h 控制大范围查询按天拆分。
四、tools bucket 桶运维工具
thanos tools bucket 包含全部桶运维子命令（实测枚举）：
thanos tools bucket --help 2>&1 | grep -oE 'tools bucket [a-z-]+' | sort -u
tools bucket cleanup
tools bucket downsample
tools bucket inspect
tools bucket ls
tools bucket mark
tools bucket replicate
tools bucket retention
tools bucket rewrite
tools bucket upload-blocks
tools bucket verify
tools bucket web
💡 工具对比：
子命令 用途 破坏性 ls / inspect / web / verify 巡检、审计、可视查看、一致性校验 无 upload-blocks 把本地 Prometheus 块导入桶（迁移场景） 无（新增） mark 给块打标记（删除/不压实/不下采样） 低（可逆） cleanup / retention 按标记与保留期物理清理 高 rewrite / replicate / downsample 重写、跨桶复制、手动降采样 高
以下均在 FILESYSTEM 桶（/etc/thanos/objstore.yml）实测。
4.1 bucket ls —— 枚举桶内块
thanos tools bucket ls --objstore.config-file=/etc/thanos/objstore.yml
01M5AV7K4X3SQDHZP4K5ZHZQB4
01M5AV8Z35D5WRA2Z64PFFE3D8
01M5AW2QJ1FQD4BTY1MEAZYJN2
01M5AW53K2913AD282X8CNZWGT
01M5AWDSX9VDFZ9KZY7QX51H7X
ULID 按时间单调递增，可直接看出块的新旧。
4.2 bucket inspect —— 块审计报表
thanos tools bucket inspect --objstore.config-file=/etc/thanos/objstore.yml
| ULID | FROM | UNTIL | RANGE | RES | #SERIES | #SAMPLES | #CHUNKS | #COMP-LEVEL | SOURCE | AGE |
|-----------------|---------|-----------|----------------|---------|---------|----------|---------|-------------|--------|-------|
| 01M5AV8Z35D5W.. | 20:05:0 | 20:10:0 | 00:05:00 | 0s | 3 | 180 | 3 | 1 | compactor | 1h 40m |
| 01M5AW2QJ1FQD4.. | 20:00:0 | 20:05:0 | 00:05:00 | 0s | 5 | 300 | 5 | 1 | compactor | 1h 45m |
| 01M5AW53K2913A.. | 19:55:0 | 20:00:0 | 00:05:00 | 0s | 5 | 300 | 5 | 1 | sidecar | 1h 50m |
| 01M5AWDSX9VDFZ.. | 19:50:0 | 19:55:0 | 00:05:00 | 0s | 5 | 300 | 5 | 1 | sidecar | 1h 55m |
可以看到每个块的时间范围、分辨率、系列数与来源（sidecar 上传 / compactor 产出）。时间越长越能看出压实合并效果。
4.3 bucket verify —— 桶一致性校验
thanos tools bucket verify --objstore.config-file=/etc/thanos/objstore.yml 2>&1 | tail -2
level=info component=verify ts=2026-10-19T20:15:42.742343213Z msg="verified blocks" result="no issues found"
要点：会下载全部块做完整校验，桶很大时用 --issues=index --objects= 等旗标缩小校验范围，避免全量下载。
4.4 bucket web —— 块可视化浏览
thanos tools bucket web \
--http-address=0.0.0.0:8135 \
--objstore.config-file=/etc/thanos/objstore.yml
ts=2026-10-19T19:55:01.874475926Z caller=intrumentation.go:60 level=info msg="changing probe status" status=ready
浏览器访问 http://<服务器IP>:8135 即块时间线 UI（按天/按块视角浏览桶内容）。只读、随时可停。
4.5 bucket upload-blocks —— 本地块导入桶
把既有 Prometheus 块目录（如老机器迁移的 data/prometheus/ 下块）导入新桶：
mkdir -p /tmp/prom-blocks && cp -r /var/lib/thanos/bucket/01M5AV7K4X3SQDHZP4K5ZHZQB4 /tmp/prom-blocks/
thanos tools bucket upload-blocks \
--objstore.config-file=/etc/thanos/objstore-upload.yml \
--path=/tmp/prom-blocks \
--label='cluster="lab-cluster"'
level=info ts=2026-10-19T20:17:11.930747443Z caller=upload.go:141 component=tools-bucket-upload-blocks msg="uploaded 1 blocks" blocks=1
⚠️ 不带 --label 会直接报错 no labels provided ... must provide at least one external label，导入时必须补上外部标签（纯 Prometheus 块没有 Thanos 外部标签）。
4.6 bucket mark —— 给块打标记
thanos tools bucket mark \
--id=01M5AV7K4X3SQDHZP4K5ZHZQB4 \
--marker=deletion-mark.json \
--details="mark for deletion demo" \
--objstore.config-file=/etc/thanos/objstore-upload.yml
marking with deletion-mark.json
⚠️ --marker 的合法值是完整文件名枚举：deletion-mark.json / no-compact-mark.json / no-downsample-mark.json，写 deletion-mark 会报 enum value must be one of deletion-mark.json,no-compact-mark.json,no-downsample-mark.json, got 'deletion-mark'。落标记后由 cleanup/compact 物理清理（受 --delete-delay 保护，默认 24h）。
4.7 bucket cleanup —— 清理已标记块
thanos tools bucket cleanup \
--objstore.config-file=/etc/thanos/objstore-upload.yml \
--delete-delay=0s
level=info ts=2026-10-19T20:18:03.114748921Z caller=cleanup.go:130 component=tools-bucket-cleanup msg="start of GC"
level=info ts=2026-10-19T20:18:03.118067604Z caller=cleanup.go:110 component=tools-bucket-cleanup msg="cleanup done"
要点：cleanup 只处理"过了 delete-delay 的删除标记块"与超期保留块；--delete-delay 是防误删缓冲（生产请保持默认 24h 以上）。危险操作（rewrite/retention）建议先 bucket verify + 快照桶再执行。
五、tools rules-check —— 规则文件校验
合法规则：
thanos tools rules-check --rules=/etc/thanos/rules.yml
Checking /etc/thanos/rules.yml
SUCCESS: 1 rule groups found
SUCCESS: 2 rules found
非法规则（表达式语法错误）：
thanos tools rules-check --rules=/etc/thanos/bad-rules.yml
Checking /etc/thanos/rules.yml
FAILED: 1 rule groups found
FAILED: 2 rules found
/etc/thanos/bad-rules.yml: field expr: invalid value "up ==": 1:6: parse error: unexpected "="
要点：ruler 启动前先跑一遍 rules-check，可避免规则文件带病上线；输出行数与 group/rule 数对应，FAILED 时附精确文件行列。
六、常见问题（FAQ）
Q1：老教程旗标在 0.42.x 报 unknown long flag 怎么办？
0.42.x 旗标变化集中在三处：① sidecar 移除 --min-block-duration（自动感知）；② query 的 --store 改为 --endpoint.sd-config-file（临时可用 --endpoint）；③ compact 保留期从连字符改点号（--retention.resolution-raw）。遇到旗标问题先 thanos <组件> --help | grep <关键词> 核对。
Q2：endpoint 文件写法不确定时如何快速自证？
用最小配置试启动，观察两处：日志无 invalid target address "": missing address，且 curl /api/v1/stores 返回非空即 schema 正确。
Q3：bucket 工具跑 S3 型桶需要注意什么？
objstore.yml 换成对应 type（如 S3 配 endpoint/bucket/access_key/secret_key/b insecure 等），子命令与本文完全一致；首次使用建议先 bucket ls 验证连通性，再跑只读类 inspect/verify，最后才考虑 mark/cleanup。
Q4：如何安全排空/迁移一个桶？
先 bucket verify 确认无坏块 → bucket replicate 全量复制到新桶 → 切换组件 objstore 配置 → 旧桶保留观察期后 bucket mark + bucket cleanup 清理。
七、参考链接
- Thanos CLI 官方参考：https://thanos.io/tip/thanos/cli/
- 桶运维工具文档：https://thanos.io/tip/thanos/tools.md/
- 存储配置格式：https://thanos.io/tip/thanos/storage.md/
- 站内相关：《Thanos 0.42.4 介绍与选型指南》（点击跳转）、《Ubuntu 22.04 安装 Thanos 0.42.4 指南》（点击跳转）、《Thanos 0.42.4 部署指南》（点击跳转）