Qdrant 部署形态

Qdrant 是 Rust 实现的向量数据库，提供单二进制与容器两种分发方式，默认 REST 端口 6333、gRPC 端口 6334。容器方式一条命令即可跑起来，关键是把 /qdrant/storage 挂载到宿主机，否则容器重建时数据一并消失。基础运维围绕三件事：健康检查、集合列表确认服务可用、API Key 控制谁能访问。

基本信息

典型使用场景

• 本地开发起一套实例：单容器加数据卷，几分钟内可跑通写入与检索
• 迁移到生产：把数据卷换成持久化存储，并给 API Key 与端口暴露范围做限制
• 版本升级演练：先备份数据卷或快照，再替换镜像标签，避免跨版本无法回退
• 排查连接超时：确认客户端走的是 REST 还是 gRPC，端口是否只放行了一个
• 容量观察：确认数据卷所在盘的剩余空间，向量与 payload 都写在这一个目录

Docker 启动（含持久化）

docker run -d --name qdrant \
  -p 6333:6333 -p 6334:6334 \
  -e QDRANT__SERVICE__API_KEY=change-me \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  qdrant/qdrant:latest
# 只给本机应用使用时改为 -p 127.0.0.1:6333:6333，避免直接暴露公网

健康检查与列表

curl http://localhost:6333/healthz          # 服务存活
curl -H 'api-key: change-me' http://localhost:6333/collections   # 集合列表
curl -H 'api-key: change-me' http://localhost:6333/collections/kb # 单个集合详情

端口与目录速查

上线前检查清单

• 数据卷是否落在持久化盘，并已确认剩余空间与备份策略
• 版本标签是否固定，回退路径是否演练过
• API Key 是否启用，端口是否只对可信网段或本机开放
• 健康检查接入监控，容器异常退出能触发告警
• 写入与检索各跑一条冒烟用例，确认鉴权头传递正确