OpenTelemetry分布式链路追踪服务器集群部署实操指南

不少朋友在搭建微服务或分布式应用时，想用 OpenTelemetry 做链路追踪，但卡在集群部署这一步。
本文从零开始，按实际环境讲解如何在一组服务器上完整跑通 OpenTelemetry Collector + Jaeger 后端，并验证追踪数据是否正常。

一、部署前必须搞清楚的3件事

1. 理解角色：OpenTelemetry 是一套规范和 SDK，真正存储展示数据的后端需要自己选，比如 Jaeger、Zipkin、SkyWalking。新手推荐 Jaeger，社区成熟，配置简单。
2. 网络规划：Collector 负责接收应用发出的追踪数据，需要开放 gRPC/HTTP 端口；Jaeger 后端一般和 Collector 部署在同一内网，减少延迟。
3. 资源评估：单机 2C4G 可以跑通 demo，生产集群建议 Collector 和 Jaeger 分开部署，且 Collector 可水平扩展。

二、用 Docker Compose 一键拉起集群组件

假设你有两台服务器：一台跑 Collector，一台跑 Jaeger。
下面步骤统一采用容器方式，降低依赖冲突。

1. 在 Collector 服务器上编写 docker-compose.yml

version: '3.8'
services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.103.0
    container_name: otel-collector
    volumes:
      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml
    command: ["--config=/etc/otel-collector-config.yaml"]
    ports:
      - "4317:4317"   # gRPC
      - "4318:4318"   # HTTP
    restart: unless-stopped

2. 创建 Collector 配置 otel-collector-config.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  otlp:
    endpoint: "jaeger-server-ip:4317"   # 换成你的 Jaeger 服务器内网IP
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp]

3. 在 Jaeger 服务器上部署后端

同样使用 Docker Compose，文件内容如下：

version: '3.8'
services:
  jaeger:
    image: jaegertracing/all-in-one:1.57
    container_name: jaeger
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    ports:
      - "16686:16686"   # UI
      - "4317:4317"     # 接收 Collector 数据
    restart: unless-stopped

然后分别在两台服务器执行 docker compose up -d 启动服务。

三、让应用把追踪数据发给 Collector

这里以 Python Flask 应用为例，展示如何集成 OpenTelemetry SDK。

1. 安装依赖

pip install opentelemetry-distro opentelemetry-exporter-otlp

2. 在应用启动时初始化

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

tracer_provider = TracerProvider()
span_processor = BatchSpanProcessor(
    OTLPSpanExporter(endpoint="http://collector-server-ip:4317", insecure=True)
)
tracer_provider.add_span_processor(span_processor)
trace.set_tracer_provider(tracer_provider)

重启应用后，只要代码中有被 OpenTelemetry 自动埋点的请求（比如 Flask 路由），就会产生追踪数据。

四、这两步帮你避开 80% 的坑

• 端口不通：如果数据没出现在 Jaeger UI，先用 telnet collector-ip 4317 和 telnet jaeger-ip 4317 检查网络连通性。集群环境注意防火墙和安全组规则。
• 版本不一致：Collector、Exporter、Jaeger 三者版本尽量对齐，推荐使用最新的稳定版。跨大版本可能因协议变更导致数据丢失。
• 采样率过高：生产环境默认配置会采样 100% 的请求，容易撑爆后端。建议在 Collector 配置中加 `processors:

batch:
memory_limiter: 和 tail_sampling` 处理器。

五、验证你的链路追踪数据

1. 打开浏览器访问 http://jaeger-server-ip:16686，进入 Jaeger UI。
2. 在 Service 下拉框中选择你应用的服务名（默认是 unknown_service，可以在 SDK 初始化时设置）。
3. 点击 Find Traces，如果看到 span 记录，说明整个链路已经跑通。

如果完全没有数据，优先检查 Collector 日志（docker logs otel-collector），看是否有连接拒绝或配置错误。

六、常见问题 FAQ

Q：Collector 必须单独一台机器吗？
A：不一定，新手测试时可以和 Jaeger 部署在同一台。但生产建议分开，方便扩容。

Q：一定要用 Jaeger 吗？
A：推荐 Jaeger 因为它原生支持 OTLP 协议，开箱即用。如果你熟悉 Prometheus + Grafana，也可以改用 Tempo。

Q：应用代码没有改动，能接入追踪吗？
A：部分框架支持自动插桩（如 Flask、Spring Boot），只安装 SDK 并配置环境变量即可，不需要改业务代码。

如果你正在处理 OpenTelemetry 分布式链路追踪服务器集群完整部署，建议先按本文步骤完整执行，再根据自己的环境做微调；
遇到异常时优先回看避坑和高频问题部分。