Windows 原生部署 Qdrant 完整教程（无 Docker 环境）

Qdrant 官方文档主推 Docker 部署，但如果你的机器上既没装 Docker 也没启用 WSL，怎么办？答案是跑官方提供的 Windows 原生二进制——解压即用，不依赖任何额外运行时。

这篇把整个过程从头写一遍：下载、目录规划、配置、开机自启、自己构建 Web 面板（Windows 官方包不含，这是最容易卡住的地方），以及验证。

一、这篇适合谁看

读完你会得到：一个能开机自启的 Qdrant 实例，带 REST API 和一个能用的 Web 管理面板，跑在 Windows 上不需要 Docker。

本文环境：Windows 10/11 x64，无 Docker、无 WSL，Qdrant v1.19.1，全部装在 D:\qdrant。

1.1 为什么不用 Docker

没有 Docker 和 WSL 时有三条路可走：装 WSL 再跑 Linux 容器、装 Docker Desktop、或者直接用官方 Windows 原生二进制。

前两条都要改变系统环境（WSL 要重启、Docker Desktop 要常驻后台还吃资源），而这里只是搭个测试用的向量库。官方发布的 Windows 原生 MSVC 构建不需要任何额外运行时，双击就能跑，是最轻的选择。

但代价要提前知道：官方对 Windows 原生的支持明显落后于 Linux。最直接的表现就是——发布包里不含 Web 面板，得自己构建（见第五节）。所以如果你要长期运行或上生产，还是建议迁到 Linux。

二、第一步：下载与目录规划

2.1 下载

去 Releases 页面找 Windows 版：

https://github.com/qdrant/qdrant/releases

文件名：qdrant-x86_64-pc-windows-msvc.zip

解压后里面只有一个 qdrant.exe（约 82MB）。

2.2 目录规划

建议所有东西都放在一个目录下，程序、数据、日志不分散。本文的布局：

D:\qdrant
├── qdrant.exe                      # 主程序（v1.19.1，约 82MB）
├── config.yaml                     # 配置文件（存储路径、遥测开关）
├── qdrant.log                      # 运行日志（追加写）
├── qdrant-windows.zip              # 原始安装包（留档，可用于重装）
├── start-qdrant.bat                # 手动启动脚本
├── start-hidden.vbs                # 隐藏窗口启动器（供开机自启调用）
├── create-autostart-shortcut.ps1   # 重建开机自启快捷方式的脚本
├── storage                         # 向量数据（核心，勿随意删除）
│   ├── collections                 # 各集合数据
│   └── raft_state.json             # 集群状态文件
├── static                          # Web 面板静态文件（手动构建产物）
└── web-ui-src                      # 面板源码（qdrant/qdrant-web-ui）
    ├── dist                        # 构建输出
    └── node_modules                # 依赖（约 500MB，仅重建时需要）

两个目录值得特别注意：

• storage 是全部向量数据所在——迁移和备份认准它，别的基本可以重建
• web-ui-src\node_modules 占了约 500MB，但只在重建面板时才需要，平时可以忽略

三、第二步：写配置文件

在 D:\qdrant 下新建 config.yaml，只需两行：

storage:
  storage_path: D:\qdrant\storage   # 数据目录，绝对路径

telemetry_disabled: true            # 关闭官方向外发送的匿名遥测

这里用绝对路径是个关键决定。

如果写成相对路径，通过不同方式启动（双击 bat / 命令行 / 开机自启）时工作目录不一样，Qdrant 会找不到数据，甚至会在别处新建一个空的 storage——表现就是”数据丢了”，但其实是启动到了另一个目录。

3.1 其余配置保持默认

默认监听 0.0.0.0，意味着同网段任何机器都能连。测试环境无所谓，但如果这台机器在公共网络里，建议改成只监听本机：

service:
  host: 127.0.0.1

四、第三步：启动与开机自启

4.1 先手动启动一次

新建 start-qdrant.bat：

@echo off
cd /d D:\qdrant
qdrant.exe >> qdrant.log 2>&1

双击运行，或者命令行执行：

D:\qdrant\start-qdrant.bat

预期结果：窗口里开始滚动日志，最后出现类似这一行——

Qdrant HTTP listening on 6333
Qdrant gRPC listening on 6334

看到这两行就说明起来了。

4.2 开机自启：绕开权限限制的办法

常规做法是建 Windows 计划任务（schtasks），但如果当前账户没有提权，创建计划任务会被系统直接拒绝，报”拒绝访问”。

这时改用「启动文件夹」方案，普通用户权限就能完成——把快捷方式丢进下面这个目录：

C:\Users\<用户名>\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\Qdrant.lnk

