Jaeger Collector报connection refused？检查Agent端口是否正确

当Jaeger Agent上报Span时遭遇“connection refused”错误，核心原因通常是Agent默认使用的UDP 6831端口与Collector实际监听的接口不匹配——标准Collector镜像默认不启用Thrift UDP服务，仅开放gRPC（14250）和HTTP（14268）等端口。本文直击痛点，系统梳理五大解决方案：验证并显式启用Collector的UDP监听、切换为开箱即用的all-in-one镜像、让应用直连Collector的gRPC或HTTP接口、确保Agent正确配置Collector地址与网络可达性，以及特别针对Mac Docker Desktop的UDP转发失效问题提供抓包诊断与host网络绕行方案，助你快速定位并彻底解决分布式追踪链路中断难题。

如果您尝试让 Jaeger Agent 向 Collector 上报 span 数据，但收到 connection refused 错误，则很可能是 Agent 配置的上报目标地址或端口与 Collector 实际监听的接口不匹配。Jaeger Agent 默认使用 UDP 协议向 localhost:6831（Thrift Compact）发送数据，而标准 jaeger-collector 镜像默认并不监听该 UDP 端口——它只暴露 gRPC（14250）和 HTTP（14268）等接收接口。以下是解决此问题的步骤：

一、验证 Collector 是否监听 UDP 6831 端口

Jaeger Collector 官方镜像（如 jaegertracing/jaeger-collector）默认不开启 UDP 监听，因此 Agent 若配置为直连 Collector 的 6831 端口，必然触发 connection refused。必须确认 Collector 进程是否实际绑定并监听该端口。

1、在运行 Collector 的主机上执行命令检查 UDP 端口监听状态：
Linux/macOS：sudo ss -uln | grep ':6831' 或 sudo netstat -uln | grep ':6831'

2、若无输出，说明 Collector 未启用 UDP 接收器，需切换部署方式或显式启用。

3、若使用 Docker 启动 Collector，需额外挂载参数启用 Thrift UDP server，例如：
docker run -d --name collector -p 6831:6831/udp -p 14250:14250 -p 14268:14268 jaegertracing/jaeger-collector:1.49 --collector.thrift-udp-server=0.0.0.0:6831

二、改用 jaeger-all-in-one 镜像替代分离部署

jaeger-all-in-one 镜像已预集成 Agent、Collector 和 Query 组件，并默认启用全部必要端口转发，可规避手动配置 UDP 监听的复杂性。该方案适用于开发与测试环境，能确保 Agent 发送的 UDP 数据被内部组件正确接收。

1、停止当前所有 Jaeger 容器：docker stop $(docker ps -q --filter ancestor=jaegertracing)

2、拉取并启动 all-in-one 镜像，强制暴露 UDP 6831 端口：
docker run -d --name jaeger -p 6831:6831/udp -p 16686:16686 -p 14250:14250 -p 14268:14268 jaegertracing/all-in-one:1.49

3、确认容器运行正常：docker logs jaeger | grep "serving traces"，出现日志表示 Collector 已就绪。

三、跳过 Agent，让 Go 应用直连 Collector 的 gRPC 接口

Go SDK 支持直接通过 gRPC 协议将 span 上报至 Collector 的 14250 端口，完全绕过 Agent 层。该方式避免 UDP 网络不可靠性及端口映射问题，且便于调试连接失败原因（如 TLS、认证、网络策略等）。

1、确保 Collector 已启用 gRPC 接收器（all-in-one 或独立 collector 默认开启）。

2、修改 Go 应用中 Jaeger reporter 配置，将 localAgentHostPort 替换为 collectorEndpoint：
cfg.Reporter.LocalAgentHostPort = "" // 清空 UDP 配置
cfg.Reporter.CollectorEndpoint = "http://localhost:14268/api/traces" // HTTP endpoint
或使用 gRPC：cfg.Reporter.CollectorEndpoint = "grpc://localhost:14250"

3、初始化 tracer 前添加日志器以捕获连接错误：
cfg.Reporter.LocalAgentHostPort = ""
cfg.Reporter.CollectorEndpoint = "http://localhost:14268/api/traces"
cfg.Reporter.Logger = jaeger.StdLogger
tracer, _ := cfg.NewTracer()

四、检查 Agent 启动时是否指定了正确的 Collector 地址

当使用独立 jaeger-agent 时，其作用是接收 UDP 数据并转发至 Collector。若 Agent 自身无法连接 Collector（如 Collector 地址错误、端口不通、网络隔离），Agent 日志将静默丢弃 span，而客户端仍会因无法送达 Agent 而报 connection refused（尤其在 Agent 未监听 UDP 时）。

1、启动 Agent 时必须显式指定 Collector 地址：
docker run -d --name agent -p 6831:6831/udp jaegertracing/jaeger-agent:1.49 --reporter.grpc.host-port=host.docker.internal:14250（Mac/Windows 使用 host.docker.internal；Linux 可用宿主机 IP）

2、验证 Agent 是否成功连接 Collector：
docker logs agent | grep "connecting to"，应显示类似 connecting to x.x.x.x:14250 的日志。

3、若 Agent 日志中出现 "connection refused" or "dial tcp: i/o timeout"，说明 Agent 与 Collector 之间 TCP 连接失败，需检查 Collector 是否运行、端口是否开放、网络是否可达。

五、验证本地回环 UDP 转发是否生效（Mac Docker Desktop 特别注意）

Mac 上 Docker Desktop 对 UDP 流量的 host network 支持不稳定，常导致 localhost:6831 在容器内不可达。此时 Agent 即使监听了 6831，Go 应用也无法送达数据，表现为 connection refused。

1、改用 --network=host 启动 Agent，使其直接使用宿主机网络栈：
docker run -d --network=host --name agent jaegertracing/jaeger-agent:1.49 --reporter.grpc.host-port=localhost:14250

2、在 Mac 主机上抓包验证 UDP 数据是否发出：
tcpdump -i lo0 -n udp port 6831 -c 3，运行 Go 应用后应有输出。

3、若仍无输出，检查 Go 应用中 reporter 配置是否仍指向 "localhost:6831"，且未被环境变量或配置覆盖。

本篇关于《Jaeger Collector报connection refused？检查Agent端口是否正确》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！