Apache Cassandra Docker 镜像文档

1. 镜像概述和主要用途

Apache Cassandra 是一个高度可扩展的分布式 NoSQL 数据库系统，旨在处理大量分布式数据中心的结构化数据。该 Docker 镜像封装了 Apache Cassandra 数据库服务，提供了一种便捷、一致且隔离的方式来部署和运行 Cassandra 实例，适用于开发、测试和生产环境。

2. 核心功能和特性

• 分布式架构：无中心节点设计，支持线性扩展
• 高可用性：跨多节点复制数据，自动故障检测和恢复
• 弹性扩展：轻松添加或删除节点，无需停机
• 高性能：优化写入操作，支持高吞吐量和低延迟
• 数据一致性：可配置的一致性级别，平衡可用性和一致性
• 容错能力：自动分片和复制，确保数据不丢失
• 多数据中心支持：跨地域数据复制，增强灾难恢复能力

3. 使用场景和适用范围

适用场景

• 大规模数据存储和管理（TB 到 PB 级）
• 需要高写入吞吐量的应用系统
• 要求 24/7 不间断运行的业务系统
• 跨地域部署的分布式应用
• 对数据可用性要求高的场景

不适用场景

• 强事务性需求（ACID 完全支持）
• 复杂的多表关联查询
• 大量需要即时一致性的读取操作

4. 使用方法和配置说明

4.1 基本使用方法

启动单节点 Cassandra 实例

docker run --name cassandra -d -p 9042:9042 cassandra

连接到 Cassandra 容器

docker exec -it cassandra cqlsh

4.2 环境变量配置

4.3 持久化数据

为确保数据持久化，需挂载数据卷：

docker run --name cassandra -d \
  -p 9042:9042 \
  -v /path/to/cassandra/data:/var/lib/cassandra \
  cassandra

4.4 配置文件自定义

如需自定义 Cassandra 配置，可挂载配置文件：

docker run --name cassandra -d \
  -p 9042:9042 \
  -v /path/to/cassandra.yaml:/etc/cassandra/cassandra.yaml \
  cassandra

5. 多节点集群部署

5.1 使用 Docker Run 部署集群

1. 启动种子节点

docker run --name cassandra-seed -d \
  -e CASSANDRA_CLUSTER_NAME=MyCluster \
  -e CASSANDRA_DC=DC1 \
  -e CASSANDRA_RACK=Rack1 \
  -p 9042:9042 \
  --network cassandra-net \
  cassandra

2. 启动 additional 节点

docker run --name cassandra-node2 -d \
  -e CASSANDRA_CLUSTER_NAME=MyCluster \
  -e CASSANDRA_SEEDS=cassandra-seed \
  -e CASSANDRA_DC=DC1 \
  -e CASSANDRA_RACK=Rack1 \
  --network cassandra-net \
  cassandra

5.2 Docker Compose 部署示例

创建 docker-compose.yml 文件：

version: '3.8'

services:
  cassandra-seed:
    image: cassandra
    container_name: cassandra-seed
    ports:
      - "9042:9042"
    environment:
      - CASSANDRA_CLUSTER_NAME=MyCluster
      - CASSANDRA_DC=DC1
      - CASSANDRA_RACK=Rack1
      - MAX_HEAP_SIZE=1G
      - HEAP_NEWSIZE=256M
    volumes:
      - cassandra-data-seed:/var/lib/cassandra
    networks:
      - cassandra-network
    restart: unless-stopped

  cassandra-node1:
    image: cassandra
    container_name: cassandra-node1
    environment:
      - CASSANDRA_CLUSTER_NAME=MyCluster
      - CASSANDRA_SEEDS=cassandra-seed
      - CASSANDRA_DC=DC1
      - CASSANDRA_RACK=Rack1
      - MAX_HEAP_SIZE=1G
      - HEAP_NEWSIZE=256M
    volumes:
      - cassandra-data-node1:/var/lib/cassandra
    networks:
      - cassandra-network
    depends_on:
      - cassandra-seed
    restart: unless-stopped

  cassandra-node2:
    image: cassandra
    container_name: cassandra-node2
    environment:
      - CASSANDRA_CLUSTER_NAME=MyCluster
      - CASSANDRA_SEEDS=cassandra-seed
      - CASSANDRA_DC=DC1
      - CASSANDRA_RACK=Rack2
      - MAX_HEAP_SIZE=1G
      - HEAP_NEWSIZE=256M
    volumes:
      - cassandra-data-node2:/var/lib/cassandra
    networks:
      - cassandra-network
    depends_on:
      - cassandra-seed
    restart: unless-stopped

networks:
  cassandra-network:
    driver: bridge

volumes:
  cassandra-data-seed:
  cassandra-data-node1:
  cassandra-data-node2:

启动集群：

docker-compose up -d

6. 验证集群状态

连接到任意节点并检查集群状态：

docker exec -it cassandra-seed nodetool status

预期输出应显示所有节点均为 UN（Up/Normal）状态。

7. 数据备份与恢复

7.1 备份数据

docker exec -it cassandra-seed nodetool snapshot -t backup-$(date +%Y%m%d)

7.2 恢复数据

# 停止 Cassandra 服务
docker exec -it cassandra-seed nodetool drain

# 恢复数据（需进入容器操作）
docker exec -it cassandra-seed bash
cd /var/lib/cassandra/data/keyspace/table/
rm -rf *-Data.db
cp snapshot/backup-20230101/* .

# 重启容器
docker restart cassandra-seed

8. 性能优化建议

• 根据工作负载调整 JVM 堆大小（MAX_HEAP_SIZE 和 HEAP_NEWSIZE）
• 生产环境中使用专用的数据卷，确保 I/O 性能
• 合理配置复制因子，平衡可用性和性能
• 根据数据访问模式设计适当的数据模型
• 监控集群性能，及时调整资源配置

9. 注意事项

• 容器名称和网络配置需保持唯一，避免冲突
• 生产环境中应配置适当的资源限制（CPU、内存）
• 多节点集群应确保节点间网络通信畅通
• 定期备份数据，防止意外丢失
• 升级前请查阅官方文档，遵循正确的升级流程