Thanos 0.42.4 部署指南

目标：以 Docker Compose 在单台 Ubuntu 服务器上部署 Thanos 0.42.4 监控体系（Prometheus + sidecar + store gateway + query + compactor），打通"采集 → 对象存储归档 → 全局查询"完整数据链路。全流程已在 Ubuntu 22.04（x86_64）+ Docker Compose v2 环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64）
Thanos：0.42.4（官方最新稳定版，2026-07-30 发布；版本查询日期 2026-10-20）
Prometheus：3.15.0（官方镜像 prom/prometheus:v3.15.0）
Docker：28.4.0，Docker Compose v2
部署目录：/opt/thanos/compose
对象存储：FILESYSTEM 后端（本地目录模拟桶；生产建议 S3/MinIO，配置同形）
端口与网络规划：

容器	对外端口（宿主机）	用途
query	8140	全局查询 Web UI / HTTP API
prometheus	8141	Prometheus Web UI
store	8143	Store Gateway HTTP
compact	8144	Compactor HTTP
sidecar	8145	Sidecar HTTP

容器网络：thanos-net，自定义网段 10.89.58.0/24（宿主机上已占用网段 10.89.33/10.89.56/10.89.57，避开即可）

二、部署方案与架构

                        ┌─────────────────────────── 宿主机目录共享 ───────────────────────────┐
                        │  ./data/prometheus（TSDB）        ./data/bucket（对象存储桶）        │
                        └──────────────┬──────────────────────────────┬───────────────────────┘
                                       │                              │
   prometheus(9090) ── 同目录共享 ──▶ sidecar ── 上传 2h 块 ──▶ FILESYSTEM 桶 ◀── 读取 ── store(10901)
        │ remote_write 无（本方案 sidecar 模式）                       ▲
        └── Prometheus 抓取自身                                      │
                                                                    │
              query(8140) ── StoreAPI 聚合 ──▶ sidecar:10901 + store:10901
                                                ▲
              compact(8144) ── 压实/降采样/保留期清理 ──▶ 桶

五个容器职责：

prometheus：数据源，带 external_labels，本地 TSDB 与 sidecar 共享目录；
sidecar：读取共享 TSDB，把 2h 块上传到桶；同时把 Prometheus 近实时数据以 StoreAPI 形式供查询；
store：Store Gateway，从桶读取历史块提供查询；
query：聚合 sidecar 与 store 两个数据源，对外提供统一 PromQL 查询；
compact：对桶内块做水平压实、降采样与保留期清理（单桶单实例）。

💡 说明：sidecar 模式是 Thanos 与 Prometheus 的经典组合；若需要 Prometheus 无本地磁盘的纯云端形态，可改用 Receive 模式（remote_write 直接收数），见 9.6 常见问题。

三、镜像与版本准备

docker pull prom/prometheus:v3.15.0

v3.15.0: Pulling from prom/prometheus
a6736d367d5c: Pull complete
...
Status: Downloaded newer image for prom/prometheus:v3.15.0
docker.io/prom/prometheus:v3.15.0

docker pull thanosio/thanos:v0.42.4

v0.42.4: Pulling from thanosio/thanos
9824cba7b2ae: Pull complete
...
Status: Downloaded newer image for thanosio/thanos:v0.42.4
docker.io/thanosio/thanos:v0.42.4

💡 国内拉取 Docker Hub 缓慢时可配置镜像加速器（/etc/docker/daemon.json 的 registry-mirrors）。Thanos 官方镜像每版本同时提供 amd64/arm64 架构。

四、部署准备

4.1 目录结构

mkdir -p /opt/thanos/compose/{etc,data/prometheus,data/store,data/compact,data/bucket}
cd /opt/thanos/compose

tree -L 2 /opt/thanos/compose

/opt/thanos/compose
├── data
│   ├── bucket      # 对象存储桶（sidecar 上传 / store 与 compact 读取）
│   ├── compact     # compactor 工作目录
│   ├── prometheus  # Prometheus TSDB（与 sidecar 共享）
│   └── store       # store gateway 索引缓存
├── docker-compose.yml
└── etc
    ├── endpoints.yml    # query 数据源清单
    ├── objstore.yml     # 对象存储配置（五个容器共用）
    └── prometheus.yml   # prometheus 配置

4.2 权限对齐（关键）

