搬瓦工部署 Zipkin 请求追踪系统教程

Zipkin 是由 Twitter 开源的分布式追踪系统，灵感来源于 Google 的 Dapper 论文。它是最早的开源追踪系统之一，以简洁和易用著称。Zipkin 帮助开发者收集微服务架构中的时序数据，用于定位延迟问题和分析服务依赖。相比 Jaeger，Zipkin 更加轻量，部署和使用门槛更低。本文将介绍如何在搬瓦工 VPS 上部署 Zipkin。部署前请确保已安装 Docker 和 Docker Compose。

一、Zipkin 核心组件

Collector：接收来自应用程序的追踪数据。
Storage：存储追踪数据，支持内存、MySQL、Elasticsearch 和 Cassandra。
API：提供 RESTful 接口查询追踪数据。
Web UI：可视化界面展示追踪链路和服务依赖。

二、系统要求

操作系统：Ubuntu 20.04+ 或 Debian 11+。
内存：至少 512MB（内存存储模式），使用 Elasticsearch 建议 2GB+。
磁盘：至少 5GB 可用空间。
Docker：已安装 Docker 和 Docker Compose。

搬瓦工 VPS 方案推荐参考全部方案，购买时使用优惠码 NODESEEK2026 可享 6.77% 折扣，购买入口：bwh81.net。

三、快速部署（内存存储）

mkdir -p /opt/zipkin && cd /opt/zipkin

cat > /opt/zipkin/docker-compose.yml <<'EOF'
version: '3.8'

services:
  zipkin:
    image: openzipkin/zipkin:latest
    restart: always
    ports:
      - "9411:9411"
    environment:
      STORAGE_TYPE: mem
      JAVA_OPTS: "-Xms256m -Xmx512m"

EOF

这是最简单的部署方式，数据存储在内存中，重启后丢失。适合开发和测试环境。

四、生产部署（MySQL 存储）

cat > /opt/zipkin/docker-compose.yml <<'EOF'
version: '3.8'

services:
  zipkin-db:
    image: mysql:8.0
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: your_root_password
      MYSQL_DATABASE: zipkin
      MYSQL_USER: zipkin
      MYSQL_PASSWORD: your_zipkin_password
    volumes:
      - zipkin_db_data:/var/lib/mysql

  zipkin:
    image: openzipkin/zipkin:latest
    restart: always
    ports:
      - "9411:9411"
    environment:
      STORAGE_TYPE: mysql
      MYSQL_HOST: zipkin-db
      MYSQL_TCP_PORT: 3306
      MYSQL_USER: zipkin
      MYSQL_PASS: your_zipkin_password
      MYSQL_DB: zipkin
      JAVA_OPTS: "-Xms256m -Xmx512m"
    depends_on:
      - zipkin-db

volumes:
  zipkin_db_data:
EOF

五、启动服务

cd /opt/zipkin
docker compose up -d

访问 http://your_server_ip:9411 进入 Zipkin Web UI。

六、应用接入

Zipkin 支持多种语言的客户端库，以下是常见的接入方式：

Python（py_zipkin）

# pip install py_zipkin requests
from py_zipkin import Encoding
from py_zipkin.zipkin import zipkin_span
import requests

def http_transport(encoded_span):
    requests.post(
        'http://zipkin-host:9411/api/v2/spans',
        data=encoded_span,
        headers={'Content-Type': 'application/json'},
    )

with zipkin_span(
    service_name='my-service',
    span_name='my-operation',
    transport_handler=http_transport,
    encoding=Encoding.V2_JSON,
    sample_rate=100.0,
):
    # 业务逻辑
    pass

通过 OpenTelemetry 接入

推荐使用 OpenTelemetry SDK，配置 Zipkin Exporter 即可将追踪数据发送到 Zipkin：

# pip install opentelemetry-exporter-zipkin-json
from opentelemetry.exporter.zipkin.json import ZipkinExporter

exporter = ZipkinExporter(endpoint="http://zipkin-host:9411/api/v2/spans")

七、配置反向代理

cat > /etc/nginx/sites-available/zipkin <<'EOF'
server {
    listen 80;
    server_name your_domain.com;

    location / {
        proxy_pass http://127.0.0.1:9411;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
EOF

ln -s /etc/nginx/sites-available/zipkin /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
certbot --nginx -d your_domain.com

八、使用 Zipkin UI

查找追踪：在搜索栏中按服务名、时间范围和标签查询追踪记录。
追踪详情：点击具体追踪查看瀑布图，展示各 Span 的耗时。
依赖图：在 Dependencies 页面查看服务间的调用关系。

九、数据清理

使用 MySQL 存储时，需要定期清理旧数据以控制磁盘占用：

# 创建定时清理脚本
cat > /opt/zipkin/cleanup.sh <<'SCRIPT'
#!/bin/bash
docker compose exec zipkin-db mysql -uzipkin -pyour_zipkin_password zipkin -e "
DELETE FROM zipkin_spans WHERE start_ts < UNIX_TIMESTAMP(DATE_SUB(NOW(), INTERVAL 30 DAY)) * 1000000;
DELETE FROM zipkin_annotations WHERE a_timestamp < UNIX_TIMESTAMP(DATE_SUB(NOW(), INTERVAL 30 DAY)) * 1000000;
"
SCRIPT
chmod +x /opt/zipkin/cleanup.sh

# 添加到 crontab（每天凌晨3点执行）
echo "0 3 * * * /opt/zipkin/cleanup.sh" | crontab -

十、常见问题

追踪数据未出现

确认应用端的 Zipkin Exporter 端点配置正确（http://host:9411/api/v2/spans），检查采样率设置。

Zipkin 启动缓慢

Zipkin 基于 Java，JVM 启动需要一定时间。可以通过减小 JAVA_OPTS 加速启动。

总结

Zipkin 是最轻量易用的开源分布式追踪系统，适合快速搭建追踪基础设施。如果需要更丰富的功能，可以参考 Jaeger；如果已经使用 Grafana 生态，推荐 Grafana Tempo。选购搬瓦工 VPS 使用优惠码 NODESEEK2026 可享 6.77% 折扣。