📚 课程目录第3章 Tempo安装与部署

3. Tempo 安装与部署：使用 Docker Compose 快速部署

本章将带领你使用 Docker Compose 在本地快速搭建一套完整的 Grafana Tempo 分布式追踪系统。我们将采用 MinIO 作为后端存储，并验证所有组件的健康状态。这是后续进行性能瓶颈定位实验的基础环境。

3.1 架构概览

本次部署的架构包含三个核心组件：Tempo（负责接收和查询 Trace 数据）、MinIO（负责持久化存储 Trace 数据）以及 Grafana（负责可视化查询）。下图展示了它们之间的交互关系：

3.2 环境准备与目录结构

在开始部署之前，请确保你的环境中已安装 Docker 和 Docker Compose。建议使用 Docker Compose V2 版本。

创建一个项目目录，并按照以下结构组织配置文件：

tempo-quickstart/
├── docker-compose.yml
├── tempo/
│   └── tempo.yaml
└── minio/
    └── data/          # MinIO 数据持久化目录（自动创建）

3.3 核心配置文件详解

3.3.1 Tempo 配置文件 (tempo.yaml)

Tempo 的配置决定了它如何接收数据、如何与后端存储交互。以下配置启用了多租户（单租户模式）、gRPC 和 HTTP 接收器，并指定 MinIO 作为存储后端。

# tempo/tempo.yaml
server:
  http_listen_port: 3200
  grpc_listen_port: 9095

distributor:
  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: 0.0.0.0:4317
        http:
          endpoint: 0.0.0.0:4318
    jaeger:
      protocols:
        grpc:
          endpoint: 0.0.0.0:14250
        thrift_http:
          endpoint: 0.0.0.0:14268

ingester:
  trace_idle_period: 10s
  max_block_duration: 5m

compactor:
  compaction:
    block_retention: 48h

storage:
  trace:
    backend: s3
    s3:
      bucket: tempo-traces
      endpoint: minio:9000
      access_key: minioadmin
      secret_key: minioadmin
      insecure: true
    pool:
      max_workers: 100
      queue_depth: 10000

配置要点：

endpoint: minio:9000 使用 Docker Compose 服务名进行通信。
insecure: true 表示使用 HTTP 而非 HTTPS，仅适用于本地开发环境。
block_retention: 48h 设置数据保留时间为 48 小时，可根据需求调整。

3.3.2 Docker Compose 编排文件 (docker-compose.yml)

该文件定义了三个服务：minio、tempo 和 grafana。它们通过同一个网络 tempo-net 进行通信。

# docker-compose.yml
version: '3.8'

services:
  minio:
    image: minio/minio:latest
    container_name: minio
    command: server /data --console-address ":9001"
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    volumes:
      - ./minio/data:/data
    networks:
      - tempo-net

  tempo:
    image: grafana/tempo:latest
    container_name: tempo
    command: [ "-config.file=/etc/tempo.yaml" ]
    ports:
      - "3200:3200"
      - "9095:9095"
      - "4317:4317"
      - "4318:4318"
      - "14250:14250"
      - "14268:14268"
    volumes:
      - ./tempo/tempo.yaml:/etc/tempo.yaml
    depends_on:
      - minio
    networks:
      - tempo-net

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    environment:
      GF_AUTH_ANONYMOUS_ENABLED: "true"
      GF_AUTH_ANONYMOUS_ORG_ROLE: "Admin"
    volumes:
      - ./grafana/datasources:/etc/grafana/provisioning/datasources
    depends_on:
      - tempo
    networks:
      - tempo-net

networks:
  tempo-net:
    driver: bridge

端口冲突检查：请确保本地 3000、3200、9000、9001、4317、4318、14250、14268 等端口未被占用。如有冲突，请在 docker-compose.yml 中修改映射端口。

3.4 配置 Grafana 数据源

为了让 Grafana 能够查询 Tempo 中的 Trace 数据，需要预先配置 Tempo 数据源。Grafana 支持通过 provisioning 方式自动加载数据源配置。

创建目录 grafana/datasources/，并添加以下文件：

# grafana/datasources/tempo-datasource.yaml
apiVersion: 1

datasources:
  - name: Tempo
    type: tempo
    access: proxy
    url: http://tempo:3200
    isDefault: true
    editable: true

3.5 启动与验证

3.5.1 启动服务

在项目根目录下执行以下命令启动所有服务：

docker compose up -d

首次启动会自动拉取镜像，请保持网络畅通。启动完成后，可以使用 docker compose ps 查看服务状态：

docker compose ps

NAME                IMAGE                         STATUS              PORTS
minio               minio/minio:latest            Up (healthy)        0.0.0.0:9000-9001->9000-9001/tcp
tempo               grafana/tempo:latest          Up                  ...
grafana             grafana/grafana:latest        Up                  ...

3.5.2 验证 Tempo 健康状态

Tempo 提供了多个 HTTP 端点用于健康检查。以下是常用的验证方法：

验证目标	端点	预期结果
服务存活检查	`GET /ready`	返回 HTTP 200 OK
构建信息	`GET /status/buildinfo`	返回 JSON 格式的版本和构建信息
MinIO 存储连通性	`GET /status/endpoints`	返回已注册的后端存储端点列表
Grafana 数据源测试	Grafana UI → Configuration → Data Sources → Tempo → Test	显示 "Data source is working"

执行以下命令快速验证：

# 检查 Tempo 是否就绪
curl -s -o /dev/null -w "%{http_code}" http://localhost:3200/ready
# 预期输出: 200

# 查看 Tempo 构建信息
curl -s http://localhost:3200/status/buildinfo | jq .

验证结果示例：

# curl http://localhost:3200/status/buildinfo
{
  "version": "2.6.0",
  "revision": "abc1234",
  "branch": "main",
  "build_date": "2024-01-15T10:00:00Z",
  "go_version": "1.21.5"
}

3.5.3 验证 MinIO 存储

MinIO 提供了一个 Web 控制台，用于管理存储桶和对象。访问 http://localhost:9001，使用用户名 minioadmin 和密码 minioadmin 登录。

在 MinIO 控制台中，你应该能看到名为 tempo-traces 的存储桶（Tempo 启动后会自动创建）。后续 Trace 数据将存储在该桶中。

3.6 常见问题与排查

问题现象	可能原因	解决方案
Tempo 容器不断重启	配置文件语法错误或 MinIO 未就绪	检查 `docker compose logs tempo`，修正 YAML 缩进；确保 MinIO 先启动
MinIO 存储桶未自动创建	Tempo 启动时 MinIO 尚未就绪	手动在 MinIO Console 创建 `tempo-traces` 桶，或重启 Tempo 容器
Grafana 数据源测试失败	Tempo 地址配置错误或网络不通	确认 `url: http://tempo:3200` 中的服务名与 docker-compose 一致
端口被占用	本地已有服务占用相同端口	修改 docker-compose.yml 中左侧映射端口，例如 `"3201:3200"`

3.7 本章小结

通过本章的实践，你已经成功使用 Docker Compose 部署了 Tempo、MinIO 和 Grafana 三件套，并验证了各组件的健康状态。现在你拥有一个完整的分布式追踪基础设施，可以接收来自应用的 Trace 数据，并将其持久化存储在 MinIO 中，最终通过 Grafana 进行可视化查询。