手把手教你用Zipkin实现分布式链路追踪，附避坑指南

去年帮朋友的电商平台排查支付超时问题时，他们的系统已经拆成了8个微服务，从用户下单到支付完成，要经过网关、用户服务、商品服务、订单服务、库存服务、支付服务、通知服务，最后还要调第三方支付接口。当时日志里每个服务单独看响应时间都在300ms以内，但用户反馈“偶尔点支付要等3秒以上”。我们3个开发对着ELK日志查了两天，按时间戳把每个服务的日志一条一条拼起来，眼睛都熬红了也没找到规律。后来我 他们试试Zipkin链路追踪，花了2小时搭好环境，第二天就发现问题：库存服务调用Redis时，偶尔会因为key过期导致缓存穿透，查库耗时1.5秒——而这个延迟在单个服务的日志里根本不明显，只有把整个调用链串起来才能看到。

这就是分布式链路追踪的价值：它能把“一次用户请求”在各个服务间的调用过程，变成一张可视化的“路线图”，每个节点的耗时、状态、参数都清清楚楚。而Zipkin作为Twitter开源的链路追踪工具，因为轻量（jar包就能跑）、易集成（Spring Cloud直接支持）、可视化强（自带Web UI），成了很多中小团队的首选。今天我就带你从“为什么需要”到“怎么实操”，3小时内把Zipkin用起来，让你以后排查问题再也不用“猜”。

从“猜问题”到“看问题”：Zipkin链路追踪到底能解决什么

为什么传统日志排查在微服务架构里会失效？

你可能会说：“我用ELK收集了所有服务的日志，按请求ID也能串起来啊，为什么非要用Zipkin？” 这就像“用地图找路”和“跟着导航走”的区别——ELK能帮你把日志“拼起来”，但Zipkin能告诉你“每段路走了多久”“哪里堵了”“有没有绕路”。

举个具体的例子：假设用户下单请求的链路是“网关→用户服务→订单服务→支付服务”，传统日志排查需要你在每个服务的日志里搜同一个请求ID，然后手动对比每个服务的处理时间。如果某个服务调用了3个下游服务（比如订单服务同时调了库存、价格、优惠3个服务），你还得把这3个分支的日志也找出来，按时间线排列。我之前帮一个团队排查问题时，光整理这些日志就用了Excel画时序图，花了4小时才发现是优惠服务的数据库索引没建对——要是用Zipkin，打开UI就能看到优惠服务的SQL耗时标红了，10分钟就能定位。

Zipkin的核心价值就在于“自动串联调用链+量化每个节点耗时”。它通过在请求经过的每个服务里埋点（记录调用开始、结束、异常等事件），然后把这些埋点数据汇总成一张完整的“调用地图”。你打开Zipkin UI，就能看到：

这次请求总共走了多少个服务（Trace视图）

每个服务处理了多久（Span耗时）

有没有服务返回错误（Status标记）

甚至能看到具体的请求参数和响应结果（如果配置了）

搞懂3个核心概念，你就超过80%的新手

很多人觉得链路追踪“高大上”，其实核心概念就3个，用“快递运输”来比喻你就明白了：

Trace（追踪）

：相当于“整个快递的运输过程”。一次用户请求（比如下单、支付）从发起到底层服务响应，整个链路就是一个Trace。每个Trace有个全局唯一的ID（Trace ID），就像快递单号，不管经过多少中转站，单号始终不变。 Span（跨度）：相当于“快递经过的每个中转站”。一个Trace会拆分成多个Span，每个Span代表一个“独立的处理单元”——比如“网关接收请求”是一个Span，“用户服务查数据库”是一个Span，“订单服务调用支付服务”也是一个Span。Span之间有父子关系，比如“订单服务调用支付服务”这个Span，就是“订单服务处理”这个Span的子Span，就像“北京中转站”是“全国运输”的一个子环节。 Annotation（注解）：相当于“中转站的记录”。每个Span会记录几个关键事件：比如请求什么时候到达服务（cs：Client Send）、服务什么时候开始处理（sr：Server Receive）、服务什么时候处理完（ss：Server Send）、客户端什么时候收到响应（cr：Client Receive）。通过这4个注解，Zipkin就能算出每个Span的耗时（ss

sr就是服务处理时间，cr

cs就是整个调用耗时）。

