Ubuntu 22.04 安装 Thanos 0.42.4 指南

目标：在 Ubuntu 22.04 服务器上从零安装 Thanos 0.42.4，并以 systemd 托管其 sidecar/store/query/compact 四个核心组件，配合本机 Prometheus 3.15.0 打通"本地采集 → 对象存储归档 → 全局查询"全链路。已在 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（Thanos sidecar 的数据源，需同机部署）
部署目录：二进制 /usr/local/bin，配置 /etc/thanos，数据 /var/lib/thanos
运行账户：专用系统用户 thanos、prometheus
端口规划（单机全组件）：

组件	gRPC (StoreAPI)	HTTP
Prometheus	—	9090
thanos sidecar	10901	10902
thanos query	10904	10903
thanos store	10905	10906
thanos compact	—	10907

二、前置条件

2.1 安装基础工具

Thanos 本体是静态编译的 Go 二进制，无运行时依赖，只需基础下载与解压工具：

apt update && apt install -y wget curl tar

命中:1 http://mirrors.aliyun.com/ubuntu jammy InRelease
正在读取软件包列表... 完成
正在分析软件包的依赖关系树... 完成
正在读取状态信息... 完成
wget 已经是最新版本 (1.21.2-2ubuntu1.1)。
tar 已经是最新版本 (1.34+dfsg-1ubuntu0.1.22.04.2)。
升级了 0 个软件包，新安装了 0 个软件包，要卸载 0 个软件包，有 0 个软件包未被升级。

2.2 安装并配置 Prometheus 3.15.0（数据源）

Sidecar 必须与一个本机 Prometheus 协同工作。若服务器尚未安装 Prometheus，按以下步骤安装官方二进制版：

cd /root
wget https://github.com/prometheus/prometheus/releases/download/v3.15.0/prometheus-3.15.0.linux-amd64.tar.gz

--2026-10-20 03:47:20--  https://github.com/prometheus/prometheus/releases/download/v3.15.0/prometheus-3.15.0.linux-amd64.tar.gz
正在解析主机 github.com (github.com)... 140.82.121.4, 140.82.121.3
正在连接 github.com (github.com)|140.82.121.4|:443... 已连接。
已发出 HTTP 请求，正在等待回应... 302 Found
位置: https://release-assets.githubusercontent.com/... [跟随至新的 URL]
--2026-10-20 03:47:21--  https://release-assets.githubusercontent.com/...
已保存至："prometheus-3.15.0.linux-amd64.tar.gz"

2026-10-19 19:47:32 (29.4 MB/s) - 已保存 "prometheus-3.15.0.linux-amd64.tar.gz" [111651578/111651578])

💡 国内网络访问 GitHub Releases 偶发缓慢或超时，可加代理：wget -e use_proxy=yes -e http_proxy=http://<代理IP>:<端口> <URL>，或从镜像站下载同名文件后校验 sha256 一致即可。

校验并安装：

sha256sum prometheus-3.15.0.linux-amd64.tar.gz

2a542df32eac02ee17b9d844fb2aa1de00dafa5476579ba8a3ba862e9d572ea0  prometheus-3.15.0.linux-amd64.tar.gz

tar -xzf prometheus-3.15.0.linux-amd64.tar.gz
useradd --no-create-home --shell /usr/sbin/nologin prometheus
mkdir -p /opt/prometheus /etc/prometheus /var/lib/prometheus
mv prometheus-3.15.0.linux-amd64/prometheus prometheus-3.15.0.linux-amd64/promtool /usr/local/bin/
prometheus --version

prometheus, version 3.15.0 (branch: HEAD, revision: 5241a27fe3c6983549fccc32f6e65917408c63cd)
  build user:       root@4635dd007a60
  build date:       20260925-07:33:45

⚠️ 关键配置：Thanos sidecar 要求 Prometheus 关闭本地块压实（min 与 max 块时长必须相等，否则 sidecar 拒绝接入），Prometheus 配置文件 /etc/prometheus/prometheus.yml 示例：

global:
  scrape_interval: 15s
  external_labels:
    cluster: prod-cluster
    replica: A

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ['localhost:9090']

  - job_name: thanos-sidecar
    static_configs:
      - targets: ['localhost:10902']

逐项说明：

external_labels：Thanos 全局视图的"身份标签"，多副本场景每个 Prometheus 必须有唯一的 replica 值（如 A/B），同一集群的实例 cluster 值相同；
job_name: thanos-sidecar：让 Prometheus 顺带抓取 sidecar 自身指标，便于监控 sidecar 健康度。

