Thanos 快速上手指南:源码构建、组件化部署与单机快速验证

原创2026-09-21 20:45:161,683 阅读
文章标签:可观测性云原生时序数据库运维

Thanos 快速上手指南:源码构建、组件化部署与单机快速验证

Thanos 是一个以单一二进制形式交付的高可用 Prometheus 增强方案,核心能力覆盖全局查询视图、高可用数据采集、历史数据备份与廉价访问。本指南将带你走通从获取 Thanos、从源码构建,到按需部署各组件、并在单机上完成端到端快速验证的完整路径,帮助你基于当前仓库快速评估、试用并逐步落地 Thanos。

Thanos 的核心能力与设计理念

Thanos 将四类核心能力集成在单个二进制中,它们是:

  • 全局查询视图(Global Query View):通过 Querier 聚合多个 Prometheus 实例的数据,用一个入口查询全部指标。
  • 高可用(High Availability):支持多副本 Prometheus 采集与去重,任意单点故障不影响查询结果。
  • 数据备份(Data Backup):通过 Sidecar 将 Prometheus 本地数据持续备份到对象存储。
  • 历史数据廉价访问(Historical, Cheap Data Access):对象存储天然廉价,Store Gateway 与 Compactor 让历史数据可以被高效查询与压缩。

这些能力对应的组件彼此独立、可以单独部署。这意味着你可以只启用一个子集来获得即时收益或进行测试,也可以在生产环境渐进式铺开——这是 Thanos 渐进式落地(gradual roll out)的核心理念。Thanos 同时适用于云原生与传统环境:有的用户跑在 Kubernetes 上,有的直接部署在裸金属。

从源码结构看,这一"单二进制多组件"的设计非常直观:cmd/thanos/main.go 在同一个 kingpin 应用中注册了 sidecar、store、query、rule、compact、tools、receive、query-frontend 全部子命令,随后按用户解析出的子命令调用对应的 setup 函数启动组件。这也解释了为什么构建产物只有一个 thanos 可执行文件,却能承担全部职责。

依赖与前置条件

Thanos 追求简单直接的部署与运维模型,唯一的外部依赖是:

  • 一个或多个 Prometheus v2.2.1+ 实例,且必须使用持久化磁盘;
  • 可选的对象存储:用于长期数据备份与历史查询,Thanos 支持多种存储提供方(见 docs/storage.md),且可随需求扩展更多提供方。

值得注意的是,即便你不配置任何对象存储,仅凭 Sidecar 暴露的 Store API 也能让 Querier 获得跨多实例的全局查询能力——对象存储只是通往历史数据与真正长期存储的路径。

获取 Thanos

获取 Thanos 二进制有以下几种途径:

  • 正式发布版本:每个 minor 版本都会为各大平台构建 tarball,并发布对应的容器镜像(quay.io/thanos/thanos,同时镜像至 Docker Hub 的 thanosio/thanos 仓库)。
  • main 分支:main 保持稳定可用,每次提交都会构建名为 main-<date>-<sha> 的镜像并推送。
  • 发布节奏:项目每 6 周进行一次 minor 版本发布(由 Release Shepherd 负责从首个 RC 到正式发布的全流程),发布细节与排期表见 docs/release-process.md。

当前仓库的 VERSION 文件标注为 0.43.0-dev,即处于 0.43.0 版本开发周期中。

从源码构建 Thanos

Thanos 完全使用 Go 编写(当前仓库 go.mod 声明 go 1.26.0),因此可以在各种 x64 操作系统上运行。

重要限制:Thanos 不能通过 go get 或 go install 方式下载安装。原因有二:

  1. 从 Go 1.17 起,go get 安装可执行文件已被弃用;
  2. 更关键的是,Thanos 的模块使用了 replace 指令(用于及时解除上游阻塞并保持对复用包的灵活控制),而这与 go install 对"同一模块主包"的要求冲突。因此 Thanos 官方短期内不会支持 go install。

从源码构建的步骤:

  1. 准备 Go 1.18+ 工具链(原文档要求;考虑到当前仓库 go.mod 已声明 go 1.26.0,实际构建请以仓库要求为准),并配置好 GOPATH、PATH=${GOPATH}/bin:${PATH};
  2. 克隆本仓库:
    git clone https://gitcode.com/gh_mirrors/than/thanos.git
    
  3. 进入仓库根目录,借助项目准备好的 Makefile 构建:
    make help    # 查看全部可用目标
    make build   # 使用 promu 构建 thanos 二进制
    