Thanos 官方镜像默认以 UID=1001 运行，Prometheus 官方镜像默认以 UID=65534（nobody）运行。为了让两个容器共享同一 TSDB 目录且都能写上传元数据，本方案把 Prometheus 容器也固定为 UID=1001（见 5.1 节 user: "1001:1001"），宿主机目录统一授权：

chown -R 1001:1001 /opt/thanos/compose/data

⚠️ 若跳过本步，容器启动后日志会出现 permission denied，详见常见问题 9.1/9.2。

4.3 配置文件

/opt/thanos/compose/etc/prometheus.yml：

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

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

⚠️ 本方案为便于快速验证上传链路，Prometheus 块时长直接给到 5 分钟（--storage.tsdb.min-block-duration=5m --storage.tsdb.max-block-duration=5m，写在 compose 的 command 里）。生产环境请改回官方推荐的 2h/2h，保证 Prometheus 关闭本地大块压实，由 Thanos Compactor 统一压实。

/opt/thanos/compose/etc/objstore.yml：

type: FILESYSTEM
config:
  directory: /bucket

/opt/thanos/compose/etc/endpoints.yml：

endpoints:
  - address: sidecar:10901
  - address: store:10901

⚠️ 0.42.x 端点文件 schema 是 endpoints[].address。误写为旧版 targets 字段时，query 日志会持续报 invalid target address "": missing address 且 /api/v1/stores 为空。

五、docker-compose.yml 详解

/opt/thanos/compose/docker-compose.yml：

services:
  prometheus:
    image: prom/prometheus:v3.15.0
    container_name: thanos-0-42-4-prometheus
    restart: unless-stopped
    user: "1001:1001"
    volumes:
      - ./etc/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./data/prometheus:/prometheus
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --storage.tsdb.path=/prometheus
      - --storage.tsdb.min-block-duration=5m
      - --storage.tsdb.max-block-duration=5m
      - --web.listen-address=0.0.0.0:9090
    ports:
      - "8141:9090"
    networks:
      - thanos-net

  sidecar:
    image: thanosio/thanos:v0.42.4
    container_name: thanos-0-42-4-sidecar
    restart: unless-stopped
    volumes:
      - ./data/prometheus:/prometheus
      - ./etc/objstore.yml:/etc/thanos/objstore.yml:ro
      - ./data/bucket:/bucket
    command:
      - sidecar
      - --tsdb.path=/prometheus
      - --prometheus.url=http://prometheus:9090
      - --objstore.config-file=/etc/thanos/objstore.yml
    ports:
      - "8145:10902"
    networks:
      - thanos-net
    depends_on:
      - prometheus

  store:
    image: thanosio/thanos:v0.42.4
    container_name: thanos-0-42-4-store
    restart: unless-stopped
    volumes:
      - ./etc/objstore.yml:/etc/thanos/objstore.yml:ro
      - ./data/store:/var/thanos/store
      - ./data/bucket:/bucket
    command:
      - store
      - --data-dir=/var/thanos/store
      - --objstore.config-file=/etc/thanos/objstore.yml
      - --http-address=0.0.0.0:10902
      - --grpc-address=0.0.0.0:10901
    ports:
      - "8143:10902"
    networks:
      - thanos-net

  query:
    image: thanosio/thanos:v0.42.4
    container_name: thanos-0-42-4-query
    restart: unless-stopped
    volumes:
      - ./etc/endpoints.yml:/etc/thanos/endpoints.yml:ro
    command:
      - query
      - --http-address=0.0.0.0:10902
      - --grpc-address=0.0.0.0:10904
      - --endpoint.sd-config-file=/etc/thanos/endpoints.yml
      - --query.replica-label=replica
    ports:
      - "8140:10902"
    networks:
      - thanos-net
    depends_on:
      - sidecar
      - store

  compact:
    image: thanosio/thanos:v0.42.4
    container_name: thanos-0-42-4-compact
    restart: unless-stopped
    volumes:
      - ./etc/objstore.yml:/etc/thanos/objstore.yml:ro
      - ./data/compact:/var/thanos/compact
      - ./data/bucket:/bucket
    command:
      - compact
      - --data-dir=/var/thanos/compact
      - --objstore.config-file=/etc/thanos/objstore.yml
      - --http-address=0.0.0.0:10902
      - --retention.resolution-raw=30d
      - --wait
    ports:
      - "8144:10902"
    networks:
      - thanos-net

networks:
  thanos-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.58.0/24

逐项说明：

