Qdrant Docker 部署教程：数据卷、API Key 和集合初始化

本文记录一套 Qdrant Docker Compose 部署方式，适合内网知识库、RAG 检索、语义搜索和 AI 助手召回层。

环境说明

• Qdrant 镜像：qdrant/qdrant
• REST 端口：6333
• gRPC 端口：6334
• 数据目录：/qdrant/storage
• 部署方式：Docker Compose
• 安全配置：API Key + 本机端口绑定 + 反向代理

1. 预检镜像

docker pull docker.1ms.run/qdrant/qdrant:latest

如果这里卡住，先处理 Docker 镜像拉取问题，再继续配置 collection 和 API Key。

2. 准备 .env

QDRANT_API_KEY=change-this-write-key
QDRANT_READ_ONLY_API_KEY=change-this-read-key

写入 Key 和只读 Key 分开，后续给检索服务用只读 Key，给数据导入任务用写入 Key。

3. 编写 compose.yaml

services:
  qdrant:
    image: docker.1ms.run/qdrant/qdrant:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:6333:6333"
      - "127.0.0.1:6334:6334"
    environment:
      QDRANT__SERVICE__API_KEY: ${QDRANT_API_KEY}
      QDRANT__SERVICE__READ_ONLY_API_KEY: ${QDRANT_READ_ONLY_API_KEY}
    volumes:
      - qdrant_storage:/qdrant/storage

volumes:
  qdrant_storage:

启动：

docker compose pull
docker compose up -d
docker compose ps
docker compose logs -f qdrant

4. 验证服务

curl -H "api-key: $QDRANT_API_KEY" http://127.0.0.1:6333/collections

如果没有带 api-key，开启 API Key 后请求会失败。这个现象可以用来验证鉴权是否生效。

5. 初始化 collection

下面创建一个名为 internal_docs 的 collection，向量维度示例为 1024：

curl -X PUT "http://127.0.0.1:6333/collections/internal_docs" \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": {
      "size": 1024,
      "distance": "Cosine"
    }
  }'

注意：size 要和 embedding 模型输出维度一致。不同 embedding 模型的维度不一定相同，不能随意照抄。

6. payload 字段设计

内网知识库不要只写入向量。建议同时保存这些 metadata：

{
  "doc_id": "runbook-2026-06",
  "source": "ops-docs",
  "title": "Docker 数据卷挂载路径说明",
  "chunk_index": 12,
  "updated_at": "2026-06-08",
  "permission_group": "ops"
}

后续做权限过滤、来源引用、过期文档清理和业务分组时，这些字段会直接影响检索质量。

7. 反向代理方向

Qdrant 容器端口建议先绑定本机，由反向代理统一处理 HTTPS、鉴权和访问日志：

location / {
    proxy_pass http://127.0.0.1:6333;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;
}

8. 快照备份

创建 collection 快照：

curl -X POST "http://127.0.0.1:6333/collections/internal_docs/snapshots" \
  -H "api-key: $QDRANT_API_KEY"

查看快照：

curl -H "api-key: $QDRANT_API_KEY" \
  "http://127.0.0.1:6333/collections/internal_docs/snapshots"

备份数据卷：

docker run --rm \
  -v qdrant_storage:/data \
  -v "$PWD":/backup \
  docker.1ms.run/alpine:3.20 \
  tar czf /backup/qdrant-storage.tgz -C /data .

常见问题

Qdrant 是不是模型服务

不是。Qdrant 是向量数据库，负责相似度检索和 payload 过滤，不负责生成回答。

6333 和 6334 都要暴露吗

不一定。REST 常用 6333，gRPC 是 6334。如果业务只用 REST，可以先只开放需要的入口。

collection 维度写错怎么办

向量维度要和 embedding 模型一致。写错后通常需要重建 collection 或重新导入数据。

只备份数据卷够不够

数据卷备份是底层兜底，collection 快照更适合按集合恢复。团队环境建议两者都留记录。