Prometheus 的 systemd 单元 /etc/systemd/system/prometheus.service（注意 min/max 块时长两行）：

[Unit]
Description=Prometheus Server
Documentation=https://prometheus.io/docs/introduction/overview/
After=network-online.target

[Service]
Type=simple
User=prometheus
Group=prometheus
ExecStart=/usr/local/bin/prometheus \
  --config.file=/etc/prometheus/prometheus.yml \
  --storage.tsdb.path=/var/lib/prometheus \
  --storage.tsdb.min-block-duration=2h \
  --storage.tsdb.max-block-duration=2h \
  --web.listen-address=0.0.0.0:9090 \
  --web.enable-lifecycle
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

💡 技术拓展：Prometheus 本地块压实策略与 Thanos 的关系——

配置行为是否适配 Thanos
默认（min=2h，max=36h）本地持续压实到 36h ❌ sidecar 校验报错，块迟迟不上传
min=max=2h 本地只保留 2h 块，压实交给 Thanos Compactor ✅ 官方推荐

2h 块由 Prometheus 产出、sidecar 上传，之后本地按保留期清理，磁盘占用与本地保留时长无关。

配置	行为	是否适配 Thanos
默认（min=2h，max=36h）	本地持续压实到 36h	❌ sidecar 校验报错，块迟迟不上传
min=max=2h	本地只保留 2h 块，压实交给 Thanos Compactor	✅ 官方推荐

三、版本选型说明

Thanos 遵循 semver，建议选官方 GitHub Releases 页最新稳定版（本文 0.42.4，查询日期 2026-10-20）；
同一 Thanos 集群内所有组件（sidecar/store/query/compact/rule/receive）必须同版本，升级时统一替换二进制并重启；
Thanos 0.42.x 要求 Prometheus ≥ 2.33；与 Prometheus 3.x 配合需 0.38 及以上版本。

四、安装方案 A：官方 tar.gz 在线安装

本方案直接从 GitHub Releases 下载官方静态二进制，适合可访问外网的服务器。

4.1 下载与校验

cd /root
wget https://github.com/thanos-io/thanos/releases/download/v0.42.4/thanos-0.42.4.linux-amd64.tar.gz

--2026-10-20 03:47:05--  https://github.com/thanos-io/thanos/releases/download/v0.42.4/thanos-0.42.4.linux-amd64.tar.gz
正在解析主机 github.com (github.com)... 140.82.121.4, 140.82.121.3
已发出 HTTP 请求，正在等待回应... 302 Found
位置: https://release-assets.githubusercontent.com/... [跟随至新的 URL]
100%[======================================>] 56,179,533  21.8MB/s 用时 2.5s

2026-10-19 19:47:16 (21.8 MB/s) - 已保存 "thanos-0.42.4.linux-amd64.tar.gz" [56179533/56179533])

sha256sum thanos-0.42.4.linux-amd64.tar.gz

5292f95f6f18199fe90cd24a5bf8eaca51ce48812a24f8778a3b9148c8fb71e1  thanos-0.42.4.linux-amd64.tar.gz

4.2 解压安装

tar -xzf thanos-0.42.4.linux-amd64.tar.gz
ls thanos-0.42.4.linux-amd64/

thanos

包内只有一个静态 thanos 二进制，所有组件都是它的子命令：

mv thanos-0.42.4.linux-amd64/thanos /usr/local/bin/thanos
chmod +x /usr/local/bin/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

4.3 创建运行账户与目录

useradd --no-create-home --shell /usr/sbin/nologin thanos
mkdir -p /etc/thanos /var/lib/thanos/bucket /var/lib/thanos/store /var/lib/thanos/compact
chown -R thanos:thanos /var/lib/thanos

目录用途：

/etc/thanos：Thanos 配置文件（对象存储、端点发现）；
/var/lib/thanos/bucket：对象存储桶根目录（本文用本地文件系统模拟桶，生产替换为 S3/MinIO 等远端后端）；
/var/lib/thanos/store：Store Gateway 的块索引缓存目录；
/var/lib/thanos/compact：Compactor 的工作目录。

4.4 对象存储配置

写入 /etc/thanos/objstore.yml：

type: FILESYSTEM
config:
  directory: /var/lib/thanos/bucket

💡 技术拓展：对象存储后端 type 常用取值对比——

