如何配置Python Couchbase SDK与容器化Couchbase节点的连接

• 3个Couchbase节点分别运行在独立容器中，共同归属同一集群
• Python应用最终将运行在单独容器内，当前为简化调试流程暂在本地运行，负责对Couchbase集群执行数据查询、插入、删除操作

已成功搭建Couchbase集群、创建存储桶，可通过localhost:8091访问Web UI对存储桶执行查询操作。

3节点集群部署完成后，Python应用无法与集群建立连接：无论是通过Docker容器IP的8091端口还是localhost地址都无法访问，连接抛出超时错误；单节点部署时连接完全正常。此前尝试配置setting-alternate-address参数未成功，怀疑配置方式有误。

测试代码 #

connection_string = "couchbase://localhost"
cluster = Cluster.connect(connection_string, ClusterOptions(PasswordAuthenticator(os.getenv("LOGIN"), os.getenv("PASSWORD"))))
# 认证成功后可打开对应存储桶
bucket = cluster.bucket('travel-sample')
coll = bucket.default_collection()
result = coll.get('airline_10')
print(result.content_as[dict])

报错信息 #

couchbase.exceptions.UnAmbiguousTimeoutException: <ec=14, category=couchbase.common, message=unambiguous_timeout, context=KeyValueErrorContext:{'key': 'airline_10', 'bucket_name': 'travel-sample', 'scope_name': '_default', 'collection_name': '_default', 'opaque': 0}, C Source=C:\Jenkins\workspace\python\sdk\python-scripted-build-pipeline\py-client\src\kv_ops.cxx:209>

问题核心原因：Couchbase SDK连接集群的逻辑并非仅使用连接字符串中填写的初始地址完成所有操作。建立初始管理连接后，SDK会从集群侧拉取所有节点的广播地址，后续KV读写、查询等操作会直连对应节点的服务端口（其中KV操作默认使用11210端口，而非8091管理端口）。多节点容器化部署时，节点默认上报的是Docker内部网桥的IP地址，本地运行的Python应用无法路由到该内部地址，就会触发KV操作超时。单节点部署时能正常连接，是因为仅将单节点的相关端口映射到了宿主机，SDK操作单节点地址时可正常连通，多节点场景下其余节点的内部地址不可达、对应服务端口未做映射，自然会连接失败。

按以下步骤操作即可修复：

1. 补全端口映射
   单节点测试时通常只映射了8091管理端口，多节点部署需要将以下Couchbase服务端口都映射到宿主机，每个节点的映射端口要错开避免冲突：
   • 8091：Web UI/REST API管理端口
   • 8092：视图查询、XDCR端口
   • 8093：N1QL查询服务端口
   • 8094：全文搜索服务端口
   • 11210：KV数据操作端口（本次报错为KV操作超时，该端口未映射/不可达是核心诱因）
   • 11207：KV SSL加密端口
2. 正确配置alternate address
   这是容器化部署Couchbase集群对外提供访问的标准配置，此前配置失败基本是因为没有给每个节点单独配置对应的外部访问地址和端口映射关系。配置方法：
   每个节点加入集群后，在对应容器内部执行couchbase-cli命令配置外部访问地址，示例：

   couchbase-cli setting-alternate-address \
     --cluster localhost:8091 \
     --username <集群管理员账号> \
     --password <集群管理员密码> \
     --set \
     --hostname <宿主机对外可访问的IP地址> \
     --port 8091=<当前节点映射到宿主机的外部8091端口> \
     --port 11210=<当前节点映射到宿主机的外部11210端口> \
     --port 8092=<当前节点映射到宿主机的外部8092端口> \
     --port 8093=<当前节点映射到宿主机的外部8093端口>
   

   配置完成后，SDK连接时会自动拉取节点的外部备用地址，直接通过宿主机IP+映射端口访问对应节点，不会再路由到Docker内部不可达的地址。
3. 修正连接字符串
   本地调试时不要仅填写couchbase://localhost，需要将所有节点的外部管理地址（宿主机IP+对应映射的管理端口）都写入连接字符串，避免初始连接时单节点故障导致连接失败，示例：

   # 示例：3个节点映射到宿主机的管理端口分别为8091、8094、8097，宿主机IP为192.168.1.100
   connection_string = "couchbase://192.168.1.100:8091,192.168.1.100:8094,192.168.1.100:8097"
   

4. 临时调试方案（仅用于本地快速验证，禁止生产使用）
   启动Couchbase容器时直接使用host网络模式，不需要做端口映射和alternate address配置即可连通，但同主机部署多节点时会出现端口冲突，仅适合临时功能验证。

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