Qdrant 生产环境手册

覆盖：部署 → 配置 → 安全 → 调优 → 备份 → 监控 → 升级 → 故障排查

基线版本：Qdrant 1.19.x（2026-09 稳定版 1.19.1）｜客户端：qdrant-client 1.19.x

开发用法另见 Qdrant开发使用指南.md，配套配置与脚本在 deploy/ 和 ops/

第 0 章 三条版本红线（升级前必读）

Qdrant 的升级路径不是线性的，踩中这几条会直接起不来或数据读不出。

版本选择建议：新部署直接用最新稳定版；已有部署跟随官方节奏一个一个升，不要跨版本。

检查当前版本：

curl -s http://127.0.0.1:6333/ | jq -r '.version'

第 1 章 部署形态怎么选

给你的建议（结合你现有的 Intel MacBook 16GB + 国内 Linux 服务器）：

• 本地开发：用官方 macOS 单二进制。不要为了跑 Qdrant 装 Docker Desktop——那东西本身就是你机器发热的主因之一。

```bash

curl -L https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-apple-darwin.tar.gz | tar -xz

./qdrant # REST 6333，Web UI: http://127.0.0.1:6333/dashboard

```

• 生产服务器：内存 ≤ 4GB 用 systemd 二进制；≥ 8GB 且已经有 Docker 运维习惯就用 Compose。

一个常见的错误认知：qdrant-client 的 --local 嵌入式模式（QdrantClient(path=...)）不是生产方案。它是纯 Python + SQLite 实现，官方明确不推荐用于生产或压测，且数据格式与 server 版不兼容——./qdrant_local 目录搬不到生产服务器上。它只适合本地验证和评测。生产必须走 server 模式，数据用脚本重新导入（点 ID 幂等的话重导不会产生重复）。

第 2 章 单机生产部署

2.1 系统准备（Linux）

# 1) 文件描述符：Qdrant 是 mmap 重度用户，默认 1024 会在高负载下莫名报错
sudo tee /etc/security/limits.d/qdrant.conf <<'EOF'
qdrant soft nofile 65536
qdrant hard nofile 65536
EOF

# 2) 磁盘：向量检索是随机读密集，机械盘性能差一个数量级，能上 NVMe 就上
#    数据目录和快照目录必须分开挂载 —— 同一块盘，盘挂了数据和备份一起没

# 3) 关闭透明大页（THP）—— 会让 mmap 访问出现不可预测的延迟毛刺
echo never | sudo tee /sys/kernel/mm/transparent_hugepage/enabled

# 4) 时间同步（快照/日志时间戳要能对上）
sudo timedatectl set-ntp true

2.2 目录规划（照抄即可）

/opt/qdrant/qdrant                 # 二进制
/etc/qdrant/config.yaml            # 配置
/etc/qdrant/qdrant.env             # 密钥（权限 600）
/var/lib/qdrant/storage/           # 数据（★ 独立盘）
/var/lib/qdrant/snapshots/         # 快照（★ 另一块盘或远端）
/var/lib/qdrant/temp/              # 临时文件
/var/log/qdrant/                   # 日志（用 systemd 时在 journald）

2.3 首次启动自检（四步，缺一不可）

# ① 服务活着吗
curl -s http://127.0.0.1:6333/healthz          # 期望: healthz check passed

# ② 就绪了吗（能服务请求）
curl -s http://127.0.0.1:6333/readyz           # 期望: readyz check passed

# ③ 认证生效了吗（没配 key 时这步会返回 200，说明在裸奔）
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:6333/collections
# 期望 401；返回 200 = api_key 没生效，立刻回去查配置

# ④ 写入→检索→删除 全链路通不通
curl -s -X PUT http://127.0.0.1:6333/collections/_smoke \
  -H "api-key: $QDRANT_API_KEY" -H 'Content-Type: application/json' \
  -d '{"vectors":{"size":4,"distance":"Cosine"}}'
