Cassandra集群化Docker完整部署：从原理到落地

单机版Cassandra用Docker跑起来真的就是一条命令的事docker run -d --name cass cassandra:4.1等上几十秒cqlsh进去建个keyspace写两行数据一路畅通。可一旦需求变成Cassandra集群化Docker完整部署很多人会下意识地觉得无非就是把这条启动命令复制三份。然后现实往往会直接给一记重拳——三个容器确实都活着nodetool status里却只有一个是UN另外两个要么DN挂在那儿要么永远停在Joining翻日志翻到头也看不出到底哪一步出了错。这个坎我在测试环境搭集群时真实踩过整整一下午耗在排查节点之间为什么互相看不见上面。所以这篇文章想做的事很具体把Cassandra集群化Docker部署从原理到落地完整走通。内容包括为什么集群部署不能靠单机思维平推、启动前必须拍板的网络和持久化方案、一套能直接复用的单机三节点compose配置、跨主机部署时真正要改的东西、集群验证与压测手段以及我自己总结的一套故障排查顺序。适合已经会在单机版上写CQL、现在想把集群概念真正落地的工程师也适合需要快速复现多节点测试拓扑、或者正在为生产容器化做技术预演的同学。文中的配置全部基于官方镜像和常见实践编写可以直接抄但不能无脑抄因为我会把每个关键参数背后的原因一并讲清楚。1. 单机跑通和集群可用之间隔着一道不小的坎1.1 集群化到底在部署什么Gossip、种子节点与副本很多人把集群化理解为多跑几个节点这是第一步就出偏差的地方。Cassandra集群和单机最大的区别不是进程数量而是节点之间存在一套自组织协作机制这套机制由三个核心组件构成第一是Gossip协议。每个节点会周期性随机选取其他节点交换状态信息靠这种八卦式的传播整个集群最终会知道每一台节点的存活情况、负载、schema版本等。Gossip本身不需要全互联但一个新节点刚加入时必须先认识至少一个老成员否则它连八卦的对象都没有。第二是种子节点seed node。它是节点的第一个联系人作用类似于新员工入职时的人力资源同事你不必认识全公司几百号人但必须有人把你拉进通讯录。种子节点不承担特殊数据角色它就是一个引导入口集群运行起来之后少了它也不会立刻崩溃但新节点加入会变得困难。第三是数据分布与复制。Cassandra把整个token环划分为2^127个范围开启vnodes即num_tokens后每个节点承担多个虚拟范围。复制因子replication factor则决定每份数据在集群里存几份。大多数生产集群会用NetworkTopologyStrategy按数据中心和机架感知来放置副本而单机环境里默认的SimpleStrategy根本不会考虑这些。把这些串起来就明白了一件事集群化部署的真正工作是让N个节点在发现机制、拓扑感知、副本放置这三层上达成一致。Docker在这中间插入的麻烦在于它让节点之间的网络寻址多了一层转换后面要讲的listen和broadcast问题就是这么来的。1.2 为什么偏偏用Docker做这件事既然容器化带来额外的网络复杂度为什么还要用Docker来部署Cassandra集群我个人的答案是三个词可复现、可隔离、可销毁。可复现意味着同一份compose文件和同一组环境变量在谁的机器上都能还原出一模一样的多节点拓扑。这在排查问题时价值极大——测试环境里复现不出来的故障生产环境出了问题就只能干瞪眼。可隔离则体现在资源上一台16G内存的开发机上可以同时跑三节点单DC和两节点双DC两套实验集群互不干扰这在物理机上至少要两到三台机器才能做到。可销毁就更直接了集群测坏了或者数据弄脏了docker compose down -v一键连数据带容器清掉从头再来这个操作在物理集群上等于重装三台机器。我之前在某个项目里需要模拟跨数据中心的部署行为如果走物理机申请流程光等机器资源就得一周。最后就是在一台宿主机上用Docker起了六个容器划分两个逻辑DC两天把整套拓扑交付给了测试组而且随时可以推倒重建。这套优势在测试和预研场景里非常值钱。2. 动手前先拍板容器网络、监听地址与数据持久化2.1 容器网络默认bridge为什么不行这是新手集群化部署翻车率最高的一个点。单机模式下网络根本不用关心-p 9042:9042映射一下宿主机端口就能连cqlsh。但集群模式下节点之间需要通过7000端口做Gossip通信和流式数据传输节点之间必须能互相访问。如果你图省事三个容器全跑在Docker默认的bridge网络上会发生一件很诡异的事容器各自有IP也能ping通彼此如果镜像里有ping工具的话但它们无法通过容器名互相解析。Docker的嵌入式DNS只在用户自定义网络上生效默认bridge网络上是没有这项服务的。而官方镜像的配置依赖CASSANDRA_SEEDS这个环境变量你可以填IP也可以填主机名填主机名更符合可读性要求但默认网络下它根本解析不了。于是节点启动后Gossip找不到种子节点状态自然就一直卡在Joining或者直接DN。解决办法也简单启动前先定义一个用户自定义网络无论是docker network create还是compose文件里声明网络都行。自定义网络上容器名就是天然的主机名Cassandra节点之间直接用名字互相发现。再进一步我建议在compose里给每个节点分配固定的静态IP理由很朴素日志里出现的是IP报错信息里出现的也是IP如果IP是固定的你拿着docker logs去比对compose配置一眼就能对上号纯靠自动分配IP的话每次重建环境IP都会变排查时还得先花时间确认谁是谁。2.2 listen_address和broadcast_address一个管听一个管说Cassandra的网络配置里有两组地址很多人栽在这里。我习惯用一个类比来解释listen_address是电话听筒里听到的自己的号码broadcast_address是印在名片上发给别人的号码。正常物理机部署时两者通常是同一个IP所以大多数教程根本不提这事。但在容器环境里两者可能是不同的——尤其跨主机部署时。官方镜像对应的环境变量是这样的环境变量作用容器里的推荐设置CASSANDRA_LISTEN_ADDRESS节点进程绑定本机网卡用于接收Gossip/流式传输容器IP如自定义网络里的172.28.0.11CASSANDRA_BROADCAST_ADDRESS告诉其他节点来连我时用这个地址单机容器场景容器IP跨主机宿主机可达IPCASSANDRA_RPC_ADDRESS绑定CQL客户端连接的地址0.0.0.0 才能从容器外访问CASSANDRA_BROADCAST_RPC_ADDRESS告诉CQL驱动连我用这个地址客户端可访问的IP按需设置最常见的错误是把CASSANDRA_LISTEN_ADDRESS设成0.0.0.0这在某些情况下看起来能用因为节点确实监听在所有网卡上但你没法预判其他节点会如何解读这个地址。更稳妥的做法是明确指定容器IP。同一个错误容易发生在只想从宿主机连cqlsh、却忘了CASSANDRA_RPC_ADDRESS必须设成0.0.0.0的场景——镜像默认rpc_address是localhost结果主机上连不上9042还以为是端口映射的问题。2.3 数据目录挂载与堆内存上限数据持久化方面官方镜像的数据目录是/var/lib/cassandra里面存数据、schema、cqlsh历史等。强烈建议挂载命名卷named volume而不是bind mount宿主机目录。原因很简单镜像里的cassandra进程是非root用户运行的bind mount宿主机目录时经常遇到目录属主或SELinux权限问题导致启动失败而命名卷由Docker管理权限初始化是现成的省去一堆麻烦。另外镜像的entrypoint脚本只在数据目录为空时根据环境变量生成cassandra.yaml所以容器第一次启动的参数就是定型参数之后再改环境变量重启是不会生效的必须清掉数据目录重新初始化。我建议把集群名、snitch、DC/rack这些拓扑相关参数在第一次启动前想清楚。内存也是单机多容器场景里特别容易忽略的。官方镜像会按容器可见内存自动计算JVM堆大小你在16G的开发机上跑三个节点每个节点可能默认配出几个GB的堆三个加起来直接把你机器干到OOM。测试环境我一般显式设置CASSANDRA_MAX_HEAP_SIZE: 512M CASSANDRA_HEAP_NEWSIZE: 100M三个节点加起来不到2G开发机能轻松扛住。生产环境另说但测试集群和CI环境这样压堆是没问题的。3. 单机三节点一套可以直接抄作业的docker-compose3.1 完整compose文件逐项解读下面这套compose文件是我在测试环境里一直在用的三节点单DC配置直接保存为docker-compose.yml即可version: 3.8 x-cassandra-common: cassandra-common image: cassandra:4.1 restart: unless-stopped networks: - cass-net healthcheck: test: [CMD-SHELL, nodetool status || exit 1] interval: 15s timeout: 10s retries: 12 start_period: 60s services: cassandra-node1: : *cassandra-common container_name: cassandra-node1 networks: cass-net: ipv4_address: 172.28.0.11 ports: - 9042:9042 environment: CASSANDRA_CLUSTER_NAME: DockerCluster CASSANDRA_DC: dc1 CASSANDRA_RACK: rack1 CASSANDRA_ENDPOINT_SNITCH: GossipingPropertyFileSnitch CASSANDRA_NUM_TOKENS: 16 CASSANDRA_SEEDS: cassandra-node1 CASSANDRA_LISTEN_ADDRESS: 172.28.0.11 CASSANDRA_BROADCAST_ADDRESS: 172.28.0.11 CASSANDRA_RPC_ADDRESS: 0.0.0.0 volumes: - cass-node1-data:/var/lib/cassandra cassandra-node2: : *cassandra-common container_name: cassandra-node2 networks: cass-net: ipv4_address: 172.28.0.12 ports: - 9043:9042 environment: CASSANDRA_CLUSTER_NAME: DockerCluster CASSANDRA_DC: dc1 CASSANDRA_RACK: rack1 CASSANDRA_ENDPOINT_SNITCH: GossipingPropertyFileSnitch CASSANDRA_NUM_TOKENS: 16 CASSANDRA_SEEDS: cassandra-node1 CASSANDRA_LISTEN_ADDRESS: 172.28.0.12 CASSANDRA_BROADCAST_ADDRESS: 172.28.0.12 CASSANDRA_RPC_ADDRESS: 0.0.0.0 volumes: - cass-node2-data:/var/lib/cassandra cassandra-node3: : *cassandra-common container_name: cassandra-node3 networks: cass-net: ipv4_address: 172.28.0.13 ports: - 9044:9042 environment: CASSANDRA_CLUSTER_NAME: DockerCluster CASSANDRA_DC: dc1 CASSANDRA_RACK: rack1 CASSANDRA_ENDPOINT_SNITCH: GossipingPropertyFileSnitch CASSANDRA_NUM_TOKENS: 16 CASSANDRA_SEEDS: cassandra-node1 CASSANDRA_LISTEN_ADDRESS: 172.28.0.13 CASSANDRA_BROADCAST_ADDRESS: 172.28.0.13 CASSANDRA_RPC_ADDRESS: 0.0.0.0 volumes: - cass-node3-data:/var/lib/cassandra volumes: cass-node1-data: cass-node2-data: cass-node3-data: networks: cass-net: driver: bridge ipam: config: - subnet: 172.28.0.0/24 gateway: 172.28.0.1几个重点说清楚。CASSANDRA_SEEDS是唯一一个节点间不同的配置维度node1填自己node2和node3填node1的容器名。这是因为整个集群只需要一个引导入口其他节点都指向它。生产环境里通常建议每数据中心配置3到5个种子节点但测试环境一个足够。GossipingPropertyFileSnitch配合CASSANDRA_DC和CASSANDRA_RACK使用节点启动时会据此生成对应的cassandra-rackdc.properties。这是正确构建DC/rack感知拓扑的前提后面用NetworkTopologyStrategy建keyspace时依赖这个设置。端口映射上node2和node3的宿主机端口分别映射成9043和9044因为同一台机器上9042只能被一个容器占用。如果只需要在容器网络内部访问这三个映射其实都可以去掉但从宿主机调试方便的角度多映射两个端口不亏。3.2 启动顺序先把种子节点养到UN这套compose第一次启动时请务必严格遵循启动顺序docker compose up -d cassandra-node1然后等着观察node1的状态。最简单的方式是循环执行docker exec -it cassandra-node1 nodetool status直到node1的状态行从什么都没有变成UN——Up和Normal。这个过程通常需要30秒到两三分钟取决于机器性能。确认node1是UN之后再把另外两个节点拉起来docker compose up -d为什么不能三个一起启动因为如果两个全新节点同时启动、又都把对方之外的节点当作种子而种子节点还没起来它们彼此之间无法通过Gossip确认自己是同一个集群就可能各自形成独立的环出现两个同名但互不相识的逻辑集群。这个状态非常隐蔽表面上看每个节点都UN但数据不会互相复制。先养好种子节点再拉其余节点能从根本上避开这个问题。3.3 首次验证nodetool status长什么样才算对三个节点都起来后在node1上执行docker exec -it cassandra-node1 nodetool status正常输出大概是这个样子Datacenter: dc1 StatusUp/Down |/ StateNormal/Leaving/Joining/Moving -- Address Load Tokens Owns (effective) Host ID Rack UN 172.28.0.11 ... 16 100.0% xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx rack1 UN 172.28.0.12 ... 16 100.0% xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx rack1 UN 172.28.0.13 ... 16 100.0% xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx rack1判断标准只有一条三行都必须是UN。Owns显示100%是因为复制因子3且节点数3时每个token range都会被复制到全部三个节点上所以每个节点的有效持有率都是满的。我见过不少人在这一步误判看到三个容器都healthy就以为成功了其实healthcheck只证明JMX能连上不代表节点间Gossip已经打通。一定要以nodetool status的输出为准。如果看到UJJoining说明节点正在流式接收数据属于正常中间状态如果长时间停在UJ不前进或者出现DN那就进入排查环节了这放到第六节专门讲。4. 跨主机部署三个节点不在同一台机器时改哪些东西4.1 端口映射与广播地址的重新定义单机三节点验证通过后很多人会直接想把这套compose搬到两台或三台物理机上。这里有个核心认知要转变跨主机时CASSANDRA_BROADCAST_ADDRESS不能再填容器IP了必须填宿主机上对其它主机可达的IP。假设node1跑在主机A上node2跑在主机B上。对于node2来说它要联系种子节点CASSANDRA_SEEDS里写的是主机A的IP——因为主机B上的容器只有通过宿主机IP和端口映射才能访问到主机A上的容器。而node1的CASSANDRA_BROADCAST_ADDRESS也必须相应地设成主机A的IP否则node2虽然能连上node1的7000端口完成引导但拿到node1广播的地址后回连时发现是个容器内网IP根本路由不过去Gossip就会反复失败。具体到操作上每台宿主机维护各自的compose文件只定义一个服务。以node1所在主机为例services: cassandra-node1: image: cassandra:4.1 container_name: cassandra-node1 network_mode: bridge ports: - 7000:7000 - 9042:9042 environment: CASSANDRA_LISTEN_ADDRESS: 172.17.0.2 CASSANDRA_BROADCAST_ADDRESS: 192.168.1.101 CASSANDRA_RPC_ADDRESS: 0.0.0.0 CASSANDRA_BROADCAST_RPC_ADDRESS: 192.168.1.101 CASSANDRA_SEEDS: 192.168.1.101这里的192.168.1.101就是主机A在局域网内的地址。node2、node3所在主机的compose里CASSANDRA_SEEDS都写192.168.1.101各自BROADCAST_ADDRESS写自己宿主机的IP。还有一点容易漏宿主机防火墙必须放行7000/tcp云服务器还得在安全组里放行。我曾经在云环境搭跨主机集群节点间怎么都gossip不上最后发现是安全组只放了9042忘了7000。4.2 用host网络模式省掉NAT的坑如果每台宿主机上只跑一个Cassandra节点其实有一个更省心的方案直接用host网络模式。network_mode: host下容器共享宿主机网络命名空间没有端口映射也没有NAT转换listen和broadcast地址统一填宿主机IPCASSANDRA_RPC_ADDRESS也直接填宿主机IP。这样配置量最少也最贴近传统物理机部署习惯节点日志里的地址和实际网络完全一致。代价是放弃端口隔离容器里的Cassandra直接暴露在宿主机网络上适合专用测试机或可控网络环境。还有个附加好处是性能省掉了docker-proxy这一层转发虽然Cassandra节点间的数据路径本来就不走用户态代理但至少排查问题时少一个变量。再往上是Swarm overlay或Kubernetes方案用服务发现替代手写种子IP那是另一个量级的复杂度适合节点规模大、生命周期动态变化的场景。三到五节点的小集群手写IP和host网络模式就已经很够用了。5. 验证和压测集群是真的不是三个容器在装睡5.1 nodetool工具箱status/ring/describecluster怎么看集群起来之后建议按顺序跑三个命令确认健康度docker exec -it cassandra-node1 nodetool status docker exec -it cassandra-node1 nodetool ring docker exec -it cassandra-node1 nodetool describeclusterstatus看的是节点存活和状态ring看的是token分布——能直观确认16个vnodes分配在三个节点上而不是挤在一处。describecluster会返回集群名、分区器、端点snitch信息用来核对三台节点是否使用了完全一致的配置。这三个命令跑完都正常只说明集群层面通了数据层面的验证还得靠CQL。这里我习惯再加一个nodetool netstats它能显示当前节点是否正在向其他节点传输数据加节点或者有大查询触发compaction时这个命令很有用。5.2 用复制因子和控制台证明数据真的多副本单纯节点状态都UN还不能证明数据复制正常必须实际建一个有副本的keyspace写入数据用一致性级别来验证。我常用的验证脚本是这样的CREATE KEYSPACE demo WITH replication { class: NetworkTopologyStrategy, dc1: 3 }; USE demo; CREATE TABLE users ( user_id uuid PRIMARY KEY, email text, created_at timestamp ); INSERT INTO users (user_id, email, created_at) VALUES (uuid(), aliceexample.com, toTimestamp(now()));注意我在测试环境坚决不用SimpleStrategy建keyspace——它和GossipingPropertyFileSnitch的DC感知模型是拧着的用它会绕开很多本应该在网络拓扑层校验的东西。然后做关键实验把其中一个节点停掉验证集群真的扛得住节点故障。docker stop cassandra-node3 docker exec -it cassandra-node1 cqlsh -e CONSISTENCY QUORUM; SELECT * FROM demo.users;复制因子3、可用节点2个时QUORUM要求两个副本响应此时读操作依然成功。如果再执行CONSISTENCY ALL会提示Unavailable——因为三个副本不可能全部响应。这个实验做完集群才算是真正验证过了。5.3 快速压测摸底cassandra-stress官方镜像里带了cassandra-stress工具不需要额外安装可以直接在容器里跑。先写后读各来一轮docker exec -it cassandra-node1 cassandra-stress write n100000 -rate threads8 docker exec -it cassandra-node1 cassandra-stress read n100000 -rate threads8默认情况下它会用SimpleStrategy RF1在压测keyspace上跑对于验证集群能工作这个目标足够了。看输出里的op rate和latency mean/99th percentile如果写入速率在一个量级上稳定、没有大面积的timeout说明节点间协调和数据流式传输都正常。真实生产压测时建议用-schema参数指定NetworkTopologyStrategy和复制因子让压测数据真正走多副本路径。压测产生的数据记得清掉别污染后续的实验。6. 故障排查与运维经验部署完成只是开始6.1 节点DN/Joining的完整排查链路集群部署失败症状大多落在两种节点显示DN或者长时间UJ不转UN。下面是我自己沉淀下来的一套排查顺序照着走比瞎翻日志高效得多。第一步确认容器本身活着。docker ps -a docker logs cassandra-node2 --tail 200如果容器在反复重启日志里多半是配置错误或权限问题。如果容器活着但节点DN继续下一步。第二步确认节点进程状态。进入容器执行nodetool status和nodetool gossipinfo。如果nodetool连不上JMX说明进程本身可能还在做启动前检查如果gossipinfo里看不到其他节点的信息问题更可能出在网络层。第三步验证网络连通性。容器里一般没有nc命令但有bash的话可以直接用这个技巧docker exec -it cassandra-node2 bash -c exec 3/dev/tcp/172.28.0.11/7000 echo ok能打印ok说明7000端口通。同时用docker network inspect cass-net确认三个容器确实在同一个网络里。跨主机场景再加上一条在两台宿主机上分别测试对端IP的7000端口是否可达防火墙和安全组是这里最常见的原因。第四步看Cassandra日志。docker logs cassandra-node2里如果出现类似Unable to gossip with any seeds的错误说明种子配置或网络有问题如果出现Unable to find peer或UnknownHost之类多半是广播地址解析异常。日志末尾有Startup complete字样才算启动完成。第五步也是最容易忽略的检查三台节点的集群名和snitch是否完全一致。我在测试环境遇到过两次看起来全对但就是连不上的情况最后都是某台节点的CASSANDRA_CLUSTER_NAME多个空格或者snitch拼写不一致。这类问题日志里会有明确提示但新手往往不看那么深。6.2 配置不一致导致的隐性故障比DN更麻烦的是半通不通的隐性故障节点状态全是UN但写入数据后个别副本一直缺失。这种问题通常来自两个原因一是早期有人用SimpleStrategy建了keyspace节点拓扑感知和多副本放置根本没正确生效二是某个节点启动时用了不同的DC/rack配置导致NetworkTopologyStrategy认为它属于另一个DC副本分配和预期不符。修复思路没有捷径把有问题的keyspace重建为NetworkTopologyStrategy重新灌数据或者把配置不一致的节点直接清掉数据目录重新加入集群。所以我才在前面反复强调首次启动的配置一定要一次到位。顺带提一个官方镜像的坑entrypoint生成cassandra.yaml之后你再改CASSANDRA_CLUSTER_NAME这些环境变量重启容器配置不会变因为数据目录里已经有生成过的yaml了。遇到这种情况要么手动改数据目录里的cassandra.yaml要么docker compose down -v彻底重建。6.3 快照备份、repair与清理节奏集群部署完成之后的运维有三件事我认为是底线备份、修复、清理。备份用快照即可一条命令docker exec -it cassandra-node1 nodetool snapshot -t backup-20250101快照文件落在/var/lib/cassandra/data/keyspace/table/snapshots/backup-20250101/用docker cp拷出来就是一份可用的数据备份。用完记得执行nodetool clearsnapshot -t backup-20250101否则快照文件一直占磁盘空间。增量备份需要运维前在cassandra.yaml里显式打开incremental_backups: true开机前就要想好临时设置不生效。修复对应nodetool repair。Cassandra的副本修复是异步的节点短暂宕机后靠hints补偿超过max_hint_window时间就会产生数据不一致必须靠repair把副本对齐。我习惯在低峰期执行docker exec -it cassandra-node1 nodetool repair -pr-pr只修复本地节点负责的主范围比全量repair节省资源。扩容加节点之后原来的节点上可能出现不再属于自己的数据这时候要跑nodetool cleanup把多余数据清掉否则磁盘会悄悄涨满。加节点和减节点本身分别对应nodetool decommission和nodetool removenode这两个操作都不能在节点故障时使用故障节点的移除要走removenode带上host id。最后说一个实实在在的习惯。每次我在这套Docker环境上做实验都会先在宿主机上开一个终端专门跑docker logs -f cassandra-node1Cassandra日志的时序信息太关键了很多故障的根因就藏在某个毫秒级的启动顺序差异里。与其事后翻日志不如一开始就让日志滚起来。集群这个东西部署成功那一刻的成就感很短暂真正决定你后续体验的是排查问题和日常维护的方法是否成体系。