构建完成后,thanos 二进制会出现在项目目录中——它是部署任何 Thanos 组件时唯一需要的产物。Makefile 中还提供了 make docker(构建 Docker 镜像)、make docker-multi-stage(多阶段构建)、make quickstart(安装依赖并运行单机快速启动脚本)等目标;make test 与 make test-e2e 则分别覆盖单元测试与基于 Docker 的端到端测试。

组件与典型部署拓扑

Tanos 各组件职责分明(KISS 与 Unix 哲学),在 docs/quick-tutorial.md 中有完整说明:

组件 职责
Sidecar 连接 Prometheus,读取其数据用于查询和/或上传到云存储
Store Gateway 服务对象存储桶内的指标数据
Compactor 对桶内数据做压缩、降采样与保留策略
Receiver 接收 Prometheus remote write 数据,暴露并/或上传到云存储
Ruler/Rule 基于 Thanos 数据进行记录与告警规则评估
Querier/Query 实现 Prometheus v1 API,聚合底层各组件数据
Query Frontend 实现 Prometheus v1 API 代理到 Querier,缓存响应并可按时段拆分查询

两种最常见的部署拓扑:

  • Sidecar 模式:每个 Prometheus 实例旁挂一个 Sidecar,Sidecar 负责备份数据并提供 Store API,适合"保留原生 Prometheus 采集体系、逐步叠加"的场景;
  • Receive 模式:通过 Thanos Receiver 接收 Prometheus remote write 数据,适合需要横向扩展写入或对接其他 remote write 兼容数据源的场景。

Kubernetes 生态下,社区维护了多种安装方式:prometheus-operator(支持部署带 Thanos 的 Prometheus)、kube-thanos(Jsonnet 模板)、以及社区 Helm charts。注意:Thanos 并不绑定 Kubernetes,仅因三者同属 CNCF 生态而流行于 K8s 之上。

单机快速体验:标准端口布局

生产环境不推荐把 Thanos 全部组件堆在单节点上——Thanos 本质上是为分布式系统设计的,小型场景使用原生 Prometheus 往往已经足够。但如果你只是想在一台机器上"玩玩看",请遵循如下标准端口布局,避免组件间端口冲突:

组件 接口 端口
Sidecar gRPC 10901
Sidecar HTTP 10902
Query gRPC 10903
Query HTTP 10904
Store gRPC 10905
Store HTTP 10906
Receive gRPC(Store API) 10907
Receive HTTP(remote write API) 10908
Receive HTTP 10909
Rule gRPC 10910
Rule HTTP 10911
Compact HTTP 10912
Query Frontend HTTP 10913

仓库为此提供了一个开箱即用的单机示例脚本 scripts/quickstart.sh,在安装了 prometheus 与 thanos 两个二进制的前提下,可通过 make quickstart 一键拉起整套环境。

深度拆解 quickstart 单机脚本

scripts/quickstart.sh 会依次启动三套 Prometheus、对应 Sidecar、两个 Query 节点、Ruler,以及可选的 Store Gateway、Receiver 与对象存储。脚本通过环境变量控制行为:

  • PROMETHEUS_EXECUTABLE / THANOS_EXECUTABLE:指定 prometheus 与 thanos 可执行文件路径;
  • MINIO_ENABLED:置为非空时,脚本自动拉起本地 MinIO(S3 兼容)作为对象存储,并生成 data/bucket.yml 配置文件;
  • OBJSTORECFG_FILE:不使用 MinIO 时,指向你自己的对象存储配置文件;
  • REMOTE_WRITE_ENABLED:置为非空时,改用 Receive 模式(三套 Receiver + remote write 写入 Prometheus)替代 Sidecar;
  • STATELESS_RULER_ENABLED:启用 Ruler 的 remote write 输出;
  • GCS_BUCKET / S3_ENDPOINT:启用 Store Gateway 与 tools bucket web。