curl -s -X PUT "http://127.0.0.1:6333/collections/_smoke/points?wait=true" \
  -H "api-key: $QDRANT_API_KEY" -H 'Content-Type: application/json' \
  -d '{"points":[{"id":1,"vector":[0.1,0.2,0.3,0.4],"payload":{"t":"ok"}}]}'
curl -s -X POST "http://127.0.0.1:6333/collections/_smoke/points/query" \
  -H "api-key: $QDRANT_API_KEY" -H 'Content-Type: application/json' \
  -d '{"query":[0.1,0.2,0.3,0.4],"limit":1}'
curl -s -X DELETE http://127.0.0.1:6333/collections/_smoke -H "api-key: $QDRANT_API_KEY"

2.4 Docker 部署

直接看 deploy/docker-compose.yml（已含密钥注入、内存上限、健康检查、日志轮转）。配 .env：

QDRANT_API_KEY=$(openssl rand -hex 32)     # 写进 .env，别进 git
QDRANT_READ_ONLY_KEY=$(openssl rand -hex 32)
QDRANT_MEM_LIMIT=4g

第 3 章 配置详解（生产必改的 8 项）

完整模板见 deploy/production.yaml，这里只讲改了会出事的那些。

3.1 覆盖优先级（先搞清这个，否则改了不生效）

内置默认值  <  config.yaml  <  环境变量 QDRANT__XXX__YYY  <  命令行参数

例：QDRANT__SERVICE__API_KEY=abc 等价于 service.api_key: abc，且优先级更高。所以密钥用环境变量注入，配置文件进 git 也不会泄密。

3.2 必改项清单

3.3 容易误解的三个参数

on_disk_payload — 设 true 时 payload 索引仍在内存。也就是说它省的是"存原文"的内存，不是索引的内存。所以字段越多、索引越多，省得越少。别指望它解决所有内存问题。

indexing_threshold_kb — 未索引数据累计到这个量才触发建 HNSW 索引。批量导入期间临时调大（如 1000000）能显著加快导入（避免边导边反复重建索引），导完必须调回（比如 20000）并等待优化器跑完，否则检索会一直扫未索引段——这是"导入后检索变慢"最常见的原因。

default_segment_number — 段数约等于可并行搜索的粒度。核多调大能提吞吐，但段越多小文件越多、内存与合并压力越大。2~4 核的机器保持 2，8 核以上可以试 4。不要设成核数那么多。

3.4 量化：内存不够的第一选择

PATCH /collections/{name}
{
  "quantization_config": {
    "scalar": { "type": "int8", "quantile": 0.99, "always_ram": true }
  }
}

关掉量化：把 quantization_config 设为 null 即可，不需要重建集合。

先量化，再考虑加机器。int8 省 75% 内存且不用重新嵌入；加机器要迁移数据、改架构、多一份运维。

第 4 章 安全加固

三层都要做，缺一层就等于没做。

4.1 网络层（最有效的一层）

# 裸机：绑回环，绝不 0.0.0.0
#   config.yaml → service.host: 127.0.0.1
#   systemd 单元里 Environment="QDRANT__SERVICE__HOST=127.0.0.1"

# 防火墙：只放行应用服务器
sudo ufw allow from 10.0.0.0/24 to any port 6333 proto tcp
sudo ufw allow from 10.0.0.0/24 to any port 6334 proto tcp
sudo ufw enable

Docker 的坑：-p 6333:6333 会绕过 ufw（Docker 直接写 iptables），必须写成 -p 127.0.0.1:6333:6333 或 -p 10.0.0.5:6333:6333。这是最常见的"我明明配了防火墙却被扫到"的原因。

4.2 认证层

# 生成两个密钥
openssl rand -hex 32     # 读写 key
openssl rand -hex 32     # 只读 key（给监控/报表）

轮换流程（不停机）：

# 1. 服务端同时配置新旧两个 key 的能力有限，标准做法是「改配置 + 重启」
NEW=$(openssl rand -hex 32)
sudo sed -i "s#^(\s*QDRANT__SERVICE__API_KEY=).*#\1$NEW#" /etc/qdrant/qdrant.env
sudo systemctl restart qdrant                      # 重启约数秒

