Ubuntu 22.04 安装 Zipkin 指南
在 Ubuntu 22.04 上安装 Zipkin 3.6.1 分布式追踪系统（Java 17 + 官方 exec jar），完成初始化、启动、JVM 堆限制、systemd 托管与链路验证（v2 API 上报 + 查询），已在 Ubuntu 22.04 实测通过
Ubuntu 22.04 安装 Zipkin 指南
目标：在 Ubuntu 22.04 上安装开源分布式追踪系统 Zipkin 3.6.1（最新稳定版），以官方 exec jar + Java 17 完成部署，实现 Zipkin v2 API 链路数据上报、查询与 Jaeger UI 等价的可视化界面，并给出 JVM 堆限制、systemd 托管与卸载方式。本文档已在 Ubuntu 22.04.5 服务器实测通过。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）
- JDK 版本：OpenJDK 17.0.20.1（
openjdk-17-jdk-headless） - Zipkin 版本：3.6.1（commit
b2b0c98，发布于 2026-04） - 运行语言：Java（Spring Boot 服务，进程为
java -jar zipkin.jar） - 安装路径：
/opt/data/zipkin/zipkin.jar（130MB exec jar） - 默认端口：9411（HTTP/UI/API）
- 数据存储：内存（默认，重启即清空；持久化见《Zipkin 配置参数详解》篇）
- 日志文件：
/var/log/zipkin.log
二、前置条件
- 拥有 root 权限或 sudo 权限
- 已安装 JDK 17（Zipkin 3.6 官方要求 Java 17+）：
sudo apt-get install -y openjdk-17-jdk-headless - 网络可访问 Maven Central（
repo1.maven.org）或 GitHub Releases - 已预留存储目录
/opt/data/zipkin
三、版本选型说明
| 版本线 | 版本 | 状态 | 说明 |
|---|---|---|---|
| Zipkin 3.x | 3.6.1 | ✅ 当前稳定版 | 基于 Spring Boot + Armeria，官方推荐；要求 Java 17+ |
| Zipkin 2.x | 2.25.x | ⚠️ 旧版 | 仅维护模式，建议升级 3.x |
| Zipkin 1.x | 1.39.x | ❌ 已停止维护 | 旧架构（Cassandra2 等），勿用于新环境 |
💡 说明：Zipkin 是单体 Java 服务：一个 exec jar 同时承担 Collector（接收端，支持 HTTP/gRPC/Kafka 等）与 Query（查询/UI）能力，与 Jaeger 的 all-in-one 类似。存储后端支持内存（默认）、Elasticsearch、Cassandra、MySQL，见《Zipkin 配置参数详解》篇。
四、部署步骤
4.1 安装 JDK 17
执行命令：
sudo apt-get update
sudo apt-get install -y openjdk-17-jdk-headless wget curl
java -version
执行结果：
openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+9-Ubuntu-0ubuntu122.04)
OpenJDK 64-Bit Server VM (build 17.0.20.1+9-Ubuntu-0ubuntu122.04, sharing)
💡 说明：
openjdk-17-jdk-headless提供完整 JDK（含jps、jcmd等运维工具），无图形依赖，适合服务器环境。
4.2 下载 Zipkin 3.6.1
执行命令：
sudo mkdir -p /opt/data/zipkin
cd /opt/data/zipkin
sudo wget https://repo1.maven.org/maven2/io/zipkin/zipkin-server/3.6.1/zipkin-server-3.6.1-exec.jar -O zipkin.jar
ls -lh zipkin.jar
执行结果：
--2026-10-08 17:53:22-- https://repo1.maven.org/maven2/io/zipkin/zipkin-server/3.6.1/zipkin-server-3.6.1-exec.jar
Resolving repo1.maven.org (repo1.maven.org)... 146.75.94.217
Connecting to repo1.maven.org (repo1.maven.org)|146.75.94.217|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 136154736 (130M) [application/java-archive]
Saving to: 'zipkin.jar'
zipkin.jar 100%[=============================>] 130M 8.7MB/s in 15s
2026-10-08 17:53:38 (8.7 MB/s) - 'zipkin.jar' saved [136154736/136154736]
-rw-r--r-- 1 root root 130M 4月 8 2026 zipkin.jar
💡 说明：exec jar 为官方发布的自包含 jar（约 130MB），内含全部依赖与启动器，无需额外安装 Tomcat 等中间件。GitHub Releases 同样提供该文件（
https://github.com/openzipkin/zipkin/releases/download/3.6.1/zipkin-server-3.6.1-exec.jar）。
4.3 启动 Zipkin（默认内存存储）
执行命令：
cd /opt/data/zipkin
nohup java -Xms256m -Xmx512m -Djava.awt.headless=true -jar zipkin.jar > /var/log/zipkin.log 2>&1 &
sleep 15
grep -E "version 3.6.1|Serving HTTP" /var/log/zipkin.log
执行结果：
________ ____ _ _____ _ _
|__ /_ _| _ \| |/ /_ _| \ | |
/ / | || |_) | ' / | || \| |
/ /_ | || __/| . \ | || |\ |
|____|___|_| |_|\_\___|_| \_|
:: version 3.6.1 :: commit b2b0c98 ::
2026-10-08T17:55:25.422Z INFO [/] 3770 --- [oss-http-*:9411] c.l.a.s.Server : Serving HTTP at /[0:0:0:0:0:0:0:0]:9411 - http://127.0.0.1:9411/
💡 说明：
:: version 3.6.1 ::为启动横幅中的版本；Serving HTTP at ... :9411表示 HTTP/UI/API 服务已就绪。启动约需 10–15 秒（Java 进程加载）。
4.4 验证 UI 与健康检查
执行命令：
curl -s -o /dev/null -w "UI redirect %{http_code} -> %{redirect_url}\n" http://localhost:9411/
curl -s -o /dev/null -w "UI %{http_code}\n" http://localhost:9411/zipkin/
curl -s http://localhost:9411/actuator/health
执行结果：
UI redirect 302 -> http://localhost:9411/zipkin/
UI 200
{"status":"UP","zipkin":{"status":"UP","details":{"InMemoryStorage{}":{"status":"UP"}}}}
💡 说明：
9411根路径 302 跳转到/zipkin/（UI 基路径）；健康检查返回status: UP，存储组件为InMemoryStorage（默认内存存储）。浏览器访问http://<服务器IP>:9411/zipkin/打开查询界面。
4.5 上报并查询真实链路数据
上报一条 span（v2 API，时间戳单位为微秒）：
TS=$(($(date +%s%6N)-300000))
curl -s -o /dev/null -w "POST HTTP %{http_code}\n" -X POST http://localhost:9411/api/v2/spans \
-H "Content-Type: application/json" \
-d "[{\"traceId\":\"e6c1d7e6f8a9b1c2d3e4f5a6b7c8d9e0\",\"id\":\"e6c1d7e6f8a9b1c2\",\"name\":\"get /orders\",\"timestamp\":${TS},\"duration\":1200,\"localEndpoint\":{\"serviceName\":\"order-svc\"},\"tags\":{\"http.method\":\"GET\"}}]"
执行结果：
POST HTTP 202
查询服务列表：
curl -s http://localhost:9411/api/v2/services
执行结果：
["order-svc"]
按 traceId 查询完整链路：
curl -s http://localhost:9411/api/v2/trace/e6c1d7e6f8a9b1c2d3e4f5a6b7c8d9e0
执行结果：
[{"traceId":"e6c1d7e6f8a9b1c2d3e4f5a6b7c8d9e0","id":"e6c1d7e6f8a9b1c2","name":"get /orders","timestamp":1791481926047,"duration":1200,"localEndpoint":{"serviceName":"order-svc"},"tags":{"http.method":"GET"}}]
💡 说明：
POST /api/v2/spans返回 202 表示接收成功；/api/v2/services返回已接入服务；/api/v2/trace/<traceId>返回该链路全部 span。注意 v2 API 的timestamp/duration单位为微秒（微秒时间戳 ≈ 毫秒 × 1000）。生产应用使用 Brave/OpenTelemetry SDK 自动上报，无需手写 JSON。
4.6 systemd 托管（生产推荐）
⚠️ 前置要求：需要 systemd 的 Linux 真机（本步骤依赖 systemd 服务管理能力）。
创建 systemd 单元文件 /etc/systemd/system/zipkin.service：
[Unit]
Description=Zipkin 3.6.1 Distributed Tracing Server
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
Environment=JAVA_OPTS=-Xms256m -Xmx512m -Djava.awt.headless=true
ExecStart=/bin/sh -c 'exec java $JAVA_OPTS -jar /opt/data/zipkin/zipkin.jar'
Restart=on-failure
RestartSec=5
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
启用并启动（每行仅操作一个单元）：
sudo systemctl daemon-reload
sudo systemctl enable zipkin
sudo systemctl start zipkin
sudo systemctl is-active zipkin
预期输出：
active
验证服务与端口：
sudo systemctl status zipkin --no-pager
ss -tlnp | grep 9411
💡 说明：
ExecStart通过sh -c包装让$JAVA_OPTS环境变量注入 JVM 参数；也可直接写ExecStart=/usr/bin/java -Xms256m -Xmx512m -jar /opt/data/zipkin/zipkin.jar。LimitNOFILE提高文件描述符上限，高吞吐上报时防止too many open files。
五、JVM 堆内存配置（256–512MB）
Zipkin 是 Java 进程，生产部署必须将堆内存限定在 256–512MB（默认堆上限为物理内存 1/4，服务器 16GB 时默认约 4GB，极易超配）。三种常见托管形态的改法：
① 脚本/前台启动： java 命令直接携带参数
nohup java -Xms256m -Xmx512m -Djava.awt.headless=true -jar /opt/data/zipkin/zipkin.jar &
② systemd 托管： Environment=JAVA_OPTS 注入（每行仅一个 Environment=）
Environment=JAVA_OPTS=-Xms256m -Xmx512m -Djava.awt.headless=true
③ Docker Compose： environment: 注入 JAVA_OPTS（官方镜像入口脚本会读取）
environment:
- JAVA_OPTS=-Xms256m -Xmx512m
验证生效值（实测回显）：
jps -v
执行结果：
3770 zipkin.jar -Xms256m -Xmx512m -Djava.awt.headless=true
执行命令：
ps -ef | grep [z]ipkin.jar
执行结果：
root 3770 1 1 17:55 ? 00:01:23 java -Xms256m -Xmx512m -Djava.awt.headless=true -jar zipkin.jar
💡 说明：
jps -v直接展示进程 JVM 参数，是最直观的生效验证；ps -ef | grep [z]ipkin.jar同样可见-Xms256m -Xmx512m。若仍显示默认大堆，检查是否启动了多个 java 进程或参数被覆盖。
六、配置说明
6.1 存储后端
默认内存存储（InMemoryStorage）重启即清空，仅适合验证。生产使用 Elasticsearch（推荐，需先部署 ES 集群）或 Cassandra/MySQL：
STORAGE_TYPE=elasticsearch ES_HOSTS=http://10.0.0.10:9200 nohup java -Xms256m -Xmx512m -jar zipkin.jar > /var/log/zipkin.log 2>&1 &
sleep 20
curl -s http://localhost:9411/actuator/health
执行结果：
{"status":"UP","zipkin":{"status":"UP","details":{"ElasticsearchStorage{initialEndpoints=http://10.0.0.10:9200, index=zipkin}":{"status":"UP"}}}}
💡 说明：
STORAGE_TYPE=elasticsearch+ES_HOSTS切换存储；ES 中自动创建按天的zipkin-span-YYYY-MM-DD、zipkin-dependency-*等索引。更多存储参数见《Zipkin 配置参数详解》篇。
6.2 采样率与监听地址
- 采样率：环境变量
SAMPLING_RATE（0.0–1.0，默认 1.0 全采样） - 监听地址：默认监听
0.0.0.0:9411，可用SERVER_PORT改端口（如SERVER_PORT=9412）
6.3 监控指标
http://localhost:9411/actuator/prometheus 输出 Prometheus 格式指标，可用于监控接入；/actuator/metrics 查看指标清单。
七、注意事项
- Java 版本：Zipkin 3.x 要求 Java 17+，2.x 支持 Java 8+；生产确认
java -version。 - 时间戳单位：v2 API
timestamp/duration单位为微秒（$(date +%s%6N)），写错单位会导致查询时间窗错乱、索引按错误日期归档。 - 内存存储不持久：默认
InMemoryStorage重启丢数据，仅限演示。 - 堆内存：务必按上文限制 256–512MB，并用
jps -v复核。 - 端口占用：9411 被占用时改
SERVER_PORT或先ss -tlnp | grep 9411排查。
八、常见问题
8.1 启动报 Unsupported Java version？
原因： JDK 版本低于 17。
解决： sudo apt-get install -y openjdk-17-jdk-headless 后 java -version 确认，再启动。
8.2 curl http://localhost:9411/ 返回 302？
原因： 正常现象，根路径重定向到 UI 基路径 /zipkin/。
解决： 直接访问 http://<服务器IP>:9411/zipkin/；API 基路径为 /api/v2/...（不加 /zipkin 前缀）。
8.3 上报 202 但 /api/v2/services 一直为空？
原因： 服务名索引存在缓存刷新周期（默认 1 分钟）；或 span 时间戳单位错误导致被归档到错误日期。
解决： 等待约 1 分钟重查；确认 timestamp 为微秒（$(date +%s%6N)）。
8.4 启动慢、内存占用高？
原因： Java 进程默认堆上限过大。
解决： 按「五、JVM 堆内存配置」节加 -Xms256m -Xmx512m 并用 jps -v 验证。
九、卸载方式
如需彻底卸载 Zipkin：
sudo systemctl stop zipkin
sudo systemctl disable zipkin
sudo rm -f /etc/systemd/system/zipkin.service
sudo systemctl daemon-reload
sudo rm -rf /opt/data/zipkin /var/log/zipkin.log
💡 说明：删除
/opt/data/zipkin即移除程序；若使用 ES 存储，数据在 ES 集群中不受影响，可在 ES 侧按需清理zipkin-*索引。
十、参考链接
本文档由 www.quzuo.net 平台开发