Qdrant Docker Compose 部署指南

使用 Docker Compose 部署向量搜索引擎 Qdrant v1.15.3，覆盖 docker-compose.yml 编写、配置注入（QDRANT__ 环境变量 与 config.yaml 挂载）、健康检查、数据持久化、端口映射与卸载清理

QdrantQdrant向量数据库Docker Compose向量NoSQL2026/10/02

Qdrant Docker Compose 部署指南

目标：使用官方 qdrant/qdrant:v1.15.3 镜像，通过 Docker Compose 在宿主机上一键启动向量相似度检索引擎 Qdrant，配置数据卷持久化、端口映射、健康检查与配置注入，并完成「建集合 → 写向量 → 相似度检索」的端到端业务验证。本文档面向容器化部署场景，所有操作在具备 Docker Compose 的宿主机上执行。

一、适用场景与前提

Compose 方式是 Qdrant 快速上手的首选：免编译、单文件编排、一行启动、随启随停。适合开发环境、内部演示、以及希望将 Qdrant 与业务容器统一编排的生产场景；如需更大的性能控制或深度系统集成，可参考同专栏《Ubuntu 22.04 安装 Qdrant 单节点指南》的二进制 + systemd 方案。

前置条件：

  • 宿主机已安装 Docker Engine 与 Docker Compose 插件（docker compose version 可验证）。
  • 具备 root 或具备 docker 组的用户权限。
  • 端口 6333（HTTP）与 6334（gRPC）未被占用。
  • 至少拥有 2GB+ 可用内存（Qdrant 索引与查询会占用内存）。
docker --version
docker compose version
# 预期输出形如：Docker version 24.x.x，Docker Compose version v2.x

二、Mirror 与目录准备

在宿主机上创建部署目录并规划持久化位置。本指南将数据与配置分别挂载到宿主机 qdrant_storage/ 与 qdrant_config/：

mkdir -p ~/qdrant/{qdrant_storage,qdrant_config}
cd ~/qdrant

目录占位符 ./ 指代 docker-compose.yml 所在目录。请勿把数据目录放在根分区等只读/受限位置。

三、编写 docker-compose.yml

在 ~/qdrant/docker-compose.yml 写入以下内容（缺省即完整可用）：

services:
  qdrant:
    image: qdrant/qdrant:v1.15.3
    container_name: qdrant
    restart: always
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - ./qdrant_storage:/qdrant/storage
      - ./qdrant_config:/qdrant/config
    environment:
      - QDRANT__SERVICE__HTTP_PORT=6333
      - QDRANT__SERVICE__GRPC_PORT=6334
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6333/readyz"]
      interval: 30s
      timeout: 10s
      retries: 5

要点说明：

  • image: qdrant/qdrant:v1.15.3：官方镜像，v1.15.3 与同专栏其他文档版本保持一致。
  • container_name: qdrant：固定容器名，便于 docker exec 进入调试。
  • restart: always：容器异常退出或宿主机重启后自动拉起。
  • ports：将容器的 6333（HTTP REST）与 6334（gRPC）映射到宿主机同名端口。
  • volumes：./qdrant_storage:/qdrant/storage 持久化业务数据；./qdrant_config:/qdrant/config 用于挂载自定义 config.yaml。
  • environment：通过 QDRANT__<SECTION>__<KEY> 形式注入配置项（详见第六节）。
  • healthcheck：容器内用 curl 探测 /readyz，每 30s 一次，连续 5 次失败判定 unhealthy。

四、启动与查看

启动（后台运行）：

docker compose up -d

首次会拉取 qdrant/qdrant:v1.15.3 镜像，视网络情况可能需要一段时间。

查看状态：

docker compose ps
# 预期 qdrant 服务 STATUS 为 healthy（遵从上文 healthcheck）

跟随查看日志：

docker compose logs -f

常用运维命令：

docker compose up -d        # 启动
docker compose ps           # 状态
docker compose logs -f      # 跟随日志
docker compose restart      # 重启
docker compose down         # 停止并移除容器（保留卷）

快速进入容器调试：

docker exec -it qdrant bash

五、健康检查与就绪验证

5.1 /readyz 与 /livez 的区别

Qdrant 提供两个健康端点：

  • /readyz：就绪检查。仅在全部数据分片加载完成、可对外服务时返回 HTTP 200 与文本 all shards are ready；数据仍在恢复/加载时返回 503。适合作为容器 HEALTHCHECK 与流量接入判定。
  • /livez：存活检查。只要进程仍在运行即返回 200，不关心数据是否就绪。适合判断进程是否崩溃，而不作为业务可用性依据。

在生产中两者含义不同：/readyz 更适合做业务就绪门槛，/livez 适合判断进程存活。

5.2 在宿主机校验

curl http://localhost:6333/readyz
# 预期输出：all shards are ready

结合 docker 的 health 状态：

docker inspect --format='{{.State.Health.Status}}' qdrant
# 预期输出：healthy

5.3 关于镜像内 curl 的说明

上文 healthcheck 依赖容器内自带 curl（官方镜像已内置）。若你使用的是不含 curl 的自定义镜像，可选两种做法：

  • 改用 wget：test: ["CMD", "wget", "-q", "-O", "-", "http://localhost:6333/readyz"]。
  • 或移除 healthcheck 段，仅用 /livez 做进程存活判断，就绪情况交给 /readyz 由外部观测。