# 2. 验证：旧 key 401，新 key 200
curl -s -o /dev/null -w 'old:%{http_code}\n' -H "api-key: $OLD" http://127.0.0.1:6333/collections
curl -s -o /dev/null -w 'new:%{http_code}\n' -H "api-key: $NEW" http://127.0.0.1:6333/collections

# 3. 逐个改应用侧配置（.env / 密钥管理服务）

更平滑的方案：在反向代理层注入密钥（客户端不感知），轮换时只改代理配置。

4.3 传输层（TLS）

开了 api_key 不开 TLS = 明文传输密钥，等于没设。三个选择：

1. 最省事：Qdrant 只绑 127.0.0.1，走 SSH 隧道或同机应用直连，不对外暴露端口；
2. 标准做法：前面挂 Nginx/Caddy 处理 TLS，Qdrant 只听内网；
3. Qdrant 原生 enable_tls: true + 证书（集群内部通信也记得开 cluster.p2p.enable_tls）。

# Nginx 反代要点（8000 → 6333）
location / {
    proxy_pass http://127.0.0.1:6333;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    client_max_body_size 128m;        # 大 batch upsert 会被 413 拦掉
    proxy_read_timeout 300s;          # 快照/大规模导入耗时长
    proxy_buffering off;              # 虽 Qdrant 主要是短请求，但保持关闭更稳
}

4.4 进程权限与审计

• 容器非 root：用 qdrant/qdrant:v1.19.1-unprivileged，或 --user=1000:2000（数据目录需 chown 1000:2000）；
• 审计日志（1.17+）：写本地文件 <storage_path>/audit/，不写 stdout。容器部署要挂卷 + sidecar 收集，否则重启即丢；
• /metrics 也要鉴权：开了 api_key 后抓取要带 key，Prometheus 用 authorization.credentials（填只读 key）。

4.5 安全自查清单（上线前逐条打勾）

[ ] api_key 已设，且不是 "changeme"/"123456" 这类弱值
[ ] curl 无 key 访问 /collections 返回 401
[ ] 6333/6334 未对公网开放（从外部机器 telnet 测试一下）
[ ] Docker 端口绑定写了 127.0.0.1 或内网 IP，不是 0.0.0.0
[ ] read_only_api_key 给监控用，应用不共用同一个 key
[ ] 容器以非 root 运行
[ ] 快照目录与应用数据目录不在同一块盘
[ ] 密钥不在 git 里（git log -S "api_key" 查一遍）

第 5 章 容量规划与调优

5.1 内存账簿（先算清账，再决定买什么）

Qdrant 的内存由四块组成：

算一遍你的场景（500 万 × 1024 维，bge-m3 同源 dense+sparse）：

结论：16GB 内存的机器，500 万块 1024 维必须开 int8 量化。这不是优化选项，是前置条件。

5.2 内存不够时的处理顺序（别跳步）

① 开 int8 量化            ← 省 75%，不动数据，不改架构
② on_disk_payload: true   ← 省 payload 原文
③ 减少 payload 索引字段   ← 每个 keyword 索引都常驻内存
④ 1.19 三级内存策略：把冷集合设 cold 层
⑤ 减到单集合 + 提高分片/上 Milvus ← 真到亿级再考虑

5.3 HNSW 参数怎么调

调优顺序：先确认过滤字段都有索引 → 再调查询 ef → 再考虑改 m 重建。

full_scan_threshold_kb：段小于此阈值直接暴力扫（更准）。小库上它意味着"根本没走 HNSW"，这也是为什么你 35 块的小库延迟只有十几毫秒。

5.4 写入性能

# 推荐批量：100~1000 点/批；再大收益递减而内存峰值上升
client.upsert(collection_name=..., points=batch, wait=False)   # 导入期用 False，吞吐翻倍
client.upsert(collection_name=..., points=last_batch, wait=True)  # 最后一批用 True，确保落盘

导入完成后必做：

