Qdrant 是用于自行部署语义搜索与 RAG 的开源向量数据库。本文介绍在 Debian 13（Trixie）和 Debian 12（Bookworm）上安装的两种方式：Docker Compose，以及由 systemd 管理的原生 deb 包。前者便于快速部署；后者适合更希望使用 systemctl 管理服务的环境。
原文命令在全新的 Debian 13.5 云镜像上测试，并记录了实际遇到的问题：Qdrant deb 包安装二进制程序和配置，但不提供 systemd 单元、专用用户，也不会创建启动所需的快照目录。这些内容需要自行配置。配套代码位于 c4geeks/qdrant 的 install-debian 目录，参数含义以 Qdrant 官方文档为准。
开始前的准备
- Debian 13 或 Debian 12，amd64 或 arm64，至少 2 GB 内存。
- 具有
sudo权限的普通用户。 - 能够访问 Qdrant 发行版、Docker 软件源和 Debian 镜像站。
- 空闲 TCP 端口 6333（REST、Web UI）和 6334（gRPC）。
先安装辅助工具：
sudo apt update
sudo apt install -y ca-certificates curl jq方法一：Docker Compose
Docker 上游镜像跨发行版保持一致，Compose 文件也可与其他服务配置一起纳入 Git。Debian 自带软件源中的 Docker 可能较旧，本文使用官方 Docker CE 软件源。
第一步：添加 Docker CE 软件源并安装
安装 Docker 引擎和 Compose 插件：
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/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/debian ${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 --version
docker compose version将用户加入 docker 组，退出后重新登录以使组权限生效：
sudo usermod -aG docker $USER全新 Trixie 主机上的安装过程如下：
第二步：将容器日志发送到 journald
对于长期运行的 systemd 主机，使用 journalctl 集中读取日志较方便。在启动容器前，将 journald 日志驱动写入 /etc/docker/daemon.json：
echo '{"log-driver":"journald"}' | sudo tee /etc/docker/daemon.json
sudo systemctl restart docker日志驱动在创建容器时确定。已有容器需重建才会使用新设置；下面创建的新容器会直接采用 journald。
第三步：通过 Docker 启动 Qdrant
检测执行时的最新版本，创建存储目录并运行容器。Qdrant 日志随后进入系统日志：
export QDRANT_VERSION=$(curl -s https://api.github.com/repos/qdrant/qdrant/releases/latest | jq -r .tag_name)
echo $QDRANT_VERSION # v1.18.1 at the time of writing
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 \
qdrant/qdrant:${QDRANT_VERSION} # https://github.com/qdrant/qdrant/releases验证驱动，并从 journald 读取日志：
docker inspect qdrant --format 'log driver={{.HostConfig.LogConfig.Type}}'
curl -sf http://localhost:6333/healthz
sudo journalctl CONTAINER_NAME=qdrant --no-pager -n 5驱动应显示 journald，健康检查应通过，Qdrant 的最新日志应来自系统日志：
第四步：改用 Docker Compose
首次体验可用 docker run，反复调整的服务更适合 Compose。以下文件集中设置 API 密钥、内存限制、持久化存储和 journald：
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
- ./qdrant_snapshots:/qdrant/snapshots
environment:
QDRANT__SERVICE__API_KEY: ${QDRANT_API_KEY}
QDRANT__TELEMETRY_DISABLED: "true"
logging:
driver: journald
deploy:
resources:
limits:
memory: 4G生成高强度密钥，将版本和密钥写入 .env，再启动服务：
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方法二：原生 deb 包与 systemd
Qdrant 在 GitHub 发行版中提供官方 deb 包。虽然软件包命名面向 Ubuntu，原文测试中仍可在 Debian 安装。它只提供二进制程序、默认配置与 Web UI 资源；服务单元、用户、存储和快照目录需要自行创建。
第一步：安装 deb 包
如果前面运行了 Docker 容器，先停止它，释放 6333 端口：
docker stop qdrant 2>/dev/null
cd /tmp
curl -fL -o "qdrant_${QDRANT_VERSION#v}-1_amd64.deb" \
"https://github.com/qdrant/qdrant/releases/download/${QDRANT_VERSION}/qdrant_${QDRANT_VERSION#v}-1_amd64.deb" # https://github.com/qdrant/qdrant/releases
sudo apt install -y "./qdrant_${QDRANT_VERSION#v}-1_amd64.deb"
qdrant --version
systemctl status qdrant 2>&1 | head -3版本命令应正常输出，而 systemctl status 会提示尚无服务单元。安装位置分别为 /usr/bin/qdrant、/etc/qdrant/config.yaml 和 /var/lib/qdrant/static：
第二步：创建用户、目录和服务单元
创建专用系统用户，同时创建存储和快照目录，并设置所有权。打包配置使用绝对路径 /var/lib/qdrant/storage 与 /var/lib/qdrant/snapshots：
sudo useradd -r -s /usr/sbin/nologin qdrant
sudo mkdir -p /var/lib/qdrant/storage /var/lib/qdrant/snapshots
sudo chown -R qdrant:qdrant /var/lib/qdrant写入服务单元。显式使用 --config-path，使程序读取软件包提供的配置，而非在工作目录中搜索：
sudo tee /etc/systemd/system/qdrant.service >/dev/null <<'EOF'
[Unit]
Description=Qdrant Vector Database
After=network.target
[Service]
Type=simple
User=qdrant
Group=qdrant
WorkingDirectory=/var/lib/qdrant
ExecStart=/usr/bin/qdrant --config-path /etc/qdrant/config.yaml
Restart=on-failure
RestartSec=5
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now qdrant
sudo systemctl is-active qdrant
curl -sf http://localhost:6333/healthz服务应显示 active，健康检查应通过：
如果未创建快照目录就启动，程序可能以 Failed to create snapshots temp directory 错误退出。原文测试确实遇到此问题，因此在 systemctl start 前，应确保两个目录都存在。
验证集合与搜索
两种安装方式使用相同的 6333 REST API。创建 demo 集合，写入三个带载荷的点，再搜索最近邻：
curl -s -X PUT http://localhost:6333/collections/demo \
-H "Content-Type: application/json" \
-d '{"vectors":{"size":4,"distance":"Cosine"}}' | jq .
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"}}
]
}' | jq .
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。相同排序说明写入、索引和查询流程已连通：
打开 Web UI
访问服务器 6333 端口的 /dashboard，Collections 面板应显示 demo 集合：
配置防火墙
Debian 云镜像通常不默认启用防火墙。若使用 nftables，只允许可信 CIDR 访问两个 Qdrant 端口。面向公网前，应先设置 API 密钥与 TLS：
sudo apt install -y nftables
sudo systemctl enable --now nftables
TRUSTED_CIDR="10.0.0.0/8" # adjust to your office or VPN range
sudo nft add table inet filter
sudo nft 'add chain inet filter input { type filter hook input priority 0 ; policy accept ; }'
sudo nft add rule inet filter input ip saddr $TRUSTED_CIDR tcp dport { 6333, 6334 } accept
sudo nft list ruleset进一步加固可参考本系列的 API 密钥、TLS 和 Nginx 安全篇。
升级 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 \
qdrant/qdrant:${QDRANT_VERSION}
# Native .deb
cd /tmp
curl -fL -o "qdrant_${QDRANT_VERSION#v}-1_amd64.deb" \
"https://github.com/qdrant/qdrant/releases/download/${QDRANT_VERSION}/qdrant_${QDRANT_VERSION#v}-1_amd64.deb"
sudo apt install -y "./qdrant_${QDRANT_VERSION#v}-1_amd64.deb"
sudo systemctl restart qdrant故障排查
Failed to create snapshots temp directory
原生服务启动前未创建 /var/lib/qdrant/snapshots。创建目录，将所有权设为 qdrant:qdrant，再重启服务。
加载集合时 WAL 文件 PermissionDenied
原生 qdrant 用户无法读取先前 Docker 以 root 身份创建的文件。可使用新的空存储目录，或在启动服务前运行 sudo chown -R qdrant:qdrant /var/lib/qdrant 修正所有权。
journalctl 中没有容器日志
日志驱动在创建容器时写入。配置好 /etc/docker/daemon.json 后，删除并重建对应容器，使新设置生效。
