Zipkin 快速上手部署与接入实战

一、Zipkin 简介

Zipkin 是分布式调用链路可视化组件，负责收集各微服务调用耗时、调用栈、异常信息，快速定位慢接口、跨服务调用故障。整体架构两层：

1. Zipkin Server：独立服务，接收链路数据、存储、提供Web可视化UI；
2. 客户端埋点：业务微服务采集Span、上报数据。

存储支持内存（测试用，重启丢失）、MySQL、Elasticsearch（生产持久化）。

重要更新：Spring Boot3 已彻底移除Sleuth，不再推荐老方案，下文两套接入方式分开讲解。

二、Windows 启动 Zipkin Server

1. 一键启动方式

官方提供独立可执行Jar，无需安装配置，Windows CMD直接执行：

1. 下载 [zipkin.jar](https://zipkin.io/pages/quickstart.html) 官方包；
2. 进入Jar所在目录执行启动命令：

java -jar zipkin.jar

2. 访问控制台

地址：http://127.0.0.1:9411/zipkin/，默认端口9411。

3. 对接Elasticsearch持久化

生产使用

java -jar zipkin.jar STORAGE_TYPE=elasticsearch ES_HOSTS=127.0.0.1:9200

默认内存模式重启所有链路数据清空，仅本地调试临时使用。

三、方案1：Spring Boot2历史项目

1. Maven依赖

<!-- 链路自动埋点、透传traceId -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>
<!-- 上报数据到Zipkin服务端 -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-sleuth-zipkin</artifactId>
</dependency>

2. 配置文件 application.yml

spring:
  application:
    name: order-service
  zipkin:
    base-url: http://127.0.0.1:9411
  sleuth:
    sampler:
      probability: 1.0 # 采样率1=100%采集，生产调低减少上报压力

3. 接入说明

1. 仅引入依赖+配置即可，无需编写任何代码；
2. RestTemplate、OpenFeign 自动在请求头透传 traceId、spanId，跨服务链路自动拼接；
3. 应用日志自动打印链路ID，格式：[服务名,traceId,spanId,是否上报]。

局限性

1. Spring Cloud 官方已停止维护Sleuth，不再迭代新特性、不修复BUG；
2. 不兼容Spring Boot3、JDK17+、Jakarta规范，新项目禁止使用；
3. 仅绑定Zipkin，切换Jaeger等链路后端改动量大。

四、方案2：Spring Boot3 Micrometer Tracing对接Zipkin

1. Maven完整依赖

<!-- 观测性标准抽象，Boot3自动装配 -->
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing</artifactId>
</dependency>
<!-- Brave实现（Sleuth底层原生实现，无缝兼容） -->
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-brave</artifactId>
</dependency>
<!-- Zipkin上报导出器 -->
<dependency>
    <groupId>zipkin.reporter2</groupId>
    <artifactId>zipkin-reporter-spring-beans</artifactId>
</dependency>

2. application.yml 配置

spring:
  application:
    name: order-service
management:
  tracing:
    enabled: true
    sampling:
      probability: 1.0
  zipkin:
    tracing:
      endpoint: http://127.0.0.1:9411/api/v2/spans

3. 能力效果

1. 零代码侵入，自动采集HTTP接口、Feign远程调用、JDBC SQL、Redis操作Span；
2. traceId、spanId自动透传，日志自动打印链路标识；
3. 抽象层设计，后续想更换Jaeger后端，只替换导出依赖即可，业务代码无改动。

五、Zipkin UI 核心功能介绍

1. 链路检索

1. 下拉选择指定微服务，限定时间范围，可按响应耗时排序筛选慢接口；
2. 支持直接粘贴 traceId 精准定位单次完整调用链路。

2. 调用链路详情

点开链路，直观展示完整调用栈：Gateway → Controller → Mapper → Redis/MQ；

每个节点独立展示耗时，红色标记异常节点，快速定位性能瓶颈和报错位置。

3. 依赖拓扑 Dependencies

自动生成所有微服务之间调用关系拓扑图，统计调用频次、成功率，梳理服务依赖全景。

六、异步场景链路断裂解决方案

线程池@Async、定时任务、MQ消费者会丢失上下文，链路断开：

1. Sleuth：使用 TraceableExecutorService 包装线程池；
2. Micrometer Tracing：使用 Tracer.currentTraceContext().wrap() 包装任务；
   消息队列场景，手动把traceId塞入消息Header，消费端取出重建链路上下文。

七、Zipkin VS SkyWalking 选型对比

对比项	Zipkin	SkyWalking
接入方式	代码引入依赖侵入接入	Java Agent字节码增强，零代码改动
监控维度	仅调用链路	链路+JVM指标+线程池+慢SQL+网关指标全覆盖
部署成本	单Jar一键启动，极简	多组件集群部署，偏重
适用场景	小项目本地调试、快速验证链路	中大型微服务集群生产长期运维

八、高频踩坑

1. UI无任何链路数据
   检查微服务能否连通9411端口、采样率是否为0、是否发起过实际接口请求；
2. 跨服务链路割裂
   Feign/RestTemplate原生自动透传；异步线程未包装上下文会断链；
3. 重启Zipkin历史数据消失
   默认内存存储，正式环境务必对接Elasticsearch持久化；
4. Boot3项目引入Sleuth直接报错
   版本不兼容，必须改用Micrometer Tracing新方案。