服务器安装单节点Qdrant 数据库

Qdrant 向量数据库 — 单节点 Docker 安装与使用教程

本教程介绍如何在远程 Linux 服务器上通过 Docker 单节点部署 Qdrant 向量数据库，使用 .env 文件管理 API Key，并从 Windows 本机远程访问。

---

目录

• 一、环境准备
• 二、部署 Qdrant
• 三、配置远程访问
• 四、从 Windows 远程访问
• 五、Python 客户端连接示例
• 六、常用运维命令
• 七、安全建议

---

一、环境准备

1.1 服务器要求

项目	最低配置	推荐配置
操作系统	Linux（Ubuntu 20.04+ / CentOS 7+）	Ubuntu 22.04 LTS
内存	2 GB	4 GB 及以上
磁盘	10 GB 可用空间	50 GB 及以上（SSD 推荐）
Docker	20.10+	最新版

1.2 安装 Docker（如尚未安装）

在远程 Linux 服务器上执行：

# 安装 Docker 官方仓库
curl -fsSL https://get.docker.com | sudo sh

# 将当前用户加入 docker 用户组（避免每次 sudo）
sudo usermod -aG docker $USER

# 重新登录或执行以下命令使组生效
newgrp docker

验证 Docker 安装：

docker --version

1.3 安装 Python 客户端库（Windows 本机）

在 Windows 本机的命令行或终端中执行：

pip install qdrant-client

---

二、部署 Qdrant

2.1 创建项目目录与 .env 文件

在 Linux 服务器上创建 Qdrant 的数据目录和配置文件：

# 创建数据持久化目录
mkdir -p ~/qdrant/storage

# 创建 .env 文件，写入自定义 API Key
cat > ~/qdrant/.env << 'EOF'
QDRANT_API_KEY=your_custom_api_key_here
EOF

# 修改 .env 文件权限（仅所有者可读写）
chmod 600 ~/qdrant/.env

提示：请将 your_custom_api_key_here 替换为一个强密码（建议 32 位以上，包含大小写字母、数字和特殊字符）。

2.2 编写 Docker Compose 配置文件

在 ~/qdrant/ 目录下创建 docker-compose.yml 文件：

version: '3.8'

services:
  qdrant:
    image: qdrant/qdrant:latest
    container_name: qdrant
    restart: always
    ports:
      - "6333:6333"  # HTTP API 端口
      - "6334:6334"  # gRPC 端口
    volumes:
      - ./storage:/qdrant/storage
    env_file:
      - .env
    environment:
      - QDRANT__SERVICE__API_KEY=${QDRANT_API_KEY}
    healthcheck:
      test: ["CMD", "bash", "-c", "echo > /dev/tcp/localhost/6333"]
      interval: 10s
      timeout: 5s
      retries: 3

2.3 启动服务

在 ~/qdrant/ 目录下执行：

docker compose up -d

2.4 验证部署

检查容器运行状态：

docker compose ps

应看到 qdrant 容器的状态为 healthy。

测试 API 是否可访问：

curl http://localhost:6333/

返回类似以下内容即表示启动成功：

{
  "title": "qdrant - vector search engine",
  "version": "1.11.x",
  "commit": "..."
}

---

三、配置远程访问

3.1 云服务器安全组

如果你的服务器是阿里云、腾讯云、AWS 等云服务器，需要在云控制台中放行以下端口：

端口	协议	用途
6333	TCP	HTTP API 远程访问
6334	TCP	gRPC 远程访问

3.2 系统防火墙配置

使用 firewalld（CentOS / RHEL）：

sudo firewall-cmd --permanent --add-port=6333/tcp
sudo firewall-cmd --permanent --add-port=6334/tcp
sudo firewall-cmd --reload

使用 ufw（Ubuntu）：

sudo ufw allow 6333/tcp
sudo ufw allow 6334/tcp

---

四、从 Windows 远程访问

4.1 浏览器访问管理面板

在 Windows 浏览器中打开：

http://你的Linux服务器公网IP:6333/dashboard

如果看到 Qdrant 管理面板，说明远程访问配置成功。

4.2 API 调用（需携带 API Key）

