【保姆级喂饭教程】 Windows下WSL2+Docker+Qdrant安装教程

前言
一、WSL2
- 0、介绍
- [1. 检查环境](#1. 检查环境)
- [2. WSL2](#2. WSL2)
- [3. ubuntu](#3. ubuntu)
- [4. 验证](#4. 验证)
- [5. 迁移 ubuntu](#5. 迁移 ubuntu)
[二、 docker](#二、 docker)
- 0、介绍
- [1. Docker Desktop](#1. Docker Desktop)
- [2. 注册](#2. 注册)
- [3. 验证](#3. 验证)
- [4. 汉化](#4. 汉化)
- [5. 镜像](#5. 镜像)
- - [3.1 国内镜像站](#3.1 国内镜像站)
  - [3.2 配置docker代理](#3.2 配置docker代理)
  - [3.3 自建镜像代理](#3.3 自建镜像代理)
- 6、命令
- - [6.1 镜像管理（Image）](#6.1 镜像管理（Image）)
  - [6.2 容器管理（Container）](#6.2 容器管理（Container）)
  - [6.3 系统管理（System）](#6.3 系统管理（System）)
  - [6.4 数据卷管理（Volume）](#6.4 数据卷管理（Volume）)
- [7. Docker Compose](#7. Docker Compose)
- - [7.1 介绍](#7.1 介绍)
  - [7.2 安装](#7.2 安装)
  - [7.3 示例](#7.3 示例)
  - [7.4 实战](#7.4 实战)
  - [7.5 命令](#7.5 命令)
  - [7.6 推荐](#7.6 推荐)
- [8. Kubernetes](#8. Kubernetes)
- - [8.1 介绍](#8.1 介绍)
  - [8.2 和 Docker Compose 的关系](#8.2 和 Docker Compose 的关系)
三、Qdrant
- [0. 介绍](#0. 介绍)
- [1. 安装](#1. 安装)
- [2. 验证](#2. 验证)
- - [2.1 Web UI](#2.1 Web UI)
  - [2.2 curl](#2.2 curl)
- [3. 管理](#3. 管理)
- [4. 使用](#4. 使用)
- - [4.1 创建集合](#4.1 创建集合)
  - [4.2 添加向量](#4.2 添加向量)
  - [4.3 相似度查询](#4.3 相似度查询)
  - [4.4 带过滤条件的查询](#4.4 带过滤条件的查询)
  - [4.5 删除向量](#4.5 删除向量)
  - [4.6 删除集合](#4.6 删除集合)
- [5. Skills](#5. Skills)
后记
参考文献

前言

整个教程分为三大部分：

WSL2：开启 Windows 的 Linux 子系统，安装 Ubuntu 发行版。

Docker：安装 Docker Desktop，配置镜像源或代理，整理常用命令。

Qdrant：拉取镜像、生产环境启动、Python SDK 的基本操作。

一、WSL2

0、介绍

WSL（Windows Subsystem for Linux，Windows 子系统 Linux）是微软开发的一项功能，它允许用户在 Windows 系统上直接运行原生 Linux 程序，而无需安装完整的虚拟机（如 VMware 或 VirtualBox）。

WSL2 是该技术的第二代版本，与第一代 WSL1 的最大区别在于：WSL2 内置了一个真正的 Linux 内核，运行在一个轻量级的虚拟机中。这意味着：

兼容性极强 ：可以运行 Docker、需要系统调用的复杂应用（如 systemd 服务），几乎与原生 Linux 环境无异。
资源占用极低：启动仅需 1-2 秒，内存动态回收，不会像传统虚拟机那样预先独占大量内存。
与 Windows 无缝集成 ：可以在 Windows 文件资源管理器中直接访问 \\wsl$ 进入 Linux 文件目录，也可以从 WSL 内直接调用 Windows 下的 .exe 程序（如 code . 启动 VSCode）。

简单来说 ：WSL2 让你在 Windows 上拥有了一个"开机即用、用完即走"的 Linux 环境，是 Windows 开发者运行 Linux 工具链、学习 Linux 命令、安装 Docker 等服务的首选方案。

如果你目前只打算用 Docker 而不打算操作 Linux 命令行，也可以只开启 WSL2 内核而不安装 Ubuntu 发行版------Docker Desktop 会自动创建自己的 docker-desktop 发行版。不过本教程为了后续操作更灵活，还是建议按流程安装一个 Ubuntu。

1. 检查环境

WSL2需要Windows版本支持，打开PowerShell，输入winver查看Windows版本

Windows 11：全部支持 WSL2。
Windows 10：Version 2004 以上，Build 19041 以上

如果Windows版本不够，请先升级Windows。

接下来通过查看可获取Linux发行版本来判断WSL是否已可用

bash 复制代码

wsl --list --online

下面的命令不行，返回的还是命令提示

bash 复制代码

wsl --status
wsl --install -d Ubuntu --location D:\Data\WorkSpace\WSL

确认了还不能用，我们需要先开启WSL2 需要两个 Windows 功能

bash 复制代码

# 启用 Windows 子系统（WSL）功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
# 启用虚拟机平台功能
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

/all：在所有用户上启用该功能
/norestart：启用功能后不会立即重启。

上面的命令关闭了重启，是怕你有东西没保存，实际要想生效是必须要重启的

重启后查看下状态

bash 复制代码

wsl --status

默认是2，但其实只有刚刚启动的WSL1，提示你更新

还是无法直接安装

bash 复制代码

wsl --install -d Ubuntu --location D:\Data\WorkSpace\WSL

2. WSL2

按照上面的提示执行命令，更新一下就是安装

bash 复制代码

wsl --update

到这一步实际上WSL2内核已经安装好了

3. ubuntu

一般教程都会继续安装一个ubuntu，不安装也行，安装了比较方便体验

bash 复制代码

wsl --install -d Ubuntu --location D:\Data\WorkSpace\WSL

这下就可以安装了，安装后设置一个账户，root还不行，起一个自己的吧

上一步的末尾让你选择是否分享用户数据，输入n选否，然后就进入ubuntu了

测试个命令

ctrl+D退出

还会打开一个gui面板，是个介绍和设置界面

查看下安装目录，直接安装到根目录了，不会自动创建系统名称，之后移动一下

4. 验证

bash 复制代码

wsl -l -v

再输入wsl就可以再次进入了，报错不用管，是我的一个外置的MySQL数据库

5. 迁移 ubuntu

后续安装多个Linux的话再把每个版本放到单独的文件夹，方便管理

二、 docker

0、介绍

Docker 是一个开源的应用容器化 平台。它可以将应用程序及其所有依赖（库、配置文件、环境变量）打包成一个标准化的单元（称为"容器"） ，并在任何安装了 Docker 的环境中运行。

与传统的虚拟机（如 VMware）相比，Docker 容器有本质区别：

对比项	传统虚拟机 (VM)	Docker 容器
比喻	一栋带完整地基和水电系统的独立别墅	共享大楼基础设施的精装公寓套房
资源占用	每个 VM 包含完整的操作系统（数 GB），资源固定独占	所有容器共用宿主机内核，只增加几 MB 到几百 MB 的额外层
启动速度	冷启动需要数十秒到数分钟	毫秒级启动
隔离程度	完全隔离（独立内核）	进程级隔离（共享内核）

Docker 的核心价值在于两点：

环境一致性：解决了"在我电脑上能跑，到你电脑上就不行"的千古难题。镜像（Image）中包含了运行所需的一切，构建完成后在任何环境下的行为完全一致。
轻量化与分层复用：多个容器可以共享同一个基础镜像层（例如 10 个基于 Python 3.10 的项目，只存储 1 份 Python 基础镜像，各自只保存其差异化的依赖层），磁盘占用远低于多个独立的虚拟环境。

Docker 与 WSL2 的关系 ：Docker Desktop 依赖 WSL2 作为后端运行引擎。简单说，WSL2 提供了运行 Linux 容器的"地基"（Linux 内核），而 Docker 是在这之上搭建的"公寓楼"（容器管理平台） 。两者配合使用，让 Windows 用户也能流畅体验原生的 Linux 容器环境。

1. Docker Desktop

目前主流的已经是直接安装Docker Desktop进行管理了。

打开docker官网，鼠标放到下载按钮上，选择自己的系统版本点击下载

https://www.docker.com/products/docker-desktop/

下载后双击安装

弹出错误，是因为docker默认安装到c盘，需要3.5个g，我只有1.2了，安装不下

正好我本来也是要安装到d盘的

根据自己习惯创建docker安装、WSL2容器、Windows容器的三个文件夹

复制代码

D:\Program\Work\docker
D:\Data\WorkSpace\Docker\WSL2
D:\Data\WorkSpace\Docker\Windows

然后在exe所在的下载文件夹打开cmd，回车

然后执行命令（路径替换为上面自己创建的）：

bash 复制代码

start /w "" "Docker Desktop Installer.exe" install -accept-license --backend=wsl-2 --installation-dir="D:\Program\Work\docker" --wsl-default-data-root="D:\Data\WorkSpace\Docker\WSL2" --windows-containers-default-data-root="D:\Data\WorkSpace\Docker\Windows"

解释：

使用 start /w 启动安装程序，并等待安装完成。
Docker Desktop Installer.exe是下载后的文件名称，如果修改了这里也要修改
安装程序会按照指定的参数进行安装：
- 使用 WSL 2 作为后端。
- 将 Docker Desktop 安装到 D:\Program\Work\docker。
- 将 WSL 2 数据存储到 D:\Data\WorkSpace\Docker\WSL2。
- 将 Windows 容器数据存储到 D:\Data\WorkSpace\Docker\Windows。
通过 -accept-license 参数，跳过许可协议的确认步骤。

执行完没反应

结合ai分析，Docker Desktop Installer.exe 是一个"自解压"安装包，会先把文件解压到 C 盘的临时目录，安装包本事是628m，可能之前需要的3g是解压的大小，那我们先修改一下系统临时目录

bash 复制代码

set TEMP=D:\Temp
set TMP=D:\Temp

再次执行，果不其然，可以看到使用的是D:\Temp

趁着没安装完看看解压了什么，也还是600多m

可恶，安装完之后会强制自动重启，我好多东西都还没保存呢，，完成的截图也还没来得及粘贴，还是不够谨慎了

安装完成之后，cmd窗口最后一行是install succeed，docker的安装窗口是close and log，谁能想到一点击就重启了

重启后docker会自动在wsl中创建一个linux发行版docker-desktop，可以在资源管理器中看到

点进去就是常见的Linux目录

重启后自动弹出一个用户协议，点击接受

2. 注册

docker使用需要注册，先skip跳过

不登录主要是限制拉取频率，私有镜像和Docker Hub访问

参考：Desktop 通用常见问题

不登录应该也可以，之后有需要再登录

在设置里的resources可以查看刚刚设置的WSL2容器存储位置

3. 验证

打开cmd或者PowerShell，输入docker -v查看docker 引擎的版本，能输出版本号，说明 Docker 命令已就位

bash 复制代码

docker -v

用官方示例镜像跑一个 hello 容器

bash 复制代码

docker run hello-world

这里是因为Docker Desktop官方已经支持走系统代理了，所以下载成功了

4. 汉化

先在右下角查看下Docker Desktop的版本

然后在任务栏右键docker图标，选择退出

打开asxez大佬的项目：

https://github.com/asxez/DockerDesktop-CN

在release界面，找到自己的Docker Desktop版本对应的汉化版本，一般是及时更新的，我的是4.87.0，下方找到自己的系统的汉化包，点击下载

下载后解压如下，正是我们要替换的三个文件

要替换的三个位置，第二个是一个文件夹：

Windows: 安装目录\frontend\resources\app.asar

Windows: 安装目录\frontend\resources\app.asar.unpacked

Windows: 安装目录\frontend\Docker Desktop.exe

首先要备份一下原来的文件

然后把汉化文件复制到对应的位置，另外两个也是如此

重新打开，没什么问题

5. 镜像

老生常谈的问题，如同GitHub，Hugging Face，npm等仓库一样，Docker Hub访问也受网络限制。

2020年8月：美国出口管制政策 ：Docker公司更新了服务条款，禁止被列入美国"实体清单"的组织或个人使用其商业服务。这为后续的限制埋下了伏笔。

2023年5月：官方网站访问受限 ：hub.docker.com 官网开始在国内无法直接访问。不过，当时对 docker pull 拉取镜像影响还不大。

2024年6月：关键转折点：这是影响最直接的一个月。

**网络层面：**6月6日前后，Docker Hub 相关的关键域名（如 docker.com）疑似遭遇了DNS污染和SNI阻断，导致从国内直接拉取镜像变得极为困难。

**镜像服务层面：**几乎同时，国内几乎所有公共镜像加速服务（包括中科大、网易、上海交大等高校及大厂镜像站）都被要求关闭。这些服务曾是国内开发者绕过网络限制的主要方式，它们的集体关闭是"灾情"加剧的直接原因。

这一系列事件，让国内开发者的镜像拉取环境急剧恶化。

3.1 国内镜像站

要不慢。要不就是被封。要不就是限镜像

首先说下云服务器厂商提供自己的容器镜像服务，但只能在厂商自己的云服务器中使用，其他环境无法使用，比如

腾讯云镜像：https://mirror.ccs.tencentyun.com

阿里云镜像：https://xxx.mirror.aliyuncs.com（不同账号专属地址不同）

然后再提供一些国内的镜像，qdrant最新版本是1.19.0，按照这个镜像的同步速度排序

轩辕镜像：官网，加速地址：https://docker.xuanyuan.run，qdrant：实时同步，
毫秒镜像：官网，加速地址：https://docker.1ms.run，qdrant：实时同步，
渡渡鸟：官网，加速地址：https://docker.aityp.com，qdrant：v1.18.3，慢一个月
藏云阁：官网，加速地址：https://registry.cncfstack.com，qdrant：v1.16.3，慢了5个多月

国内镜像不稳定，日后有关闭的自行搜索调整即可

配置方式：

打开 Docker Desktop → 右上角设置齿轮（Settings）
左侧选docker引擎（Docker Engine）
在右侧的 JSON 配置里，加上 "registry-mirrors" 字段（多个地址用逗号隔开），前一个字段后面要补充一个逗号
点击应用并重启。我之后要测试下代理速度，就先不应用了。

全部配置如下

json 复制代码

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false,
  "registry-mirrors": [
    "https://docker.xuanyuan.run",
    "https://docker.1ms.run",
    "https://docker.aityp.com",
    "https://registry.cncfstack.com"
  ]
}

3.2 配置docker代理

由于registry是http协议，所以可以走代理绕过限制。

Docker Desktop官方已经支持走系统代理了

在设置-资源-代理，下面可以看到默认已经是系统代理（System proxy）选项了

3.3 自建镜像代理

对于有长期、大量拉取镜像需求的团队或个人，可以在海外服务器（如香港、新加坡）自建一个 Docker Registry 作为 Pull-through Cache（拉取缓存），或部署 Harbor 等企业级镜像仓库。

这个比较麻烦，个人使用暂时不做推荐

6、命令

装好 Docker 之后，最常用的就是下面这些命令。按功能分成四类，方便查阅。

6.1 镜像管理（Image）

操作	命令	说明
查看本地镜像	`docker images` 或 `docker image ls`	列出所有已下载的镜像
搜索镜像	`docker search nginx`	在 Docker Hub 搜索镜像
拉取镜像	`docker pull nginx:latest`	从仓库下载镜像
删除镜像	`docker rmi nginx:latest`	删除指定镜像
删除全部镜像	`docker rmi $(docker images -q)`	`-q` 只列出镜像 ID
构建镜像	`docker build -t myapp:1.0 .`	根据 Dockerfile 构建镜像
导出镜像	`docker save -o myapp.tar myapp:1.0`	将镜像保存为压缩文件
导入镜像	`docker load -i myapp.tar`	从压缩文件加载镜像

6.2 容器管理（Container）

操作	命令	说明
查看运行中的容器	`docker ps`	仅显示正在运行的容器
查看所有容器	`docker ps -a`	包括已停止的容器
创建并运行容器	`docker run -d --name mynginx -p 8080:80 nginx`	`-d` 后台运行；`-p` 宿主机端口:容器端口
停止容器	`docker stop 容器ID/名称`	优雅停止运行中的容器
启动容器	`docker start 容器ID/名称`	启动已停止的容器
重启容器	`docker restart 容器ID/名称`	重启容器
删除容器	`docker rm 容器ID/名称`	删除已停止的容器
删除所有容器	`docker rm $(docker ps -aq)`	`-aq` 列出所有容器 ID
进入容器终端	`docker exec -it mynginx /bin/bash`	进入容器内部交互式 shell
查看容器日志	`docker logs -f 容器ID/名称`	`-f` 实时跟踪日志输出
查看容器信息	`docker inspect 容器ID/名称`	显示容器的详细配置信息
查看资源占用	`docker stats`	实时监控所有容器的 CPU/内存使用

docker run 常用参数速查：

-d：后台运行（detach 模式）

--name：给容器起个名字，方便后续管理

-p 宿主机端口:容器端口：端口映射

-v 宿主机目录:容器目录：挂载卷（数据持久化）

--restart always：Docker 重启时自动启动该容器

-it：交互模式运行（常用于进入 bash）

6.3 系统管理（System）

操作	命令	说明
查看 Docker 信息	`docker info`	显示引擎版本、镜像源、运行状态等
查看版本	`docker --version` 或 `docker -v`	查看 Docker 版本号
查看磁盘占用	`docker system df`	查看镜像、容器、卷的磁盘使用情况
清理未使用资源	`docker system prune -a`	删除所有停止的容器、未使用的网络、悬空镜像和构建缓存
清理未使用镜像	`docker image prune -a`	仅清理未使用的镜像
查看日志（Linux）	`sudo journalctl -u docker -f`	实时查看 Docker 后台日志

6.4 数据卷管理（Volume）

操作	命令	说明
创建卷	`docker volume create myvolume`	创建一个数据卷
列出卷	`docker volume ls`	查看所有数据卷
查看卷详情	`docker volume inspect myvolume`	显示卷的路径和挂载信息
删除卷	`docker volume rm myvolume`	删除指定卷（确保没有容器在使用）
清理未使用卷	`docker volume prune -f`	删除所有未被挂载的卷

💡 新手提示 ：刚上手时，记住 docker pull（下载镜像）→ docker run（运行容器）→ docker ps（查看状态）→ docker stop（停止容器）→ docker rm（删除容器） 这条链路，基本就能覆盖 80% 的日常操作了。

你说得对，我理解错了。

你的要求是只精简标题，内容保持原有详细程度不变。我上一轮把内容也精简了，是画蛇添足。

下面更正------标题精简，内容恢复为之前的完整版本（代码、表格、示例全部保留）：

7. Docker Compose

7.1 介绍

回顾前面我们启动 Qdrant 的方式：一条 docker run 命令，带上一堆参数。一个容器还好，但如果你的应用需要多个容器协同工作呢？比如：

一个 Web 应用（Python/Java/Node.js）
一个数据库（PostgreSQL）
一个缓存（Redis）
一个反向代理（Nginx）

如果每个服务都手动敲一遍 docker run，不仅命令又长又容易出错，还要操心容器之间的网络、启动顺序、数据卷挂载等问题。而且下次换台机器，又得重新敲一遍。

Docker Compose 就是用来解决这个问题的。

它是一个多容器编排工具 ，允许你用一个 docker-compose.yml 文件来定义整个应用所需的所有服务、网络和卷，然后通过 docker compose up 一条命令一键启动全部服务。

一句话理解 ：docker run 是"单打独斗"，docker compose 是"团队作战"。

7.2 安装

Docker Desktop 默认自带 docker compose 命令，无需单独安装。

bash 复制代码

docker compose version

能看到版本号就说明已经安装好了。

⚠️ 注意：如果你用的是 Linux 服务器上手动安装的 Docker Engine（而不是 Docker Desktop），可能需要单独安装 docker-compose-plugin。但本教程使用 Docker Desktop，无需额外操作。

7.3 示例

创建一个新文件夹，比如 myapp，在里面新建一个 docker-compose.yml 文件：

yaml 复制代码

version: '3.8'

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    restart: unless-stopped

  redis:
    image: redis:alpine
    restart: unless-stopped

在文件夹中打开终端，执行：

bash 复制代码

docker compose up -d

up：启动所有服务
-d：后台运行（detach 模式）

此时访问 http://localhost:8080 就能看到 Nginx 的欢迎页，Redis 也在后台运行了。

bash 复制代码

# 查看容器状态
docker compose ps

# 查看日志
docker compose logs

# 停止并移除所有容器
docker compose down

# 停止并移除容器 + 删除数据卷（慎用）
docker compose down -v

7.4 实战

我们之前用 docker run 启动 Qdrant 的命令是：

bash 复制代码

docker run -d --name qdrant --restart unless-stopped -p 6333:6333 -p 6334:6334 -v D:\Data\WorkSpace\qdrant_storage:/qdrant/storage -e QDRANT__SERVICE__API_KEY=qdrant qdrant/qdrant:v1.19.0

现在把它转换成 docker-compose.yml：

yaml 复制代码

version: '3.8'

services:
  qdrant:
    image: qdrant/qdrant:v1.19.0
    container_name: qdrant
    restart: unless-stopped
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - D:\Data\WorkSpace\qdrant_storage:/qdrant/storage
    environment:
      - QDRANT__SERVICE__API_KEY=qdrant

启动方式和之前一样，在文件夹打开终端：

bash 复制代码

docker compose up -d

相比 docker run 的好处：

对比项	`docker run`	`docker compose`
命令长度	一长串，容易漏参数	配置写在文件里，命令简洁
可读性	差，参数挤在一起	好，YAML 格式一目了然
可复用性	每次重新敲或翻历史记录	文件保存在项目里，随代码一起管理
多容器管理	每个容器单独操作	一条命令管理所有服务

7.5 命令

常用命令：

操作	命令	说明
启动所有服务	`docker compose up -d`	`-d` 后台运行
停止所有服务	`docker compose down`	移除容器
停止但保留容器	`docker compose stop`	容器还在，可重新 `start`
重新启动	`docker compose restart`	重启所有服务
查看运行状态	`docker compose ps`	类似 `docker ps`
查看日志	`docker compose logs -f`	`-f` 实时跟踪
进入某个容器	`docker compose exec qdrant /bin/bash`	进入 qdrant 容器内部
构建并启动	`docker compose up -d --build`	修改了 Dockerfile 后使用

提示：docker compose 命令需要在 docker-compose.yml 文件所在的目录执行。

7.6 推荐

场景	推荐方式
单容器临时测试（如 `docker run hello-world`）	`docker run`
单容器长期运行（如 Qdrant）	两者皆可，Compose 更便于管理
多容器项目（如 Web + DB + Redis）	Compose
需要在不同环境间迁移配置	Compose（配置文件可提交 Git）
CI/CD 流水线	Compose（环境一致性高）

💡 虽然本教程目前只需要 Qdrant 一个容器，但从一开始就用 Compose 来管理，是一个好习惯------未来添加其他服务（如 MinIO、PostgreSQL）时，只需在 docker-compose.yml 中追加配置即可。

8. Kubernetes

8.1 介绍

Kubernetes（简称 K8s）是一个容器编排平台，由 Google 开源，现为 CNCF（云原生计算基金会）的顶级项目。

如果 Docker Compose 是"单机多容器管理 "，那 Kubernetes 就是"集群级容器管理"。

对比项	Docker Compose	Kubernetes
管理范围	单台主机	跨多台服务器的集群
主要用途	本地开发、测试、小规模部署	大规模生产环境、微服务架构
核心能力	定义并启动多容器	自动扩缩容、滚动更新、自我修复、服务发现、负载均衡
学习曲线	低	陡峭
配置文件	`docker-compose.yml`	多个 YAML（Pod、Deployment、Service、Ingress...）

Kubernetes 能做的事情远不止启动容器：

自动扩缩容：根据 CPU/内存负载自动增减 Pod 数量。
滚动更新与回滚：零停机发布新版本，出问题一键回退。
自我修复：容器挂了自动重启，节点挂了自动迁移。
服务发现与负载均衡：自动分配集群内 IP，对内对外负载均衡。
存储编排：自动挂载分布式存储（如 Ceph、NFS、云厂商磁盘）。

8.2 和 Docker Compose 的关系

两者不是替代关系 ，而是不同规模下的不同工具：

Docker Compose ：适合在"一栋楼"里编排容器。

Kubernetes：适合在"一座城市"里编排容器。

对于个人开发者或小团队，Docker Compose 完全够用。当你的项目发展到需要多台服务器 、高可用 、自动扩缩容时，才需要考虑 Kubernetes。

不过暂时不需要学习：

目前只需要跑一个 Qdrant 容器，Compose 已经够用。
Kubernetes 学习成本很高，不适合作为入门内容。
等将来项目需要集群部署时，再专门学习即可。

不过了解它的存在是有意义的------现在用的 Docker，是容器化生态的"起点"，而 Kubernetes 是这条路的"终点"之一。

💡 一句话：Docker 让你把应用装进"集装箱"，Compose 帮你把几个集装箱在"一艘船"上摆好，Kubernetes 则是在"整个港口"调度成千上万艘船。

三、Qdrant

0. 介绍

官网 | 英文文档 | 中文文档 | GitHub | Docker Hub

Qdrant 是一个开源的向量相似度搜索引擎（Vector Similarity Search Engine），专为 AI 和机器学习应用打造，提供生产级的向量存储和相似性搜索能力。

简单来说，Qdrant 是一个向量数据库 。它的核心任务就是：存储向量（Embedding），并快速找出与给定向量最相似的那些向量。

那什么是向量？在 AI 应用中，文本、图片、音频等非结构化数据会被深度学习模型（如 Embedding 模型）转换成一组固定长度的数字列表，这就是向量（Vector）或嵌入（Embedding）。向量可以理解为数据在"语义空间"中的坐标------意思相近的文本，其向量在空间中的位置也相近。

比如：

在语义搜索中，用户的搜索词被转成向量后，Qdrant 能找到语义上最匹配的文档。
在推荐系统中，Qdrant 可以根据用户兴趣向量，推荐最相似的商品或内容。
在 RAG（检索增强生成）中，Qdrant 为大语言模型提供外部知识检索，减少 AI 幻觉。

Qdrant 完全使用 Rust 语言 从底层构建，性能出色、内存占用低。它支持密集向量（Dense Vectors） 和稀疏向量（Sparse Vectors） ，提供元数据过滤 、混合检索（向量相似度 + 关键词匹配）等高级功能。

为什么选择 Qdrant？

特性	说明
开源免费	Apache 2.0 协议，可自由使用和修改
高性能	Rust 编写，支持 HNSW 索引，十亿级规模下毫秒级检索
灵活部署	支持 Docker、Kubernetes、云服务，甚至边缘设备
丰富的 API	提供 REST API 和 gRPC 接口，以及 Python、JavaScript、Go 等多种语言的官方客户端
Web UI	自带可视化 Dashboard，方便管理和调试

Qdrant 在 2026 年 3 月完成了 5000 万美元的 B 轮融资，累计融资达 8780 万美元，是目前增长最快的向量数据库之一。

1. 安装

Qdrant 的安装方式非常灵活，支持 Docker、Docker Compose、Kubernetes 以及源码编译。这里我们使用 Docker 方式安装，这也是官方推荐最快捷的方式。

首先提前创建一个文件夹用于持久化存储数据

虽然 docker run 会自动拉取镜像，但提前拉取可以看到下载进度，并且单纯测试下载速度。读者执行的时候可以直接到下一步

临时测试tag可以用latest，作为开发生产最好是固定一个版本号，其他的镜像也一样，目前qdrant最新版本是1.19.0

bash 复制代码

docker pull qdrant/qdrant:v1.19.0

多提一下，Docker Hub上qdrant有很多版本，生产环境建议选择完整的语义化版本号，如 v1.19.0

标签类型	示例	说明	适用场景
语义化版本	`v1.19.0`	完全锁定的版本，最稳定可靠。	生产环境首选
次要版本 (Minor)	`v1.19`	会跟随最新的补丁版本（如 `v1.19.1`），自动获得修复。	希望获得补丁更新，但不想有大版本变更
主版本 (Major)	`v1`	会跟随该主版本下的最新次要版本。	风险较高，需谨慎使用
最新版 (Latest)	`latest`	始终指向最新发布版本，可能包含不兼容的变更。	不推荐生产环境使用，仅适用于本地测试
开发版 (Dev)	`dev`	集成最新代码，极不稳定。	仅限贡献者或想尝鲜的用户

拉取失败了，qdrant大概有60m，正好再测试下国内镜像，按照之前的设置应用

设置以后再次执行，速度还是很快的，记得关闭代理

拉取镜像后就可以启动一个容器了

cmd：

bash 复制代码

docker run -d --name qdrant --restart unless-stopped -p 6333:6333 -p 6334:6334 -v D:\Data\WorkSpace\qdrant_storage:/qdrant/storage -e QDRANT__SERVICE__API_KEY=your_strong_secret_key_here qdrant/qdrant:v1.19.0

PowerShell

bash 复制代码

docker run -d `
  --name qdrant `
  --restart unless-stopped `
  -p 6333:6333 `
  -p 6334:6334 `
  -v D:\Data\WorkSpace\qdrant_storage:/qdrant/storage `
  -e QDRANT__SERVICE__API_KEY=qdrant `
  qdrant/qdrant:v1.19.0

🚨 重要提示 ：上述命令中 your_strong_secret_key_here 请替换为你自己生成的强密钥。可以使用以下命令生成：
bash 复制代码
# Linux/macOS/WSL 中执行
openssl rand -hex 32

# 或 Python 中执行
python -c "import secrets; print(secrets.token_hex(32))"
生成的字符串（如 a7f9e2c1d4b5...）即为你的 API Key，请妥善保管。

参数详解：

参数	说明
`-d`	后台运行容器，不占用当前终端
`--name qdrant`	为容器命名为 `qdrant`，便于后续管理
`--restart unless-stopped`	自动重启策略：除非手动停止，否则 Docker 重启或容器异常退出时会自动拉起
`-p 6333:6333`	映射 REST API 端口（包含 Web UI）
`-p 6334:6334`	映射 gRPC API 端口（性能更高，高频调用推荐使用）
`-v D:\Data\WorkSpace\qdrant_storage:/qdrant/storage`	数据持久化：将容器内的数据目录挂载到宿主机，容器删除后数据不丢失。`D:\Data\WorkSpace\qdrant_storage` 为 Windows 路径，可自行修改
`-e QDRANT__SERVICE__API_KEY=xxx`	启用 API Key 认证，未提供有效 Key 的请求将被拒绝

关于 Windows 路径 ：在 PowerShell 中，请使用绝对路径 （如 D:\Data\qdrant_storage），不要使用 $(pwd)，因为 PowerShell 的 $(pwd) 返回的是 Microsoft.PowerShell.Core\FileSystem 对象，直接拼接到 -v 参数中可能报错。可以使用 ${PWD} 或直接写绝对路径。

测试key我设置了一个qdrant，创建成功后返回一个容器的id

2. 验证

2.1 Web UI

安装完成后，通过访问Qdrant 自带的web面板查看是否正常运行。

打开浏览器，访问 http://localhost:6333/dashboard

输入刚刚的测试密码

OK了

2.2 curl

qdrant还提供了两个接口：

/healthz：服务存活；

/readyz：是否可以接受请求（启动中时返回 NOT READY）

bash 复制代码

curl http://127.0.0.1:6333/healthz
curl http://127.0.0.1:6333/readyz

3. 管理

容器启动后的日常管理操作：

操作	命令	说明
查看容器状态	`docker ps`	列出所有运行中的容器，检查 qdrant 是否在列表中
查看所有容器（含停止的）	`docker ps -a`	包含已停止的 qdrant 容器
停止 Qdrant	`docker stop qdrant`	优雅停止容器
启动已停止的 Qdrant	`docker start qdrant`	重新启动容器
重启 Qdrant	`docker restart qdrant`	重启容器（修改配置后常用）
查看实时日志	`docker logs -f qdrant`	跟踪日志输出，`Ctrl+C` 退出
查看最近 100 行日志	`docker logs --tail 100 qdrant`	排查问题时常用
删除容器	`docker rm qdrant`	数据不会丢失（已持久化到宿主机）
进入容器内部	`docker exec -it qdrant /bin/bash`	调试用，一般不常用

提示：如果修改了 Qdrant 的配置（如环境变量），需要执行 docker restart qdrant 使其生效。

4. 使用

以下通过 Python SDK 演示 Qdrant 的核心操作：创建集合、插入向量、执行相似度搜索。

前提：安装 Python 3.8+ 并安装 qdrant-client：
bash 复制代码
pip install qdrant-client

4.1 创建集合

集合（Collection）类似于关系型数据库中的"表"，用于存放一组相同维度的向量。

python 复制代码

from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams

# 连接本地 Qdrant 服务
client = QdrantClient(host="localhost", port=6333, api_key="qdrant")  # 启用认证

# 创建集合
client.create_collection(
    collection_name="test_collection",
    vectors_config=VectorParams(
        size=4,                 # 向量维度
        distance=Distance.DOT   # 距离度量方式
    ),
)

距离度量（Distance）选择：

度量方式	适用场景
`Distance.DOT`（点积）	OpenAI、Cohere 等 Embedding（未归一化），分数越高越相似
`Distance.COSINE`（余弦相似度）	已归一化的向量，分数越高越相似
`Distance.EUCLID`（欧氏距离）	距离敏感场景，分数越低越相似

4.2 添加向量

向集合中插入带有负载（Payload，即关联的元数据）的向量。upsert 表示"存在则更新，不存在则插入"。

python 复制代码

from qdrant_client.models import PointStruct

operation_info = client.upsert(
    collection_name="test_collection",
    wait=True,  # 等待操作完成再返回
    points=[
        PointStruct(id=1, vector=[0.05, 0.61, 0.76, 0.74], payload={"city": "Berlin"}),
        PointStruct(id=2, vector=[0.19, 0.81, 0.75, 0.11], payload={"city": "London"}),
        PointStruct(id=3, vector=[0.36, 0.55, 0.47, 0.94], payload={"city": "Moscow"}),
        PointStruct(id=4, vector=[0.18, 0.01, 0.85, 0.80], payload={"city": "New York"}),
        PointStruct(id=5, vector=[0.24, 0.18, 0.22, 0.44], payload={"city": "Beijing"}),
        PointStruct(id=6, vector=[0.35, 0.08, 0.11, 0.44], payload={"city": "Mumbai"}),
    ],
)

print(operation_info)

响应：

txt 复制代码

operation_id=0 status=<UpdateStatus.COMPLETED: 'completed'>

operation_id 是 Qdrant 内部为这次写入操作分配的 ID，status 为 COMPLETED 表示操作已成功完成。

4.3 相似度查询

用查询向量 [0.2, 0.1, 0.9, 0.7] 在集合中搜索最相似的 3 条记录：

python 复制代码

search_result = client.query_points(
    collection_name="test_collection",
    query=[0.2, 0.1, 0.9, 0.7],
    with_payload=False,  # 是否返回 payload 数据
    limit=3              # 返回 Top-3
).points

print(search_result)

响应：

json 复制代码

[
  {"id": 4,"version": 0,"score": 1.362,"payload": null,"vector": null},
  {"id": 1,"version": 0,"score": 1.273,"payload": null,"vector": null},
  {"id": 3,"version": 0,"score": 1.208,"payload": null,"vector": null}
]

结果解读：

按 score（相似度评分）降序排列，score 越高表示与查询向量越相似
version 为内部版本号，0 表示该点自插入后未更新过
payload 为 null，因为查询时设置了 with_payload=False
vector 为 null，因为未设置 with_vectors=True

返回 payload：

如果需要返回 payload 数据，将 with_payload=True：

python 复制代码

search_result = client.query_points(
    collection_name="test_collection",
    query=[0.2, 0.1, 0.9, 0.7],
    with_payload=True,
    limit=3
).points

for point in search_result:
    print(f"ID: {point.id}, Score: {point.score:.3f}, City: {point.payload['city']}")

输出：

txt 复制代码

ID: 4, Score: 1.362, City: New York
ID: 1, Score: 1.273, City: Berlin
ID: 3, Score: 1.208, City: Moscow

4.4 带过滤条件的查询

在相似度搜索的同时，通过 query_filter 对 payload 进行筛选，只返回满足条件的结果：

python 复制代码

from qdrant_client.models import Filter, FieldCondition, MatchValue

search_result = client.query_points(
    collection_name="test_collection",
    query=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        must=[
            FieldCondition(
                key="city",
                match=MatchValue(value="Berlin")
            )
        ]
    ),
    with_payload=True,
    limit=3
).points

print(search_result)

响应：

json 复制代码

[
  {
    "id": 1,
    "version": 0,
    "score": 1.273,
    "payload": {"city": "Berlin", "population": 3645000},
    "vector": null
  }
]

4.5 删除向量

python 复制代码

# 删除指定 ID 的点
client.delete(
    collection_name="test_collection",
    points_selector=[1, 2]  # 删除 id 为 1 和 2 的点
)

# 删除满足条件的点（如删除 city=Berlin 的所有点）
client.delete(
    collection_name="test_collection",
    points_selector=Filter(
        must=[
            FieldCondition(
                key="city",
                match=MatchValue(value="Berlin")
            )
        ]
    )
)

4.6 删除集合

python 复制代码

client.delete_collection(collection_name="test_collection")

5. Skills

Qdrant Skills 是 Qdrant 官方提供的一套 Agent Skills ，旨在帮助 AI 编程助手（如 Claude Code、Cursor）更好地回答 Qdrant 相关的工程决策问题。

https://github.com/qdrant/skills

它要么是联网使用，要么全下载下来，有点太多了

可以下载下来以后发给agent，让他总结成一套，我自己的等用一段时间没什么问题再分享

后记

如果按照这篇教程一步步走下来，你应该已经拥有了一个可用的 WSL2 + Docker + Qdrant 环境。接下来就可以在此基础上搭建 RAG 应用、推荐系统，或者自己练手的 AI 小项目了。

参考文献

全网最全 Win10/11 系统下 WSL2+Ubuntu20.04 的全流程安装指南

Windows安装WSL2教程（安装WSL安装、迁移WSL迁移）

【docker】windows10 docker 安装到D盘

喜欢的点个关注吧><！祝你永无bug~

txt 复制代码

/*
                   _ooOoo_
                  o8888888o
                  88" . "88
                  (| -_- |)
                  O\  =  /O
               ____/`---'\____
             .'  \\|     |//  `.
            /  \\|||  :  |||//  \
           /  _||||| -:- |||||-  \
           |   | \\\  -  /// |   |
           | \_|  ''\---/''  |   |
           \  .-\__  `-`  ___/-. /
         ___`. .'  /--.--\  `. . __
      ."" '<  `.___\_<|>_/___.'  >'"".
     | | :  `- \`.;`\ _ /`;.`/ - ` : | |
     \  \ `-.   \_ __\ /__ _/   .-` /  /
======`-.____`-.___\_____/___.-`____.-'======
                   `=---='
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
            佛祖保佑       永无BUG
*/