去年带实习生做项目时，他一开始总搞不清Trace和Span的关系，我让他在Postman里调一个下单接口，然后去Zipkin UI看Trace详情——他发现整个Trace像一棵“树”，根节点是网关的Span，下面分支出用户服务、订单服务的Span，订单服务下面又分支出库存、支付的Span，瞬间就明白了：“原来一次请求就像一棵大树，每个服务的处理都是一个树枝！”

3小时实战：从环境搭建到微服务集成的全流程

第一步：30分钟搭好Zipkin环境，3种部署方式任你选

Zipkin的环境搭建比你想象的简单，甚至不用写代码，下载jar包就能跑。但选对部署方式和存储方案，能避免后期90%的麻烦。

先说部署方式

：

快速体验版：直接用官方jar包跑，适合测试。从Zipkin GitHub Releases下载最新的zipkin-server-x.x.x-exec.jar，然后命令行运行java -jar zipkin-server-x.x.x-exec.jar，默认端口9411，浏览器访问http://localhost:9411就能看到UI。但这种方式数据存在内存里，服务重启就丢，只能用来玩。

生产可用版：用Docker部署，配合外部存储（MySQL/Elasticsearch）。我 直接用Docker Compose，配置文件里指定存储方式，比如MySQL：

 version: '3'
 services:
 zipkin:
 image: openzipkin/zipkin
 ports:
 
"9411:9411"
 environment:
 
STORAGE_TYPE=mysql
 
MYSQL_HOST=你的MySQL地址
 
MYSQL_TCP_PORT=3306
 
MYSQL_DB=zipkin
 
MYSQL_USER=root
 
MYSQL_PASS=你的密码
 depends_on:
 
mysql
 mysql:
 image: mysql:8.0
 environment:
 
MYSQL_ROOT_PASSWORD=你的密码
 
MYSQL_DATABASE=zipkin
 
 运行docker-compose up -d，Zipkin就会自动在MySQL创建表（不用手动建库表，它会初始化），数据持久化就解决了。 
存储方案怎么选？ 我整理了3种常用方案的对比，你可以根据团队情况选： 

 

 

 
存储方式
 
适用场景
 
配置复杂度
 
查询性能
 
持久化能力
 
 
 

 

 
内存
 
本地测试、临时验证
 
★☆☆☆☆（无需配置）
 
★★★★★（内存查询快）
 
★☆☆☆☆（服务重启数据丢失）
 
 

 
MySQL
 
中小团队、数据量不大（日均百万级以下）
 
★★☆☆☆（配数据库地址即可）
 
★★★☆☆（单表查询，大数据量慢）
 
★★★★★（持久化到磁盘）
 
 

 
Elasticsearch
 
大团队、高并发（日均千万级以上）
 
★★★☆☆（需配置ES集群地址、索引）
 
★★★★☆（分布式索引，支持复杂查询）
 
★★★★★（持久化，支持按时间删除旧数据）
 
 

我自己搭过5个团队的Zipkin环境，中小团队用MySQL足够了，配置简单，出问题也好排查。如果你的服务QPS超过1万，或者需要存3个月以上的追踪数据，再考虑Elasticsearch。 
第二步：Spring Cloud微服务集成，5步搞定埋点和数据上报 
环境搭好了，接下来要让微服务把追踪数据发给Zipkin。以最常用的Spring Cloud项目为例，其实就是“加依赖+改配置”，不用写一行业务代码。 
加依赖：在每个微服务的pom.xml里加这两个依赖（Spring Cloud Sleuth是埋点工具，Zipkin是上报工具，两者配合使用）： 

xml

org.springframework.cloud

spring-cloud-starter-sleuth

org.springframework.cloud

spring-cloud-sleuth-zipkin

配Zipkin地址：在application.yml里指定Zipkin Server的地址，让服务知道把数据发给谁： 

yaml

spring:

zipkin:

base-url: http://你的Zipkin地址:9411 # 比如http://localhost:9411

sleuth:

sampler:

probability: 0.1 # 采样率10%，后面会讲为什么不设100%

配服务名（重要！）：每个服务一定要配spring.application.name，不然Zipkin UI里显示的服务名会是“unknown”，根本分不清哪个是哪个： 

yaml

spring:

application:

name: order-service # 订单服务就叫order-service，用户服务叫user-service

测试接口准备：写个简单的测试接口，比如订单服务调用户服务： 

java

// 订单服务接口

@RestController

@RequestMapping(“/order”)

