mac 使用 Docker 安装向量数据库Milvus独立版的保姆级别教程

Milvus

• 特点：开源的云原生向量数据库，支持多种索引类型和GPU加速，能够在亿级向量规模下实现低延迟高吞吐。具有灵活的部署选项和强大的社区支持。

• 适用场景：适合处理超大规模数据和高性能需求的应用，如图像搜索、推荐系统和自然语言处理。

• 了解更多关于Milvus的信息

一、环境准备

1. 硬件要求

• 内存：至少 8GB（推荐 16GB+），Milvus 依赖的 etcd 和 MinIO 组件会占用约 4GB 内存。
• 磁盘：至少 50GB 可用空间（存储向量数据和索引）。
• CPU：双核 Intel 或 Apple Silicon（M1/M2）芯片。

2. 软件要求

• macOS 版本：10.14（Mojave）或更高版本（如 macOS 14 Sonoma）。
• Docker Desktop：安装最新版（支持 Apple Silicon 芯片的 ARM 架构镜像）。

---

二、安装 Docker Desktop

1. 下载 Docker Desktop

   访问 Docker 官网，下载适合 macOS 的版本（支持 Intel 和 Apple Silicon）。

2. 安装并启动 Docker

   • 双击下载的 .dmg 文件，将 Docker 图标拖入 Applications 文件夹。
   • 打开 Docker Desktop，首次启动时需授权权限（如访问文件系统、网络等）。
   • 登录 Docker Hub 账号（可选，但推荐以便拉取镜像）。

3. 验证 Docker 是否安装成功

   在终端运行以下命令：

   docker --version
   docker-compose --version  # 确保 Docker Compose 已集成（v2.x+）

   输出：

三、安装 Milvus 独立版

**1.**拉取 Milvus 镜像

docker pull milvusdb/milvus:v2.3.12

2.创建配置文件目录

mkdir -p ~/milvus/conf

cd ~/milvus

3. 下载 Milvus 的 Docker Compose 配置文件

在终端运行以下命令，下载 Milvus 官方提供的 docker-compose.yml 文件（以 Milvus v2.3.12 为例）：

wget https://github.com/milvus-io/milvus/releases/download/v2.3.12/milvus-standalone-docker-compose.yml -O docker-compose.yml

在 macOS 终端中遇到 command not found: wget 错误，通常是因为系统未安装 wget 工具。wget 是一个常用的命令行工具，用于从网络下载文件（支持 HTTP、HTTPS 和 FTP 协议）。以下是解决方法：

方法1： 用 curl -o docker-compose.yml [URL]

方法2 ：通过 Homebrew 安装 wget

1. 安装 Homebrew（如果尚未安装）

   Homebrew 是 macOS 上的包管理器，可以方便地安装和管理命令行工具。

   在终端运行以下命令安装 Homebrew：

   |---|---------------------------------------------------------------------------------------------------|
   | | /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" |

2. 使用 Homebrew 安装 wget

   安装完 Homebrew 后，运行以下命令安装 wget

   |---|---------------------|
   | | brew install wget |

3. 验证安装

   安装完成后，运行以下命令验证 wget 是否可用：

   |---|------------------|
   | | wget --version |

   如果输出版本信息（如 GNU Wget 1.21.4），则表示安装成功。

或手动创建文件：

# docker-compose.yml
version: '3.8'
services:
  etcd:
    image: quay.io/coreos/etcd:v3.5.5
    container_name: milvus-etcd
    environment:
      - ETCD_AUTO_COMPACTION_MODE=revision
      - ETCD_AUTO_COMPACTION_RETENTION=1000
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/etcd:/etcd
    ports:
      - "2379:2379"
    command: etcd -advertise-client-urls=http://0.0.0.0:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd

  minio:
    image: minio/minio:RELEASE.2023-03-20T20-16-18Z
    container_name: milvus-minio
    environment:
      MINIO_ACCESS_KEY: minioadmin
      MINIO_SECRET_KEY: minioadmin
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/minio:/minio_data
    ports:
      - "9000:9000"
      - "9001:9001"
    command: minio server /minio_data --console-address ":9001"

  standalone:
    image: milvusdb/milvus:v2.3.12
    container_name: milvus-standalone
    ports:
      - "19530:19530"  # gRPC 端口
      - "9091:9091"    # HTTP 端口
    environment:
      ETCD_ENDPOINTS: etcd:2379
      MINIO_ADDRESS: minio:9000
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/milvus:/var/lib/milvus
    depends_on:
      - "etcd"
      - "minio"

4. 启动 Milvus 服务

在终端进入 docker-compose.yml 所在目录，运行以下命令：

docker compose up -d

• -d 表示后台运行。
• 首次启动会下载 Milvus、etcd 和 MinIO 的镜像（约 2GB），需耐心等待。

3. 验证服务状态

运行以下命令检查容器是否正常运行：

docker compose ps

输出示例：

NAME                COMMAND                  STATE           PORTS
milvus-etcd         "/usr/local/bin/etcd..." Up (healthy)   2379/tcp, 2380/tcp
milvus-minio        "/usr/bin/docker-ent..." Up (healthy)   9000/tcp, 9001/tcp
milvus-standalone   "/tini -- milvus run..." Up (healthy)   0.0.0.0:19530->19530/tcp, 0.0.0.0:9091->9091/tcp

4. 访问 Milvus Web UI

• 打开浏览器，访问 http://localhost:9091/webui。
• 默认无需登录，可直接查看 Milvus 的运行状态、集合信息等。

---

四、连接 Milvus 客户端

1. 使用 PyMilvus 连接

安装 PyMilvus：

pip3 install pymilvus==2.5.4

测试连接：

from pymilvus import connections

connections.connect(
    host="localhost",
    port="19530",
    user="",
    password=""
)
print(connections.list_connections())  # 输出连接信息

2. 使用 cURL 测试健康检查

curl -I http://localhost:9091/healthz

返回 HTTP/1.1 200 OK 表示服务正常。

---

五、常见问题排查

1. 镜像下载慢

   • 配置 Docker 国内镜像源（如阿里云、中科大等）。

   • 修改 Docker Desktop 的 Settings > Docker Engine，添加以下配置：

     {
       "registry-mirrors": ["https://<your-mirror-url>"]
     }

2. 容器启动失败

   • 检查日志：

     docker compose logs -f

     常见原因：

     • 端口冲突：

       修改 docker-compose.yml 中的端口映射（如 19530:19530 改为 19531:19530）

     • 内存不足：

       在 Docker Desktop 设置中增加内存分配（建议至少 4GB）

3. Apple Silicon 芯片兼容性问题

   • 确保使用 Milvus 的 ARM 镜像（如 milvusdb/milvus:v2.5.4-arm64）。
   • 修改 docker-compose.yml 中的镜像标签为 -arm64。

4. 数据持久化问题

   • 默认数据存储在 ./volumes/ 目录下，删除容器前需备份该目录。

   • 停止并删除容器：

     docker compose down -v # -v 删除数据卷

---

六、卸载 Milvus

1. 停止并删除容器：

   docker compose down -v

2. 删除配置文件和卷：

   rm -rf docker-compose.yml volumes/

---

总结

通过本教程，你可以在 macOS 上快速部署 Milvus 独立版，并通过 Web UI 或客户端进行交互。Milvus 独立版适合开发测试和小规模生产环境，如需分布式部署，可参考官方 Kubernetes 部署方案。你也可以参考使用Docker安装 Milvus 独立版(官方文档)。