使用Python SDK无法连接Couchbase集群，求助问题排查

问题场景 #

• 可通过cURL命令正常访问Couchbase集群：

  curl -u $CB_USERNAME:$CB_PASSWORD  http://$CB_HOST/pools/default/buckets
  

• 使用Python SDK连接时触发UnAmbiguousTimeoutException，代码如下：

  from datetime import timedelta
  from couchbase.auth import PasswordAuthenticator
  from couchbase.cluster import Cluster
  from couchbase.options import ClusterOptions
  import os
  
  # Configuration
  CB_HOST = os.environ.get('CB_HOST')
  CB_BUCKET = os.environ.get('CB_BUCKET')
  CB_USERNAME = os.environ.get('CB_USERNAME')
  CB_PASSWORD = os.environ.get('CB_PASSWORD')
  
  # Initialize Couchbase connection
  auth = PasswordAuthenticator(CB_USERNAME, CB_PASSWORD)
  options = ClusterOptions(auth)
  cluster = Cluster(f'couchbase://{CB_HOST}', options)
  

• 完整报错信息：

  Traceback (most recent call last):
    File "/Users/luc/code/couchbase/examples/main.py", line 27, in <module>
      cluster = Cluster(f'couchbase://{CB_HOST}', options)
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    File "/Users/luc/code/couchbase/examples/venv/lib/python3.11/site-packages/couchbase/cluster.py", line 99, in __init__
      self._connect()
    File "/Users/luc/code/couchbase/examples/venv/lib/python3.11/site-packages/couchbase/logic/wrappers.py", line 98, in wrapped_fn
      raise e
    File "/Users/luc/code/couchbase/examples/venv/lib/python3.11/site-packages/couchbase/logic/wrappers.py", line 82, in wrapped_fn
      ret = fn(self, *args, **kwargs)
            ^^^^^^^^^^^^^^^^^^^^^^^^^
    File "/Users/luc/code/couchbase/examples/venv/lib/python3.11/site-packages/couchbase/cluster.py", line 105, in _connect
      raise ErrorMapper.build_exception(ret)
  couchbase.exceptions.UnAmbiguousTimeoutException: UnAmbiguousTimeoutException(<ec=14, category=couchbase.common, message=unambiguous_timeout (14), C Source=/Users/couchbase/jenkins/workspace/python/sdk/python-packaging-pipeline/py-client/src/connection.cxx:199>)
  

排查与解决方法 #

• 端口差异导致拦截：
  cURL用的是HTTP管理端口（默认8091），Python SDK使用的是Couchbase原生协议端口（默认11210，启用TLS则为11207）。需确认集群的这些原生端口是否在本地防火墙、集群安全组中开放。
• 协议与TLS配置不匹配：
  如果集群启用了TLS加密，连接字符串需改为couchbases://{CB_HOST}，并显式开启TLS选项：

  from couchbase.options import ClusterOptions, ClusterTimeoutOptions
  
  # 延长连接超时时间
  timeout_opts = ClusterTimeoutOptions(connect_timeout=timedelta(seconds=10))
  # 启用TLS并配置超时
  options = ClusterOptions(
      PasswordAuthenticator(CB_USERNAME, CB_PASSWORD),
      timeout_options=timeout_opts,
      enable_tls=True
  )
  cluster = Cluster(f'couchbases://{CB_HOST}', options)
  

• 默认超时时间过短：
  显式设置更长的连接超时时间（如上述代码中的10秒），避免因网络延迟导致超时。
• 主机名解析问题：
  尝试将CB_HOST替换为集群节点的IP地址，排除DNS解析失败的可能。
• 集群节点列表不完整：
  如果是多节点集群，连接字符串建议列出所有节点（如couchbase://node1,node2,node3），SDK会自动选择可用节点建立连接。

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