Milvus 二进制部署实战：手工拉起 etcd、MinIO 与 Milvus Standalone 全链路

本篇技术指南基于 Milvus 仓库中的 二进制部署文档，完整讲解如何在没有 Docker 与 Kubernetes 的裸机 Linux 环境中，以二进制文件方式安装 etcd、MinIO 与 Milvus Standalone 三个服务，打通“元数据存储 + 对象存储 + 向量数据库”的完整链路。读完本文，你将掌握每个服务的启动命令与参数含义，理解 Milvus 二进制运行所依赖的底层库与配置文件，并能结合仓库源码与默认配置验证整套部署是否可用。

部署方式总览

Milvus Standalone 并不是一个单一进程就能跑起来的系统。从仓库配置 configs/milvus.yaml 的结构可以看到，Milvus 启动后需要两类外部依赖：

• etcd：用于存储 Milvus 的元数据（collection、partition、index、segment 等元信息）以及服务发现。配置文件注释明确写道“Related configuration of etcd, used to store Milvus metadata & service discovery”（见 configs/milvus.yaml）；
• MinIO（或任何兼容 S3 API 的对象存储）：负责向量数据、索引文件等持久化存储，默认配置为 address: localhost:9000、bucketName: a-bucket（见 configs/milvus.yaml）。

因此，二进制方式部署的完整步骤就是：先起 etcd，再起 MinIO，最后拉起 Milvus 二进制。仓库中的 deployments/binary/README.md 给出的正是这条路径，本文在其基础上结合仓库实际代码与配置逐项展开。

先确认版本：以 docker-compose 为版本基准

原文档在开始前给出一条重要提示：安装前可以先参考 deployments/docker/standalone/docker-compose.yml 来确认 etcd 与 MinIO 所需的版本。当前仓库中该 compose 文件锁定的版本是：

组件	镜像/版本	关键端口
etcd	quay.io/coreos/etcd:v3.5.25	2379（gRPC/HTTP client）
MinIO	minio/minio:RELEASE.2024-05-28T17-19-04Z	9000（S3 API）、9001（Console）
Milvus	milvusdb/milvus:v3.0.0	19530（gRPC）、9091（健康检查/HTTP）

这说明二进制部署应选择 etcd 3.5.x 系列与较新的 MinIO 发行版。原文档示例中 wget 的 etcd 是 v3.5.0 早期版本，实际操作时建议对齐到 compose 中的 v3.5.25，避免行为差异。

第一步：启动 etcd 服务

原文档给出的启动命令如下（官方安装渠道可参考 etcd 的 Release 页面）：

$ wget https://github.com/etcd-io/etcd/releases/download/v3.5.0/etcd-v3.5.0-linux-amd64.tar.gz
$ tar zxvf etcd-v3.5.0-linux-amd64.tar.gz
$ cd etcd-v3.5.0-linux-amd64
$ ./etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd

三个参数各司其职：

• -advertise-client-urls=http://127.0.0.1:2379：向客户端公布的访问地址。因为本教程中 etcd 与 Milvus 同机部署，用 127.0.0.1 即可；
• -listen-client-urls http://0.0.0.0:2379：实际监听地址，绑定所有网卡，方便后续扩展为跨机访问；
• --data-dir /etcd：etcd 的持久化数据目录，必须可写。

值得注意的是，这套命令与 compose 文件中 etcd 服务的 command 字段完全一致（etcd -advertise-client-urls=http://etcd:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd，见 deployments/docker/standalone/docker-compose.yml），差别仅在 advertise 地址：容器网络中用服务名 etcd，本机部署用 127.0.0.1。

compose 中还有一组值得借鉴的运行参数（容器内通过环境变量注入）：ETCD_AUTO_COMPACTION_MODE=revision、ETCD_AUTO_COMPACTION_RETENTION=1000、ETCD_QUOTA_BACKEND_BYTES=4294967296、ETCD_SNAPSHOT_COUNT=50000，用于自动压缩历史 revision、限制后端配额，防止元数据增长拖垮 etcd。二进制部署时可以用同样的 ETCD_AUTO_COMPACTION_MODE 等环境变量或命令行参数来配置。

