Node.js使用SDK连接Couchbase报unambiguous_timeout错误如何解决

问题复现 #

使用如下代码尝试连接Couchbase云数据库时，抛出超时错误：

var couchbase = require('couchbase')

async function main() {
  const clusterConnStr = "cb.zbextwxyrtpxpht.cloud.couchbase.com"
  const username = 'couchbase-admin'
  const password = 'Password1234$$'
  const bucketName = 'travel-sample'

  console.log("Connecting to couchbase");

  const cluster = await couchbase.connect(clusterConnStr, {
    username: username,
    password: password,
    timeouts: {
      kvTimeout: 10000, // milliseconds
    },
  })
}

// Run the main function
main()
  .catch((err) => {
    console.log('ERR:', err)
    process.exit(1)
  })
  .then(process.exit)

运行后返回错误：

ERR: [Error: unambiguous_timeout] { code: 14 }

故障原因及解决方法 #

按出现概率从高到低排序：

• 连接字符串缺少加密协议前缀
  这是该场景下最高发的问题。Couchbase云实例强制要求TLS加密连接，必须在连接字符串前加couchbases://前缀（注意末尾带s，对应加密协议）。当前代码使用裸域名作为连接地址，SDK会默认访问非加密的11210端口，云实例不开放该端口，所有连接请求会被直接丢弃触发超时。
  修复方式：将连接字符串修改为

  const clusterConnStr = "couchbases://cb.zbextwxyrtpxpht.cloud.couchbase.com"
  

• 访问IP未加入实例白名单
  Couchbase云实例默认开启网络访问控制，所有不在白名单内的IP发起的请求都会被拦截丢弃，表现为连接超时。
  修复方式：登录Couchbase云控制台，进入对应实例的安全配置页，将运行代码环境的公网IP添加到IP访问白名单中。本地调试阶段可临时添加0.0.0.0/0放行所有IP测试连通性，生产环境禁止该配置，避免安全风险。
• 连接超时配置过短
  当前代码仅配置了KV操作超时kvTimeout，首次连接时的TLS握手、集群信息拉取、身份认证流程走独立的connectTimeout配置，默认值较短，公网网络波动时很容易触发超时。
  修复方式：在连接配置的timeouts字段中补充连接超时配置，建议设置为20000毫秒（20秒）：

  timeouts: {
    connectTimeout: 20000,
    kvTimeout: 10000,
  }
  

• 本地网络端口拦截
  Couchbase加密连接需要使用11207（KV服务）、18091（管理服务）端口，如果当前运行环境处于公司内网、开启了本地防火墙/网络代理，可能会拦截上述端口的出方向请求，导致连接失败。
  修复方式：联系网络管理员放通对应端口的出方向访问权限，本地测试可临时关闭防火墙验证连通性。

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