怎么快速打开这个目录：按 Win + R，输入 shell:startup 回车。

启动链路是三层：

Qdrant.lnk  →  wscript start-hidden.vbs  →  start-qdrant.bat  →  qdrant.exe

中间那层 VBS 的作用是隐藏控制台窗口。因为直接把 bat 放进启动文件夹的话，开机后会挂着一个黑色命令行窗口，看着难受。

start-hidden.vbs 的内容：

Set ws = CreateObject("Wscript.Shell")
ws.Run "D:\qdrant\start-qdrant.bat", 0, False

第二个参数 0 表示隐藏窗口。

两个常用操作：

• 取消自启：删掉启动文件夹里那个快捷方式即可（不影响已经在跑的实例）
• 重建快捷方式：powershell -ExecutionPolicy Bypass -File D:\qdrant\create-autostart-shortcut.ps1

4.3 停止与验证

停止：

taskkill /F /IM qdrant.exe

验证是否就绪：

curl http://localhost:6333/readyz    # 返回 "all shards are ready" 表示就绪
curl http://localhost:6333/          # 返回版本 JSON，如 {"version":"1.19.1"}

启动失败、端口占用、存储错误都会写进 D:\qdrant\qdrant.log，排查问题时先看它末尾。

五、第四步：手搓 Web 面板

这是 Windows 原生部署最容易卡住的地方。

Windows 官方发布包里不包含 Dashboard 静态文件。所以刚部署完访问 /dashboard 会返回 404——这不是装错了，是本来就没有。

解法是从官方源码构建一份，放进 D:\qdrant\static。过程不复杂，但有两个 Windows 特有的坑。

5.1 构建命令

先把面板源码克隆到 D:\qdrant\web-ui-src：

cd /d/qdrant
git clone https://github.com/qdrant/qdrant-web-ui.git web-ui-src
cd web-ui-src
npm install

然后在 Git Bash 里执行构建（本机 Node v24.18.0）：

cd /d/qdrant/web-ui-src
git pull                                  # 如需升级
MSYS_NO_PATHCONV=1 npx vite build --base /dashboard/
rm -rf /d/qdrant/static && mkdir -p /d/qdrant/static
cp -r dist/. /d/qdrant/static/
taskkill /F /IM qdrant.exe                # 重启后生效
D:/qdrant/start-qdrant.bat

Vite 是面板用的前端构建工具；它的 --base 参数决定资源引用的基准路径——因为面板挂在 /dashboard 子路径下，必须告诉它。下面两个坑都是围绕这个参数产生的。

5.2 坑一：不要用 npm run 脚本

面板的 package.json 里已经有一个现成的脚本 npm run build-qdrant，看起来应该直接用它。但在 Windows 上不要用。

原因：npm 在 Windows 上是通过 cmd.exe 执行 script 的，而 cmd 不会剥离单引号。脚本里写的是 --base '/dashboard/'，于是 vite 实际收到的 base 值是：

'/dashboard/'      ← 带着单引号

结果就是生成的 index.html 和 JS 里的资源基准路径全部损坏，形如：

/''/dashboard/'/assets/...

页面打开后所有资源 404，表现是白屏。

麻烦的是错误信息完全不指向真正的原因——控制台只会报资源 404，很容易往”版本不兼容””依赖装错了”方向排查半天，而实际问题是引号。

所以正确做法是绕开 npm 脚本，直接用 npx vite build 并显式传参（不加引号）。

5.3 坑二：Git Bash 会转换路径参数

如果你在 Git Bash 里执行：

npx vite build --base /dashboard/     # ❌ 会出错

会失败。因为 Git Bash 基于 MSYS，它会自动把”看起来像 Unix 路径”的参数转换成 Windows 路径——/dashboard/ 会被转成 C:/Program Files/Git/dashboard/ 之类。

所以必须加环境变量前缀禁用这个转换：

MSYS_NO_PATHCONV=1 npx vite build --base /dashboard/    # ✓ 正确

如果你的命令行是 CMD 或 PowerShell，不需要这个前缀（它们没有这个转换机制）。

5.4 怎么确认构建对了

构建完成后，检查 dist/index.html 里的资源路径：

/dashboard/assets/...        ✓ 正确

只要看到路径里出现了引号、或者多了一层目录（比如 C:/Program Files/Git/），就是没构建对。

这一步花 10 秒，能省掉后面排查白屏的半小时。

5.5 两个可以忽略的告警

面板打开后，浏览器控制台可能报这两条，都是正常的：

• cloud/data.json 404 —— 官方构建产物中本身不含该文件
• Api key is used with unsecure connection —— 未配置 API Key 时的提示

