Jaeger单机安装部署全攻略：从零到一的完整指南

一、Jaeger单机部署的核心价值与适用场景

Jaeger作为CNCF孵化的开源分布式追踪系统，单机部署模式为开发测试环境和小型项目提供了轻量级解决方案。相较于集群部署，单机版具有资源占用低（约2GB内存）、部署简单（单节点运行全量组件）、成本可控（无需额外存储集群）三大优势。典型适用场景包括：本地开发环境追踪微服务调用链、CI/CD流水线中的性能测试、小型团队初期链路监控需求。

二、环境准备与依赖管理

1. 系统要求与资源分配

操作系统：推荐Linux（Ubuntu 20.04+/CentOS 8+）或macOS（11.0+）
硬件配置：最低2核CPU、4GB内存（生产环境建议4核8GB）
存储空间：根据存储后端选择，Elasticsearch方案需预留20GB+磁盘空间

2. 依赖组件安装

# Docker环境准备（以Ubuntu为例）
sudo apt update
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt install -y docker-ce docker-ce-cli containerd.io
# Docker Compose安装（v2.0+）
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

三、核心组件部署方案

1. 全量组件Docker部署（推荐）

# docker-compose.yml
version: '3.8'
services:
  jaeger-collector:
    image: jaegertracing/jaeger-collector:1.48
    command: ["--es.server-urls=http://elasticsearch:9200", "--collector.zipkin.host-port=:9411"]
    ports:
      - "14250:14250"  # 模型.proto/gRPC
      - "14268:14268"  # 模型.proto/Thrift
      - "9411:9411"    # Zipkin兼容
    depends_on:
      - elasticsearch
  jaeger-query:
    image: jaegertracing/jaeger-query:1.48
    command: ["--es.server-urls=http://elasticsearch:9200", "--query.base-path=/jaeger"]
    ports:
      - "16686:16686"  # UI访问端口
    depends_on:
      - elasticsearch
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.17.3
    environment:
      - discovery.type=single-node
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
    ports:
      - "9200:9200"
    volumes:
      - es_data:/usr/share/elasticsearch/data
volumes:
  es_data:
    driver: local

关键配置说明：

使用Elasticsearch 7.x作为存储后端，兼顾性能与稳定性
暴露16686端口提供Web UI访问
配置512MB堆内存防止ES容器OOM

2. 内存存储快速部署（开发环境）

# 单命令启动（仅用于临时测试）
docker run -d --name jaeger \
  -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
  -p 5775:5775/udp \
  -p 6831:6831/udp \
  -p 6832:6832/udp \
  -p 5778:5778 \
  -p 16686:16686 \
  -p 14268:14268 \
  -p 14250:14250 \
  jaegertracing/all-in-one:1.48

适用场景：临时调试、功能演示，数据重启后丢失

四、存储后端选型与配置

1. Elasticsearch方案（生产推荐）

版本兼容性：Jaeger 1.48支持ES 6.x-7.x

索引管理：

# 创建索引模板（可选）
curl -XPUT "http://localhost:9200/_template/jaeger-span" -H 'Content-Type: application/json' -d'
{
  "index_patterns": ["jaeger-span-*"],
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 0
  }
}'

数据保留策略：通过ILM（Index Lifecycle Management）自动管理索引生命周期

2. Cassandra方案（高写入场景）

# docker-compose片段
cassandra:
  image: cassandra:4.0
  ports:
    - "9042:9042"
  environment:
    - CASSANDRA_START_RPC=true
  volumes:
    - cassandra_data:/var/lib/cassandra
# Jaeger配置需添加：
# --cassandra.servers=cassandra
# --cassandra.keyspace=jaeger_v1_test

五、验证与使用指南

1. 服务健康检查

# 检查ES状态
curl -XGET "http://localhost:9200/_cat/health?v"
# 检查Jaeger服务
curl -s http://localhost:14268 | grep "Jaeger Collector"

2. 示例应用接入（Go语言）

package main
import (
    "log"
    "time"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/jaeger"
    "go.opentelemetry.io/otel/sdk/resource"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    semconv "go.opentelemetry.io/otel/semconv/v1.4.0"
)
func initTracer() (*sdktrace.TracerProvider, error) {
    exp, err := jaeger.New(jaeger.WithCollectorEndpoint(jaeger.WithEndpoint("http://localhost:14268/api/traces")))
    if err != nil {
        return nil, err
    }
    tp := sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exp),
        sdktrace.WithResource(resource.NewWithAttributes(
            semconv.SchemaURL,
            semconv.ServiceNameKey.String("demo-service"),
        )),
    )
    otel.SetTracerProvider(tp)
    return tp, nil
}
func main() {
    tp, err := initTracer()
    if err != nil {
        log.Fatal(err)
    }
    defer func() {
        if err := tp.Shutdown(context.Background()); err != nil {
            log.Printf("Error shutting down tracer provider: %v", err)
        }
    }()
    tracer := otel.Tracer("demo-tracer")
    ctx, span := tracer.Start(context.Background(), "main-operation")
    defer span.End()
    time.Sleep(100 * time.Millisecond)
    log.Println("Operation completed")
}

3. Web UI高级功能

服务依赖图：通过”Dependencies”菜单可视化服务调用关系
Trace比较：支持多Trace并行对比分析
高级搜索：支持标签过滤（如error=true）、耗时范围筛选

六、运维与优化建议

1. 性能调优参数

参数	默认值	推荐生产值	说明
`--collector.num-workers`	10	CPU核心数*2	处理并发请求
`--es.max-num-spans`	0（无限制）	10000	单次查询返回Span数
`--query.timeout`	30s	60s	查询超时时间

2. 持久化存储配置

# 持久化卷配置示例
volumes:
  jaeger_data:
    driver: local
    driver_opts:
      type: xfs
      device: /dev/sdb1
      o: bind

3. 安全加固措施

启用HTTPS：通过Nginx反向代理配置SSL证书
访问控制：集成OAuth2/JWT认证中间件
数据加密：启用ES的TLS加密传输

七、常见问题解决方案

1. 数据写入失败排查

检查ES日志：docker logs elasticsearch
验证索引状态：curl -XGET "localhost:9200/_cat/indices?v"
调整批量大小：添加--es.bulk.size=1000参数

2. UI访问404错误

确认查询服务端口映射正确
检查--query.base-path配置是否与Nginx代理路径匹配
清除浏览器缓存后重试

八、升级与迁移指南

1. 版本升级流程

# 1. 备份数据
docker exec elasticsearch curl -XGET "localhost:9200/_snapshot/my_backup/snapshot_1?pretty"
# 2. 停止旧版本
docker-compose down
# 3. 修改镜像版本号
# 在docker-compose.yml中更新image标签
# 4. 启动新版本
docker-compose up -d
# 5. 验证索引兼容性
curl -XGET "localhost:9200/_cat/indices?v" | grep jaeger

2. 存储后端迁移

使用Jaeger的jaeger-es-index-cleaner工具清理旧索引
通过Elasticsearch的reindex API迁移数据
更新Jaeger配置指向新存储

结语

Jaeger单机部署为开发者提供了快速验证分布式追踪能力的有效途径。通过合理配置存储后端、优化资源分配和实施运维监控，单机环境完全能够满足中小规模系统的链路追踪需求。建议定期进行数据备份和性能基准测试，确保系统稳定运行。对于生产环境，建议逐步向集群部署方案过渡，以获得更高的可用性和扩展性。

Jaeger单机部署指南：快速搭建分布式追踪系统