etcd 健康检查可参考 compose 中的做法：etcdctl endpoint health。

第二步：启动 MinIO 服务

原文档的 MinIO 启动命令如下：

$ wget https://dl.min.io/server/minio/release/linux-amd64/minio
$ chmod +x minio
$ ./minio server /minio

/minio 是 MinIO 的数据根目录（需可写），MinIO 启动后会监听 9000 端口提供 S3 API，9001 端口提供 Web 控制台（可通过追加 --console-address ":9001" 显式开启，与 compose 文件保持一致）。

认证凭据是关键衔接点：compose 文件中 MinIO 用环境变量 MINIO_ACCESS_KEY: minioadmin、MINIO_SECRET_KEY: minioadmin 启动；而 configs/milvus.yaml 中 Milvus 侧的默认值恰好也是 accessKeyID: minioadmin、secretAccessKey: minioadmin。这意味着：

• 如果你用裸命令 ./minio server /minio 启动（未设置 MINIO_ACCESS_KEY/SECRET_KEY），MinIO 会要求你先设置访问密钥，或生成默认凭据，此时需要让 Milvus 侧的 minio.accessKeyID / minio.secretAccessKey 与之对应；
• 最简单的做法是在启动 MinIO 前显式设置 MINIO_ACCESS_KEY=minioadmin 与 MINIO_SECRET_KEY=minioadmin，与 Milvus 默认配置保持一致，无需改任何配置文件。

第三步：获取 Milvus 二进制文件

原文档指出的一个重要现状是：当前可以通过 Milvus 的 Docker 镜像来获取最新的 Milvus 二进制文件（官方表示未来会直接上传二进制文件）。也就是说，虽然最终运行不依赖 Docker，但获取产物仍需一次 Docker 交互：

$ docker run -d --name milvus milvusdb/milvus:v3.0.0 /bin/bash
$ docker cp milvus:/milvus .

这两条命令的语义是：用一个常驻 bash 的容器挂出文件系统，再把镜像内 /milvus 目录（包含 bin/milvus 主程序与 lib/ 下的 C++ 核心动态库）复制到本地。得到的目录结构与仓库构建产物一致——入口程序位于 bin/milvus，共享库位于 lib/，这一点直接影响了后面的启动方式。

第四步：安装 Milvus 系统级依赖

Milvus 的二进制由 Go 主程序 + C++ 计算核心（internal/core）构成，运行时需要系统提供三组动态库。原文档给出的安装命令（Debian/Ubuntu 系）：

$ sudo apt-get install libopenblas-dev   # BLAS 数值计算库，向量距离计算依赖
$ sudo apt-get install libgomp1          # GCC OpenMP 运行时，多线程并行依赖
$ sudo apt-get install libtbb2           # Intel TBB 线程构建块库

这三个包分别支撑向量索引计算中的线性代数运算、OpenMP 并行和 TBB 并发原语。缺少其中任何一个，./bin/milvus run standalone 都可能在加载阶段报“无法打开共享对象文件”之类的链接错误。使用其他发行版时（如 CentOS/RHEL），需换成对应的 openblas-devel、libgomp、tbb 包。

第五步：启动 Milvus Standalone

$ cd milvus
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD/lib
$ ./bin/milvus run standalone

两个细节决定了这条命令能否成功：

1. LD_LIBRARY_PATH 必须包含 ./lib：bin/milvus 通过 cgo 链接了 lib/ 下的 C++ 核心动态库（仓库中 internal/core 即这些库的来源），不设这个环境变量会直接链接失败；
2. run standalone 是 CLI 的固定子命令：从 cmd/milvus/help.go 可以看到，Milvus CLI 提供 milvus run [server type]、milvus stop [server type] 以及 milvus mck（数据一致性检查）三类命令，standalone 是 server type 之一。

启动流程本身可以从源码印证。cmd/milvus/run.go 中 execute 方法依次执行：解析 server type、创建运行时目录并写 PID 文件（防止重复启动同一角色）、打印版本 banner、注入 GitCommit/BuildTime 等构建信息到环境变量，最后调用 roles.Run()。真正的组件装配（连接 etcd、初始化元数据、注册各服务）发生在 cmd/roles/roles.go 的角色运行逻辑中——这也解释了为什么 Milvus 启动前必须保证 etcd 与 MinIO 已经就绪：任何一步连不上外部依赖，角色初始化都会失败。

