基于Spring Cloud的分布式追踪系统Docker部署指南

本文将以thombergs/code-examples项目中的Spring Cloud分布式追踪系统为例，详细介绍如何使用Docker Compose部署一个完整的微服务追踪环境。这个部署方案包含了API服务、客户服务和OpenTelemetry收集器，能够帮助开发者快速搭建分布式追踪基础设施。

系统架构概述

该分布式追踪系统由三个核心组件构成：

1. API服务：作为系统的入口点，监听8080端口
2. 客户服务：提供业务功能，动态分配端口
3. OpenTelemetry收集器：负责接收、处理和导出追踪数据

Docker Compose文件详解

版本声明

version: "3.5"

使用Docker Compose 3.5版本，该版本提供了良好的兼容性和功能支持。

服务定义

1. API服务

api-service:
  build: api-service/
  image: api-service:latest
  ports:
    - "8080:8080"

• build：指定构建上下文为api-service目录
• image：构建后的镜像名称和标签
• ports：将容器8080端口映射到主机8080端口，便于外部访问

2. 客户服务

customer-service:
  build: ./customer-service/
  image: customer-service:latest
  ports:
    - "8081"

• 与API服务类似，但端口映射仅指定容器端口，由Docker自动分配主机端口
• 这种配置适用于内部服务，不需要固定主机端口

3. OpenTelemetry收集器

collector:
  image: logzio/otel-collector-traces
  environment:
    - LOGZIO_REGION=${LOGZIO_REGION}
    - LOGZIO_TRACES_TOKEN=${LOGZIO_TRACES_TOKEN}
  ports:
    - "1777:1777"
    - "9411:9411"
    - "9943:9943"
    - "6831:6831"
    - "6832:6832"
    - "14250:14250"
    - "14268:14268"
    - "4317:4317"
    - "55681:55681"
    - "8888:8888"

• 使用预构建的logzio/otel-collector-traces镜像
• 需要配置两个环境变量：区域和追踪令牌（通过环境变量传入）
• 开放多个端口以支持不同协议的追踪数据接收：
  • 1777：Zipkin端口
  • 9411：Zipkin API端口
  • 6831/6832：Jaeger Thrift Compact/Binary协议
  • 14250：Jaeger gRPC
  • 14268：Jaeger HTTP
  • 4317：OTLP gRPC
  • 55681：OTLP HTTP
  • 8888：健康检查和指标端口

部署实践指南

准备工作

1. 安装Docker和Docker Compose
2. 准备环境变量文件(.env)，包含LOGZIO_REGION和LOGZIO_TRACES_TOKEN
3. 确保各服务代码已准备就绪

启动系统

docker-compose up -d

此命令将：

1. 构建api-service和customer-service镜像
2. 拉取otel-collector-traces镜像
3. 启动所有容器

验证部署

1. 访问API服务：http://localhost:8080
2. 检查收集器健康状态：http://localhost:8888
3. 通过日志验证服务间通信和追踪数据

技术要点解析

分布式追踪原理

该系统实现了基于OpenTelemetry的分布式追踪，工作流程如下：

1. 微服务生成追踪数据
2. 通过OTLP或其他协议发送到收集器
3. 收集器处理并转发到后端存储(如Logz.io)
4. 用户通过可视化工具分析追踪数据

端口映射策略

• 对外服务(如API)使用固定主机端口
• 内部服务使用动态端口分配
• 收集器开放多种协议端口以提高兼容性

环境变量管理

敏感配置(如令牌)通过环境变量传入，避免硬编码，提高安全性。

常见问题解决

1. 端口冲突：检查主机端口是否被占用，可修改映射配置
2. 收集器启动失败：验证环境变量是否正确设置
3. 服务间通信问题：检查网络配置和健康状态
4. 追踪数据不完整：确认各服务是否正确配置了追踪导出

扩展建议

1. 添加Prometheus和Grafana实现指标监控
2. 集成日志收集系统(如ELK)
3. 配置服务自动扩缩容
4. 增加健康检查和就绪探针

通过本文介绍的Docker Compose部署方案，开发者可以快速搭建一个功能完整的Spring Cloud分布式追踪环境，为微服务系统的可观测性提供坚实基础。