couchbase java sdk 成功打开 bucket 却查询超时，通常并非客户端配置错误，而是网络可达性不一致所致：bucket 连接走负载均衡器（如 aws elb），而 n1ql 查询需直连集群节点，若节点端口未对客户端开放，必然触发连接超时。
couchbase java sdk 成功打开 bucket 却查询超时，通常并非客户端配置错误，而是网络可达性不一致所致：bucket 连接走负载均衡器（如 aws elb），而 n1ql 查询需直连集群节点，若节点端口未对客户端开放，必然触发连接超时。
在使用 Couchbase Java SDK 时，日志中出现 Opened bucket bucket-name 表明 Bucket 初始化成功，但后续执行 N1QL 查询（如 bucket.query()）却持续抛出 Operation timed out 异常（目标端口如 11210、18093、8093），这是典型的网络路径不对称问题。
根本原因在于：Couchbase 客户端采用多通道通信模型：
- Key-Value 操作（含 Bucket 打开）默认通过集群入口（如 ELB 或 DNS 名）协商并建立连接，依赖端口 11210（或 TLS 的 11207）；
- N1QL 查询则需客户端直接与集群中一个或多个数据节点通信，默认使用 Query 服务端口 8093（HTTP）或 18093（HTTPS），且客户端会从集群配置中获取真实节点 IP 列表（如 10.10.7.100, 10.10.7.114），绕过负载均衡器直连。
因此，即使 ELB 安全组放行了客户端访问，若后端 Couchbase 节点的安全组（Security Group）未显式允许客户端 IP 访问以下关键端口，查询必然失败：
| 服务类型 | 默认端口 | 协议 | 用途 |
|---|---|---|---|
| Key-Value | 11210 / 11207 | TCP | Bucket 连接、文档读写 |
| Query (N1QL) | 8093 / 18093 | HTTP/HTTPS | SQL++ 查询执行 |
| Management | 8091 / 18091 | HTTP/HTTPS | 集群配置拉取（SDK Doctor 依赖） |
✅ 解决方案步骤：
立即学习“Java免费学习笔记（深入）”；
- 确认客户端所在网络（如 EC2 实例安全组、本地防火墙）已放行上述端口（尤其 8093 和 18093）；
- 检查 Couchbase 集群各节点的安全组规则，确保入站（Inbound）允许来自客户端 IP 段的 TCP:8093、TCP:18093、TCP:11210；
- 若使用私有 DNS（如 cb-dns），确保客户端可解析该域名，且 18091 管理端口可达（SDK Doctor 依赖此端口获取集群拓扑）；
- （可选）强制 SDK 使用 DNS SRV 记录或指定节点列表，避免自动发现不可达节点：
ClusterEnvironment env = ClusterEnvironment.builder() .ioConfig(IoConfig.networkResolution(NetworkResolution.SRV)) .build();
Cluster cluster = Cluster.connect("couchbase://cb-dns", ClusterOptions.clusterOptions("username", "password").environment(env));
⚠️ **重要提醒：** - 不要仅靠延长 `queryTimeout()` 来“解决”超时——这只会掩盖网络问题，无法建立真实连接； - SDK Doctor 报错 `[ERRO] All endpoints specified by your connection string were unreachable` 是明确信号：客户端无法访问任何集群管理端点（`18091`），说明基础网络连通性已中断，应优先排查 DNS 解析与 `18091` 端口可达性； - 在云环境（如 AWS）中，ELB 仅代理部分流量（如 KV），**绝不会代理 Query、Index、Search 等服务端口**，必须确保客户端与所有 Couchbase 节点的对应端口直连。 完成网络策略修正后，重启应用即可恢复正常查询能力——此时日志将显示 `QueryEndpoint` 成功连接，而非反复 `Could not connect to remote socket`。