public class OrderController {

@Autowired

private RestTemplate restTemplate;

@GetMapping(“/create”)

public String createOrder() {

// 调用用户服务获取用户信息

String userInfo = restTemplate.getForObject(“http://user-service/user/info”, String.class);

return “订单创建成功，用户信息：” + userInfo;

}

}

// 用户服务接口

@RestController

@RequestMapping(“/user”)

public class UserController {

@GetMapping(“/info”)

public String getUserInfo() {

return “用户ID:123, 用户名:test”;

}

}

启动服务并测试：先启动Zipkin，再启动用户服务、订单服务，用Postman调http://localhost:8080/order/create（假设订单服务端口8080），多调几次（因为采样率10%，可能要调10次左右才会有一次被采样）。然后打开Zipkin UI（http://localhost:9411），在“服务名”下拉框选order-service，点“Find Traces”，就能看到刚才的调用链路了！ 
我第一次集成时，调了20多次接口都没在Zipkin看到数据，后来发现是采样率设成了0.0（默认0.1，我手滑改错了），改回0.1后立刻就有数据了——所以配采样率时一定要仔细检查，别犯这种低级错误。 
第三步：10个踩坑经验，帮你绕过新手90%的坑 
集成完跑起来不难，但要让Zipkin真正“好用”，还得避开这些实战中才会遇到的坑。这些都是我和身边朋友踩过的，每个坑都浪费了至少半天时间： 
采样率不是越高越好，100%采样可能拖垮服务 
刚开始用Zipkin时，很多人觉得“采样率设100%，所有请求都追踪，排查问题更方便”。但在高并发服务（比如QPS 1万+）上，100%采样会导致： 
每个请求都要生成Span、上报数据，服务CPU占用增加10%-20% 
Zipkin Server接收大量数据，存储压力骤增（MySQL每天可能增长几十G） 
 默认用10%采样率，线上环境可以根据QPS调整，比如QPS 1000用20%，QPS 1万用5%。如果想针对特定接口提高采样率（比如支付接口），可以用Sleuth的Sampler自定义采样规则，只对/pay/*接口设100%采样。 
Trace ID传递失败？检查这3个地方 
有时候你会发现，网关的Trace ID和下游服务的Trace ID对不上，链路断成好几段。这90%是因为“Trace ID没传递下去”，要检查： 
网关层：如果用Spring Cloud Gateway，需要加spring-cloud-gateway-sleuth依赖，不然网关不会传递Trace ID头（X-B3-TraceId、X-B3-SpanId） 
HTTP调用工具：用RestTemplate要加@LoadBalanced注解，用Feign默认支持，但要确保Feign的依赖里包含sleuth 
自定义线程池：如果服务里用了new Thread()或线程池处理任务，Trace ID会丢失，需要用Sleuth的TraceableExecutorService包装线程池（具体用法可以看Spring Cloud Sleuth文档） 
存储数据查不到？Elasticsearch索引要注意 
用Elasticsearch存储时，有时候刚调用完接口，Zipkin UI里查不到数据，等几分钟才出来。这是因为Elasticsearch默认是“近实时索引”，数据写入后1秒左右才可见。如果需要实时性高，可以在Zipkin配置里加ES_INDEX_AUTO_CREATE=true，并把索引刷新间隔设小（但会影响性能，权衡使用）。 
别忽视“本地调试不追踪”的配置 
本地开发时，如果每次启动服务都上报追踪数据，会污染Zipkin的测试数据。可以在application-dev.yml里把采样率设为0： 

yaml

spring:

sleuth:

sampler:

probability: 0 # 本地环境不采样

你按这些步骤操作，2小时就能搭好可用的Zipkin链路追踪平台。下次线上服务再出问题，不用再对着日志发呆——打开Zipkin UI，看看哪个Span标红了，哪个节点耗时异常，问题一目了然。要是你试了之后遇到其他坑，或者有更高效的配置方法，欢迎在评论区告诉我，咱们一起完善这份指南！

---

说到Trace ID和Span ID的生成啊，你完全不用操心，Spring Cloud Sleuth会自动帮你搞定。默认情况下，Trace ID是一串由0-9、a-f组成的十六进制随机数，长度要么是16位（对应64位二进制），要么是32位（对应128位二进制）；Span ID呢，固定是16位的十六进制随机数。这俩就像快递单号和中转站编号，前者保证一次请求从开始到结束的全局唯一性，后者标记每个服务里的具体调用单元，这样不管服务怎么嵌套，Zipkin都能准确把链路串起来。

不过我得提醒你，千万别手痒去改它们的生成规则。之前有个朋友觉得默认的ID太长，自己写了个生成器改成8位数字，结果Zipkin UI直接显示“无效Trace ID”，存储到Elasticsearch时索引也建不起来——因为Zipkin的Web界面、存储组件（比如MySQL的表结构、ES的索引映射）都是按标准格式设计的，改了格式等于打破了规则。要是你有特殊需求，比如想把订单号和Trace ID关联起来，其实不用动ID本身，用“自定义标签”就好。比如在订单服务里，调用tracer.currentSpan().tag("order_no", "20231025001")，把订单号作为标签添加到当前Span里，之后在Zipkin UI里查这个Trace时，Tags那一列就能找到你加的order_no，既不影响链路追踪，又能实现业务关联，这才是聪明的做法。

---

Zipkin和SkyWalking、Jaeger有什么区别，该怎么选？

三者都是主流链路追踪工具，但定位不同：Zipkin胜在轻量（jar包直接运行，无需额外依赖）、易集成（Spring Cloud原生支持），适合中小团队或刚接触链路追踪的场景；SkyWalking功能更全（支持链路追踪+APM监控+日志分析），但部署复杂（需ES/MySQL存储，Agent探针侵入性稍高），适合大型复杂系统；Jaeger由Uber开源，对K8s兼容性更好，适合容器化部署的团队。如果你的服务是Spring Cloud技术栈，追求“开箱即用”，选Zipkin；如果需要全链路监控（含JVM指标、调用拓扑），选SkyWalking。

Zipkin收集的追踪数据包含哪些信息，会泄露敏感数据吗？

默认情况下，Zipkin收集的数据包括：Trace ID（全局追踪ID）、Span ID（局部调用单元ID）、调用时间戳、各Span耗时（cs/sr/ss/cr四个注解的时间差）、服务名、方法名、错误状态（如异常堆栈简化信息）。不会包含请求体、响应体、用户密码等敏感数据，除非手动在代码中通过brave.Tracer添加自定义标签（如tracer.currentSpan().tag(“user_id”, userId)）。 避免上报敏感信息，若需记录用户ID等标识，可通过脱敏处理（如只保留前4位+星号）。

集成Zipkin后服务响应变慢，是正常的吗？如何优化？

轻微变慢是正常的，因为Zipkin需要生成Span、上报数据，会占用少量CPU和网络资源。但如果响应延迟增加超过50ms，通常是这两个原因导致：①采样率过高（如设为100%），高并发下每个请求都生成追踪数据；②数据上报方式不合理（同步上报、单次请求单独发送）。优化方法：采样率设为5%-20%（非核心接口可更低），通过spring.sleuth.sampler.probability配置；开启异步上报（Spring Cloud Sleuth默认异步），并配置批量发送（zipkin.sender.type=kafka用Kafka批量转发）；存储用Elasticsearch替代MySQL，减少写入瓶颈。

微服务用了不同语言（如Java+Go），Zipkin能追踪跨语言调用吗？

可以。Zipkin的追踪原理是通过HTTP头（如X-B3-TraceId、X-B3-SpanId）传递上下文，只要不同语言的服务都遵循B3协议（Zipkin默认协议），就能串联链路。例如：Java服务用Spring Cloud Sleuth自动传递头，Go服务可集成zipkin-go客户端，Python用py-zipkin，在HTTP请求时手动添加B3头（如X-B3-TraceId: 4f9a3f2b6e123456）。去年帮一个Java+Node.js的项目集成时，就是通过Node.js的Express中间件拦截请求，读取并传递B3头，最终实现跨语言链路串联。

Zipkin的Trace ID和Span ID是怎么生成的，能自定义吗？

默认由Spring Cloud Sleuth生成：Trace ID是16位（64位）或32位（128位）十六进制随机数，Span ID是16位十六进制随机数，两者均全局唯一。不 自定义生成规则，因为Zipkin UI和存储组件（如Elasticsearch）依赖标准格式解析。如果有特殊需求（如Trace ID关联业务订单号），可通过“自定义标签”实现（如tracer.currentSpan().tag(“order_no”, “20231025001”)），在Zipkin UI的“Tags”列能看到，不影响原生ID的生成逻辑。