Qdrant 入门系列02 – 在 Ubuntu 26.04、24.04 和 22.04 上安装 Qdrant

Qdrant 是支持 AI 应用大规模检索的开源向量数据库。本文介绍在 Ubuntu LTS 上通过 Docker 或原生 deb 包安装的方法。前者适合大多数团队；后者适合需要系统服务、但不使用 Docker 的环境。步骤覆盖 Ubuntu 26.04、24.04 和 22.04，并使用可识别发行版版本的命令。

完成后，Qdrant 服务、REST API 和内置 Web UI 都应可用，还会创建一个小型向量集合以验证检索。原文所有命令在全新的 Ubuntu 24.04 LTS 虚拟机上测试，配套代码位于 c4geeks/qdrant 的 install-ubuntu 目录，参数含义以 Qdrant 官方文档为准。

初次接触稠密检索时，可先理解向量搜索与传统关键词搜索的差别；如果正在比较独立数据库和 PostgreSQL 扩展，也可评估 pgvector。

开始前的准备

Ubuntu 26.04、24.04 或 22.04 LTS 服务器，至少 2 GB 内存。官方 Docker 镜像支持 amd64 与 arm64。
具有 sudo 权限的用户。
可以访问 GitHub 发行版下载服务和 Docker 软件源。
两个空闲 TCP 端口：6333 用于 REST 和 Web UI，6334 用于 gRPC。
约 1 GB 的镜像空间，以及 /var/lib/qdrant/storage 中存储数据集所需的容量。

先更新软件包索引：

sudo apt update
sudo apt install -y ca-certificates curl jq

方法一：使用 Docker 安装

Docker 是常用的部署方式。上游提供的镜像也用于生产环境，本地与集群使用相同程序。

第一步：安装 Docker 引擎

添加 Docker apt 软件源，安装引擎与 Compose 插件：

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

. /etc/os-release
echo deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu ${VERSION_CODENAME} stable \
  | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

将用户加入 docker 组，便于日常运行命令。退出并重新登录后，组变更才会生效：

sudo usermod -aG docker $USER
docker --version
docker compose version

第二步：检测版本并拉取镜像

固定具体标签可提高可重复性。下面读取执行时的最新发行版标签，保存在变量中供后续使用：

export QDRANT_VERSION=$(curl -s https://api.github.com/repos/qdrant/qdrant/releases/latest | jq -r .tag_name)
echo $QDRANT_VERSION

docker pull qdrant/qdrant:${QDRANT_VERSION}  # https://github.com/qdrant/qdrant/releases

第三步：配置持久化存储并运行

创建宿主机数据目录，挂载到容器内的 /qdrant/storage，然后启动服务：

sudo mkdir -p /var/lib/qdrant/storage

docker run -d \
  --name qdrant \
  --restart unless-stopped \
  -p 6333:6333 -p 6334:6334 \
  -v /var/lib/qdrant/storage:/qdrant/storage:z \
  qdrant/qdrant:${QDRANT_VERSION}

确认容器运行且端口已绑定：

docker ps --filter name=qdrant --format table {{.Names}}\t{{.Status}}\t{{.Ports}}

输出中应看到 Up 状态，以及 REST、gRPC 到宿主机的端口映射：

### 第四步：验证安装

下面三个端点分别用于确认服务存活、已准备好处理查询，以及实际版本：

curl -sf http://localhost:6333/healthz
curl -s http://localhost:6333/ | jq .
curl -s http://localhost:6333/readyz

健康检查应通过，版本响应应与镜像标签一致，就绪检查应表明分片已加载：

### 第五步：创建首个集合并搜索

集合保存数据点，即向量及其元数据。创建名为 demo、使用四维向量和余弦距离的集合，再插入或更新三个示例点：

curl -s -X PUT http://localhost:6333/collections/demo \
  -H Content-Type: application/json \
  -d '{vectors:{size:4,distance:Cosine}}'

curl -s -X PUT http://localhost:6333/collections/demo/points \
  -H Content-Type: application/json \
  -d '{
    points: [
      {id:1, vector:[0.1,0.2,0.3,0.4], payload:{city:Nairobi}},
      {id:2, vector:[0.2,0.3,0.4,0.5], payload:{city:Berlin}},
      {id:3, vector:[0.9,0.8,0.7,0.6], payload:{city:Tokyo}}
    ]
  }'