访问带鉴权的 API 时，需要在请求头中携带 api-key：

curl -H "api-key: your_custom_api_key_here" http://你的Linux服务器公网IP:6333/

---

五、Python 客户端连接示例

5.1 基本连接与集合操作

在 Windows 本机上创建 qdrant_demo.py：

from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct
import numpy as np

# 连接远程 Qdrant 服务
client = QdrantClient(
    url="http://你的Linux服务器公网IP:6333",
    api_key="your_custom_api_key_here"
)

# 列出已有集合
print("已有集合:", client.get_collections().collections)

# 创建集合
collection_name = "my_collection"
vector_size = 384  # 根据你的嵌入模型调整

try:
    client.create_collection(
        collection_name=collection_name,
        vectors_config=VectorParams(size=vector_size, distance=Distance.COSINE)
    )
    print(f"集合 '{collection_name}' 创建成功")
except Exception as e:
    print(f"集合已存在或创建失败: {e}")

# 写入向量数据
points = [
    PointStruct(
        id=1,
        vector=np.random.rand(vector_size).tolist(),
        payload={"title": "文档一", "category": "科技"}
    ),
    PointStruct(
        id=2,
        vector=np.random.rand(vector_size).tolist(),
        payload={"title": "文档二", "category": "体育"}
    ),
    PointStruct(
        id=3,
        vector=np.random.rand(vector_size).tolist(),
        payload={"title": "文档三", "category": "财经"}
    ),
]

client.upsert(collection_name=collection_name, points=points)
print("向量数据写入成功")

# 搜索相似向量
test_query_vector = np.random.rand(vector_size).tolist()

# 2. 使用正确的维度进行查询
search_results = client.query_points(
    collection_name="test_my_collection",
    query=test_query_vector,  # 传入 384 维的向量
    limit=3
)

# 打印搜索结果
for point in search_results.points:
    print(f"ID: {point.id}, Score: {point.score}, Payload: {point.payload}")

5.2 运行示例

python qdrant_demo.py

---

六、常用运维命令

6.1 容器管理

# 查看容器状态
docker compose ps

# 查看实时日志
docker compose logs -f

# 停止服务
docker compose down

# 重启服务
docker compose restart

# 更新镜像到最新版本
docker compose pull
docker compose up -d

6.2 更换 API Key

修改 .env 文件中的 QDRANT_API_KEY 值，然后重启容器：

# 编辑 .env 文件
nano ~/qdrant/.env

# 重启服务使新 Key 生效
docker compose restart

注意：更换 API Key 后，所有客户端必须同步更新配置中的 Key，否则将无法连接。

6.3 数据备份

Qdrant 的数据存储在 ~/qdrant/storage 目录下，可直接复制该目录进行备份：

tar -czf qdrant_backup_$(date +%Y%m%d).tar.gz ~/qdrant/storage

---

七、安全建议

1. 强密码策略：API Key 建议使用 32 位以上随机字符串，可使用 openssl rand -hex 32 生成。

2. 限制访问 IP：在云服务器安全组中，将 6333 和 6334 端口的访问来源限制为你的 Windows 本机公网 IP。

3. .env 文件安全：确保 .env 文件权限为 600（仅所有者可读写），不要将其提交到版本控制系统。

4. 定期更新镜像：定期执行 docker compose pull && docker compose up -d 以获取最新安全补丁。

5. HTTPS 代理（生产环境）：如果需要通过公网访问，建议在 Qdrant 前面部署 Nginx 反向代理并配置 TLS 证书，将 HTTP 升级为 HTTPS。

---

常见问题

Q1：容器启动后立即退出怎么办？

检查日志排查原因：docker compose logs qdrant

Q2：Windows 无法访问服务器 6333 端口？

依次排查：云服务器安全组是否放行 → 系统防火墙是否放行 → 服务器 IP 是否正确。

Q3：如何删除集合？

client.delete_collection(collection_name="my_collection")

Q4：单节点能支撑多大的数据量？

在 4GB 内存的服务器上，单节点 Qdrant 可轻松处理千万级向量数据，QPS 可达数千。如果数据量或并发继续增长，可平滑升级至多节点集群模式。