Node.js 应用连接 Cassandra 时，socket timeout 的场景比想象中更复杂：它可能发生在 TCP 三次握手阶段，也可能发生在 CQL 请求发送后等待结果帧的阶段。二者虽然最终都表现为异常堆栈里的 timeout 字样，但修复方向和参数位置完全不同。如果直接把所有超时一味调大，往往只是延长故障恢复时间，并不能消除根因。

socket timeout 不是单一错误：先分清连接超时和读取超时

在 DataStax Node.js 驱动中，socketOptions 下最常接触的两个参数是 connectTimeout 和 readTimeout。connectTimeout 控制客户端与 Cassandra 节点建立 TCP 连接时最多等待多久，一旦超过这个时间还没有完成三次握手，驱动会直接抛出连接超时。这个阶段通常在应用首次连接节点、节点重启后连接重建，或者节点 IP 不可达时触发。需要注意的是，connectTimeout 再长，也不能解决节点本身不监听 9042 端口的问题，它只是避免客户端无限挂起。

readTimeout 则发生在连接建立之后：客户端发送 CQL 请求后，会等待服务端返回 RESULT 帧。如果 Cassandra 节点在 readTimeout 毫秒内没有返回任何字节，Node.js 驱动会认为这次读取超时，并关闭或标记该连接。读超时的原因可能是查询本身太慢、节点 GC 停顿、网络丢包，也可能是连接池中排队时间太长导致请求还没真正发送到服务端。因此排查时不能只看超时这两个字，需要从堆栈或日志里确认是连接阶段还是读取阶段。

从报错形式上看，连接超时通常伴随 connect timed out 或 Socket was closed，而读取超时更多表现为 Operation timed out 或消息中包含 read timeout。把这两个阶段区分清楚，后续调整参数才不会盲目。

Node.js 驱动中必须对齐的超时配置和连接池参数

先用一段最小化配置说明参数结构。下面示例基于 cassandra-driver 包，展示了 socketOptions、pooling 和 protocolOptions 的基础设置。

const cassandra = require('cassandra-driver');
const client = new cassandra.Client({
  contactPoints: ['127.0.0.1'],
  localDataCenter: 'datacenter1',
  keyspace: 'app',
  socketOptions: {
    connectTimeout: 10000,
    readTimeout: 20000,
    keepAlive: true,
    keepAliveDelay: 30000
  },
  pooling: {
    coreConnectionsPerHost: {
      '0': 2,
      '1': 1
    },
    maxConnectionsPerHost: {
      '0': 4,
      '1': 2
    }
  }
});

这里的 readTimeout 设置成了 20 秒，但如果你的查询有部分可能超过 20 秒，这个值就偏小。一般建议 readTimeout 略大于单次查询的最大可接受耗时，而不是无限放大。驱动还有 per-query 超时，可以在 execute 的第三个参数里覆盖默认值，适合对慢查询单独控制。

连接池的作用很容易被忽略。Cassandra 驱动会为每个节点维护多条连接，默认情况下按距离决定核心连接数。如果 maxConnectionsPerHost 过小，高并发下请求会在客户端侧排队，等真正发送到服务端时可能已经超过了 readTimeout。此时日志里即使出现 socket timeout，服务端也不一定有慢查询。调大连接池之前，先确认节点能够承受更多连接；如果客户端连接数已经占满，报错会向 NoHostAvailableError 方向发展。

另一个关键点是 keepAlive。跨机房或经过 NAT 设备时，空闲 TCP 连接容易被中间设备断开，下次请求会突然遇到 ECONNRESET 或 socket hang up。启用 keepAlive 并设置 keepAliveDelay 能显著减少这类伪超时。

从 Cassandra 服务端和网络层定位超时根因

客户端报 socket timeout 后，第一件事不是改参数，而是确认服务端到底有没有收到请求以及执行了多久。Cassandra 提供了 nodetool tpstats，可以查看各个线程池的阻塞和延迟情况。如果 Native-Transport-Requests 存在大量 Pending 或 Blocked，说明节点入口线程已经饱和，客户端请求会排队，自然容易触发读超时。

nodetool tpstats > /tmp/tpstats.log
nodetool proxyhistograms
nodetool cfstats | grep -E "Read latency|Local read latency"

上面的命令中，proxyhistograms 能显示读写延迟分布，帮助判断慢查询是全局现象还是个别表导致。如果某个表的 Local read latency 远高于其他表，就该继续查看该表的查询语句是否缺少分区键过滤、是否触发了 ALLOW FILTERING，或者数据模型出现超大分区。

网络层排查也不可省略。用 ping 看丢包率，用 telnet 127.0.0.1 9042 看端口连通性，还可以在客户端节点执行 netstat -an | grep 9042 观察 TIME_WAIT 是否过多。过多 TIME_WAIT 通常是连接频繁重建导致，可能是连接池参数不合理或服务端主动断开。抓包能进一步确认是客户端提前断开了 TCP 连接，还是服务端一直没有返回数据。

还有一类隐藏原因是 DNS 解析变慢。Node.js 驱动默认会解析 contactPoints 对应的主机名，如果 DNS 服务器抖动，连接建立阶段就会消耗大量时间，最终表现为 connectTimeout。生产环境建议将 contactPoints 配置为静态 IP，或者确保 DNS 缓存策略合理。

生产实践：调整超时、改造查询与增加容错

定位到具体原因后，可以按优先级做几件事。如果是查询本身慢，应该优先优化 CQL，而不是不断调大超时。例如给范围查询加上 LIMIT，使用 TOKEN 分页遍历大表，避免没有分区键的过滤条件。下面是一个基于主键分页读取的示例，避免一次拉取过多数据导致读超时。

async function loadUsersInBatches(client) {
  const pageSize = 1000;
  let pageState = null;
  do {
    const options = {
      prepare: true,
      fetchSize: pageSize,
      readTimeout: 15000
    };
    if (pageState) {
      options.pageState = pageState;
    }
    const result = await client.execute(
      'SELECT id, email FROM users WHERE tenant_id = ?',
      ['tenant-01'],
      options
    );
    for (const row of result.rows) {
      // 逐批处理
      await processUser(row);
    }
    pageState = result.pageState;
  } while (pageState);
}

上面的代码通过 fetchSize 控制每次从 Cassandra 拉取的行数，并通过 pageState 继续下一页，避免单次查询积压过多数据。对写路径来说，如果写入超时，可以检查客户端批次是否过大，拆分为更小的 batch 或异步写入。

同时，客户端要增加快速失败和重试机制。socket timeout 很多时候是瞬时抖动，可以在捕获异常后做有限次重试，但要避免对非幂等写入盲目重试。示例中通过 isSocketTimeout 做识别，并用指数退避控制重试间隔。

async function executeWithRetry(client, query, params, retries = 2) {
  for (let attempt = 0; attempt <= retries; attempt++) {
    try {
      return await client.execute(query, params, { prepare: true, readTimeout: 8000 });
    } catch (err) {
      const isTimeout = /socket timeout|read timeout|Operation timed out/i.test(err.message);
      if (!isTimeout || attempt === retries) {
        throw err;
      }
      const delay = 200 * Math.pow(2, attempt);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

最后是熔断与降级。当 Cassandra 持续出现 socket timeout 时，不要让 Node.js 进程无限堆积等待，可以为 Cassandra 访问封装一层熔断器，在失败率超过阈值后短暂拒绝请求，给集群恢复时间。也可以对非核心查询启用本地缓存，减少实时访问压力。这样即便底层的连接或读超时没有完全消除，整体服务仍然能保持可用。