六、第五步：验证能用

6.1 REST API（不装任何依赖）

注意下面的写法：JSON 用单引号包住，这样里面的双引号就不需要转义。这是 curl 传 JSON 的标准写法，用双引号包会直接语法错误。

# 1) 创建集合：4 维向量，点积距离
curl -X PUT http://localhost:6333/collections/my_collection \
  -H "Content-Type: application/json" \
  -d '{"vectors":{"size":4,"distance":"Dot"}}'

# 2) 写入一个向量（带 payload）
curl -X PUT "http://localhost:6333/collections/my_collection/points?wait=true" \
  -H "Content-Type: application/json" \
  -d '{"points":[{"id":1,"vector":[0.1,0.2,0.3,0.4],"payload":{"label":"example"}}]}'

# 3) 相似度检索 top3
curl -X POST "http://localhost:6333/collections/my_collection/points/search" \
  -H "Content-Type: application/json" \
  -d '{"vector":[0.1,0.2,0.3,0.4],"limit":3,"with_payload":true}'

# 4) 查看集合列表
curl http://localhost:6333/collections

预期结果：

• 第 1 步返回 {"result":true,"status":"ok"}
• 第 3 步返回的 result 数组里有一条记录，id 为 1，score 接近 1.0（因为查询向量和存储的向量完全一样）

如果第 3 步返回空数组，检查集合名写对没有——以及第 2 步是否真的执行成功了。

6.2 Python 客户端

from qdrant_client import QdrantClient

client = QdrantClient(url="http://localhost:6333")   # gRPC 默认走 6334
client.create_collection(
    collection_name="my_collection",
    vectors_config={"size": 4, "distance": "Dot"},
)
client.upsert(
    collection_name="my_collection",
    points=[{"id": 1, "vector": [0.1, 0.2, 0.3, 0.4], "payload": {"label": "example"}}],
)
print(client.search(collection_name="my_collection", query_vector=[0.1, 0.2, 0.3, 0.4], limit=3))

安装：pip install qdrant-client

七、访问端点一览

八、备份与迁移

冷备份（推荐，最简单）：停止 Qdrant 后，直接拷贝整个 D:\qdrant\storage 目录。

热备份（快照 API），运行中也能做：

curl -X POST http://localhost:6333/collections/my_collection/snapshots

生成的文件在：

D:\qdrant\storage\collections\my_collection\snapshots\

迁移到其他机器：把 storage 目录（或快照文件）复制过去，用同版本 Qdrant 挂载即可。

九、故障排查

十、版本升级

1. 从 Releases 页下载新版 qdrant-x86_64-pc-windows-msvc.zip：github.com/qdrant/qdrant/releases
2. taskkill /F /IM qdrant.exe 停止实例
3. 用新版 qdrant.exe 覆盖旧的（config.yaml 和 storage 保持不动）
4. 重启后用 /readyz 验证

如有数据结构变更，Qdrant 会自动做增量迁移。升级前建议先按第八节备份。

注意：升级 Qdrant 主程序不影响自己构建的 Web 面板（它在 static 目录里，与主程序解耦）。但如果面板功能异常，可能需要重新克隆面板源码构建一次。

十一、小结

Windows 原生部署 Qdrant 本身很简单——解压、配两行 yaml、双击就跑。真正花时间的只有两件事：

1. Web 面板要自己构建（官方 Windows 包不含），而且构建命令在 Windows 上有两个坑：不能用 npm 脚本（cmd 不剥离单引号，导致资源路径损坏、页面白屏），Git Bash 里要加 MSYS_NO_PATHCONV=1（否则路径参数被转换）
2. 开机自启受权限限制，计划任务被拒时用「启动文件夹」方案绕过，中间加一层 VBS 隐藏窗口

另外两个容易踩的点，都不在”部署”本身，但排查起来同样费时：

• config.yaml 里的 storage_path 一定用绝对路径——否则不同启动方式会指向不同目录，看起来像数据丢了
• curl 传 JSON 要用单引号包整个 body——用双引号包会导致内层引号语法错误

最后再提醒一次：官方对 Windows 原生的支持落后于 Linux/Docker。

如果这个向量库后面要长期跑或者上生产，迁到 Linux 更省心——用 musl 静态版 qdrant-x86_64-unknown-linux-musl.tar.gz，不依赖系统 glibc，出问题的概率明显更低。迁移时只需要把 storage 目录带过去。

参考链接

• Qdrant Releases（各平台预编译包）：https://github.com/qdrant/qdrant/releases
• Qdrant 官方文档：https://qdrant.tech/documentation/
• Web 面板源码仓库：https://github.com/qdrant/qdrant-web-ui