# 把索引阈值调回正常值并触发优化器
curl -X PATCH http://127.0.0.1:6333/collections/{name} \
  -H "api-key: $KEY" -H 'Content-Type: application/json' \
  -d '{"optimizers_config":{"indexing_threshold":20000}}'

# 看优化器状态，等到所有段都 index 完成
curl -s http://127.0.0.1:6333/collections/{name} -H "api-key: $KEY" \
  | jq '.result.optimizer_status, .result.segments_count, .result.indexed_vectors_count'

indexed_vectors_count 远小于 points_count = 索引还没建完，此时检索走暴力扫，慢且费 CPU。

第 6 章 备份与恢复

6.1 两种备份，各有职责（都要有）

关键认知：你的分块语料是可重建的（有 build_chunks.py），所以逻辑层天然有备份。但快照仍必须做——重新嵌入 500 万块的成本和耗时不能接受作为常规恢复手段。

6.2 快照命令

KEY=your_api_key

# 单个 collection 快照（最常用）
curl -X POST http://127.0.0.1:6333/collections/kb_chunks_v1/snapshots -H "api-key: $KEY"
# → {"result":{"name":"kb_chunks_v1-2026-09-23-...snapshot","size":...}}

# 全实例快照（所有 collection 一起）
curl -X POST http://127.0.0.1:6333/snapshots -H "api-key: $KEY"

# 列出 / 删除
curl -s http://127.0.0.1:6333/collections/kb_chunks_v1/snapshots -H "api-key: $KEY" | jq -r '.result[].name'
curl -X DELETE http://127.0.0.1:6333/collections/kb_chunks_v1/snapshots/<snapshot_name> -H "api-key: $KEY"

# 恢复：把快照导回（可指定为新的 collection 名，便于先验证再切换）
curl -X PUT http://127.0.0.1:6333/collections/kb_chunks_v1/snapshots/recover \
  -H "api-key: $KEY" -H 'Content-Type: application/json' \
  -d '{"location":"file:///var/lib/qdrant/snapshots/kb_chunks_v1-xxx.snapshot"}'

# 从远端恢复（先上传到 Qdrant 能访问的 URL，或放本地路径恢复）

6.3 定时备份（用 ops/qdrant_ops.sh）

# crontab -e
# 每天 03:00 快照 + 保留 7 天
0 3 * * * /opt/qdrant/ops/qdrant_ops.sh backup-all >> /var/log/qdrant/backup.log 2>&1
# 每天 03:10 把快照同步到异地（另一个盘/对象存储）
10 3 * * * rsync -a --delete /var/lib/qdrant/snapshots/ /mnt/backup/qdrant-snapshots/

三条硬要求：

1. 异地：快照不能只躺在数据目录旁边，机器整体故障时一起没；
2. 保留策略：至少 7 天滚动，升级前额外留一份带标签的；
3. 必须演练：没恢复过的备份等于没有备份。每季度做一次到独立环境的恢复测试，记录实际耗时（这才是真实 RTO）。

6.4 RPO / RTO 参考

想压低 RPO 就加密快照频率（每小时一次对几百 MB 的库完全可行）。

第 7 章 监控与告警

7.1 三个端点的分工（别搞混）

7.2 必须告警的六件事

规则文件见 deploy/prometheus-alerts.yml。

反向告诫：不要对 page cache 内存占用告警。OS 把空闲内存用作缓存是正常且有益的行为（Qdrant 的 mmap 性能就靠它），对它告警会带来大量无效通知。要盯的是进程 RSS 是否逼近上限。

7.3 没有 Prometheus 时的轻量方案

你现有的栈是 Bark 推送，够用。用 ops/qdrant_ops.sh 的 watch 子命令，每 5 分钟跑一次，异常才推送：

*/5 * * * * /opt/qdrant/ops/qdrant_ops.sh watch >> /var/log/qdrant/watch.log 2>&1

它检查：服务可达性、磁盘水位、优化器状态、索引完成度、快照新鲜度（超过 36 小时未备份则告警）。快照新鲜度这一条很多团队不做，结果出事时才发现备份脚本早就静默失败了。

