环境搭建与安装

系统要求

硬件要求

组件	最低配置	推荐配置
CPU	4 核	8 核及以上
内存	8 GB	16 GB 及以上
磁盘	50 GB SSD	100 GB SSD 及以上
GPU	可选	NVIDIA GPU（用于 GPU 索引）

软件要求

Docker 20.10.0 或更高版本
Docker Compose 2.0.0 或更高版本
Python 3.8 或更高版本（用于 Python SDK）

安装方式

方式一：Docker Compose 安装（推荐）

这是最简单、最常用的安装方式，适合开发和测试环境。

Linux 系统安装

步骤 1：下载安装脚本

bash

# 创建 Milvus 工作目录
mkdir -p ~/milvus
cd ~/milvus

# 下载 Docker Compose 配置文件
wget https://github.com/milvus-io/milvus/releases/download/v2.4.0/milvus-standalone-docker-compose.yml -O docker-compose.yml

步骤 2：启动 Milvus 服务

bash

# 启动服务
docker-compose up -d

# 查看服务状态
docker-compose ps

步骤 3：验证安装

bash

# 检查容器是否正常运行
docker ps

# 查看日志
docker logs milvus-standalone

macOS 系统安装

步骤 1：安装 Docker Desktop

bash

# 使用 Homebrew 安装
brew install --cask docker

# 或从官网下载安装
# https://www.docker.com/products/docker-desktop

步骤 2：下载并启动 Milvus

bash

# 创建 Milvus 工作目录
mkdir -p ~/milvus
cd ~/milvus

# 下载配置文件
curl -L https://github.com/milvus-io/milvus/releases/download/v2.4.0/milvus-standalone-docker-compose.yml -o docker-compose.yml

# 启动服务
docker-compose up -d

步骤 3：验证安装

bash

# 检查容器状态
docker ps

# 查看日志
docker logs milvus-standalone

macOS 注意事项：

确保 Docker Desktop 已启动
在 Docker Desktop 设置中分配足够的内存（建议至少 8GB）
如果使用的是 Apple Silicon (M1/M2)，确保启用 Rosetta 2

Windows 系统安装

步骤 1：安装 Docker Desktop

下载 Docker Desktop for Windows
- 访问 https://www.docker.com/products/docker-desktop
- 下载并安装

启用 WSL 2 后端（推荐）

powershell

# 以管理员身份运行 PowerShell
wsl --install

# 设置 WSL 默认版本为 2
wsl --set-default-version 2

步骤 2：下载并启动 Milvus

powershell

# 创建 Milvus 工作目录
New-Item -ItemType Directory -Force -Path ~
milvus
Set-Location ~
milvus

# 下载配置文件
Invoke-WebRequest -Uri "https://github.com/milvus-io/milvus/releases/download/v2.4.0/milvus-standalone-docker-compose.yml" -OutFile "docker-compose.yml"

# 启动服务
docker-compose up -d

步骤 3：验证安装

powershell

# 检查容器状态
docker ps

# 查看日志
docker logs milvus-standalone

Windows 注意事项：

确保在 Docker Desktop 设置中启用 WSL 2 后端
分配足够的内存（建议 8GB 以上）
防火墙可能需要放行 19530 端口

方式二：Kubernetes 安装（生产环境）

适合大规模生产环境的分布式部署。

使用 Helm 安装

bash

# 添加 Milvus Helm 仓库
helm repo add milvus https://zilliztech.github.io/milvus-helm/
helm repo update

# 安装 Milvus
helm install my-milvus milvus/milvus

# 查看安装状态
kubectl get pods

方式三：源码编译安装

适合需要定制或贡献代码的开发者。目前仅支持 Linux 系统。

Linux 系统编译安装

环境准备

bash

# 安装依赖（Ubuntu/Debian）
sudo apt-get update
sudo apt-get install -y build-essential libssl-dev

# 安装依赖（CentOS/RHEL）
sudo yum groupinstall -y "Development Tools"
sudo yum install -y openssl-devel

# 安装 Go（需要 1.18+）
# 访问 https://golang.org/dl/ 下载安装

# 安装 CMake（需要 3.18+）
# 访问 https://cmake.org/download/ 下载安装

编译安装步骤

bash

# 克隆源码
git clone https://github.com/milvus-io/milvus.git
cd milvus

# 安装依赖并编译
./scripts/install_deps.sh
make

# 启动服务
./scripts/start_services.sh

注意事项：

编译需要大量内存（建议 16GB 以上）
首次编译时间较长（可能需要 30 分钟以上）
确保网络连接正常，需要下载大量依赖

