通过 Docker 安装 Milvus 向量数据库（一）：从零部署到连通验证-Django,Django中文网！

通过 Docker 安装 Milvus 向量数据库（一）：从零部署到连通验证

在 AI 应用越来越“检索优先”的今天，向量数据库几乎成了很多项目的标配：文本嵌入、图片特征、音频指纹都可以被表示成向量，然后通过相似度检索快速找到“最像的内容”。Milvus 作为社区里非常主流的向量数据库之一，上手门槛并不高，尤其是用 Docker 方式部署，基本可以做到“拉配置 → 一条命令起服务 → 立刻连通验证”。

这篇文章我会用一种“可复制的实战路线”来写：尽量不讲空概念，重点讲你在服务器或本机上如何把 Milvus 跑起来、怎么确认它真的可用，以及遇到常见报错如何快速定位。本文是系列第一篇，目标是：先把 Milvus 稳稳地跑起来并连通。

一、Milvus 是什么？为什么它适合做相似度检索

向量数据库和传统关系型数据库最大的不同在于：它不是围绕“精确匹配”优化，而是围绕“相似度搜索”优化。比如你给一段文本做嵌入，得到 768 维向量；你再输入一句话做嵌入，系统可以在毫秒级返回最相似的若干条向量记录，背后通常用到 ANN（近似最近邻）索引结构，把高维搜索从“暴力全表扫”变成“近似但极快”。

Milvus 的典型用法包括：

语义搜索：问题 → 嵌入 → 检索相似文档片段
推荐系统：用户向量/内容向量 → 找近邻
RAG：检索增强生成，先检索再让大模型回答
去重与聚类：找相似内容、找重复商品/文章/图片

把概念先放一边，我们这篇只干一件事：跑起来。

二、部署前准备：你需要确认的 4 件事

在开干之前，建议你先确认以下条件，能省掉一半排障时间：

1）Docker 与 Docker Compose 已安装

你需要能正常执行 docker ps、docker compose version（或 docker-compose version）
如果是服务器环境，建议 Docker 版本别太旧

2）机器资源别太极限

体验级：2 核 4G 也能跑，但并发别太高
稍微稳定一点：4 核 8G 起步更舒服
磁盘建议预留几十 GB（日志、数据、索引增长很快）

3）端口规划 Milvus 组件较多，通常需要暴露服务端口（例如 Milvus 服务端口、监控端口等）。如果你处于云服务器环境，记得同时确认：

本机防火墙放行
云安全组放行否则你会遇到“容器里起来了，但外部连不上”的假故障。

4）目录权限 数据持久化通常会挂载到宿主机目录，确保该目录对 Docker 进程可写。

三、推荐的 Docker Compose 部署思路

用 Compose 部署的好处是：组件依赖关系清晰，启动/停止/重启一套命令搞定。通常你会准备一个目录，比如：

milvus-docker/
docker-compose.yml
volumes/（数据目录）
logs/（可选）

下面给一个“可直接落地的示例骨架”。注意：不同 Milvus 版本的组件组合会略有差异，但大体结构接近。你可以先用这份跑通，再按自己的版本需要微调。

version: "3.8"

services:
  etcd:
    image: quay.io/coreos/etcd:latest
    container_name: milvus-etcd
    environment:
      - ETCD_AUTO_COMPACTION_MODE=revision
      - ETCD_AUTO_COMPACTION_RETENTION=1000
      - ETCD_QUOTA_BACKEND_BYTES=4294967296
      - ETCD_SNAPSHOT_COUNT=50000
    command: &gt;
      etcd
      -advertise-client-urls=http://0.0.0.0:2379
      -listen-client-urls=http://0.0.0.0:2379
      --data-dir=/etcd
    volumes:
      - ./volumes/etcd:/etcd
    networks:
      - milvus-net

  minio:
    image: minio/minio:latest
    container_name: milvus-minio
    environment:
      - MINIO_ROOT_USER=minioadmin
      - MINIO_ROOT_PASSWORD=minioadmin
    command: server /data --console-address ":9001"
    volumes:
      - ./volumes/minio:/data
    ports:
      - "9000:9000"
      - "9001:9001"
    networks:
      - milvus-net

  milvus:
    image: milvusdb/milvus:latest
    container_name: milvus-standalone
    command: ["milvus", "run", "standalone"]
    environment:
      - ETCD_ENDPOINTS=etcd:2379
      - MINIO_ADDRESS=minio:9000
      - MINIO_ACCESS_KEY=minioadmin
      - MINIO_SECRET_KEY=minioadmin
    ports:
      - "19530:19530"
      - "9091:9091"
    depends_on:
      - etcd
      - minio
    volumes:
      - ./volumes/milvus:/var/lib/milvus
    networks:
      - milvus-net

networks:
  milvus-net:
    name: milvus-net

