apache/cassandra-ubuntu2004_test

Apache Cassandra Docker 镜像技术文档

1. 镜像概述和主要用途

Apache Cassandra 是一个高度可扩展的分布式 NoSQL 数据库，专为处理大量结构化和半结构化数据而设计，具有高可用性、线性扩展能力和容错特性。Docker 镜像封装了 Apache Cassandra 的运行环境，简化了部署流程，确保环境一致性，并支持快速集成到容器化架构中。

主要用途：

• 快速部署单节点或多节点 Cassandra 集群
• 简化开发、测试和生产环境的一致性配置
• 集成到容器编排平台（如 Kubernetes、Docker Swarm）实现自动化运维

2. 核心功能和特性

2.1 数据库核心特性

• 分布式架构：无中心节点设计，节点对等，避免单点故障
• 高可用性：支持多副本复制（可配置副本因子），自动故障检测与恢复
• 线性扩展：通过添加节点实现存储容量和吞吐量的水平扩展，无需停机
• 可调一致性：支持基于 CAP 定理的可调一致性级别（如 ONE、QUORUM、ALL 等）
• 多数据中心支持：原生支持跨地域数据复制，满足灾备需求
• 高性能写入：优化写入路径，适合高写入负载场景（如日志、传感器数据）

2.2 Docker 镜像增强特性

• 轻量级封装：基于官方 Linux 发行版（如 Debian/Ubuntu），镜像体积优化
• 环境变量配置：支持通过环境变量动态调整核心配置（无需手动修改 cassandra.yaml）
• 即开即用：内置默认配置，单节点部署可直接运行
• 兼容性：支持官方 Cassandra 所有稳定版本（如 3.x、4.x 系列）

3. 使用场景和适用范围

3.1 典型使用场景

• 高写入负载系统：如社交媒体用户行为日志、物联网传感器数据采集
• 高可用性要求场景：***交易记录、***数据存储（需确保服务不中断）
• 跨地域部署：跨国企业多区域数据同步，满足低延迟访问需求
• 大数据分析平台：与 Spark、Flink 等计算框架集成，存储中间结果或原始数据
• 海量数据存储：PB 级数据存储需求，需线性扩展能力的业务

3.2 适用范围

• 需支持每秒数万至数十万写入操作的业务
• 对数据一致性要求可灵活调整的场景（非强一致性刚需）
• 容器化或云原生架构环境
• 开发/测试环境快速搭建

4. 使用方法和配置说明

4.1 获取镜像

官方维护的 Apache Cassandra Docker 镜像可通过 Docker Hub 获取：

bash
docker pull cassandra:latest  # 获取最新稳定版
# 或指定版本（如 4.0）
docker pull cassandra:4.0

4.2 基本运行（单节点）

4.2.1 快速启动

bash
docker run --name cassandra-node1 -d \
  -p 7000:7000 \  # 节点间通信端口（内部）
  -p 7001:7001 \  # SSL 节点间通信端口
  -p 9042:9042 \  # CQL 客户端端口（默认 9042）
  -p 9160:9160 \  # Thrift 客户端端口（已 deprecated，可选）
  cassandra:latest

4.2.2 验证运行状态

bash
# 查看容器日志
docker logs -f cassandra-node1

# 进入容器并连接 CQL Shell
docker exec -it cassandra-node1 cqlsh

4.3 持久化存储配置

为避免容器重启后数据丢失，需挂载宿主机目录存储数据：

bash
docker run --name cassandra-node1 -d \
  -p 7000:7000 -p 9042:9042 \
  -v /path/on/host/cassandra/data:/var/lib/cassandra \  # 数据目录
  -v /path/on/host/cassandra/logs:/var/log/cassandra \  # 日志目录
  cassandra:latest

注意：宿主机目录需提前创建并赋予权限（如 chmod 777 /path/on/host/cassandra，生产环境建议使用更严格的权限控制）。

4.4 环境变量配置

通过 -e 参数指定环境变量，覆盖默认配置（无需手动修改 cassandra.yaml）。常用变量如下：

示例：自定义集群名称和种子节点

bash
docker run --name cassandra-node1 -d \
  -e CASSANDRA_CLUSTER_NAME="MyAppCluster" \
  -e CASSANDRA_LISTEN_ADDRESS="172.17.0.2" \  # 容器 IP（需提前确认或使用 --network 固定）
  -p 9042:9042 \
  cassandra:latest

