Jaeger单机安装部署全攻略：从环境准备到生产就绪

2025年11月1日 互联网

Jaeger单机安装部署全攻略：从环境准备到生产就绪

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

Jaeger作为CNCF毕业的分布式追踪系统，单机部署模式特别适合以下场景：开发测试环境快速验证、中小型服务架构的轻量级监控、CI/CD流水线中的临时追踪需求。相较于集群部署，单机模式具有资源占用低（约500MB内存起）、配置简单、启动快速（<30秒）等优势，但需注意其存储容量限制（默认内存存储仅支持数万条追踪数据）。

二、环境准备与依赖检查

2.1 系统要求验证

  • 操作系统：Linux（推荐Ubuntu 20.04+/CentOS 8+）或macOS（通过Docker）
  • 硬件配置：最低2核CPU、4GB内存（生产建议8GB+）
  • 磁盘空间：至少10GB可用空间（使用Elasticsearch存储时需更多）

2.2 依赖安装

  1. # Ubuntu示例
  2. sudo apt update
  3. sudo apt install -y docker.io docker-compose
  4. sudo systemctl enable --now docker
  6. # 权限配置（避免sudo运行）
  7. sudo usermod -aG docker $USER
  8. newgrp docker  # 立即生效

2.3 网络端口规划

组件 默认端口 用途
Collector 14250 模型.thrift协议接收
Query 16686 Web UI访问
Agent 6831 UDP接收zipkin格式数据

三、三种主流部署方式详解

3.1 All-in-One Docker镜像（推荐新手）

  1. docker run -d --name jaeger \
  2.   -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
  3.   -p 5775:5775/udp \
  4.   -p 6831:6831/udp \
  5.   -p 6832:6832/udp \
  6.   -p 5778:5778 \
  7.   -p 16686:16686 \
  8.   -p 14250:14250 \
  9.   -p 14268:14268 \
  10.   -p 9411:9411 \
  11.   jaegertracing/all-in-one:1.45

关键参数说明：

  • COLLECTOR_ZIPKIN_HOST_PORT：兼容Zipkin协议
  • 多端口映射覆盖所有协议（Thrift/gRPC/HTTP）

3.2 Docker Compose精细化配置

  1. version: '3'
  2. services:
  3.   jaeger:
  4.     image: jaegertracing/all-in-one:1.45
  5.     command: ["--collector.http-port=14268", "--query.base-path=/jaeger"]
  6.     ports:
  7.       - "16686:16686"
  8.       - "14268:14268"
  9.     environment:
  10.       - SPAN_STORAGE_TYPE=memory  # 可替换为elasticsearch
  11.     volumes:
  12.       - ./jaeger-data:/data

高级配置技巧：

  • 通过环境变量MEMORY_MAX_TRACES控制内存存储上限（默认无限制）
  • 使用--query.static-files挂载自定义UI资源

3.3 二进制包部署（生产环境推荐）

  1. # 下载解压
  2. wget https://github.com/jaegertracing/jaeger/releases/download/v1.45.0/jaeger-1.45.0-linux-amd64.tar.gz
  3. tar xvf jaeger-*.tar.gz
  4. cd jaeger-*/
  6. # 启动命令（带内存限制）
  7. ./jaeger-all-in-one \
  8.   --memory.max-traces=50000 \
  9.   --query.port=16686 \
  10.   --collector.port=14268

生产环境优化建议：

  • 添加--collector.num-workers=4提升并发处理能力
  • 使用--log-level=debug临时调试（生产建议info）

四、存储后端配置指南

4.1 内存存储（默认）

适用场景：临时测试、短生命周期追踪
限制：

  • 重启后数据丢失
  • 默认无上限（需通过参数控制）

4.2 Elasticsearch存储

  1. # docker-compose片段
  2. storage:
  3.   image: docker.elastic.co/elasticsearch/elasticsearch:7.17.3
  4.   environment:
  5.     - discovery.type=single-node
  6.     - ES_JAVA_OPTS=-Xms512m -Xmx512m
  8. jaeger:
  9.   environment:
  10.     - SPAN_STORAGE_TYPE=elasticsearch
  11.     - ES_SERVER_URLS=http://storage:9200

性能调优：

  • 索引模板配置：--es.max-doc-count=100000控制单索引文档数
  • 冷热数据分离：通过ILM策略自动管理索引生命周期

五、生产环境实践建议

5.1 持久化存储方案

  1. # 使用本地卷持久化（Docker）
  2. docker run -d --name jaeger \
  3.   -v /opt/jaeger-data:/storage \
  4.   -e STORAGE_TYPE=badger \
  5.   -e BADGER_DIRECTORY_KEY=/storage/badger \
  6.   jaegertracing/jaeger:1.45