脚本的核心流程(Sidecar 模式)大致为:

  1. 创建规则文件 data/rules.yml,内含一个记录规则 job:go_threads:sum 和一个告警规则 HighGoThreads;
  2. 启动 3 个 Prometheus(监听 9090/9091/9092),每个都带 external_labels: prometheus=prom-<i>,并启用 --web.enable-lifecycle(Sidecar 依赖 Prometheus 的 reload 端点);
  3. 为每个 Prometheus 启动一个 Sidecar,分别暴露 gRPC 10901/10911/10921 与 HTTP 10902/10912/10922,并把它们以 --endpoint 127.0.0.1:109<i>1 形式收集起来;
  4. 启动 Ruler(监听 HTTP 19999、gRPC 19998),指向两个 Query 节点评估上述规则;
  5. 启动两个 Query 节点(gRPC 10903/10913、HTTP 10904/10914),通过 --query.replica-label prometheus 与 --query.replica-label receive_replica 开启基于副本标签的去重,并向 Ruler、Sidecar(及可选的 Store)注册全部 Store API 端点;
  6. 若启用对象存储,最后还会启动 tools bucket web(HTTP 10933)供浏览器直接浏览桶内数据。

全部进程由 trap 'kill 0' SIGTERM 统一管理,等待信号退出。这套拓扑恰好演示了 Sidecar、Query、Rule、Store 与对象存储之间的完整调用链,也是快速验证"全局查询 + 去重 + 历史数据"的最短路径。

对象存储配置要点

对象存储是所有"块感知"组件(sidecar、compact、receive、store)的主要存储后端。配置方式有两种:

  • --objstore.config-file <path>:引用 YAML 配置文件;
  • --objstore.config <yaml>:直接在命令行内联 YAML(推荐,配置一目了然,免去额外文件管理)。

需要注意:每个组件只读取一个 bucket;若传入多文档 YAML(以 --- 分隔),只有第一个文档生效,其余被静默忽略。需要不同组件使用不同 bucket 时,应各自独立部署实例。

支持的存储提供方与成熟度见 docs/storage.md 的对照表,包括 Google Cloud Storage、AWS/S3(及 MinIO 等 S3 兼容存储)、Azure、OpenStack Swift、腾讯 COS、阿里云 OSS、百度 BOS、Oracle OCI、本地文件系统等。其中本地文件系统仅建议用于测试与演示,生产环境请选择强一致性的对象存储(强一致对单例 Compaction 是必要的)。

以 S3 为例,最小配置只需提供 bucket、endpoint、access_key、secret_key;若设置 aws_sdk_auth: true,则改用 AWS SDK 默认认证链(环境变量、~/.aws/config、IAM 等),此时仅需 bucket 与 endpoint。prefix 字段允许在同一桶内用前缀隔离不同数据源,便于不借助工具直接辨认块来源。更多参数(signature_version2、http_config、part_size、sse_config 服务端加密、STS 端点、存储分级等)的完整说明与 AWS IAM 策略示例都在 docs/storage.md 中。

运维配套:Mixin、Grafana 与告警

在运维层面,仓库提供了开箱即用的监控配套(原文档将其列为 Operating 章节的推荐起点):

这些均由 mixin/ 下的 libsonnet 源文件通过 make examples 生成,可随版本演进保持一致,是上线前监控自身健康度的标配。

部署到 Kubernetes 与交互式学习

  • 若想在不装任何东西的情况下先体验,官方维护了免费、浏览器内运行的交互式教程(Killercoda Thanos 课程),覆盖多个场景并持续更新;配套的图文教程见 docs/quick-tutorial.md,其中还详细演示了 Sidecar 的 Store API 暴露、旧数据回传(--shipper.upload-compacted)、外部标签约定(每个 Prometheus 实例必须有一组全局唯一的标识标签,如 region、monitor、replica)、Querier 静态端点与 dns+/dnssrv+ 服务发现,以及 HA 对去重(--query.replica-label)等实战细节。
  • 在 Kubernetes 上,可优先参考 prometheus-operator、kube-thanos 与社区 Helm charts;仓库内也有 tutorials/kubernetes-helm/README.md(使用官方 Prometheus Helm Chart 部署 Sidecar)与 tutorials/thanos-with-cilium/README.md(与 Cilium 集成的示例)可供参考。

社区、贡献与进一步阅读

Thanos 是完全开源的项目,欢迎新贡献者与社区成员。你可以通过 CNCF Slack 的 #thanos 频道与 GitHub Issues 参与讨论;贡献规范见 CONTRIBUTING.md,维护者名单见 MAINTAINERS.md。项目还沉淀了大量年度演讲与社区博客(涵盖 LastPass、Reddit、Monzo、HelloFresh、Alibaba Cloud 等用户的规模实践),相关主题索引可追溯到官方文档的历史记录。

进一步深入学习的仓库内资源:

登录后查看全文
thanos