Qdrant 的两张门
Qdrant 对外开两个接入面：REST 在 6333，gRPC 在 6334。官方 Python/Go/Rust/Java SDK 默认走 gRPC，批量 upsert 与向量检索复用 HTTP/2 多路复用，报文更小、吞吐更高。两个端口读写的是同一份 collection 数据，鉴权与来源限制必须一起做，只加固其中一个等于没加固。
基本信息
| 服务 | Qdrant（gRPC 接口） |
|---|---|
| 协议 | HTTP/2 + gRPC（可配 TLS） |
| 默认端口 | 6334（REST 为 6333） |
| 鉴权 | api-key 头，gRPC 侧同名为 metadata |
| 暴露面 | 仅应用网段，勿映射公网 |
典型使用场景
- SDK 批量写入：百万级向量入库用 gRPC 分片 upsert，避免 REST 逐条往返
- RAG 检索链路：应用侧查询走 6334，高并发下 P99 更稳
- 从 REST 迁移到 gRPC：只换端口不动业务语义，先确认中间链路是否放通 HTTP/2
- 容器与 K8s：Service 把 6334 暴露给业务 Pod，6333 留给运维与调试
- 发布前连通性验证：用 grpcurl 枚举服务，确认网关没有截断 HTTP/2
连通性验证
连通性验证
grpcurl -plaintext qdrant01:6334 list # 枚举 gRPC 服务
nc -zv qdrant01 6334 # 只看 TCP 是否可达
ss -lntp | grep -E '633[34]' # 本机监听核对
# K8s 临时调试: kubectl -n vec port-forward svc/qdrant 6334:6334排障与核对
| 检查项 | 做法 | 异常表现 |
|---|---|---|
| 监听与协议 | ss -lntp | grep 6334 | 只有 6333 在听：SDK 整批连不上 |
| 鉴权覆盖 | 不带 api-key 直连 6334 | 能写入说明鉴权只做在了 REST 上 |
| 网关透传 | 经反代 grpcurl 枚举服务 | 报 HTTP/2 不支持：缺 grpc_pass 或 h2c |
| 版本匹配 | server 版本与 SDK 版本对照 | 大版本不匹配时 proto 不兼容，报字段错误 |
Qdrant 单机与分布式节点都用 6334 这个默认值；分布式部署还会用到内部 gRPC 通信口（Qdrant 默认 6335），做网络策略时不要只放通 6334。用 Nginx 反代时 REST 走 proxy_pass，gRPC 必须走 grpc_pass 并开启 HTTP/2。
给 6333 加了鉴权却漏掉 6334，写权限仍然敞着：两个端口要么共用同一套认证与来源限制，要么就把 6334 限制在应用网段内。
REST 与 gRPC 怎么选
REST 调试直观，curl 就能试，适合一次性查询与排障；gRPC 的优势在批量场景：单连接多路复用、protobuf 报文更小、并发写入不必自己拼批次。生产里常见的分工是业务服务走 6334、运维巡检走 6333，两条路径共用同一套 api-key 与来源限制策略。
用负载均衡承接 6334 时注意 gRPC 的连接级分发问题：HTTP/2 长连接下按连接轮询会把流量压在少数后端，需要支持 HTTP/2 的负载均衡或客户端侧负载均衡，否则扩容后热点依旧。