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：

ini 复制代码

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

生效命令：

powershell 复制代码

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

验证：

powershell 复制代码

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

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

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

powershell 复制代码

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

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

2.1 命令

powershell 复制代码

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 查看日志

powershell 复制代码

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 验证端口

powershell 复制代码

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

四、创建业务用户与 Keyspace

4.1 进入 cqlsh

powershell 复制代码

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

4.2 创建角色（推荐）

sql 复制代码

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;

验证：

sql 复制代码

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

4.3 创建项目 Keyspace

sql 复制代码

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

GRANT ALL PERMISSIONS ON KEYSPACE ironman TO ypironman;

退出：

sql 复制代码

exit

五、Spring Boot 项目配置

5.1 application.yml

yaml 复制代码

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 启动顺序

先启动 Cassandra 容器，等待 Startup complete
再启动 Spring Boot 项目
项目首次启动会自动创建 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 标签。

powershell 复制代码

# 错误 ❌
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