Qdrant 向量库运维手册

适用 AIKE 智能客服 · kbimport 知识库插件。集合命名规则：kb_business_{商户ID}（一商户一集合）。本文为官网公开副本，无需登录后台即可查阅。

1. 架构概览

MySQL (ai_knowledge FAQ)
    ↓ Embedding API（百炼 text-embedding-v4）
Qdrant 集合 kb_business_{商户ID}
    ↓ 语义检索
KnowledgeRetriever → AI 直答 / LLM 上下文

安全：Qdrant 必须绑定 127.0.0.1，禁止 0.0.0.0:6333 对外开放。

2. 一键安装（Linux / 宝塔）

SSH 登录服务器，在项目根目录执行：

cd /www/wwwroot/你的站点目录
bash install_qdrant.sh

或：

bash scripts/qdrant/install.sh

脚本会：拉取镜像 qdrant/qdrant:latest、创建容器 wolive-qdrant、数据卷 wolive_qdrant_data、健康检查 /readyz。

若 iptables 报错，执行 bash scripts/qdrant/fix_docker_iptables.sh 后重试；脚本会自动尝试 host 网络模式。

Windows 本机测试

install_qdrant.bat

需已安装 Docker Desktop。

3. 日常运维命令

后台也可在 向量检索配置 → 检测连接 查看 Embedding / Qdrant / MySQL 索引统计。

4. 备份与恢复

4.1 备份 Qdrant 数据卷（推荐）

# 停止写入（可选，热备可跳过）
docker stop wolive-qdrant

# 导出卷到 tar
docker run --rm \
  -v wolive_qdrant_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/qdrant_backup_$(date +%Y%m%d).tar.gz -C /data .

docker start wolive-qdrant

4.2 恢复

docker stop wolive-qdrant
docker run --rm \
  -v wolive_qdrant_data:/data \
  -v $(pwd):/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/qdrant_backup_YYYYMMDD.tar.gz -C /data"
docker start wolive-qdrant

注意：MySQL 中的 ai_knowledge、ai_vector_chunk 需与 Qdrant 一致。换机恢复后建议在后台执行 全量重建向量 校验。

4.3 MySQL 相关表（建议一并备份）

• wolive_ai_knowledge — FAQ 原文
• wolive_ai_vector_chunk — 向量块元数据
• wolive_addon_kbimport_setting — 商户向量配置

5. 后台向量运维

集合命名规则：kb_business_{business_id}，一商户一集合，payload 含 business_id 过滤。

6. 卸载 kbimport 插件时的行为

保留：以下 MySQL 表与数据不会删除（重装插件后仍可用）：

• wolive_ai_vector_chunk
• wolive_addon_kbimport_setting
• wolive_ai_knowledge（主业务 FAQ 表，非插件专有但向量依赖它）

默认清理（可在插件 config 关闭）：

• 删除 Qdrant 中所有 kb_business_* 集合
• 删除 runtime/kbimport/ 导入暂存
• 删除 runtime/log/kbimport_vector.log
• 总后台卸载后会清系统缓存（含查询 Embedding 缓存）

清理报告写入：runtime/log/kbimport_uninstall.log

插件 config 项：uninstall_purge_qdrant、uninstall_purge_runtime（0=保留，1=清理）。

Qdrant Docker 容器与数据卷不会随插件卸载删除；需手动执行 bash scripts/qdrant/uninstall.sh。

7. 完全卸载 Qdrant 服务

bash scripts/qdrant/uninstall.sh

仅删除容器 wolive-qdrant，保留数据卷 wolive_qdrant_data。

彻底删除向量数据：

docker volume rm wolive_qdrant_data

不可逆：执行前请确认已备份。

8. 故障排查

向量错误日志：runtime/log/kbimport_vector.log

9. 常用 REST API 示例

# 集群就绪
curl -s http://127.0.0.1:6333/readyz

# 集合详情
curl -s http://127.0.0.1:6333/collections/kb_business_1

# 删除单个集合（慎用）
curl -X DELETE http://127.0.0.1:6333/collections/kb_business_1

10. 相关脚本路径