Milvus 单机版 — WSL2 启动笔记（Windows + Docker）

场景：Windows 系统，已安装 WSL2 + Docker Desktop，compose 文件放在 F 盘。 目标：在 WSL2 终端中启动 Milvus 单机版（etcd + MinIO + Milvus）。

---

一、核心原则：路径怎么写

WSL 访问 Windows 磁盘时，盘符会被挂载到 /mnt/ 下，所有 \ 换成 /，盘符改为小写。

⚠️ WSL 终端里必须用正斜杠 /，不能写 F:\，否则会报错。

---

二、启动步骤（方案二：WSL 终端）

1. 前置检查

# 确认 Docker 可用（Docker Desktop 需先启动）
docker --version
docker compose version

若提示命令不存在，检查 Docker Desktop → Settings → Resources → WSL Integration，确认你的发行版已勾选并重启。

2. 进入文件目录

假设 milvus-standalone-docker-compose.yml 放在 F:\milvus\：

cd /mnt/f/milvus
ls   # 确认能看到 milvus-standalone-docker-compose.yml

3. 启动 Milvus（后台运行）

docker compose -f ./milvus-standalone-docker-compose.yml up -d

4. 验证

docker compose ps

三个容器均显示 Up (healthy) 即成功：

• milvus-etcd（元数据管理，端口 2379）
• milvus-minio（对象存储，端口 9000/9001）
• milvus-standalone（向量服务，端口 19530/9091）

---

三、常用命令速查

# 停止（保留容器和数据卷）
docker compose -f ./milvus-standalone-docker-compose.yml stop

# 停止并删除容器（保留数据卷）
docker compose -f ./milvus-standalone-docker-compose.yml down

# 彻底重置（删除容器 + 数据卷，慎用！）
docker compose -f ./milvus-standalone-docker-compose.yml down -v

# 查看实时日志
docker compose -f ./milvus-standalone-docker-compose.yml logs -f

# 仅看某个服务日志
docker compose logs -f milvus-standalone

---

四、常见坑 & 解决方案

1️⃣ F 盘（非 C 盘）找不到文件

现象：no such file or directory 原因：Docker Desktop 默认只共享 C 盘。 解决：Docker Desktop → Settings → Resources → WSL Integration / File Sharing → 勾选对应磁盘 → Apply & Restart。

2️⃣ 权限错误 / etcd、MinIO 健康检查失败

现象：容器反复重启，permission denied 原因：Milvus 官方建议数据卷放在 Linux 文件系统，NTFS 跨挂载对 Unix 权限敏感。 解决：把 yml 里的 volumes 改到 WSL 路径，如：

volumes:
  - /home/你的用户名/milvus-data/etcd:/etcd
  - /home/你的用户名/milvus-data/minio:/minio_data

3️⃣ 端口占用（19530 / 9091 等）

排查：

# WSL 内
ss -lntp | grep :19530

解决：在 yml 里改端口映射，如 "19531:19530"。

4️⃣ 内存不足（OOM）

要求：WSL2 至少 4GB，Milvus 单机建议 8-16GB。 解决：编辑 Windows 用户目录下的 .wslconfig（%UserProfile%\.wslconfig）：

[wsl2]
memory=8GB

改完后重启 WSL：wsl --shutdown，再重新打开终端。

5️⃣ 配置改乱了想重置

docker compose -f ./milvus-standalone-docker-compose.yml down -v
# 删除 volumes 目录后重新 up -d

---

五、官方建议小结

• 开发 / 测试：单机版足够。
• 生产环境：使用 Milvus Cluster（集群版）。
• 数据卷位置：优先放在 WSL 的 Linux 文件系统（~/、/home/...），性能和稳定性更好；直接从 /mnt/f 挂载 NTFS 可能踩权限坑。

---

六、一键复制版（完整流程）

# 进入 F 盘的 milvus 目录
cd /mnt/f/milvus

# 启动
docker compose -f ./milvus-standalone-docker-compose.yml up -d

# 检查状态
docker compose ps

# 查看日志（确认无报错）
docker compose logs -f milvus-standalone

---