执行相似度搜索，最接近查询向量的点应获得最高分：

curl -s -X POST http://localhost:6333/collections/demo/points/search \
  -H Content-Type: application/json \
  -d '{vector:[0.15,0.25,0.35,0.45],limit:3,with_payload:true}' \
  | jq .

Berlin 排在第一，Nairobi 第二，Tokyo 最后，因为 Tokyo 的向量方向与查询相反。这说明写入、索引和查询的整个流程已经连通：

### 第六步：打开内置 Web UI

容器提供 /dashboard 页面。在浏览器中访问服务器 6333 端口下的该路径。Collections 面板会显示刚创建的 demo，包含状态、数据点数量和向量配置：

点击侧边栏的 Console，即可在浏览器中发送 REST 请求，适合快速实验和帮助尚不熟悉 curl 的同事入门：

## Docker Compose 替代方案

Compose 可将 API 密钥、内存限制等集中在一个文件中。将以下内容保存为 docker-compose.yml，并在同目录的 .env 中定义 QDRANT_VERSION 和 QDRANT_API_KEY：

services:
  qdrant:
    image: qdrant/qdrant:${QDRANT_VERSION}  # https://github.com/qdrant/qdrant/releases
    container_name: qdrant
    restart: unless-stopped
    ports:
      - 6333:6333
      - 6334:6334
    volumes:
      - ./qdrant_storage:/qdrant/storage:z
      - ./qdrant_snapshots:/qdrant/snapshots:z
    environment:
      QDRANT__SERVICE__API_KEY: ${QDRANT_API_KEY}
      QDRANT__TELEMETRY_DISABLED: true
    deploy:
      resources:
        limits:
          memory: 4G

生成高强度 API 密钥并启动：

echo QDRANT_VERSION=${QDRANT_VERSION} > .env
echo QDRANT_API_KEY=$(openssl rand -base64 32) >> .env

docker compose up -d
docker compose logs -f --tail=20 qdrant

此后每个 curl 请求都必须携带 api-key 请求头：

curl -s http://localhost:6333/collections \
  -H api-key: $(grep QDRANT_API_KEY .env | cut -d= -f2)

方法二：原生 deb 包与 systemd

原生方式让 systemd 直接管理 Qdrant。适用于禁止 Docker、需要与 journalctl 更紧密结合，或整体使用原生软件包的环境。

下载最新发行版的官方 deb 包，发行页面提供 amd64 与 arm64 版本：

