Apache Cassandra 测试 Docker 镜像文档

1. 镜像概述和主要用途

该 Docker 镜像专为 Apache Cassandra 测试场景设计，提供了一个预配置的环境，用于执行各种测试任务，包括单元测试、集成测试和性能测试。镜像基于官方 Apache Cassandra 构建，集成了必要的测试工具和依赖项，旨在简化测试流程并确保环境一致性。

2. 核心功能和特性

• 多版本支持：兼容多个 Apache Cassandra 版本，可通过环境变量灵活切换
• 测试工具集成：包含 Cassandra Stress、cqlsh 及其他测试实用程序
• 可定制配置：支持通过环境变量和挂载配置文件自定义 Cassandra 实例
• 多节点测试：内置支持创建本地多节点集群，用于测试分布式特性
• 数据持久化：提供数据卷支持，确保测试数据在容器重启后不丢失
• 健康检查：内置健康检查机制，便于监控测试环境状态

3. 使用场景和适用范围

• 开发环境测试：开发人员本地测试 Cassandra 功能和配置变更
• CI/CD 集成：作为 CI/CD 流程的一部分，自动执行测试套件
• 性能基准测试：使用内置工具运行性能测试并收集指标
• 集群行为测试：模拟多节点集群环境，测试数据一致性、故障转移等特性
• 兼容性测试：在不同 Cassandra 版本上验证应用兼容性

4. 使用方法和配置说明

4.1 基本用法

4.1.1 拉取镜像

docker pull apache/cassandra-testing:latest

4.1.2 启动单节点测试容器

docker run -d --name cassandra-test \
  -p 9042:9042 \
  apache/cassandra-testing:latest

4.1.3 进入容器执行测试

docker exec -it cassandra-test /bin/bash
# 在容器内执行测试命令
cassandra-stress write n=10000 -node localhost

4.2 自定义配置

4.2.1 通过环境变量配置

docker run -d --name cassandra-test \
  -e CASSANDRA_VERSION=4.0.0 \
  -e CASSANDRA_CLUSTER_NAME=TestCluster \
  -e CASSANDRA_NUM_TOKENS=256 \
  -e MAX_HEAP_SIZE=2G \
  -e HEAP_NEWSIZE=512M \
  apache/cassandra-testing:latest

4.2.2 挂载自定义配置文件

docker run -d --name cassandra-test \
  -v /path/to/cassandra.yaml:/etc/cassandra/cassandra.yaml \
  -v /path/to/jvm.options:/etc/cassandra/jvm.options \
  apache/cassandra-testing:latest

5. Docker 部署方案示例

5.1 单节点测试环境

docker run -d --name cassandra-test \
  -p 7000:7000 \
  -p 7001:7001 \
  -p 7199:7199 \
  -p 9042:9042 \
  -p 9160:9160 \
  -e CASSANDRA_CLUSTER_NAME=TestCluster \
  -e CASSANDRA_DC=dc1 \
  -e CASSANDRA_RACK=rack1 \
  -v cassandra-data:/var/lib/cassandra \
  -v cassandra-logs:/var/log/cassandra \
  apache/cassandra-testing:latest

5.2 Docker Compose 配置（多节点测试集群）

version: '3.8'

services:
  cassandra-seed:
    image: apache/cassandra-testing:latest
    container_name: cassandra-seed
    environment:
      - CASSANDRA_CLUSTER_NAME=TestCluster
      - CASSANDRA_DC=dc1
      - CASSANDRA_RACK=rack1
      - CASSANDRA_SEEDS=cassandra-seed
      - CASSANDRA_NUM_TOKENS=256
      - MAX_HEAP_SIZE=2G
      - HEAP_NEWSIZE=512M
    volumes:
      - seed-data:/var/lib/cassandra
      - seed-logs:/var/log/cassandra
    ports:
      - "9042:9042"
    healthcheck:
      test: ["CMD", "cqlsh", "-e", "describe keyspaces"]
      interval: 30s
      timeout: 10s
      retries: 5

  cassandra-node1:
    image: apache/cassandra-testing:latest
    container_name: cassandra-node1
    environment:
      - CASSANDRA_CLUSTER_NAME=TestCluster
      - CASSANDRA_DC=dc1
      - CASSANDRA_RACK=rack1
      - CASSANDRA_SEEDS=cassandra-seed
      - CASSANDRA_NUM_TOKENS=256
    volumes:
      - node1-data:/var/lib/cassandra
    depends_on:
      cassandra-seed:
        condition: service_healthy

  cassandra-node2:
    image: apache/cassandra-testing:latest
    container_name: cassandra-node2
    environment:
      - CASSANDRA_CLUSTER_NAME=TestCluster
      - CASSANDRA_DC=dc1
      - CASSANDRA_RACK=rack1
      - CASSANDRA_SEEDS=cassandra-seed
      - CASSANDRA_NUM_TOKENS=256
    volumes:
      - node2-data:/var/lib/cassandra
    depends_on:
      cassandra-seed:
        condition: service_healthy

volumes:
  seed-data:
  seed-logs:
  node1-data:
  node2-data:

6. 配置参数和环境变量

6.1 核心环境变量

6.2 端口映射

7. 测试执行示例

7.1 运行 Cassandra Stress 性能测试

# 启动容器并运行写性能测试
docker run --rm -it apache/cassandra-testing:latest \
  cassandra-stress write n=100000 -rate threads=20 -node localhost

7.2 执行集成测试套件

# 挂载本地测试代码并执行测试
docker run -it --rm \
  -v $(pwd)/test-suite:/tests \
  -e TEST_MODE=integration \
  apache/cassandra-testing:latest \
  /bin/bash -c "cd /tests && ./run-integration-tests.sh"

7.3 在 CI/CD 管道中使用（GitLab CI 示例）

cassandra-test:
  stage: test
  image: apache/cassandra-testing:latest
  services:
    - name: apache/cassandra-testing:latest
      alias: cassandra
  script:
    - wait-for-it cassandra:9042 -t 60
    - cqlsh cassandra -e "CREATE KEYSPACE test WITH replication = {'class':'SimpleStrategy', 'replication_factor':1};"
    - cassandra-stress read n=1000 -node cassandra

8. 高级配置和注意事项

• 资源限制：运行性能测试时建议设置适当的 CPU 和内存限制，避免系统资源竞争
• 网络配置：多节点测试时需确保容器间网络通畅，可使用 Docker 网络进行隔离
• 数据清理：测试完成后使用 docker volume prune 清理未使用的数据卷
• 日志收集：通过挂载日志目录或使用日志驱动收集测试过程日志
• 安全注意事项：该镜像默认关闭认证机制，不建议用于生产环境
• 版本兼容性：不同 Cassandra 版本间配置参数可能存在差异，使用时需参考对应版本文档

9. 故障排除

• 启动失败：检查容器日志 docker logs <container-id>，确认配置是否正确
• 节点无法加入集群：验证种子节点地址是否可达，网络配置是否正确
• 性能测试结果异常：检查主机资源使用情况，确保没有其他进程占用过多资源
• 测试超时：增加容器内存限制或调整测试参数降低负载