type 说明备注
S3 AWS S3 及一切 S3 兼容（MinIO/Ceph 等）生产最常用，需 access_key/secret_key
GCS Google Cloud Storage 需服务账号 JSON
AZURE Azure Blob Storage 需存储账号与密钥
FILESYSTEM 本地目录模拟桶仅实验/单机，不具备异地容灾

本文采用 FILESYSTEM 打通全链路；生产环境改为 S3 型后端只需替换本文件，组件命令不变。

type	说明	备注
S3	AWS S3 及一切 S3 兼容（MinIO/Ceph 等）	生产最常用，需 access_key/secret_key
GCS	Google Cloud Storage	需服务账号 JSON
AZURE	Azure Blob Storage	需存储账号与密钥
FILESYSTEM	本地目录模拟桶	仅实验/单机，不具备异地容灾

五、安装方案 B：离线安装（内网断网环境）

内网服务器无法直连 GitHub 时，在任意外网机器下载安装包，经内部跳板传入后按相同步骤安装。

在外网机下载（命令与校验值与方案 A 一致）：

wget https://github.com/thanos-io/thanos/releases/download/v0.42.4/thanos-0.42.4.linux-amd64.tar.gz
sha256sum thanos-0.42.4.linux-amd64.tar.gz

5292f95f6f18199fe90cd24a5bf8eaca51ce48812a24f8778a3b9148c8fb71e1  thanos-0.42.4.linux-amd64.tar.gz

传入内网服务器（以跳板 scp 为例，IP 按实际环境替换）：

scp thanos-0.42.4.linux-amd64.tar.gz root@192.168.1.100:/root/

内网服务器上执行与方案 A 完全相同的解压、安装、建户、建目录步骤（4.2 与 4.3 节），此处不再重复。离线安装后务必执行 sha256 校验，确保传输过程中文件未损坏。

六、方案对比与选择建议

维度	方案 A：在线 tar.gz	方案 B：离线 tar.gz
是否需联网	需访问 GitHub	不需要（跳板传入）
版本控制	下载时即锁定	安装包版本完全可控
适用场景	能出网的云主机	内网隔离环境
优缺点	简单直接	多一步分发，注意校验

两种方案产物完全一致（同一静态二进制），选择依据只有网络条件。Thanos 不提供官方 deb/rpm 包，也不建议用第三方打包源安装。

七、systemd 托管 Thanos 全组件

7.1 sidecar（与 Prometheus 同机，必装）

/etc/systemd/system/thanos-sidecar.service：

[Unit]
Description=Thanos Sidecar
Documentation=https://thanos.io/tip/thanos/sidecar.md/
After=network-online.target prometheus.service
Requires=prometheus.service

[Service]
Type=simple
User=thanos
Group=thanos
ExecStart=/usr/local/bin/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:10902
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

参数说明：

--tsdb.path：与 Prometheus --storage.tsdb.path 指向同一目录，sidecar 由此读取本地块并上传；
--prometheus.url：sidecar 通过 HTTP API 读取 Prometheus 近实时数据与外部标签；
--grpc-address：sidecar 的 StoreAPI 端口，供 Query 连接。

由于 sidecar 需要读 TSDB 并写入上传元数据，而 Prometheus 以 prometheus 用户运行、sidecar 以 thanos 用户运行，需为两者建立共享组：

usermod -aG prometheus thanos
chown -R prometheus:thanos /var/lib/prometheus
chmod -R g+rwX /var/lib/prometheus
find /var/lib/prometheus -type d -exec chmod g+s {} \;

⚠️ 若不做共享授权，sidecar 日志会反复出现 updating meta file failed ... /var/lib/prometheus/thanos.shipper.json.tmp: permission denied，详见常见问题 9.3。

7.2 store（Store Gateway，历史块查询）

/etc/systemd/system/thanos-store.service：

[Unit]
Description=Thanos Store Gateway
Documentation=https://thanos.io/tip/thanos/store.md/
After=network-online.target

[Service]
Type=simple
User=thanos
Group=thanos
ExecStart=/usr/local/bin/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:10906
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

参数说明：

--data-dir：本地索引缓存目录（store 会把桶内块的索引文件缓存到本地，重启不丢）；
--grpc-address：StoreAPI 端口，供 Query 连接，与 sidecar 的 10901 区分开。

7.3 query（全局查询）

先写端点发现文件 /etc/thanos/endpoints.yml：

endpoints:
  - address: localhost:10901
  - address: localhost:10905

⚠️ 0.42.x 的端点文件 schema 是 endpoints[].address（字符串数组）。若误写为旧版的 targets 列表，Query 日志会持续报 invalid target address "": missing address，且 /api/v1/stores 返回空。

