Docker环境下Cassandra首次启动时Spring Boot连接失败问题排查

• 现有waitForCassandra方法的验证逻辑不够严谨：它只确认了Cassandra的端口连通性或表面服务状态，但Cassandra启动后还需要完成系统表加载、节点状态切换为正常（UN状态）、keyspace初始化等后续内部操作。此时虽然端口能通，但Cassandra并未完全就绪，Spring Boot客户端创建通道时会因服务内部未准备好而失败；重启Spring Boot容器时，Cassandra已经完成所有初始化步骤，因此能正常连接。
• 存在Docker网络DNS解析延迟的可能：第一次启动Spring Boot容器时，容器的DNS缓存尚未同步cassandra服务的别名解析，导致客户端无法正确定位节点；重启容器后DNS缓存更新，解析恢复正常。

方案1：增强验证逻辑，用Cassandra Driver做真实连通性校验 #

放弃仅检查端口的方式，改用Spring Boot依赖的Cassandra Java Driver尝试建立会话、执行查询，确认服务及keyspace完全就绪。示例代码如下：

import com.datastax.oss.driver.api.core.CqlSession;
import com.datastax.oss.driver.api.core.metadata.Node;
import org.springframework.stereotype.Component;

import java.net.InetSocketAddress;
import java.time.Duration;
import java.util.concurrent.TimeUnit;

@Component
public class CassandraHealthChecker {

    public void waitForCassandraReady(String contactPoint, int port, String keyspace, Duration timeout) throws InterruptedException {
        long start = System.currentTimeMillis();
        boolean ready = false;

        while (!ready && System.currentTimeMillis() - start < timeout.toMillis()) {
            try (CqlSession session = CqlSession.builder()
                    .addContactPoint(new InetSocketAddress(contactPoint, port))
                    .withLocalDatacenter("datacenter1")
                    .withKeyspace(keyspace)
                    .build()) {
                // 执行简单查询验证服务连通性
                session.execute("SELECT cluster_name FROM system.local");
                // 检查所有节点是否处于正常状态
                boolean allNodesUp = session.getMetadata().getNodes().values().stream()
                        .allMatch(node -> node.getState() == Node.State.UP);
                if (allNodesUp) {
                    ready = true;
                    System.out.println("Cassandra服务及keyspace已完全就绪");
                }
            } catch (Exception e) {
                System.out.println("Cassandra尚未就绪，2秒后重试...");
                TimeUnit.SECONDS.sleep(2);
            }
        }

        if (!ready) {
            throw new RuntimeException("等待Cassandra超时，服务未就绪");
        }
    }
}

通过CommandLineRunner在应用启动前调用该检查方法：

import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;

import java.time.Duration;

@Component
public class StartupRunner implements CommandLineRunner {

    private final CassandraHealthChecker healthChecker;

    public StartupRunner(CassandraHealthChecker healthChecker) {
        this.healthChecker = healthChecker;
    }

    @Override
    public void run(String... args) throws Exception {
        healthChecker.waitForCassandraReady("cassandra", 9042, "cbusha", Duration.ofSeconds(30));
    }
}

方案2：利用Docker健康检查实现容器依赖 #

在docker-compose.yml中给Cassandra配置健康检查，让Spring Boot容器仅在Cassandra通过健康检查后启动。修改Cassandra的配置：

cassandra:
    image: cassandra:latest
    ports:
      - 9042:9042
    volumes:
      - ./cassandra/image:/var/lib/cassandra
    environment:
      - CASSANDRA_AUTHENTICATOR=AllowAllAuthenticator
      - CASSANDRA_AUTHORIZER=AllowAllAuthorizer
    healthcheck:
      test: ["CMD", "cqlsh", "-e", "SELECT cluster_name FROM system.local"]
      interval: 10s
      timeout: 5s
      retries: 5

然后在Spring Boot容器的配置中添加依赖规则：

spring-app:
    # 你的Spring Boot容器其他配置
    depends_on:
      cassandra:
        condition: service_healthy

这种方式由Docker负责确保Cassandra完全就绪后再启动Spring Boot应用，从根源避免连接问题。

方案3：配置Cassandra客户端自动重试 #

在application.yml中添加客户端重试配置，让客户端初始化时自动重试连接，直到Cassandra就绪：

spring:
  cassandra:
    contact-points: cassandra
    port: 9042
    keyspace-name: cbusha
    local-datacenter: datacenter1
    schema-action: CREATE_IF_NOT_EXISTS
    connect-timeout-millis: 30000
    read-timeout-millis: 30000
    driver-config:
      basic:
        retry-policy:
          class: com.datastax.oss.driver.api.core.retry.DefaultRetryPolicy
          max-retries: 5
      request:
        timeout: 30000

该方案依赖客户端自动重试，可靠性略低于前两种主动等待的方式。

内容的提问来源于stack exchange，提问作者Jackie