user: "1001:1001"（prometheus 服务）：与 thanosio 镜像运行 UID 对齐，双方共用 ./data/prometheus 才能互写（TSDB 与 thanos.shipper.json 上传台账）；
sidecar 的 ./data/prometheus:/prometheus：必须与 prometheus 的 --storage.tsdb.path 指向同一宿主机目录，这是 sidecar 模式的前提；
三个组件（sidecar/store/compact）都要挂载桶目录 ./data/bucket:/bucket，漏挂任意一个都会触发 mkdir /bucket: permission denied（9.2 节）；
command 直接以列表形式传子命令与旗标（镜像 ENTRYPOINT 是 thanos）；
0.42.x 保留期旗标为点号分隔：--retention.resolution-raw（写成连字符会报 unknown long flag）；
thanos-net 显式指定 10.89.58.0/24 网段，避免与宿主机其他 compose 网段冲突。

六、启动部署

cd /opt/thanos/compose
docker compose up -d

[+] Running 6/6
 ✔ Network compose_thanos-net  Created
 ✔ Container thanos-0-42-4-prometheus  Started
 ✔ Container thanos-0-42-4-sidecar     Started
 ✔ Container thanos-0-42-4-store       Started
 ✔ Container thanos-0-42-4-query       Started
 ✔ Container thanos-0-42-4-compact     Started

查看运行状态（输出节选，仅列 Thanos 栈容器）：

docker compose ps

NAME                       IMAGE                     STATUS
thanos-0-42-4-compact      thanosio/thanos:v0.42.4   Up 9 minutes
thanos-0-42-4-prometheus   prom/prometheus:v3.15.0   Up 10 minutes
thanos-0-42-4-query        thanosio/thanos:v0.42.4   Up 19 minutes
thanos-0-42-4-sidecar      thanosio/thanos:v0.42.4   Up 9 minutes
thanos-0-42-4-store        thanosio/thanos:v0.42.4   Up 9 minutes

确认网络与容器 IP：

docker network ls | grep 58

b57a4c1a88f1   compose_thanos-net   bridge    local

docker inspect thanos-0-42-4-query --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'

10.89.58.3

七、部署验证

7.1 Query 数据源注册

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

OK

curl -s http://localhost:8140/api/v1/stores | python3 -m json.tool

{
    "status": "success",
    "data": {
        "sidecar": [
            {
                "name": "sidecar:10901",
                "lastCheck": "2026-10-19T20:03:19.554017581Z",
                "lastError": null,
                "labelSets": [
                    {
                        "cluster": "compose-cluster",
                        "replica": "A"
                    }
                ]
            }
        ],
        "store": [
            {
                "name": "store:10901",
                "lastCheck": "2026-10-19T20:03:19.554017581Z",
                "lastError": null,
                "labelSets": []
            }
        ]
    }
}

sidecar 与 store 两个数据源均注册成功且无 lastError。

7.2 实时数据查询

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

{"status":"success","data":{"resultType":"vector","result":[{"metric":{"__name__":"up","cluster":"compose-cluster","instance":"localhost:9090","job":"prometheus"},"value":[1792440772.950,"1"]}]}}

样本带 cluster="compose-cluster" 外部标签，说明 Query → Sidecar → Prometheus 链路正常。浏览器访问 http://<服务器IP>:8140 即 Query Web UI；http://<服务器IP>:8141 为 Prometheus 自身 UI。

7.3 块上传验证（约 5~10 分钟后）

Prometheus 产出首个 5m 块后，sidecar 日志出现上传记录：

docker logs thanos-0-42-4-sidecar 2>&1 | grep 'upload new block'

ts=2026-10-19T20:03:19.301443329Z caller=shipper.go:479 level=info msg="upload new block" id=01M5AW53K2913AD282X8CNZWGT
ts=2026-10-19T20:07:49.299766995Z caller=shipper.go:479 level=info msg="upload new block" id=01M5AWDSX9VDFZ9KZY7QX51H7X

桶目录落块：

ls data/bucket/

01M5AW2QJ1FQD4BTY1MEAZYJN2
01M5AW53K2913AD282X8CNZWGT
01M5AWDSX9VDFZ9KZY7QX51H7X

💡 生产环境使用 S3 型后端时，用 thanos tools bucket ls --objstore.config-file=... 达到同等效果，用法见《Thanos 0.42.4 常用 CLI 命令与工具详解》（点击跳转）。

八、运维操作