配置默认值为什么“开箱即用”

二进制部署最省事的一点是：configs/milvus.yaml 的默认值恰好对准了本教程的单机拓扑：

• etcd.endpoints: localhost:2379（configs/milvus.yaml）——与本机 2379 端口的 etcd 一致；
• minio.address: localhost:9000（configs/milvus.yaml）——与本机 MinIO 一致；
• bucketName: a-bucket 且配置注释说明“Bucket with this name will be created if it does not exist”——MinIO 侧无需手工建桶；
• 本地数据缓存目录 localStorage.path: /var/lib/milvus/data/，用于存放搜索/查询时的向量数据本地副本，请确保该目录可写。

需要强调的是配置加载优先级：配置注释写明“etcd preferentially acquires valid address from environment variable ETCD_ENDPOINTS when Milvus is started”，即 环境变量 ETCD_ENDPOINTS、MINIO_ADDRESS、MINIO_ACCESS_KEY_ID/MINIO_SECRET_ACCESS_KEY 优先于 yaml 文件中的值（compose 文件正是通过 ETCD_ENDPOINTS: etcd:2379、MINIO_ADDRESS: minio:9000 覆盖默认地址的）。因此，如果 etcd/MinIO 不在本机默认端口，优先用环境变量覆盖，而不是改 yaml。

另外，yaml 中的 etcd.rootPath: by-dev 与 minio.rootPath: files 是 Milvus 在共享 etcd / MinIO 实例时区分多套部署的命名空间前缀，配置注释建议“在首次启动前再修改”；对单机独立部署可保持默认，若要让多个 Milvus 实例共用同一套 etcd/MinIO，则应分别为每个实例设置不同的 rootPath。

启动后验证

compose 文件中 standalone 服务的健康检查是 curl -f http://localhost:9091/healthz（deployments/docker/standalone/docker-compose.yml）。二进制部署同理：Milvus 起来后（compose 中给了 90s 的 start_period，首启加载元数据与本地缓存需要一定时间），执行

$ curl http://localhost:9091/healthz

返回 OK 即代表服务可用；此时 gRPC 端口 19530 已开放，可接入任何 Milvus SDK（如仓库 client/ 目录下的 Go SDK）创建 collection、写入与检索向量。

常见问题与注意事项

• 端口占用：2379（etcd）、9000/9001（MinIO）、19530/9091（Milvus）需全部空闲，跨机部署时防火墙要放行这些端口；
• 版本对齐：etcd 建议 3.5.x（compose 锁定 v3.5.25），MinIO 使用 2024-05 之后的 release，Milvus 镜像版本与 compose 中的 v3.0.0 保持一致；
• 数据目录权限：etcd 的 --data-dir /etcd、MinIO 的 /minio、Milvus 的 /var/lib/milvus/data/ 三个目录都要求运行用户可写，生产环境建议用普通用户而非 root 运行；
• 修改 rootPath 的时机：etcd.rootPath、minio.rootPath 一旦有数据写入后再改，将导致读不到旧数据（配置注释中明确警告），务必在首次启动前确定；
• 停止服务：与 run 对应，CLI 提供 milvus stop [server type]（见 cmd/milvus/help.go），配合 run 时创建的 PID 文件定位进程。

小结

二进制部署的价值在于脱离容器运行时、便于裸机、嵌入式或特殊网络环境落地，代价是需要手工管理 etcd 与 MinIO 两个依赖的生命周期。按本文顺序执行——校验版本、启动 etcd、启动 MinIO、从镜像取出 bin/milvus + lib/、安装 openblas/gomp/tbb 三个系统依赖、设置 LD_LIBRARY_PATH 后 ./bin/milvus run standalone——即可得到一套与 deployments/docker/standalone/docker-compose.yml 等价、且全部使用本地默认配置（localhost:2379 / localhost:9000）的 Milvus Standalone 环境，并通过 9091 端口的 /healthz 接口完成上线验证。