7.4 日志

log_level: INFO          # 生产用 INFO；DEBUG 会打印每次请求，只临时开
logger:
  format: json           # 接 ELK/Loki 时开，便于结构化检索

排障三板斧：

journalctl -u qdrant --since "10 min ago"                    # systemd
docker logs --since 10m qdrant 2>&1 | grep -iE "error|warn"  # 容器
journalctl -u qdrant | grep -i optimizer                     # 优化器专门看

第 8 章 日常运维与升级

8.1 巡检节奏

8.2 集合级运维动作

关于删除的内存回收：Qdrant 靠优化器在 deleted_threshold（默认 20% 垃圾）达到后 vacuum 回收。所以删完数据内存不会立刻降，这是设计如此，不是 bug。急着回收就临时把 deleted_threshold 调小并等待优化器跑完。

8.3 升级流程（照做，别即兴）

# ---------- 升级前 ----------
qdrant_ops.sh backup-all                        # ① 全量快照
cp /etc/qdrant/config.yaml /etc/qdrant/config.yaml.bak.$(date +%F)   # ② 备份配置
curl -s http://127.0.0.1:6333/ | jq -r .version  # ③ 记录当前版本号

# ④ 读 release notes，确认升级路径合法（能不能跳版本！见第 0 章）
# ⑤ 确认应用侧没用已删除的旧端点（1.19 起 /search /recommend /discover 已删）

# ---------- 升级（Docker）----------
sed -i 's/qdrant:v1.19.0/qdrant:v1.19.1/' docker-compose.yml
docker compose pull && docker compose up -d
docker compose logs -f qdrant        # 观察启动日志有无迁移报错

# ---------- 升级（二进制）----------
systemctl stop qdrant
cp /opt/qdrant/qdrant /opt/qdrant/qdrant.bak.$(date +%F)
curl -L <对应版本二进制> | tar -xz -C /opt/qdrant/
systemctl start qdrant

# ---------- 升级后验证 ----------
curl -s http://127.0.0.1:6333/ | jq -r .version      # 版本对了吗
curl -s http://127.0.0.1:6333/readyz                  # 就绪了吗
# 跑你的 20 题评测集，对比升级前后 Recall —— 这是唯一能证明"没坏"的方法
python3 qdrant_import.py --eval

# ---------- 回滚预案（必须提前想好）----------
# 二进制：换回 .bak 二进制 + 配置；若存储格式已迁移，用升级前快照恢复
# Docker：改回旧 tag；同上

一条经验：Qdrant 的 小版本升级（1.19.0 → 1.19.1） 通常是安全的；跨小版本（1.18 → 1.19）必读 release notes；跨大版本迁移（1.15 → 1.17+）必须逐版本升。

8.4 扩缩容

第 9 章 故障排查手册（症状 → 原因 → 处理）

9.1 启动类

9.2 检索类

9.3 内存 / 性能类

9.4 认证 / 权限类

9.5 集群类

第 10 章 命令速查表

# 环境
export Q="http://127.0.0.1:6333"
export KEY="你的api_key"
AUTH=(-H "api-key: $KEY")

# ==================== 健康与状态 ====================
curl -s $Q/healthz                                   # 活否
curl -s $Q/readyz                                    # 就绪否
curl -s $Q/ | jq                                      # 版本 + 基本信息
curl -s $Q/telemetry "${AUTH[@]}" | jq                # 运行态遥测
curl -s $Q/metrics "${AUTH[@]}" | grep '^# HELP' | head -40   # 指标清单

# ==================== 集合管理 ====================
curl -s $Q/collections "${AUTH[@]}" | jq -r '.result.collections[].name'
curl -s $Q/collections/{name} "${AUTH[@]}" \
  | jq '{points:.result.points_count, indexed:.result.indexed_vectors_count, segs:.result.segments_count, opt:.result.optimizer_status, size:.result.config.params.vectors.size}'
