Zipkin 安装部署指南

zjc 于 2026-08-17 发布

下载地址/官网：Zipkin Quickstart

Zipkin 用来接收微服务上报的 trace 数据，并展示 Gateway、Consumer、Provider、Mail 之间的调用链。Windows 和 Ubuntu 直接运行官方 zipkin.jar，macOS 使用 Homebrew 安装，前提是已经安装 JDK 21。

Windows 部署 Zipkin

  1. 创建目录：
New-Item -ItemType Directory -Force -Path D:\apps\zipkin
  1. 下载官方可执行 JAR：
$zipkinVersion = "3.6.1"
Invoke-WebRequest `
  -Uri "https://repo1.maven.org/maven2/io/zipkin/zipkin-server/$zipkinVersion/zipkin-server-$zipkinVersion-exec.jar" `
  -OutFile "D:\apps\zipkin\zipkin.jar"
  1. 启动：
java -jar D:\apps\zipkin\zipkin.jar
  1. 新开 PowerShell 验证：
Invoke-RestMethod -Uri "http://127.0.0.1:9411/health"

返回内容包含 UP 字样即可。

  1. 打开页面：
http://127.0.0.1:9411/zipkin/
  1. 停止服务时，在启动窗口按 Ctrl+C。

Ubuntu 部署 Zipkin

  1. 下载并安装到 /opt/zipkin：
ZIPKIN_VERSION=3.6.1
sudo mkdir -p /opt/zipkin
sudo curl -L \
  "https://repo1.maven.org/maven2/io/zipkin/zipkin-server/${ZIPKIN_VERSION}/zipkin-server-${ZIPKIN_VERSION}-exec.jar" \
  -o /opt/zipkin/zipkin.jar
  1. 创建运行用户：
sudo useradd --system --home /opt/zipkin --shell /usr/sbin/nologin zipkin
sudo chown -R zipkin:zipkin /opt/zipkin
  1. 创建 systemd 服务：
sudo vim /etc/systemd/system/zipkin.service

写入：

[Unit]
Description=Zipkin Server
After=network.target

[Service]
User=zipkin
Group=zipkin
ExecStart=/usr/bin/java -jar /opt/zipkin/zipkin.jar
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
  1. 启动并设置开机自启：
sudo systemctl daemon-reload
sudo systemctl enable --now zipkin
  1. 查看状态：
sudo systemctl status zipkin --no-pager
sudo journalctl -u zipkin -f
  1. 验证：
curl http://127.0.0.1:9411/health

macOS 部署 Zipkin

macOS 有 Homebrew 包，可以直接安装。

  1. 安装 Zipkin：
brew install zipkin
  1. 前台启动，适合观察日志：
zipkin
  1. 如果要后台运行并随用户登录启动：
brew services start zipkin
  1. 验证：
curl http://127.0.0.1:9411/health
  1. 打开页面：
http://127.0.0.1:9411/zipkin/

接入微服务

生产环境 Zipkin 和应用部署在同一台服务器时，项目配置如下：

management:
  tracing:
    sampling:
      probability: 0.1
    export:
      zipkin:
        endpoint: http://127.0.0.1:9411/api/v2/spans

https://github.com/springvortex/spring-cloud-alibaba/blob/release/v1.0.0/service-provider/src/main/resources/application-prod.yaml

验证调用链的方法：

  1. 启动 Nacos、Provider、Consumer、Gateway 和 Zipkin。
  2. 通过 Gateway 发起一次请求。
  3. 在 Zipkin 页面点击搜索。
  4. 找到对应 trace，查看每一跳的耗时。

数据保存方式

默认情况下，Zipkin 把数据保存在内存里。进程重启后调用链会丢失，适合本机开发和临时排查。

生产环境要配置外部存储，常用选择是 MySQL 或 Elasticsearch。以 MySQL 为例，需要：

  1. 创建 zipkin 数据库和专用账号。
  2. 初始化 Zipkin 官方 MySQL 表结构。
  3. 通过环境变量指定 STORAGE_TYPE=mysql 和数据库连接信息。
  4. 重启 Zipkin。

官方 MySQL 表结构入口：

https://github.com/openzipkin/zipkin/blob/master/zipkin-storage/mysql-v1/src/main/resources/mysql.sql

安全边界

  1. Zipkin 9411 只给应用和运维人员访问，不要暴露公网。
  2. 远程查看时使用 VPN、堡垒机或内网反向代理。
  3. Zipkin 里有接口名、耗时、异常等信息，不能当成公开页面。

常见问题

启动提示找不到 java

先执行 java -version。Ubuntu systemd 环境里使用 /usr/bin/java，如果 Java 装在其他位置，要修改 zipkin.service 里的 ExecStart。

页面能打开但没有数据

检查业务服务的 Zipkin endpoint 是否正确，确认端口是 9411，路径是 /api/v2/spans。然后确认当前请求的采样率不是 0。

调用链只有单个服务

说明 trace 上下文没有跨服务传播。检查 Gateway、Consumer、Provider、Mail 是否都引入了链路追踪相关依赖，并确认配置生效。

重启后数据消失

这是默认内存存储的正常行为。需要保留历史数据时，配置 MySQL 或 Elasticsearch 存储。