Cassandra 4.0.11 Docker 安装与配置手册

适用场景：Windows 64GB 内存开发机，Docker Desktop + WSL2 后端，Spring Boot 项目连接。
版本：Cassandra 4.0.11（镜像标签固定，切勿使用 latest 避免自动升级到 5.x）

---

一、前置检查

1.1 确认 WSL2 内存已放开

编辑 C:\Users\<用户名>\.wslconfig：

[wsl2]
memory=28GB
processors=10
swap=4GB
swapFile=C:\\temp\\wsl-swap.vhdx
localhostForwarding=true

生效命令：

wsl --shutdown
wsl --terminate docker-desktop
# 重启 Docker Desktop

验证：

wsl -d docker-desktop -e free -h
# 应显示 total 约 27-28GB

1.2 清理旧卷（如曾被 5.0 污染）

如果之前误用 cassandra:latest 或 5.0.x 启动过，数据卷可能已被污染，必须删除重建：

docker volume ls
docker volume rm <旧卷ID或名>

---

二、创建容器（带内存限制）

2.1 命令

docker run -d `
  --name cassandra `
  -p 9042:9042 `
  -e MAX_HEAP_SIZE=4G `
  -e HEAP_NEWSIZE=1G `
  -v "D:/Java/docker/cassandra/init:/docker-entrypoint-initdb.d" `
  -v "D:/Java/docker/cassandra/cassandra.yaml:/etc/cassandra/cassandra.yaml" `
  -v "cassandra_data:/var/lib/cassandra" `
  --memory=6g `
  --memory-reservation=2g `
  cassandra:4.0.11

2.2 参数说明

参数	说明
MAX_HEAP_SIZE=4G	JVM 最大堆内存
HEAP_NEWSIZE=1G	JVM 新生代大小
--memory=6g	Docker 硬限制容器总内存 6GB
--memory-reservation=2g	软限制，空闲时允许降到 2GB
cassandra:4.0.11	固定版本标签，禁用 latest

2.3 挂载说明

主机路径	容器路径	作用
D:/Java/docker/cassandra/init	/docker-entrypoint-initdb.d	初始化 CQL 脚本
D:/Java/docker/cassandra/cassandra.yaml	/etc/cassandra/cassandra.yaml	配置文件
cassandra_data (命名卷)	/var/lib/cassandra	数据持久化

⚠️ 注意：如果 cassandra.yaml 曾被 5.0 写入过，4.0 可能读不懂，建议首次启动时先不挂载此文件，确认正常后再挂载。

---

三、启动等待与验证

Cassandra 4.0 首次初始化需要 30 秒 ~ 2 分钟，切勿立即连接。

3.1 查看日志

docker logs --tail 30 -f cassandra

等待出现以下关键字：

Startup complete
Listening for CQL clients on /0.0.0.0:9042
Created default superuser role 'cassandra'

3.2 验证端口

docker ps
# 应显示 0.0.0.0:9042->9042/tcp

---

四、创建业务用户与 Keyspace

4.1 进入 cqlsh

docker exec -it cassandra cqlsh -u cassandra -p cassandra

4.2 创建角色（推荐）

CREATE ROLE IF NOT EXISTS ypironman 
  WITH PASSWORD = 'ypIronman123' 
  AND LOGIN = true 
  AND SUPERUSER = true;

⚠️ Cassandra 4.0 语法要点：

• 必须用 LOGIN = true，否则 LIST USERS 看不到该用户
• SUPERUSER 前用 AND，不是直接写 SUPERUSER;

验证：

LIST USERS;
-- 应显示 cassandra 和 ypironman 两行

4.3 创建项目 Keyspace

CREATE KEYSPACE IF NOT EXISTS ironman 
WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};

GRANT ALL PERMISSIONS ON KEYSPACE ironman TO ypironman;

退出：

exit

---

五、Spring Boot 项目配置

5.1 application.yml

spring:
  data:
    cassandra:
      contact-points: localhost
      port: 9042
      keyspace-name: ironman
      username: ypironman
      password: ypIronman123
      local-datacenter: datacenter1
      schema-action: CREATE_IF_NOT_EXISTS
      request:
        timeout: 10s
      connection:
        connect-timeout: 10s
        init-query-timeout: 10s

5.2 启动顺序

1. 先启动 Cassandra 容器，等待 Startup complete
2. 再启动 Spring Boot 项目
3. 项目首次启动会自动创建 bms_data 等表结构

---

六、常见错误速查

错误	原因	解决
No enum constant org.apache.cassandra.auth.Permission.SELECT_MASKED	数据卷被 Cassandra 5.0 污染	删除旧卷，用 4.0.11 重建
Lost connection to remote peer / ConnectionInitException	Cassandra 还没启动完成	等日志出现 Startup complete 再连
Authentication error: username and/or password are incorrect	用户不存在或密码错误	用 cassandra/cassandra 进 cqlsh 创建用户
Invalid keyspace ironman	Keyspace 未创建	执行 CREATE KEYSPACE ironman ...
LIST USERS 看不到新建用户	创建时没加 LOGIN = true	ALTER ROLE ypironman WITH LOGIN = true;

---

七、内存管理（64GB 机器）

区域	分配	说明
Windows 系统 + IDEA	~12GB	IDEA -Xmx12288m
Ollama 本地模型	~18-20GB	qwen3.5:27b / coder-30b
WSL2 / Docker 总池	28GB	.wslconfig 限制
Cassandra 容器	6GB（JVM 4G）	开发环境足够
Docker 池内余量	~22GB	给 Dify、Redis、RabbitMQ 等

---

八、版本锁定建议

永远不要对 Cassandra 使用 latest 标签。

# 错误 ❌
docker pull cassandra:latest

# 正确 ✅
docker pull cassandra:4.0.11

Cassandra 大版本（4.x → 5.x）数据文件不兼容，一旦误升，回退必须删数据卷重建。

---

适用版本：Cassandra 4.0.11 + Docker Desktop (WSL2) + Spring Boot 2.x