4. 存储后端：S3/GCS/Azure Blob 配置、本地文件系统、MinIO 测试环境搭建

Tempo 的存储后端决定了追踪数据的持久化、可靠性与查询性能。生产环境推荐使用对象存储（S3、GCS、Azure Blob），本地文件系统仅适用于单机开发或快速验证，MinIO 则是搭建兼容 S3 的测试环境的最佳选择。本章逐一讲解各后端的配置要点与搭建步骤。

4.1 存储后端选型对比

4.2 本地文件系统配置

本地文件系统是最简单的存储后端，无需外部依赖，适合快速启动 Tempo 进行功能验证。

# tempo.yaml 本地文件系统配置片段
storage:
  trace:
    backend: local                     # 后端类型
    local:
      path: /var/tempo/traces          # 数据存储目录
    wal:
      path: /var/tempo/wal             # 预写日志目录

• backend: local — 启用本地文件系统存储。
• local.path — 追踪数据块（blocks）存放路径，需确保磁盘空间充足。
• wal.path — 预写日志路径，用于 crash recovery。

4.3 S3 配置详解

S3 是 Tempo 最常用的生产存储后端。配置时需指定 bucket、region、端点及认证信息。

# tempo.yaml S3 配置片段
storage:
  trace:
    backend: s3
    s3:
      bucket: tempo-traces             # S3 bucket 名称
      region: us-east-1                # 区域
      endpoint: s3.amazonaws.com       # S3 端点（可选）
      access_key: ${AWS_ACCESS_KEY_ID}
      secret_key: ${AWS_SECRET_ACCESS_KEY}
      insecure: false                  # 是否跳过 TLS 验证
    wal:
      path: /var/tempo/wal

• bucket — 必须提前创建，Tempo 不会自动创建。
• endpoint — 使用 AWS S3 时可不填，使用 MinIO 或其他 S3 兼容存储时必须指定。
• access_key / secret_key — 建议通过环境变量注入，避免明文写入配置文件。
• insecure — 测试环境可设为 true，生产环境必须为 false。

4.4 GCS 配置详解

GCS 配置与 S3 类似，但使用 Google Cloud 的认证方式。

# tempo.yaml GCS 配置片段
storage:
  trace:
    backend: gcs
    gcs:
      bucket: tempo-traces-gcs
      prefix: tempo                  # 可选，对象前缀
      chunk_buffer_size: 10485760    # 10MB 缓冲
    wal:
      path: /var/tempo/wal

• 认证方式：Tempo 默认使用 GOOGLE_APPLICATION_CREDENTIALS 环境变量指向的服务账号 JSON 文件。
• prefix — 可选，用于在同一 bucket 内隔离不同环境的数据。
• chunk_buffer_size — 上传缓冲大小，默认 10MB，可根据网络带宽调整。

4.5 Azure Blob 配置详解

Azure Blob 使用连接字符串或托管身份进行认证。

# tempo.yaml Azure Blob 配置片段
storage:
  trace:
    backend: azure
    azure:
      container: tempo-traces         # 容器名称
      storage_account_name: mystorageaccount
      storage_account_key: ${AZURE_STORAGE_KEY}
      max_buffers: 4                  # 并发上传缓冲数
    wal:
      path: /var/tempo/wal

• container — 类似 S3 bucket，需提前创建。
• storage_account_name / storage_account_key — 认证凭据，建议使用环境变量。
• max_buffers — 控制并发上传的缓冲数量，影响写入吞吐。

4.6 MinIO 测试环境搭建

MinIO 是兼容 S3 API 的开源对象存储，非常适合在本地或 CI 中模拟 S3 行为。以下使用 Docker 快速搭建。

4.6.1 启动 MinIO 容器

# 启动 MinIO 单节点
docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -e MINIO_ROOT_USER=admin \
  -e MINIO_ROOT_PASSWORD=password123 \
  -v /data/minio:/data \
  minio/minio server /data --console-address ":9001"

• 9000 — S3 API 端口。
• 9001 — MinIO Web 控制台端口。
• MINIO_ROOT_USER / MINIO_ROOT_PASSWORD — 管理员凭据。

4.6.2 创建 bucket

# 使用 mc 客户端创建 bucket
docker exec minio mc alias set local http://localhost:9000 admin password123
docker exec minio mc mb local/tempo-traces

4.6.3 配置 Tempo 连接 MinIO

# tempo.yaml MinIO 配置片段
storage:
  trace:
    backend: s3
    s3:
      bucket: tempo-traces
      endpoint: http://localhost:9000   # MinIO 端点
      access_key: admin
      secret_key: password123
      insecure: true                   # 本地测试跳过 TLS
    wal:
      path: /var/tempo/wal

4.7 存储后端架构总览

下图展示了 Tempo 与不同存储后端的集成关系，以及数据写入与查询的路径。

4.8 配置参数速查表

4.9 常见问题与避坑

• Bucket 不存在： Tempo 不会自动创建 bucket，启动前需手动创建。
• 权限不足： 确保存储账号有 s3:PutObject、s3:GetObject、s3:ListBucket 权限。
• MinIO 端点协议： 本地测试使用 http://，生产环境必须使用 https://。
• WAL 路径独立： WAL 目录不要与数据目录重叠，避免数据损坏。
• 对象存储延迟： 跨区域访问会增加写入延迟，建议将 Tempo 与存储部署在同一区域。