/etc/systemd/system/thanos-query.service：

[Unit]
Description=Thanos Query
Documentation=https://thanos.io/tip/thanos/query.md/
After=network-online.target

[Service]
Type=simple
User=thanos
Group=thanos
ExecStart=/usr/local/bin/thanos query \
  --http-address=0.0.0.0:10903 \
  --grpc-address=0.0.0.0:10904 \
  --endpoint.sd-config-file=/etc/thanos/endpoints.yml \
  --query.replica-label=replica
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

参数说明：

--endpoint.sd-config-file：静态端点发现配置文件（推荐写法）；旧旗标 --endpoint=<addr> 仍可用但已标记废弃；
--query.replica-label=replica：多副本去重标签，Query 对该标签不同值的同指标样本自动合并。

7.4 compact（桶内压实与降采样）

/etc/systemd/system/thanos-compact.service：

[Unit]
Description=Thanos Compactor
Documentation=https://thanos.io/tip/thanos/compact.md/
After=network-online.target

[Service]
Type=simple
User=thanos
Group=thanos
ExecStart=/usr/local/bin/thanos compact \
  --data-dir=/var/lib/thanos/compact \
  --objstore.config-file=/etc/thanos/objstore.yml \
  --http-address=0.0.0.0:10907 \
  --retention.resolution-raw=30d \
  --retention.resolution-5m=90d \
  --retention.resolution-1h=0d \
  --wait
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

参数说明：

--retention.resolution-raw=30d：原始分辨率（0s）数据保留 30 天；
--retention.resolution-5m=90d：5 分钟降采样数据保留 90 天；
--retention.resolution-1h=0d：1 小时降采样数据永久保留；
--wait：处理完存量压实后不退出，常驻等待新块；
⚠️ 注意 0.42.x 旗标是点号分隔（--retention.resolution-raw），写成连字符 --retention-resolution-raw 会直接报 unknown long flag；
⚠️ 同一桶只能运行一个 compactor 实例，多实例并发压实会破坏块一致性。

7.5 启动与自启动

逐个启动（sidecar 依赖 Prometheus 先就绪）：

systemctl daemon-reload
systemctl enable --now prometheus.service

Created symlink /etc/systemd/system/multi-user.target.wants/prometheus.service → /etc/systemd/system/prometheus.service.

systemctl enable --now thanos-sidecar.service

Created symlink /etc/systemd/system/multi-user.target.wants/thanos-sidecar.service → /etc/systemd/system/thanos-sidecar.service.

systemctl enable --now thanos-store.service

Created symlink /etc/systemd/system/multi-user.target.wants/thanos-store.service → /etc/systemd/system/thanos-store.service.

systemctl enable --now thanos-query.service

Created symlink /etc/systemd/system/multi-user.target.wants/thanos-query.service → /etc/systemd/system/thanos-query.service.

systemctl enable --now thanos-compact.service

Created symlink /etc/systemd/system/multi-user.target.wants/thanos-compact.service → /etc/systemd/system/thanos-compact.service.

7.6 运行状态验证

systemctl is-active prometheus thanos-sidecar thanos-store thanos-query thanos-compact

active
active
active
active
active

systemctl status thanos-query --no-pager -n 0

