使用Python访问Couchbase集群时遇UnAmbiguousTimeoutException(错误码14)

问题原因 #

出现UnAmbiguousTimeoutException的核心原因是客户端无法与存储目标文档的Couchbase节点建立KV连接，具体可能由以下几点导致：

• Docker端口映射不完整：你的couchbase2容器仅映射了管理端口8091到主机8090，但KV操作依赖的11210/11211端口未暴露，主机无法直接访问该节点的KV服务。
• 集群节点地址解析问题：Couchbase集群会向客户端返回内部节点名称（如couchbase1、couchbase2），但主机无法解析这些Docker内部主机名，导致客户端无法连接到对应节点。
• 未配置外部地址：集群默认返回内部节点地址给客户端，若未设置可被外部主机访问的External Hostname，客户端无法正确路由到集群节点。

调试方法 #

• 验证端口连通性：在主机上使用nc或telnet测试端口是否可达：

  # 测试couchbase1的KV端口
  nc -zv localhost 11210
  # 若已给couchbase2映射KV端口，测试对应端口（比如11212）
  nc -zv localhost 11212
  

• 检查集群节点地址配置：登录Couchbase Web界面（localhost:8091），进入Settings > Network > Hostnames，查看每个节点的External地址是否为主机可访问的地址。
• 开启SDK调试日志：在代码中添加日志配置，查看SDK尝试连接的节点及错误细节：

  import logging
  logging.basicConfig(level=logging.DEBUG)
  from couchbase.logic import logger
  logger.setLevel(logging.DEBUG)
  

• 确认文档存在性：先用SQL++查询验证文档是否存在（排除文档不存在的可能）：

  result = cluster.query("SELECT * FROM `travel-sample` WHERE META().id = 'airline_10'")
  for row in result:
      print(row)
  

解决方案 #

1. 完善Docker Compose端口映射 #

更新couchbase2的端口配置，暴露所有必要端口（避免与couchbase1端口冲突）：

version: "3.7"

services:
  couchbase1:
    image: couchbase:enterprise
    ports:
      - "8091-8096:8091-8096"
      - "11210-11211:11210-11211"
    volumes:
      - ./db-data1:/opt/couchbase/var
  
  couchbase2:
    image: couchbase:enterprise
    ports:
      - "8090:8091"          # 管理端口
      - "8097-8102:8091-8096" # 其他服务端口（与couchbase1不冲突）
      - "11212-11213:11210-11211" # KV端口映射到主机11212-11213
    volumes:
      - ./db-data2:/opt/couchbase/var

volumes:
  db-data1:
  db-data2:

2. 配置集群外部地址 #

登录Couchbase Web界面（localhost:8091）：

• 进入Settings > Network > Hostnames
• 对couchbase1，设置External Hostname为localhost（对应主机直接映射的端口）
• 对couchbase2，设置External Hostname为localhost，并确保其KV端口对应主机的11212
• 保存配置后，集群会向客户端返回可访问的外部地址

3. 调整SDK连接字符串（可选） #

若暂时无法修改集群配置，可在连接时指定所有可访问的节点地址：

cluster = Cluster.connect('couchbase://localhost,localhost:11212',
                          ClusterOptions(PasswordAuthenticator(
                              'Administrator',
                              'some-pw-that-is-better-than-this!'
                          )))

4. 验证Bucket状态 #

确保travel-sample Bucket处于Online状态，可在Web界面的Buckets页面查看，若为离线状态需重新启动Bucket。

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