linux上用zipkin监控hyperf微服务需两端打通：一端用docker run -d -p 9411:9411 --name zipkin openzipkin/zipkin快速启动zipkin服务端；另一端在hyperf中正确配置opentracing.php，确保default=>env('tracer_driver','zipkin')、zipkin块结构正确、endpoint_url含/api/v2/spans、启用tracemiddleware与各aspect，否则链路会断。
在 Linux 上用 Zipkin 监控 Hyperf 微服务，核心是“两端打通”：一端是 Zipkin 服务端能收数据，另一端是 Hyperf 能正确发 Span。不装错、不漏配、不混驱动，三步就能跑通。
快速启动 Zipkin 服务端（Linux）
推荐用 Docker 一键拉起，无需编译或配 Java 环境：
- 执行：
docker run -d -p 9411:9411 --name zipkin openzipkin/zipkin - 访问
http://localhost:9411，看到 Zipkin UI 即表示服务已就绪 - 默认使用内存存储，适合开发测试；生产环境需挂载 MySQL/Elasticsearch，通过
-e STORAGE_TYPE=elasticsearch等参数切换
Hyperf 项目配置 Zipkin 上报
关键不是装包，而是改对 config/autoload/opentracing.php：
-
driver 必须显式设为 'zipkin'：顶层
'default' => env('TRACER_DRIVER', 'zipkin')不能少，且TRACER_DRIVER=zipkin要写进.env -
'zipkin'配置块必须在'tracer'下一级，结构如下：
'tracer' => [
'default' => env('TRACER_DRIVER', 'zipkin'),
'zipkin' => [
'endpoint_url' => 'http://localhost:9411/api/v2/spans',
'timeout' => 2.0,
'app' => [
'name' => env('APP_NAME', 'hyperf-service'),
'ipv4' => '127.0.0.1',
'port' => 9501,
],
],
],
-
endpoint_url必须带完整路径/api/v2/spans，少写会 404；Docker 容器内调用宿主机 Zipkin，建议改用host.docker.internal或宿主机真实 IP
启用自动埋点与验证链路
仅配好配置不会自动上报，还需激活中间件和切面：
- 确保
Hyperf\Tracer\Middleware\TraceMiddleware已注册到 HTTP 中间件队列（检查config/autoload/middlewares.php） - 确认
Hyperf\Tracer\Aspect\HttpClientAspect、DbAspect、RedisAspect等已启用（默认开启，可查config/autoload/aspects.php） - 启动服务：
php bin/hyperf.php start，发起一次 HTTP 请求（如curl http://127.0.0.1:9501/health） - 刷新 Zipkin UI → “Find Traces”，应能看到服务名、耗时、状态码；点击可展开完整调用链
常见断链原因速查
链路空白或只有一层？重点检查这几项：
- 环境变量
TRACER_DRIVER是不是写成了jaeger或空值 -
endpoint_url是否误用了 Jaeger 的 UDP 地址（Zipkin 只走 HTTP） -
app.name在多个服务中是否重复——重复会导致 UI 里全堆成一个服务节点 - 本地开发时
app.ipv4写了127.0.0.1没问题；K8s 环境必须换成$POD_IP，否则拓扑图 IP 显示异常