Python SDK 安装

安装前准备

Linux 系统

bash

# 确保 Python 3.8+ 已安装
python3 --version

# 安装 pip（如未安装）
sudo apt-get install -y python3-pip  # Ubuntu/Debian
sudo yum install -y python3-pip      # CentOS/RHEL

macOS 系统

bash

# 使用 Homebrew 安装 Python
brew install python@3.11

# 或使用 pyenv 管理 Python 版本
brew install pyenv
pyenv install 3.11.0
pyenv global 3.11.0

Windows 系统

powershell

# 从官网下载 Python 安装包
# https://www.python.org/downloads/

# 或使用 Chocolatey
choco install python

# 验证安装
python --version
pip --version

安装 pymilvus

所有操作系统通用安装

bash

# 基础安装
pip install pymilvus

# 安装指定版本
pip install pymilvus==2.4.0

# 安装包含额外依赖（如 protobuf）
pip install pymilvus[model]

Linux/macOS 虚拟环境安装（推荐）

bash

# 创建虚拟环境
python3 -m venv milvus_env

# 激活虚拟环境
source milvus_env/bin/activate  # Linux/macOS

# 安装 pymilvus
pip install pymilvus

Windows 虚拟环境安装（推荐）

powershell

# 创建虚拟环境
python -m venv milvus_env

# 激活虚拟环境
.\milvus_env\Scripts\activate

# 安装 pymilvus
pip install pymilvus

验证安装

python

import pymilvus

# 查看版本
print(f"PyMilvus 版本: {pymilvus.__version__}")

# 测试导入
from pymilvus import connections, FieldSchema, CollectionSchema, DataType, Collection
print("所有模块导入成功！")

操作系统特定注意事项

Linux 注意事项

某些发行版可能需要安装 python3-dev 包

bash

sudo apt-get install -y python3-dev  # Ubuntu/Debian
sudo yum install -y python3-devel    # CentOS/RHEL

macOS 注意事项

如果使用 Apple Silicon (M1/M2)，可能需要安装 Rosetta 2
bash
```
softwareupdate --install-rosetta
```
某些依赖可能需要 Xcode Command Line Tools
bash
```
xcode-select --install
```

Windows 注意事项

确保 Python 和 pip 已添加到系统 PATH
安装时可能需要 Visual C++ Build Tools
如果遇到权限问题，使用管理员权限运行 PowerShell

安装 Attu（图形化管理工具）

Attu 是 Milvus 的官方图形化管理界面，方便进行可视化管理。

Docker 安装 Attu（全平台通用）

bash

# 运行 Attu 容器
docker run -p 8000:3000 -e MILVUS_URL=localhost:19530 zilliz/attu:latest

访问 http://localhost:8000 即可使用 Attu。

桌面版安装

Linux 桌面版

bash

# 下载 AppImage 版本
wget https://github.com/zilliztech/attu/releases/latest/download/attu-linux.AppImage

# 添加执行权限
chmod +x attu-linux.AppImage

# 运行
./attu-linux.AppImage

macOS 桌面版

bash

# 使用 Homebrew 安装
brew install --cask attu

# 或下载 DMG 安装包
# 访问 https://github.com/zilliztech/attu/releases 下载

macOS 注意事项：

如果提示 "无法打开，因为无法验证开发者"，前往系统偏好设置 > 安全性与隐私 > 通用，点击 "仍要打开"
Apple Silicon 版本可能需要 Rosetta 2

Windows 桌面版

powershell

# 下载安装包
# 访问 https://github.com/zilliztech/attu/releases 下载 .exe 安装程序

# 或使用 Chocolatey
choco install attu

# 或使用 Winget
winget install Attu

Windows 注意事项：

安装时可能需要管理员权限
如果防火墙提示，允许 Attu 访问网络
首次启动可能需要几分钟初始化

配置说明

Docker Compose 配置文件详解

yaml

version: "3.5"

