Zipkin 配置参数详解

目标：详解 Zipkin 3.6.1 的全部配置参数——配置加载方式与优先级、存储后端（内存/Elasticsearch/Cassandra/MySQL）、采集端（HTTP/gRPC/Kafka/RabbitMQ/ActiveMQ/Pulsar/Scribe）、查询与 UI、自追踪等分组的环境变量清单与默认值，全部配置项经 /actuator/env 实测采集。本文档已在 Ubuntu 22.04 服务器实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS
• Zipkin 版本：3.6.1（commit b2b0c98）
• 配置载体：环境变量（${VAR:default} 占位符模型）
• 默认配置来源：jar 内 BOOT-INF/classes/zipkin-server-shared.yml（153 个配置键）与 zipkin-server.yml
• 生效值查询接口：http://<服务器IP>:9411/actuator/env
• 默认监听端口：9411

二、配置方式总览

Zipkin 是单体 Java 服务，配置全部通过环境变量注入（与 Jaeger v2 的 YAML 配置驱动不同，也不同于 Netdata 的 conf 文件）：启动进程前设置环境变量，进程启动时读取 zipkin-server-shared.yml 中的 ${VAR:default} 占位符展开生效。

三种设置方式（以 ES 存储为例）：

① 命令行前缀（前台/脚本启动）：

STORAGE_TYPE=elasticsearch ES_HOSTS=http://10.0.0.10:9200 \
  nohup java -Xms256m -Xmx512m -jar /opt/data/zipkin/zipkin.jar > /var/log/zipkin.log 2>&1 &

② systemd 托管： Environment= 每行一个变量（见《Ubuntu 22.04 安装 Zipkin 指南》）。

③ Docker Compose / 官方镜像： environment: 段注入（镜像入口脚本读取 JAVA_OPTS 并展开全部环境变量）。

实测生效值查询（actuator/env）：

执行命令：

curl -s http://localhost:9411/actuator/env | python3 -m json.tool | head -40

执行结果（节选）：

{
    "propertySources": [
        {"name": "systemProperties"},
        {"name": "systemEnvironment"},
        {"name": "Config resource 'class path resource [zipkin-server-shared.yml]' via location 'optional:classpath:/'"},
        {"name": "Config resource 'class path resource [zipkin-server.yml]' via location 'optional:classpath:/'"},
        {"name": "applicationInfo"},
        {"name": "defaultProperties"}
    ]
}

💡 说明：/actuator/env 返回 6 个属性源；其中 zipkin-server-shared.yml 为共享默认配置（153 个键），zipkin-server.yml 为 2 个键（zipkin.server.version 与 spring.application.name）。配置加载优先级：systemProperties > systemEnvironment > zipkin-server-shared.yml > zipkin-server.yml > applicationInfo > defaultProperties，即环境变量永远覆盖内置默认值。

三、配置分组速查表

四、存储配置

4.1 通用

4.2 内存存储（默认，STORAGE_TYPE=mem）

⚠️ 注意：内存存储重启即清空，仅适合演示/验证。

4.3 Elasticsearch 存储（STORAGE_TYPE=elasticsearch）

启动示例：

STORAGE_TYPE=elasticsearch ES_HOSTS=http://10.0.0.10:9200 \
  nohup java -Xms256m -Xmx512m -jar /opt/data/zipkin/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"}}}}

4.4 Cassandra 存储（STORAGE_TYPE=cassandra3）

4.5 MySQL 存储（STORAGE_TYPE=mysql）

五、采集端配置（Collector）

Zipkin 支持 HTTP、gRPC、Kafka、RabbitMQ、ActiveMQ、Pulsar、Scribe 七种采集通道，默认全部启用，未配置地址的通道静默关闭。

5.1 HTTP / gRPC 采集

5.2 Kafka 采集

5.3 RabbitMQ 采集

5.4 ActiveMQ 采集

5.5 Pulsar 采集

5.6 Scribe（Thrift 遗留协议）

六、查询与 UI 配置

6.1 查询服务（Query）

修改端口示例：

QUERY_PORT=9412 nohup java -Xms256m -Xmx512m -jar /opt/data/zipkin/zipkin.jar > /var/log/zipkin.log 2>&1 &

💡 说明：Zipkin 的采集（HTTP）、查询 API、UI 共用同一个端口（9411），不像 Jaeger 那样 Collector/Query 分端口。多实例同机部署时用 QUERY_PORT 错开。

6.2 UI 配置

💡 说明：UI 的 query-limit、default-lookback、base-path、environment（右上角环境标签）在 zipkin-server-shared.yml 的 zipkin.ui 段中固定，不暴露环境变量占位（除 UI_ENABLED）。

七、自追踪配置（Self-Tracing）

Zipkin 可追踪自身处理流程（用于排查自身性能）：

八、服务端与 HTTP 参数

九、注意事项

• 环境变量在启动前设置：进程运行中修改环境变量不生效，必须重启（systemctl restart zipkin 或 docker compose restart zipkin）。
• SAMPLING_RATE 与 COLLECTOR_SAMPLE_RATE：二者互为别名，控制采集端采样率（默认 1.0 全采样）。
• QUERY_PORT 就是对外端口：9411 是采集 + 查询 + UI 的统一端口，改端口仅需改 QUERY_PORT。
• ES 单节点务必 ES_INDEX_REPLICAS=0：否则索引副本无法分配，ES 呈黄/红状态。
• 生效值以 /actuator/env 为准：排查配置是否生效先查该接口，再查 /actuator/health 的存储详情。

十、常见问题

10.1 修改环境变量后不生效？

原因： 环境变量在 JVM 启动时读取一次。

解决： 重启进程（sudo systemctl restart zipkin 或重新执行 nohup 命令），再用 /actuator/env 核对。

10.2 ES 健康检查显示 DOWN？

原因： ES_HOSTS 写错、ES 未启动、或认证信息缺失。

解决： 检查 curl -s http://<ES_HOSTS>/ 是否 200；确认 ES_USERNAME/ES_PASSWORD 与 ES 侧 xpack 一致。

10.3 ES 索引显示黄/红色？

原因： 单节点 ES 上 ES_INDEX_REPLICAS=1（默认）导致副本无法分配。

解决： 启动前设置 ES_INDEX_REPLICAS=0，并清理已建错误索引后重建模板。

10.4 /actuator/env 访问 404？

原因： actuator 端口是 9411（与主服务同端口），根路径 /actuator 存在但端点路径拼写错误。

解决： 先访问 http://<IP>:9411/actuator 查看端点清单，再访问 /actuator/env。

十一、参考链接

• Zipkin 官方配置文档（configuration.md）
• zipkin-server-shared.yml（默认配置源码）
• Zipkin 存储架构
• Spring Boot Actuator env 端点

本文档由 www.quzuo.net 平台开发