openzipkin/zipkin-cassandra 镜像文档

1. 镜像概述与主要用途

本镜像为 quay.io/openzipkin/zipkin-cassandra 的镜像，基于 Apache Cassandra 3.11.4 构建，集成 Zipkin 配置加载器（ZipkinConfigurationLoader），主要用于为 Zipkin 分布式追踪系统提供 Cassandra 存储后端支持，实现追踪数据的持久化存储与动态配置管理。

2. 核心功能与特性

• 基础组件版本：集成 Apache Cassandra 3.11.4，提供稳定的分布式存储能力
• Zipkin 配置集成：包含 ZipkinConfigurationLoader 编译模块，支持 Zipkin 与 Cassandra 存储的动态配置加载
• Java 8 兼容性：采用 -source 1.8 -target 1.8 编译参数，确保与 Java 8 运行环境兼容
• 轻量级构建：构建过程中自动清理临时文件（如 Apache Cassandra 源码包），减少镜像体积

3. 使用场景与适用范围

• Zipkin 后端存储：作为 Zipkin 分布式追踪系统的存储层，存储追踪链路数据（如 span、trace 信息）
• 持久化追踪数据：适用于需要长期保留追踪数据、支持高吞吐写入的生产/测试环境
• Cassandra 存储场景：针对已采用 Cassandra 作为分布式存储方案的架构，提供 Zipkin 无缝集成能力

4. 详细使用方法与配置说明

4.1 环境变量配置

4.2 Docker 运行示例

基础运行命令

docker run -d \
  --name zipkin-cassandra \
  -p 9042:9042 \  # Cassandra CQL 端口  
  -e CASSANDRA_VERSION=3.11.4 \  # 可省略，默认3.11.4  
  openzipkin/zipkin-cassandra:latest  

带数据持久化的运行命令

挂载 Cassandra 数据目录至宿主机，避免容器重启后数据丢失：

docker run -d \
  --name zipkin-cassandra \
  -p 9042:9042 \
  -v /path/to/cassandra/data:/var/lib/cassandra \  # 数据持久化目录  
  -v /path/to/zipkin-config:/etc/zipkin \  # 自定义 Zipkin 配置文件挂载（可选）  
  openzipkin/zipkin-cassandra:latest  

4.3 Docker Compose 配置示例

与 Zipkin 服务联动部署（典型分布式追踪架构）：

version: '3.8'  
services:  
  zipkin-cassandra:  
    image: openzipkin/zipkin-cassandra:latest  
    container_name: zipkin-cassandra  
    ports:  
      - "9042:9042"  
    volumes:  
      - cassandra-data:/var/lib/cassandra  
    environment:  
      - CASSANDRA_VERSION=3.11.4  
    networks:  
      - zipkin-network  

  zipkin-server:  
    image: openzipkin/zipkin:latest  
    container_name: zipkin-server  
    ports:  
      - "9411:9411"  
    environment:  
      - STORAGE_TYPE=cassandra3  # 指定 Cassandra 存储  
      - CASSANDRA_CONTACT_POINTS=zipkin-cassandra:9042  # 连接 Cassandra 容器  
    depends_on:  
      - zipkin-cassandra  
    networks:  
      - zipkin-network  

networks:  
  zipkin-network:  

volumes:  
  cassandra-data:  # 持久化卷  

4.4 配置说明

• Cassandra 连接配置：需确保 Zipkin 服务通过 CASSANDRA_CONTACT_POINTS 环境变量指向本镜像容器的 IP:端口（默认 9042），例如 zipkin-cassandra:9042（Docker 网络内通过容器名访问）。
• 自定义 ZipkinConfigurationLoader：若需修改配置加载逻辑，可挂载自定义 ZipkinConfigurationLoader.java 文件至容器编译目录，重新编译（需确保 Java 8 环境）。

5. 注意事项

• 版本限制：当前镜像默认集成 Cassandra 3.11.4，暂不支持动态切换其他版本（如需其他版本，需基于原 Dockerfile 重新构建并修改 CASSANDRA_VERSION）。
• Java 环境依赖：编译与运行需 Java 8 环境，不兼容 Java 9+。
• 网络隔离：生产环境建议通过 Docker 网络隔离容器，仅暴露必要端口（如 9042），并限制访问来源。