services:
  etcd:
    container_name: milvus-etcd
    image: quay.io/coreos/etcd:v3.5.5
    environment:
      - ETCD_AUTO_COMPACTION_MODE=revision
      - ETCD_AUTO_COMPACTION_RETENTION=1000
      - ETCD_QUOTA_BACKEND_BYTES=4294967296
      - ETCD_SNAPSHOT_COUNT=50000
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/etcd:/etcd
    command: etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
    healthcheck:
      test: ["CMD", "etcdctl", "endpoint", "health"]
      interval: 30s
      timeout: 20s
      retries: 3

  minio:
    container_name: milvus-minio
    image: minio/minio:RELEASE.2023-03-20T20-16-18Z
    environment:
      MINIO_ACCESS_KEY: minioadmin
      MINIO_SECRET_KEY: minioadmin
    ports:
      - "9001:9001"
      - "9000:9000"
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/minio:/minio_data
    command: minio server /minio_data --console-address ":9001"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3

  standalone:
    container_name: milvus-standalone
    image: milvusdb/milvus:v2.4.0
    command: ["milvus", "run", "standalone"]
    environment:
      ETCD_ENDPOINTS: etcd:2379
      MINIO_ADDRESS: minio:9000
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/milvus:/var/lib/milvus
    ports:
      - "19530:19530"
      - "9091:9091"
    depends_on:
      - etcd
      - minio

关键配置项说明

配置项	说明	默认值
`ETCD_ENDPOINTS`	etcd 服务地址	`etcd:2379`
`MINIO_ADDRESS`	MinIO 对象存储地址	`minio:9000`
`MINIO_ACCESS_KEY`	MinIO 访问密钥	`minioadmin`
`MINIO_SECRET_KEY`	MinIO 密钥	`minioadmin`

常用操作命令

启动和停止服务

Linux/macOS

bash

# 启动服务
docker-compose up -d

# 停止服务
docker-compose down

# 停止并删除数据卷
docker-compose down -v

# 重启服务
docker-compose restart

# 查看日志
docker-compose logs -f standalone

# 查看所有容器状态
docker-compose ps

Windows

powershell

# 启动服务
docker-compose up -d

# 停止服务
docker-compose down

# 停止并删除数据卷
docker-compose down -v

# 重启服务
docker-compose restart

# 查看日志
docker-compose logs -f standalone

# 查看所有容器状态
docker-compose ps

数据备份

Linux/macOS

bash

# 备份数据目录
cp -r volumes/milvus /backup/milvus-$(date +%Y%m%d)

# 备份 etcd 数据
cp -r volumes/etcd /backup/etcd-$(date +%Y%m%d)

# 创建压缩备份
tar -czvf milvus-backup-$(date +%Y%m%d).tar.gz volumes/

Windows

powershell

# 备份数据目录（PowerShell）
$date = Get-Date -Format "yyyyMMdd"
Copy-Item -Path "volumes\milvus" -Destination "\backup\milvus-$date" -Recurse

# 备份 etcd 数据
Copy-Item -Path "volumes\etcd" -Destination "\backup\etcd-$date" -Recurse

# 使用 7-Zip 创建压缩备份
7z a milvus-backup-$date.zip volumes\

数据恢复

Linux/macOS

bash

# 停止服务
docker-compose down

# 恢复数据
cp -r /backup/milvus-20240115 volumes/milvus
cp -r /backup/etcd-20240115 volumes/etcd

# 重启服务
docker-compose up -d

Windows

powershell

# 停止服务
docker-compose down

# 恢复数据
$date = "20240115"
Copy-Item -Path "\backup\milvus-$date" -Destination "volumes\milvus" -Recurse -Force
Copy-Item -Path "\backup\etcd-$date" -Destination "volumes\etcd" -Recurse -Force

# 重启服务
docker-compose up -d

常见问题

端口冲突

如果 19530 端口被占用，可以修改 docker-compose.yml：

yaml

ports:
  - "19531:19530" # 将主机端口改为 19531

内存不足

Linux/macOS

如果遇到内存不足问题，可以调整 Milvus 配置：

yaml

environment:
  - MILVUS_CACHE_SIZE=2048 # 设置缓存大小为 2GB

Windows

在 Docker Desktop 设置中调整：

打开 Docker Desktop
点击 Settings（设置）
选择 Resources（资源）
调整 Memory（内存）到 8GB 或更高
点击 Apply & Restart（应用并重启）

连接失败

Linux

检查防火墙设置：

bash

# 检查防火墙状态
sudo systemctl status firewalld

# 开放端口
sudo firewall-cmd --permanent --add-port=19530/tcp
sudo firewall-cmd --reload

# 或使用 ufw
sudo ufw allow 19530/tcp

macOS

bash

# 检查防火墙设置
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# macOS 防火墙通常不会阻止本地连接
# 如果使用的是第三方防火墙，请手动放行 19530 端口

Windows

powershell

# 以管理员身份运行 PowerShell
# 检查防火墙规则
Get-NetFirewallRule -DisplayName "*Milvus*"

# 添加入站规则
New-NetFirewallRule -DisplayName "Milvus" -Direction Inbound -LocalPort 19530 -Protocol TCP -Action Allow