curl -s $Q/collections/{name}/exists "${AUTH[@]}"
curl -X DELETE $Q/collections/{name} "${AUTH[@]}"

# ==================== 计数与抽样 ====================
curl -s -X POST $Q/collections/{name}/points/count "${AUTH[@]}" \
  -H 'Content-Type: application/json' -d '{"exact":true}' | jq .result.count

curl -s -X POST $Q/collections/{name}/points/scroll "${AUTH[@]}" \
  -H 'Content-Type: application/json' \
  -d '{"limit":3,"with_payload":true,"with_vector":false}' | jq

# ==================== 检索 ====================
curl -s -X POST $Q/collections/{name}/points/query "${AUTH[@]}" \
  -H 'Content-Type: application/json' \
  -d '{"query":[0.1,0.2,0.3],"limit":5,"with_payload":true}' | jq
# 带过滤 + 指定 ef
# -d '{"query":[..],"limit":5,"params":{"hnsw_ef":128},
#      "filter":{"must":[{"key":"chunk_type","match":{"value":"code"}}]}}'

# ==================== 索引与优化 ====================
curl -X PUT $Q/collections/{name}/index "${AUTH[@]}" \
  -H 'Content-Type: application/json' \
  -d '{"field_name":"chunk_type","field_schema":"keyword"}'
curl -s $Q/collections/{name}/index "${AUTH[@]}" | jq        # 列出所有索引
curl -X PATCH $Q/collections/{name} "${AUTH[@]}" \
  -H 'Content-Type: application/json' \
  -d '{"optimizers_config":{"indexing_threshold":20000}}'

# ==================== 快照与备份 ====================
curl -X POST $Q/collections/{name}/snapshots "${AUTH[@]}" | jq .result.name
curl -X POST $Q/snapshots "${AUTH[@]}" | jq .result.name                 # 全实例
curl -s $Q/collections/{name}/snapshots "${AUTH[@]}" | jq -r '.result[].name'
curl -X DELETE $Q/collections/{name}/snapshots/{snap} "${AUTH[@]}"
curl -X PUT $Q/collections/{name}/snapshots/recover "${AUTH[@]}" \
  -H 'Content-Type: application/json' \
  -d '{"location":"file:///var/lib/qdrant/snapshots/xxx.snapshot"}'

# ==================== Alias（版本切换）====================
curl -s $Q/aliases "${AUTH[@]}" | jq
curl -X POST $Q/collections/aliases "${AUTH[@]}" \
  -H 'Content-Type: application/json' \
  -d '{"actions":[{"delete_alias":{"alias_name":"kb_current"}},
                  {"create_alias":{"collection_name":"kb_chunks_v2","alias_name":"kb_current"}}]}'

# ==================== 集群 ====================
curl -s $Q/cluster "${AUTH[@]}" | jq
curl -X POST $Q/cluster/recover "${AUTH[@]}"

附：上线前检查清单

【部署】
[ ] 版本写死，未使用 latest
[ ] 数据目录与快照目录在不同物理盘
[ ] nofile 已放开到 65536
[ ] MEM 上限已设（容器 mem_limit / systemd MemoryMax）
[ ] 日志轮转已配（避免磁盘被日志写满）

【安全】
[ ] api_key + read_only_api_key 已设，无 key 访问返回 401
[ ] 端口未对公网开放，Docker 绑定写了 127.0.0.1 或内网 IP
[ ] 容器非 root 运行
[ ] 密钥不在 git 中

【数据】
[ ] 集合已按语义分块入库，payload 索引已建（filter 用到的字段全覆盖）
[ ] 导入后 indexing_threshold 已调回，indexed_vectors_count ≈ points_count
[ ] 量化已按内存情况开启
[ ] 评测集已跑，Recall@5 达标（≥90%）

【运维】
[ ] 定时快照 + 异地同步已配
[ ] 至少完成一次恢复演练（真实计时）
[ ] 监控告警已配（磁盘、优化器错误、服务不可达、快照新鲜度）
[ ] 升级流程与回滚预案已写成文档

相关文件