Badger存储优势：

  • 嵌入式KV存储，无需额外服务
  • 支持ACID事务
  • 冷启动速度比Elasticsearch快3倍

5.2 安全加固配置

  1. # 启用TLS示例
  2. jaeger:
  3.   environment:
  4.     - COLLECTOR_TLS_ENABLED=true
  5.     - COLLECTOR_TLS_CERT_FILE=/certs/server.crt
  6.     - COLLECTOR_TLS_KEY_FILE=/certs/server.key
  7.   volumes:
  8.     - ./certs:/certs

证书生成命令：

  1. openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt -days 365 -nodes

5.3 监控集成方案

Prometheus指标暴露：

  1. ./jaeger-collector \
  2.   --prometheus.server-port=14269 \
  3.   --prometheus.reporter=grpc

Grafana仪表盘配置：

  • 导入Jaeger官方Dashboard（ID：10711）
  • 关键监控项：
    • jaeger_collector_traces_received_total
    • jaeger_storage_span_write_errors_total
    • jaeger_query_services_count

六、常见问题解决方案

6.1 数据丢失问题排查

  1. 检查存储类型配置：curl localhost:16686/debug/config
  2. 内存存储超限：调整--memory.max-traces参数
  3. Elasticsearch连接失败：验证ES_SERVER_URLS和证书

6.2 性能瓶颈优化

场景：每秒处理>1000个span时出现延迟
解决方案：

  1. 增加Collector工作线程：--collector.num-workers=8
  2. 启用批处理：--collector.queue-size=10000
  3. 升级到gRPC协议：--collector.grpc-server.host-port=:14250

6.3 跨主机通信配置

Agent到Collector的UDP配置：

  1. # agent配置
  2. components:
  3.   Reporter:
  4.     CollectorHostPorts: "collector-host:14250"
  5.     BufferFlushInterval: 1s

防火墙规则：

  1. # 允许Jaeger协议端口
  2. sudo ufw allow 14250/tcp
  3. sudo ufw allow 6831/udp

七、升级与维护策略

7.1 版本升级流程

  1. # 1. 备份数据（Elasticsearch场景）
  2. curl -XPOST "http://localhost:9200/_flush"
  4. # 2. 停止服务
  5. docker stop jaeger
  7. # 3. 升级镜像
  8. docker pull jaegertracing/all-in-one:1.46
  10. # 4. 启动新版本（保持数据卷）
  11. docker run -d --name jaeger \
  12.   -v jaeger-data:/storage \
  13.   jaegertracing/all-in-one:1.46

7.2 日常维护命令

  1. # 查看存储使用情况
  2. docker exec jaeger du -sh /storage
  4. # 清理过期数据（Badger存储）
  5. docker exec jaeger ./jaeger-storage-cleanup \
  6.   --storage-type=badger \
  7.   --badger.directory-key=/storage/badger \
  8.   --ttl=86400  # 24小时

八、扩展功能集成

8.1 与OpenTelemetry集成

  1. # 接收OTLP格式数据
  2. jaeger:
  3.   command: ["--collector.otlp.enabled=true", "--collector.otlp.grpc.host-port=:4317"]

客户端配置示例（Go）：

  1. exporter, err := otlptracegrpc.New(context.Background(),
  2.     otlptracegrpc.WithInsecure(),
  3.     otlptracegrpc.WithEndpoint("localhost:4317"))

8.2 动态采样配置

  1. # 通过环境变量配置
  2. jaeger:
  3.   environment:
  4.     - COLLECTOR_SAMPLING_STRATEGIES="{\"default_strategy\":{\"type\":\"probabilistic\",\"param\":0.5}}"

策略类型说明：

  • probabilistic：概率采样（如0.5表示50%采样率）
  • ratelimiting：令牌桶限流
  • adaptive：基于负载的动态采样

九、总结与最佳实践

  1. 开发环境：优先使用Docker all-in-one镜像，配置--memory.max-traces=10000
  2. 生产环境：采用Elasticsearch存储+TLS加密+Prometheus监控的组合方案
  3. 性能基准：单机模式建议控制在每秒500-1000个span的处理量
  4. 扩展建议：当追踪数据量超过百万级时，应考虑迁移到集群部署

通过本文介绍的部署方案，开发者可以在30分钟内完成Jaeger的单机环境搭建，并根据实际需求进行存储、安全、监控等方面的深度配置。建议定期验证数据持久化策略的有效性，特别是在进行版本升级或配置变更时。

最新文章