你会看到 3 个核心组件：

etcd：保存元数据（相当关键）
minio：对象存储（用于数据与索引文件等）
milvus：主服务（standalone 模式更适合快速上手）

> 小建议：首次上手一定先用 standalone，别一上来就分布式；你先把链路跑通，再考虑扩展。

四、启动与停止：用最少命令完成闭环

进入 docker-compose.yml 所在目录后：

启动：

docker compose up -d

查看容器状态：

docker ps

你希望看到三个容器都在运行，并且状态为 Up。如果有容器反复重启，先别急着改配置，第一步是看日志。

查看 Milvus 日志：

docker logs -f milvus-standalone

如果你看到类似“服务已启动”“监听端口已准备就绪”等信息（不同版本日志略不同），基本说明 Milvus 主服务已起来。

停止并保留数据：

docker compose down

停止并删除数据（谨慎）：

docker compose down -v

> -v 会把挂载的匿名卷一并清理。若你使用的是宿主机目录挂载，目录还在，但容器内部卷会被清理。生产环境请务必明确自己在清理什么。

五、连通验证：确认 Milvus 真正可用

光看到容器 Up 并不等于可用，我们要做一个最简单的验证：能连上 + 能建集合 + 能插入向量 + 能检索。

下面给一个“最小 Python 验证脚本”的思路（伪代码风格，便于你替换为自己的依赖与写法）。你只需要把连接地址改成你实际部署的地址与端口即可。

from pymilvus import connections, FieldSchema, CollectionSchema, DataType, Collection
import random

# 1) 连接
connections.connect(
    alias="default",
    host="127.0.0.1",
    port="19530"
)

# 2) 定义 schema
dim = 8
fields = [
    FieldSchema(name="id", dtype=DataType.INT64, is_primary=True, auto_id=False),
    FieldSchema(name="vec", dtype=DataType.FLOAT_VECTOR, dim=dim),
]
schema = CollectionSchema(fields, description="demo collection")

# 3) 创建集合
col_name = "demo_vectors"
col = Collection(name=col_name, schema=schema)

# 4) 插入数据
ids = [i for i in range(1, 101)]
vectors = [[random.random() for _ in range(dim)] for _ in range(100)]
col.insert([ids, vectors])

# 5) 建索引（简化示例）
index_params = {"index_type": "IVF_FLAT", "metric_type": "L2", "params": {"nlist": 64}}
col.create_index(field_name="vec", index_params=index_params)

# 6) 加载并搜索
col.load()
query = [vectors[0]]
search_params = {"metric_type": "L2", "params": {"nprobe": 8}}
res = col.search(query, "vec", search_params, limit=5, output_fields=["id"])

print(res)

你只要看到 res 返回了一组近邻结果，就说明：

服务端口连通
集合创建成功
写入成功
索引可用
搜索可用

到这里，“部署闭环”就完成了。

六、常见问题与排查顺序（非常实用）

1）容器启动后立刻退出

优先看日志：

docker logs milvus-standalone
docker logs milvus-etcd
docker logs milvus-minio

通常原因集中在：

环境变量写错（例如对象存储地址/账号密码）
挂载目录权限不足（写不了数据）
端口冲突（宿主机已有服务占用）

2）外部连不上，但容器里看起来正常

重点排查：

云服务器安全组是否放行端口
系统防火墙是否拦截
你连接的 host 是否正确（不要把容器内地址当宿主机地址）

如果你是本机测试，连接 127.0.0.1:19530；如果你是远程服务器，连接“服务器公网 IP + 映射端口”。

3）写入/建索引很慢或直接卡住

大概率和资源有关：

内存不足导致频繁换页
磁盘 IO 太慢
容器资源限制过低

建议先做两件事：

给服务器更稳定的 CPU/内存
把数据目录放在更快的磁盘上（尤其是索引文件）

4）数据持久化后重启丢失

检查你是否做了“宿主机目录挂载”。如果你只用默认匿名卷或误用了清理命令，很容易出现“重启后空了”。推荐使用固定目录挂载，并做好备份策略。

七、下一篇会做什么

本篇完成了 Milvus 的 Docker 部署与连通验证。下一篇（系列二）我会继续往前走一步，把它变成“可用于业务”的形态，例如：

更合理的目录结构与配置管理
监控与健康检查（怎么看它是不是快挂了）
与嵌入模型配合的最小检索链路（从文本到向量到检索）
常用索引参数怎么选（不再只停留在默认值）

如果你现在的目标是“先把向量库跑起来”，照着本文做，基本就能在一个晚上把环境跑通。只要跑通一次，你后面做 RAG、语义搜索、内容推荐都会顺很多。

ForrestadBashar@gmail.com

时间：2025-12-15 访问次数:14

通过 Docker 安装 Milvus 向量数据库（一）：从零部署到连通验证