# 重启单个组件（改配置后）
docker compose restart query

# 查看组件日志
docker compose logs -f sidecar

# 停止/启动全栈
docker compose stop
docker compose start

# 修改 compose 配置后应用
docker compose up -d

# 彻底销毁（保留数据）
docker compose down
# 彻底销毁（含数据，危险）
docker compose down -v && rm -rf data/*

扩容提示：新增第二个 Prometheus 副本时，复制 prometheus+sidecar 两组 service，改容器名并设置 replica: B、不同 TSDB 目录；query 的 endpoints.yml 追加新 sidecar 地址后重启 query，--query.replica-label=replica 会自动完成双副本去重。

九、常见问题（FAQ）

Q1：prometheus 容器日志报 permission denied，sidecar 报 updating meta file failed ... thanos.shipper.json.tmp: permission denied？

实测回显（节选）：

caller=sidecar.go:478 level=error msg="updating meta file failed" err="open /prometheus/thanos.shipper.json.tmp: permission denied"

原因：TSDB 共享目录的宿主机属主与容器 UID 不一致（prometheus 镜像默认 UID=65534，thanosio 镜像 UID=1001）。解决：按 4.2/5.1 节，chown -R 1001:1001 ./data 且 prometheus 服务加 user: "1001:1001"，然后 docker compose up -d 重建。

Q2：sidecar 反复报 create upload dir: mkdirat thanos: permission denied 或 upload ... mkdir /bucket: permission denied？

原因：sidecar/store/compact 未挂载桶目录（漏写 ./data/bucket:/bucket），或挂载了但宿主机目录不可写。本方案实测中漏挂 sidecar 的桶目录即稳定复现该报错。补齐挂载并保证 data/bucket 属主为 1001 后 docker compose up -d 恢复。

Q3：query 的 /api/v1/stores 为空，日志持续 update of endpoint failed ... addr=""？

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

Q4：sidecar 日志报 failed to validate prometheus flags ... Compaction needs to be disabled？

原因：Prometheus 的 min/max 块时长不相等（默认 max=36h），sidecar 拒绝工作。两侧 --storage.tsdb.min-block-duration 与 --storage.tsdb.max-block-duration 必须相等（本方案演示用 5m，生产用 2h）。

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

原因：0.42.x 旗标是点号分隔（--retention.resolution-raw）。修改 compose 的 command 后 docker compose up -d。

Q6：想完全摆脱本地 TSDB、用纯 remote_write 接入怎么办？

将 sidecar 模式换为 Receive 模式：Prometheus 配置 remote_write 指向 receive 的 /api/v1/receive 端口，receive 组件（需 --receive.hashrings-file 分片配置与本机 --receive.local-endpoint 登记）接收数据落自有 TSDB 并上传桶，query 把 receive 的 StoreAPI 加入端点即可。单机 hashring 示例：

[
  {
    "hashring": "ring0",
    "endpoints": ["localhost:10907"]
  }
]

⚠️ 实测要点：hashring 端点未含本机地址时，receive 以 mode=RouterOnly 启动，remote_write 会持续 context deadline exceeded；必须加 --receive.local-endpoint=localhost:10907 使其进入 mode=RouterIngestor 才会落盘。

十、升级与回滚

# 升级（以 0.43.0 为例，版本号按官方 releases 实查为准）
docker pull thanosio/thanos:v0.43.0
sed -i 's|thanosio/thanos:v0.42.4|thanosio/thanos:v0.43.0|g' docker-compose.yml
docker compose up -d

# 回滚
sed -i 's|thanosio/thanos:v0.43.0|thanosio/thanos:v0.42.4|g' docker-compose.yml
docker compose up -d

⚠️ 全栈组件必须同版本升级/回滚；桶内历史块向后兼容，升级失败可直接回退镜像版本，数据无损。

十一、参考链接

Thanos 官方文档：https://thanos.io
官方 Compose 上手示例：https://thanos.io/tip/thanos/getting-started.md/
sidecar 组件说明：https://thanos.io/tip/thanos/sidecar.md/
对象存储配置：https://thanos.io/tip/thanos/storage.md/
镜像仓库：https://hub.docker.com/r/thanosio/thanos
站内相关：《Prometheus 3.x Docker Compose 部署指南》（点击跳转）、《Thanos 0.42.4 常用 CLI 命令与工具详解》（点击跳转）、《Thanos 0.42.4 介绍与选型指南》（点击跳转）