# 或者临时关闭防火墙（不推荐用于生产环境）
Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled False

确保以下端口开放：

19530: Milvus gRPC 端口
9091: Milvus 指标端口
8000: Attu 端口（如果使用）

操作系统特定问题

Linux 问题

问题：权限被拒绝

bash

# 解决：将用户添加到 docker 组
sudo usermod -aG docker $USER
# 重新登录或执行
newgrp docker

问题：磁盘空间不足

bash

# 查看磁盘使用
df -h

# 清理 Docker 空间
docker system prune -a

macOS 问题

问题：Docker Desktop 无法启动

确保 macOS 版本支持 Docker Desktop
重启 Docker Desktop
重置 Docker Desktop 到出厂设置

问题：端口被占用

bash

# 查找占用端口的进程
lsof -i :19530

# 终止进程
kill -9 <PID>

Windows 问题

问题：WSL 2 后端未启用

powershell

# 启用 WSL 2
wsl --install

# 设置默认版本
wsl --set-default-version 2

# 重启计算机

问题：Hyper-V 未启用

powershell

# 以管理员身份运行
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

# 或者通过控制面板启用
# 控制面板 -> 程序 -> 启用或关闭 Windows 功能 -> 勾选 Hyper-V

问题：路径格式错误

powershell

# Windows 路径需要使用双反斜杠或正斜杠
# 错误示例
volumes:\milvus\data

# 正确示例
volumes:/milvus/data
# 或
volumes: "C:\\milvus\\data"

下一步

完成环境搭建后，你可以：

环境搭建与安装 ​

系统要求 ​

硬件要求 ​

软件要求 ​

安装方式 ​

方式一：Docker Compose 安装（推荐） ​

Linux 系统安装 ​

macOS 系统安装 ​

Windows 系统安装 ​

方式二：Kubernetes 安装（生产环境） ​

使用 Helm 安装 ​

方式三：源码编译安装 ​

Linux 系统编译安装 ​

Python SDK 安装 ​

安装前准备 ​

Linux 系统 ​

macOS 系统 ​

Windows 系统 ​

安装 pymilvus ​

所有操作系统通用安装 ​

Linux/macOS 虚拟环境安装（推荐） ​

Windows 虚拟环境安装（推荐） ​

验证安装 ​

操作系统特定注意事项 ​

Linux 注意事项 ​

macOS 注意事项 ​

Windows 注意事项 ​

安装 Attu（图形化管理工具） ​

Docker 安装 Attu（全平台通用） ​

桌面版安装 ​

Linux 桌面版 ​

macOS 桌面版 ​

Windows 桌面版 ​

配置说明 ​

Docker Compose 配置文件详解 ​

关键配置项说明 ​

常用操作命令 ​

启动和停止服务 ​

Linux/macOS ​

Windows ​

数据备份 ​

Linux/macOS ​

Windows ​

数据恢复 ​

Linux/macOS ​

Windows ​

常见问题 ​

端口冲突 ​

内存不足 ​

Linux/macOS ​

Windows ​

连接失败 ​

Linux ​

macOS ​

Windows ​

操作系统特定问题 ​

Linux 问题 ​

macOS 问题 ​

Windows 问题 ​

下一步 ​

环境搭建与安装

系统要求

硬件要求

软件要求

安装方式

方式一：Docker Compose 安装（推荐）

Linux 系统安装

macOS 系统安装

Windows 系统安装

方式二：Kubernetes 安装（生产环境）

使用 Helm 安装

方式三：源码编译安装

Linux 系统编译安装

Python SDK 安装

安装前准备

Linux 系统

macOS 系统

Windows 系统

安装 pymilvus

所有操作系统通用安装

Linux/macOS 虚拟环境安装（推荐）

Windows 虚拟环境安装（推荐）

验证安装

操作系统特定注意事项

Linux 注意事项

macOS 注意事项

Windows 注意事项

安装 Attu（图形化管理工具）

Docker 安装 Attu（全平台通用）

桌面版安装

Linux 桌面版

macOS 桌面版

Windows 桌面版

配置说明

Docker Compose 配置文件详解

关键配置项说明

常用操作命令

启动和停止服务

Linux/macOS

Windows

数据备份

Linux/macOS

Windows

数据恢复

Linux/macOS

Windows

常见问题

端口冲突

内存不足

Linux/macOS

Windows

连接失败

Linux

macOS

Windows

操作系统特定问题

Linux 问题

macOS 问题

Windows 问题

下一步