六、配置注入方式

Compose 中有两种注入 Qdrant 配置的方式，二选一或并用：

6.1 环境变量覆盖（推荐）

Qdrant 支持以 QDRANT__<SECTION>__<KEY> 形式，用环境变量覆盖 config.yaml 中任意点路径。上文 HTTP_PORT/GRPC_PORT 即为 service.http_port/service.grpc_port 的等价覆盖。想在 compose 中限制线程数，可追加：

    environment:
      - QDRANT__STORAGE__PERFORMANCE__MAX_SEARCH_THREADS=2
      - QDRANT__STORAGE__OPTIMIZER_CPU_BUDGET=1

6.2 挂载 config.yaml（完整配置场景）

把完整配置写入 qdrant_config/config.yaml，再让容器以显式 --config-path 启动：

services:
  qdrant:
    image: qdrant/qdrant:v1.15.3
    command: ["qdrant", "--config-path", "/qdrant/config/config.yaml"]
    volumes:
      - ./qdrant_config:/qdrant/config

qdrant_config/config.yaml 示例（节选，仍以 /qdrant/storage 为数据目录）：

log_level: INFO
storage:
  storage_path: /qdrant/storage
service:
  http_port: 6333
  grpc_port: 6334
telemetry_disabled: false

两种方式均可对运行时行为做精准裁剪，生产环境建议用完整 config.yaml 保持配置一致、可审计，简单场景用环境变量更省事。

七、端到端业务验证

对 http://localhost:6333 执行「建集合 → 写向量 → 检索」的完整链路。

7.1 使用 curl（REST）

1）创建集合 demo，128 维向量，余弦距离：

curl -X PUT http://localhost:6333/collections/demo \
  -H "Content-Type: application/json" \
  -d '{"vectors":{"size":128,"distance":"Cosine"}}'
# 预期：{"result":true,"status":"ok","time":...}

2）写入 2 条向量及 payload：

curl -X PUT http://localhost:6333/collections/demo/points \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      {"id": 1, "vector": [1,0,0,0,0,0,0,0,0,0], "payload": {"title":"hello qdrant","category":"c1"}},
      {"id": 2, "vector": [0,1,0,0,0,0,0,0,0,0], "payload": {"title":"world","category":"c2"}}
    ]
  }'
# 预期：{"result":{"operation_id":0,"status":"acknowledged"},"status":"ok",...}

向量维度须为 128（与集合定义一致）；示例为突出方向差异仅列出前 10 维，其余为 0。完整全维度的脚本化写法见下文 Python 演示。

3）查询与 [1,0,...,0] 最相似的向量（命中 id=1）：

curl -X POST http://localhost:6333/collections/demo/points/search \
  -H "Content-Type: application/json" \
  -d '{"vector":[1,0,0,0,0,0,0,0,0,0],"limit":2,"with_payload":true}'

4）查询集合列表：

curl http://localhost:6333/collections
# 预期：{"result":{"collections":[{"name":"demo"}]},"status":"ok"}

7.2 使用 Python 客户端（官方 SDK）

官方维护 qdrant-client Python 包，脚本化更清晰。可用宿主机 Python 或临时容器运行：

docker run --rm --network host \
  python:3 sh -c \
  'pip install -q qdrant-client \
   && python -c "
import os
from qdrant_client import QdrantClient
from qdrant_client.models import VectorParams, Distance, PointStruct
c = QdrantClient(url=\"http://localhost:6333\")
name = \"demo_py\"
if c.collection_exists(name): c.delete_collection(name)
c.create_collection(name, vectors_config=VectorParams(size=128, distance=Distance.COSINE))
vec = [1.0] + [0.0]*127
vec2 = [0.0] + [1.0] + [0.0]*126
c.upsert(name, points=[
    PointStruct(id=1, vector=vec, payload={\"title\":\"hello qdrant\",\"category\":\"c1\"}),
    PointStruct(id=2, vector=vec2, payload={\"title\":\"world\",\"category\":\"c2\"})])
r = c.search(name, query_vector=vec, limit=2, with_payload=True)
print(r[0].id, r[0].score, r[0].payload)
"'

预期 top-1 命中 id=1 score≈1.0（与查询向量一致），id=2 score≈0.0，完全符合余弦相似度预期。

7.3 数据持久化确认

容器停止并删除后数据仍保留在宿主机卷中：

docker compose restart
curl http://localhost:6333/collections
# demo 集合仍在，说明数据由 ./qdrant_storage 持久化

八、卸载 / 清理

docker compose down -v
# -v 连带删除 compose 数据卷（./qdrant_storage 对应目录中的数据）

区别对照：

  • docker compose down：停止并移除容器与网络，保留数据卷，数据可复用（数据其实直接写宿主机目录，卷名差异不影响容量）。
  • docker compose down -v：停止并移除容器后，一并删除 compose 管理的卷及其中的数据。

本指南用绑定挂载（./qdrant_storage），数据落在宿主机目录；down -v 不会删除该目录，down 也不会。如需彻底清除，请手动 rm -rf qdrant_storage。此操作会永久删除全部业务数据，执行前务必确认已备份。

Qdrant Docker Compose 部署指南 - Quzuo