4.5 集群部署（Docker Compose）

通过 Docker Compose 快速搭建多节点集群（以 3 节点为例）：

4.5.1 创建 docker-compose.yml

yaml
version: '3.8'

services:
  cassandra-seed:
    image: cassandra:latest
    container_name: cassandra-seed
    ports:
      - "9042:9042"
    environment:
      - CASSANDRA_CLUSTER_NAME=MyCluster
      - CASSANDRA_SEEDS=cassandra-seed  # 种子节点自身
      - CASSANDRA_LISTEN_ADDRESS=cassandra-seed  # 容器名作为 hostname（需 Docker 网络支持）
      - CASSANDRA_RPC_ADDRESS=0.0.0.0
    volumes:
      - seed-data:/var/lib/cassandra
    networks:
      - cassandra-net

  cassandra-node1:
    image: cassandra:latest
    container_name: cassandra-node1
    depends_on:
      - cassandra-seed
    environment:
      - CASSANDRA_CLUSTER_NAME=MyCluster
      - CASSANDRA_SEEDS=cassandra-seed  # 指向种子节点
      - CASSANDRA_LISTEN_ADDRESS=cassandra-node1
      - CASSANDRA_RPC_ADDRESS=0.0.0.0
    volumes:
      - node1-data:/var/lib/cassandra
    networks:
      - cassandra-net

  cassandra-node2:
    image: cassandra:latest
    container_name: cassandra-node2
    depends_on:
      - cassandra-seed
    environment:
      - CASSANDRA_CLUSTER_NAME=MyCluster
      - CASSANDRA_SEEDS=cassandra-seed
      - CASSANDRA_LISTEN_ADDRESS=cassandra-node2
      - CASSANDRA_RPC_ADDRESS=0.0.0.0
    volumes:
      - node2-data:/var/lib/cassandra
    networks:
      - cassandra-net

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

networks:
  cassandra-net:
    driver: bridge

4.5.2 启动集群

bash
docker-compose up -d

4.5.3 验证集群状态

bash
# 进入种子节点容器
docker exec -it cassandra-seed nodetool status

# 预期输出（3 个节点均为 UN 状态，即 Up/Normal）：
# Datacenter: datacenter1
# ===============
# Status=Up/Down
# |/ State=Normal/Leaving/Joining/Moving
# --  Address        Load       Tokens  Owns (effective)  Host ID                               Rack
# UN  172.20.0.2     70.52 KiB  256     66.2%             xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  rack1
# UN  172.20.0.3     68.4 KiB   256     67.9%             xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  rack1
# UN  172.20.0.4     68.4 KiB   256     65.9%             xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  rack1

4.6 数据备份与恢复

4.6.1 备份（使用 nodetool snapshot）

bash
# 进入容器创建快照
docker exec -it cassandra-node1 nodetool snapshot -t my_backup my_keyspace

# 快照默认存储路径：/var/lib/cassandra/data/<keyspace>/<table>-<uuid>/snapshots/my_backup
# 通过挂载卷将快照复制到宿主机：
docker cp cassandra-node1:/var/lib/cassandra/data/my_keyspace/ /path/on/host/backups/

4.6.2 恢复

bash
# 将备份数据复制到目标节点
docker cp /path/on/host/backups/my_keyspace cassandra-node1:/var/lib/cassandra/data/

# 进入容器恢复快照
docker exec -it cassandra-node1 nodetool refresh my_keyspace my_table

5. 注意事项

• 存储性能：生产环境需使用 SSD 存储，并通过 volumes 挂载宿主机目录（避免容器内存储性能瓶颈）。
• 网络配置：跨主机集群需确保节点间端口（7000、7001）互通，CASSANDRA_BROADCAST_ADDRESS 需设置为宿主机可访问的 IP。
• 资源限制：根据数据量和负载调整容器 CPU/内存限制（如 --cpus 2 -m 4g），避免资源竞争导致性能下降。
• 版本兼容性：集群节点需使用相同的 Cassandra 主版本（如 4.0.x），跨主版本升级需遵循官方迁移指南。
• 安全配置：生产环境需启用 SSL 加密（配置 cassandra.yaml 中的 server_encryption_options），并限制 RPC 访问 IP。