Thanos 快速上手指南:源码构建、组件化部署与单机快速验证
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 方式下载安装。原因有二:
- 从 Go 1.17 起,
go get安装可执行文件已被弃用; - 更关键的是,Thanos 的模块使用了
replace指令(用于及时解除上游阻塞并保持对复用包的灵活控制),而这与go install对"同一模块主包"的要求冲突。因此 Thanos 官方短期内不会支持go install。
从源码构建的步骤:
- 准备 Go 1.18+ 工具链(原文档要求;考虑到当前仓库 go.mod 已声明 go 1.26.0,实际构建请以仓库要求为准),并配置好
GOPATH、PATH=${GOPATH}/bin:${PATH}; - 克隆本仓库:
git clone https://gitcode.com/gh_mirrors/than/thanos.git - 进入仓库根目录,借助项目准备好的
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 模式)大致为:
- 创建规则文件
data/rules.yml,内含一个记录规则job:go_threads:sum和一个告警规则HighGoThreads; - 启动 3 个 Prometheus(监听
9090/9091/9092),每个都带external_labels: prometheus=prom-<i>,并启用--web.enable-lifecycle(Sidecar 依赖 Prometheus 的 reload 端点); - 为每个 Prometheus 启动一个 Sidecar,分别暴露 gRPC
10901/10911/10921与 HTTP10902/10912/10922,并把它们以--endpoint 127.0.0.1:109<i>1形式收集起来; - 启动 Ruler(监听 HTTP
19999、gRPC19998),指向两个 Query 节点评估上述规则; - 启动两个 Query 节点(gRPC
10903/10913、HTTP10904/10914),通过--query.replica-label prometheus与--query.replica-label receive_replica开启基于副本标签的去重,并向 Ruler、Sidecar(及可选的 Store)注册全部 Store API 端点; - 若启用对象存储,最后还会启动
tools bucket web(HTTP10933)供浏览器直接浏览桶内数据。
全部进程由 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 章节的推荐起点):
- Jsonnet Mixins:mixin/README.md 提供了通过 Jsonnet 一键生成告警规则、记录规则与 Grafana 仪表盘的入口;
- 示例 Grafana 仪表盘:examples/dashboards/dashboards.md(overview、query、store、compact、receive、rule、sidecar、bucket-replicate、query-frontend 等);
- 示例告警规则:examples/alerts/alerts.md 与配套的 examples/alerts/rules.yaml、examples/alerts/tests.yaml。
这些均由 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 等用户的规模实践),相关主题索引可追溯到官方文档的历史记录。
进一步深入学习的仓库内资源:
- docs/quick-tutorial.md:组件级图文教程(Sidecar、Query、Store Gateway、Compactor、Ruler)
- docs/components/query.md、docs/components/sidecar.md、docs/components/store.md、docs/components/compact.md、docs/components/rule.md、docs/components/receive.md:各组件完整配置参考
- docs/storage.md:对象存储配置与桶内数据格式
- docs/service-discovery.md:Querier 的 Store API 发现机制
- docs/integrations.md:与外部系统的集成方式
- docs/release-process.md:版本发布节奏与流程
- scripts/quickstart.sh:单机快速验证脚本