● thanos-query.service - Thanos Query
     Loaded: loaded (/etc/systemd/system/thanos-query.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-19 19:50:09 UTC; 31s ago
       Docs: https://thanos.io/tip/thanos/query.md/
   Main PID: 2503 (thanos)
      Tasks: 13 (limit: 5753)
     Memory: 13.6M
        CPU: 77ms

Query 就绪与数据源注册验证：

curl -s http://localhost:10903/-/ready

OK

curl -s http://localhost:10903/api/v1/stores

{"status":"success","data":{"sidecar":[{"name":"localhost:10901","lastCheck":"2026-10-19T19:51:39.342231212Z","lastError":null,"labelSets":[{"cluster":"prod-cluster","replica":"A"}],"minTime":1792439414000,"maxTime":9223372036854775807}],"store":[{"name":"localhost:10905","lastCheck":"2026-10-19T19:51:39.342231212Z","lastError":null,"labelSets":[],"minTime":9223372036854775807,"maxTime":-9223372036854775808}]}}

sidecar 已注册且带外部标签 {cluster="prod-cluster", replica="A"}，store 尚无历史块（minTime/maxTime 为空属正常，等首批 2h 块上传后变化）。

7.7 端到端数据验证

curl -s 'http://localhost:10903/api/v1/query?query=up'

{"status":"success","data":{"resultType":"vector","result":[{"metric":{"__name__":"up","cluster":"prod-cluster","instance":"localhost:10902","job":"thanos-sidecar"},"value":[1792439531.284,"1"]},{"metric":{"__name__":"up","cluster":"prod-cluster","instance":"localhost:9090","job":"prometheus"},"value":[1792439531.284,"1"]}]}}

查询结果带有 cluster="prod-cluster" 外部标签，说明数据已经过 Thanos 链路（Query → Sidecar → Prometheus）。Query Web UI 地址：http://<服务器IP>:10903，可直接用 PromQL 浏览全部数据源。

八、配置说明

/etc/thanos/objstore.yml：对象存储配置，五个组件共用同一份（sidecar 上传、store 读取、compact 压实都指向同一个桶）；
/etc/thanos/endpoints.yml：Query 的数据源清单，新增 store/下级 query 时在此追加 address 后 systemctl restart thanos-query；
/etc/prometheus/prometheus.yml：数据源配置，核心是 external_labels 与 2h 块时长；
所有单元文件位于 /etc/systemd/system/，改动后需 systemctl daemon-reload。

九、常见问题（FAQ）

Q1：sidecar 启动后反复打印 failed to validate prometheus flags ... Compaction needs to be disabled，HTTP /-/ready 返回 NOT OK？

实测回显（节选）：

ts=2026-10-19T19:50:09.222974083Z caller=sidecar.go:198 level=warn msg="failed to validate prometheus flags. Is Prometheus running? Retrying" err="found that TSDB Max time is 1d12h and Min time is 2h. Compaction needs to be disabled"

原因：Prometheus 未设置 --storage.tsdb.max-block-duration=2h（默认最大压实窗口 36h，即 1d12h）。解决：按 2.2 节在 prometheus.service 补齐 min/max 两行，systemctl daemon-reload && systemctl restart prometheus，再重启 sidecar，日志出现 changing probe status status=ready 即恢复。

Q2：sidecar 日志报 updating meta file failed ... thanos.shipper.json.tmp: permission denied？

原因：TSDB 目录属主是 prometheus，sidecar 的 thanos 用户无写权限，无法维护上传台账。解决：按 7.1 节执行共享组授权（usermod -aG prometheus thanos + 组写权限 + 目录 SGID），重启 sidecar 后日志出现 successfully loaded prometheus external labels 即正常。

Q3：query 启动后 /api/v1/stores 为空、日志报 invalid target address ""？

原因：endpoints.yml 用了旧版 targets 字段，0.42.x 只认 endpoints[].address。按 7.3 节格式修正后重启 query。

Q4：compact 报 unknown long flag '--retention-resolution-raw'？

原因：0.42.x 保留期旗标为点号分隔（--retention.resolution-raw），连字符写法已废弃。改用点号写法即可。

Q5：查询正常但桶里一直没有块？

排查顺序：① 确认 Prometheus min=max=2h（Q1）；② 首个 2h 块要等 Prometheus 运行满 2 小时才产出，属正常等待；③ 确认 objstore.yml 的 directory 属主可写（chown -R thanos:thanos /var/lib/thanos）；④ 观察 journalctl -u thanos-sidecar | grep upload，出现 upload new block 即为成功。

十、卸载与清理

systemctl disable --now thanos-compact.service
systemctl disable --now thanos-query.service
systemctl disable --now thanos-store.service
systemctl disable --now thanos-sidecar.service
rm -f /etc/systemd/system/thanos-{compact,query,store,sidecar}.service
systemctl daemon-reload
rm -f /usr/local/bin/thanos
rm -rf /etc/thanos /var/lib/thanos

如需连同 Prometheus 一并卸载：

systemctl disable --now prometheus.service
rm -f /etc/systemd/system/prometheus.service
systemctl daemon-reload
rm -f /usr/local/bin/prometheus /usr/local/bin/promtool
rm -rf /etc/prometheus /var/lib/prometheus /opt/prometheus

十一、参考链接

Thanos 官方文档：https://thanos.io
安装与发布页：https://github.com/thanos-io/thanos/releases
sidecar 组件说明：https://thanos.io/tip/thanos/sidecar.md/
对象存储配置：https://thanos.io/tip/thanos/storage.md/
站内相关：《Ubuntu 24.04 安装 Prometheus 3.x》（点击跳转）、《Thanos 0.42.4 常用 CLI 命令与工具详解》（点击跳转）、《Thanos 0.42.4 部署指南》（点击跳转）