📚 课程目录第3章 Jaeger快速部署实战

3、Jaeger快速部署实战：Docker Compose搭建All-in-one环境、配置与启动验证

本章聚焦于最快速的 Jaeger 上手路径——使用 Docker Compose 部署 All-in-one 模式。All-in-one 将 Agent、Collector、Query 服务、UI 及内存存储整合到单个容器中，适合开发测试、功能验证及小规模演示场景。你将通过 5 个步骤完成从环境准备到链路验证的完整闭环。

3.1 部署架构概览

All-in-one 模式将 Jaeger 后端组件合并为单一进程，客户端应用通过 UDP 或 HTTP 上报 Span 数据。下图展示了本次部署的组件关系与数据流：

3.2 环境准备与前置检查

在启动 Jaeger 之前，请确认主机满足以下最低要求：

组件	版本要求	验证命令
Docker Engine	≥ 20.10	`docker --version`
Docker Compose	≥ 2.0	`docker compose version`
可用磁盘空间	≥ 2 GB	`df -h`
可用内存	≥ 1 GB	`free -h`

推荐配置： 开发笔记本（4 核 CPU、8 GB 内存）即可流畅运行 All-in-one 模式。若需长期存储或高并发测试，请切换为生产模式（Cassandra/Elasticsearch + 独立 Collector）。

3.3 编写 docker-compose.yml

在项目目录下创建 docker-compose.yml，内容如下：

version: '3.8'

services:
  jaeger-all-in-one:
    image: jaegertracing/all-in-one:1.60
    container_name: jaeger-aio
    ports:
      - "16686:16686"   # Web UI
      - "14268:14268"   # HTTP 接收 Span
      - "14250:14250"   # gRPC 接收 Span
      - "6831:6831/udp" # Thrift Compact UDP
      - "6832:6832/udp" # Thrift Binary UDP
      - "5778:5778"     # Agent 配置管理
    environment:
      - COLLECTOR_OTLP_ENABLED=true
      - LOG_LEVEL=info
    networks:
      - jaeger-net

networks:
  jaeger-net:
    driver: bridge

3.4 启动服务与端口验证

执行以下命令启动 Jaeger All-in-one 容器：

# 启动容器（后台模式）
docker compose up -d

# 查看容器运行状态
docker compose ps

# 实时查看启动日志
docker compose logs -f jaeger-all-in-one

启动成功后，日志末尾应出现类似输出：

{"level":"info","msg":"Starting Jaeger All-in-one","version":"1.60.0"}
{"level":"info","msg":"Starting agent","udp_port":6831}
{"level":"info","msg":"Starting collector","http_port":14268,"grpc_port":14250}
{"level":"info","msg":"Starting query service","port":16686}

使用 netstat 或 ss 验证关键端口监听状态：

端口	协议	用途	验证命令
16686	TCP	Jaeger UI 查询接口	`curl -s http://localhost:16686/api/services \| head -5`
14268	TCP	HTTP Span 接收	`curl -s -o /dev/null -w "%{http_code}" http://localhost:14268/api/traces`
6831	UDP	Thrift Compact 协议	`ss -uln \| grep 6831`
6832	UDP	Thrift Binary 协议	`ss -uln \| grep 6832`

3.5 生成示例链路并验证

Jaeger All-in-one 内置了示例应用 HotROD，可用于快速生成演示链路。启动方式如下：

# 方式一：通过 Docker 直接运行 HotROD 示例
docker run --rm --network jaeger-net \
  -p 8080:8080 \
  -e JAEGER_AGENT_HOST=jaeger-aio \
  -e JAEGER_AGENT_PORT=6831 \
  jaegertracing/example-hotrod:1.60 all

# 方式二：在 docker-compose.yml 中添加 hotrod 服务
services:
  hotrod:
    image: jaegertracing/example-hotrod:1.60
    container_name: hotrod
    ports:
      - "8080:8080"
    environment:
      - JAEGER_AGENT_HOST=jaeger-aio
      - JAEGER_AGENT_PORT=6831
    networks:
      - jaeger-net
    depends_on:
      - jaeger-all-in-one

访问 http://localhost:8080 点击任意按钮（如“Frontend”），即可生成分布式调用链路。随后打开 Jaeger UI：

http://localhost:16686

在 UI 中执行以下验证步骤：

选择服务： 在 Service 下拉框中选择 frontend 或 driver。
查找 Trace： 点击 “Find Traces” 按钮，确认返回至少一条 Trace 记录。
查看详情： 点击任意 Trace ID，展开 Span 瀑布图，确认包含 HTTP GET、redis、mysql 等 Span 标签。
检查依赖图： 切换到 “Dependencies” 页面，查看服务间调用关系图。

  验证成功标志： UI 页面正常显示 Trace 列表，瀑布图展示完整的 Span 层级与耗时，依赖图呈现 frontend → driver → redis/mysql 的调用拓扑。

3.6 常见问题与排障

现象	可能原因	解决方案
容器启动后立即退出	端口冲突或内存不足	检查 16686/14268 端口占用；增加 Docker 内存限制
UI 无法访问	防火墙或 Docker 网络未暴露端口	执行 `docker compose ps` 确认端口映射；检查安全组规则
HotROD 无法上报 Span	Agent 地址配置错误或网络不通	确认 `JAEGER_AGENT_HOST` 指向 All-in-one 容器名；检查 UDP 6831 端口可达性
UI 显示 “No services found”	未产生任何 Trace 数据	确认 HotROD 已启动并产生请求；等待 10 秒后刷新页面

注意： All-in-one 模式使用内存存储，容器重启后所有 Trace 数据将丢失。生产环境请务必配置持久化存储后端（如 Elasticsearch 或 Cassandra）。

3.7 本章小结

通过 Docker Compose 部署 Jaeger All-in-one 环境，你已完成以下关键实践：

理解 All-in-one 模式的组件整合与数据流路径
掌握 docker-compose.yml 的端口映射与环境变量配置
学会使用 HotROD 示例应用生成分布式调用链路
熟练操作 Jaeger UI 进行 Trace 查询、瀑布图分析与依赖图查看