QDRANT_PKG_VERSION=${QDRANT_VERSION#v}
cd /tmp
curl -fL --retry 3 -o qdrant_${QDRANT_PKG_VERSION}-1_amd64.deb \
  https://github.com/qdrant/qdrant/releases/download/${QDRANT_VERSION}/qdrant_${QDRANT_PKG_VERSION}-1_amd64.deb  # https://github.com/qdrant/qdrant/releases

sudo apt install -y ./qdrant_${QDRANT_PKG_VERSION}-1_amd64.deb

创建专用系统用户、存储目录，并准备 systemd 服务单元：

sudo useradd -r -s /sbin/nologin qdrant
sudo mkdir -p /var/lib/qdrant/storage /etc/qdrant
sudo chown -R qdrant:qdrant /var/lib/qdrant

将下列内容写入 /etc/systemd/system/qdrant.service：

[Unit]
Description=Qdrant Vector Database
After=network.target

[Service]
Type=simple
User=qdrant
Group=qdrant
WorkingDirectory=/var/lib/qdrant
ExecStart=/usr/bin/qdrant
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

重新加载 systemd，启用并启动服务：

sudo systemctl daemon-reload
sudo systemctl enable --now qdrant
sudo systemctl status qdrant --no-pager
journalctl -u qdrant -n 20 --no-pager

原生安装使用相同的健康检查端点：

curl -sf http://localhost:6333/healthz

安全开放防火墙

不要在没有认证时将 Qdrant 暴露到公网。默认 Docker 示例没有访问认证，只适合受控体验环境。若启用了 UFW，只允许可信 CIDR 访问 REST 和 gRPC：

TRUSTED_CIDR=10.0.0.0/8   # adjust to your office or VPN range

sudo ufw allow from $TRUSTED_CIDR to any port 6333 proto tcp
sudo ufw allow from $TRUSTED_CIDR to any port 6334 proto tcp
sudo ufw reload
sudo ufw status numbered

面向互联网时，应将 Qdrant 绑定到 127.0.0.1，在前面配置 Nginx、TLS 与 API 密钥。本系列安全篇给出完整加固方法。

升级 Qdrant

Docker 升级通常通过更换镜像标签完成。停止容器，重新读取版本并重建；持久化存储卷在此过程中保留：

export QDRANT_VERSION=$(curl -s https://api.github.com/repos/qdrant/qdrant/releases/latest | jq -r .tag_name)
docker pull qdrant/qdrant:${QDRANT_VERSION}  # https://github.com/qdrant/qdrant/releases
docker stop qdrant && docker rm qdrant
docker run -d --name qdrant --restart unless-stopped \
  -p 6333:6333 -p 6334:6334 \
  -v /var/lib/qdrant/storage:/qdrant/storage:z \
  qdrant/qdrant:${QDRANT_VERSION}

Compose 环境修改 .env 中的 QDRANT_VERSION，再运行 docker compose pull && docker compose up -d。原生环境下载新 deb 包，通过 apt install 就地升级，然后重启服务。

常见问题排查

6333 端口已被占用

若 docker run 报 bind: address already in use，找出占用者，停止对应服务或改用其他宿主机端口：

sudo ss -ltnp | grep -E ':(6333|6334)\b'

# Remap if you cannot free the port
docker run -d --name qdrant -p 16333:6333 -p 16334:6334 \
  -v /var/lib/qdrant/storage:/qdrant/storage:z \
  qdrant/qdrant:${QDRANT_VERSION}

容器反复重启

先查看日志。常见原因是绑定挂载的权限问题，例如 SELinux 或 AppArmor 的限制与目录访问要求冲突：

docker logs --tail=50 qdrant
sudo chown -R 1000:1000 /var/lib/qdrant/storage

Web UI 正常，但集合列表为空

全新安装本来就没有集合。通过 Console 或 curl 创建集合后，点击 Collections 标题旁的刷新图标。

用一杯咖啡支持我们，我们的每一篇[文档]都经过实际操作和精心打磨，而不是简单地从网上复制粘贴。期间投入了大量心血，只为能够真正帮助到您。

Docker Qdrant Qdrant 入门系列 Ubuntu

ZYF发表在Rocky Linux 9 从入门到精通002 — 系统安装
我在用ventoy工具引导安装Rocky…
木子发表在CentOS 7 迁移至 Rocky Linux 8.7 全过程
8 已经不再更新。可以看看日志看是否有报…
shingler发表在CentOS 7 迁移至 Rocky Linux 8.7 全过程
dnf -y --releasever=…
peter.liu发表在CentOS 7 迁移至 Rocky Linux 8.7 全过程
谢谢，参照此教程，花了两天时间，将一台旧…
keeper发表在在 Rocky Linux 9.x 上安装 Docker CE
感谢，刚接触docker，学到一些。7
木子发表在MySQL进阶15 — 复制技术
纯金点赞 👍👍👍
Bryan_S发表在MySQL基础04 — 配置文件
很赞，对于数据库小白而言，我有了基本的了…

登录管理

标签云

开始前的准备

方法一：使用 Docker 安装

第一步：安装 Docker 引擎

第二步：检测版本并拉取镜像

第三步：配置持久化存储并运行

方法二：原生 deb 包与 systemd

安全开放防火墙

升级 Qdrant

常见问题排查

6333 端口已被占用

容器反复重启

Web UI 正常，但集合列表为空

发送评论编辑评论

登 录 管 理

标 签 云

开始前的准备

方法一：使用 Docker 安装

第一步：安装 Docker 引擎

第二步：检测版本并拉取镜像

第三步：配置持久化存储并运行

方法二：原生 deb 包与 systemd

安全开放防火墙

升级 Qdrant

常见问题排查

6333 端口已被占用

容器反复重启

Web UI 正常，但集合列表为空

发送评论 编辑评论

推荐文章

登录管理

标签云

发送评论编辑评论