美国服务器部署Milvus前要准备哪些依赖,如何验证向量检索可用?
首次部署的重点不是把所有组件分别安装一遍,而是先确认美国服务器能够稳定运行 Docker、具备足够的内存和磁盘,并使用与 Milvus 服务端匹配的 Python 客户端完成一次“写入向量—建立可查询状态—返回近邻结果”的闭环。对于单机测试或小规模应用,Milvus Standalone 是较合适的起点,它会通过 Docker Compose 一并启动 Milvus、etcd 和 MinIO,通常不需要另外安装这两个依赖。
建议先按 Ubuntu 22.04/24.04、x86_64、4 vCPU、8 GiB 内存、SSD 磁盘的条件准备美国服务器。50 GB 以上磁盘可用于基础测试,但不能据此推断生产容量。向量原始数据可按“N × D × 4 字节”估算,其中 N 是向量数量,D 是维度。例如 100 万条 768 维 float32 向量仅原始数据就约为 3,072,000,000 字节,即 3.072 GB 十进制、约 2.86 GiB;再加上索引、日志、元数据和预留空间,实际磁盘需求会明显增加。
一、部署前准备条件
1. 确认系统、架构和资源
先在服务器上执行以下检查:
uname -m
cat /etc/os-release
nproc
free -h
df -h /
df -h /opt 2>/dev/null || true
timedatectl status
典型判断方式如下:
| 检查项 | 建议结果 | 不满足时的影响 |
|---|---|---|
| CPU 架构 | x86_64 | ARM 架构需要确认对应 Docker 镜像是否支持 |
| CPU | 4 vCPU 起步 | 建立索引和高并发搜索时可能变慢 |
| 内存 | 8 GiB 起步 | etcd、MinIO、Milvus 和索引会共同占用内存 |
| 磁盘 | SSD,测试建议 50 GB 以上 | 拉取镜像、写入数据或构建索引时可能空间不足 |
| 系统时间 | 已同步 | 影响日志排序、证书和部分客户端行为 |
| 文件系统 | 可正常写入 /opt 或指定数据目录 | 容器可能因权限或只读挂载启动失败 |
如果计划存储大量高维向量,不要只按向量原始大小准备磁盘。还应为索引、数据增长、临时文件和日志预留空间。生产环境通常还需要独立的数据盘,而不是把 Milvus 数据放在系统盘上。
2. 确认网络和端口
首次启动需要从镜像仓库拉取 Docker 镜像,因此服务器需要能够进行 DNS 解析和出站 HTTPS 访问。入站访问则建议只开放给实际应用服务器或管理网段。
常见端口用途如下:
| 端口 | 用途 | 建议暴露范围 |
|---|---|---|
| 19530/TCP | Milvus 客户端主要连接端口 | 仅应用服务器或受控管理网段 |
| 9091/TCP | 健康检查和 HTTP 管理接口 | 优先限制为本机 |
| 2379/TCP | etcd 内部服务 | 不对公网开放 |
| 9000、9001/TCP | MinIO 内部及管理服务 | 不对公网开放 |
在云服务器控制台的安全组中,优先只允许应用服务器的私网地址访问 19530。若应用和 Milvus 在同一台美国服务器上运行,可以只让应用通过 127.0.0.1:19530 访问。不要因为客户端连接失败,就直接把 2379、9000 或 9001 全部开放到公网。
3. 安装并验证 Docker Compose
如果服务器已有 Docker,先确认 Docker Compose 插件可用:
docker --version
docker compose version
sudo systemctl is-active docker
预期可以看到 Docker 版本、Compose v2 版本,并且 Docker 服务返回 active。如果命令不存在,可以在 Ubuntu 22.04/24.04 上使用 Docker 软件源安装。不要在同一台服务器上混用多个来源的 Docker 组件,尤其要注意 docker.io 和 Docker 软件源中的 docker-ce 可能产生版本或组件冲突。
以下命令适用于使用 Docker 软件源的 Ubuntu 环境:
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
. /etc/os-release
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu ${VERSION_CODENAME} stable" \
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker run --rm hello-world
sudo docker compose version
如果系统不是 Ubuntu,或者 VERSION_CODENAME 对应的发行版不在软件源支持范围内,应先按该发行版的 Docker 安装方式处理,不要直接套用上述命令。
二、准备 Milvus Standalone 文件
1. 固定 Milvus 版本
首次部署不建议直接下载不固定的 latest 文件。服务端版本、Compose 文件和 Python 客户端应尽量保持同一兼容系列。下面以 Milvus 2.4.x 为示例,v2.4.24 只是示例版本,实际使用时应替换为已确认存在且符合项目要求的版本。
先创建部署目录并保存 Compose 文件:
sudo mkdir -p /opt/milvus/standalone
sudo chown -R "$USER":"$USER" /opt/milvus
cd /opt/milvus/standalone
MILVUS_VERSION=v2.4.24
COMPOSE_URL="https://github.com/milvus-io/milvus/releases/download/${MILVUS_VERSION}/milvus-standalone-docker-compose.yml"
curl -fL "$COMPOSE_URL" -o docker-compose.yml
test -s docker-compose.yml
如果下载返回 404,应检查版本号和发布文件名称,不要随意使用其他版本的 Compose 文件替代。下载后先检查配置是否能被 Compose 解析:
docker compose config
docker compose config --services
正常情况下可以看到 etcd、minio 和 standalone 等服务。不同 Milvus 版本的服务名、镜像标签和环境变量可能存在差异,因此不要在未检查配置的情况下手动改写服务名。
2. 检查端口发布范围
查看 Compose 文件中的端口定义:
grep -nE 'ports:|19530|9091|2379|9000|9001' docker-compose.yml
再检查当前服务器是否已经占用 Milvus 端口:
sudo ss -lntp | grep -E ':19530|:9091|:2379|:9000|:9001' || true
如果 19530 已被其他程序占用,Milvus 容器可能无法启动。此时应先确认占用进程,再决定停止旧服务或调整端口。不要直接杀掉未知进程。
若 Compose 文件将 19530 发布到所有网卡,至少应在云安全组中限制来源地址。对于只在本机使用的环境,可以在确认当前版本服务名和 Compose 合并规则后,将 19530、9091 绑定到 127.0.0.1;修改前先备份配置:
cp -a docker-compose.yml "docker-compose.yml.$(date +%Y%m%d-%H%M%S).bak"
etcd 和 MinIO 的端口不应为了远程调试而直接开放到公网。
三、启动 Milvus 及其依赖
1. 拉取镜像并启动
在 Compose 文件所在目录执行:
cd /opt/milvus/standalone
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
首次拉取需要的时间取决于美国服务器到镜像仓库的网络质量和磁盘写入速度。启动后,docker compose ps 应至少显示 etcd、MinIO 和 Milvus 主服务处于 Up 或健康状态。
可以查看完整日志:
sudo docker compose logs --tail=100
也可以只持续观察启动过程:
sudo docker compose logs -f --tail=100
看到 Milvus 主服务持续重启、unhealthy 或退出时,先按 docker compose ps 中的实际服务名查看日志,不要立即执行删除容器或删除卷操作。
2. 验证容器和健康接口
先确认容器状态:
sudo docker compose ps
然后检查 Milvus 健康接口:
curl --fail --silent --show-error \
http://127.0.0.1:9091/healthz
常见成功结果为:
OK
也可以直接测试 19530 端口是否监听:
nc -zv 127.0.0.1 19530
如果系统没有 nc,可以使用 Bash 的 TCP 检查:
timeout 3 bash -c '</dev/tcp/127.0.0.1/19530' \
&& echo "19530 is reachable" \
|| echo "19530 is not reachable"
这一步只能说明端口和健康接口可访问,还不能证明向量写入和检索正常。真正的验证需要使用客户端创建集合、插入向量并执行搜索。

四、用 Python 客户端验证向量检索
1. 安装与服务端匹配的 PyMilvus
先准备 Python 环境:
sudo apt-get update
sudo apt-get install -y python3 python3-venv
cd /opt/milvus/standalone
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "pymilvus>=2.4,<2.5"
这里的客户端范围对应前面的 Milvus 2.4.x 示例。如果实际服务端使用 2.5.x 或其他版本,应把客户端范围调整到相同兼容系列。安装后检查版本:
python -c "import pymilvus; print(pymilvus.__version__)"
2. 创建测试集合并执行近邻搜索
创建验证脚本:
cat > /opt/milvus/standalone/smoke_test.py <<'PY'
import time
from pymilvus import MilvusClient
client = MilvusClient(uri="http://127.0.0.1:19530")
collection_name = f"a5_smoke_{int(time.time())}"
client.create_collection(
collection_name=collection_name,
dimension=3,
metric_type="COSINE",
consistency_level="Strong",
)
data = [
{"id": 1, "vector": [1.0, 0.0, 0.0]},
{"id": 2, "vector": [0.9, 0.1, 0.0]},
{"id": 3, "vector": [0.0, 1.0, 0.0]},
]
insert_result = client.insert(
collection_name=collection_name,
data=data,
)
print("collection:", collection_name)
print("inserted:", insert_result.get("insert_count"))
result = client.search(
collection_name=collection_name,
data=[[1.0, 0.0, 0.0]],
limit=2,
output_fields=["id"],
)
print("search_result:", result)
if not result or not result[0]:
raise RuntimeError("search returned no result")
top_id = result[0][0]["id"]
if top_id != 1:
raise RuntimeError(f"unexpected top id: {top_id}")
print("vector search check: PASS")
PY
cd /opt/milvus/standalone
. .venv/bin/activate
python smoke_test.py
预期输出类似下面的示例,具体距离值会因客户端和服务端版本略有差异:
collection: a5_smoke_1710000000
inserted: 3
search_result: [[{'id': 1, 'distance': 1.0}, {'id': 2, 'distance': 0.993883...}]]
vector search check: PASS
这个测试验证了以下链路:
- Python 客户端能够连接 19530。
- Milvus 可以创建指定维度和距离类型的集合。
- 向量能够写入集合。
- Milvus 能够根据查询向量返回近邻结果。
- 最接近
[1, 0, 0]的向量是 ID 1,而不是随机返回结果。
测试脚本使用的是人工构造的 3 维向量,目的是验证 Milvus 服务和索引检索链路,不代表业务文本的语义检索质量。接入真实 embedding 模型时,必须确保写入向量和查询向量使用同一个模型、同一个维度、相同的数据类型和一致的距离度量。模型输出为 768 维时,集合字段也必须是 768 维,不能使用 1536 维集合直接写入。
3. 从远程应用服务器验证
如果应用和 Milvus 不在同一台美国服务器上,应优先使用私网地址连接。先从应用服务器检查端口:
nc -zv MILVUS_PRIVATE_IP 19530
将 MILVUS_PRIVATE_IP 替换成 Milvus 服务器的私网地址。如果端口不通,依次检查云安全组、服务器防火墙、监听地址和路由,不要先修改 Python 代码。
远程应用的连接示例:
from pymilvus import MilvusClient
client = MilvusClient(uri="http://MILVUS_PRIVATE_IP:19530")
print(client.list_collections())
如果只能使用公网地址,应同时限制来源 IP、关闭不需要的端口,并考虑在应用层增加访问控制。Milvus 19530 不是适合直接面向任意公网客户端开放的管理接口。
五、常见失败及处理顺序
1. 镜像拉取失败
先检查 DNS 和出站 HTTPS:
getent hosts github.com
curl -I https://github.com
sudo docker info
如果 GitHub 或镜像仓库无法访问,可能是 DNS、云厂商出站策略、镜像仓库限流或服务器网络问题。此时先解决镜像获取问题,不要反复执行 docker compose up -d。如果镜像已经部分拉取,可以重新执行:
sudo docker compose pull
sudo docker compose up -d
2. Milvus 容器反复重启
执行:

sudo docker compose ps
sudo docker compose logs --tail=200
sudo docker stats --no-stream
df -h
free -h
重点查看以下情况:
- 内存持续接近耗尽:降低测试数据规模或提高服务器内存。
- 磁盘接近满:先停止写入并清理无关日志,不能直接删除 Milvus 数据目录。
- etcd 或 MinIO 未就绪:等待依赖启动完成,再观察 Milvus 日志。
- 端口冲突:确认 19530、9091 是否被其他服务占用。
- 配置解析错误:重新执行
docker compose config,检查缩进、变量和版本文件。
3. 健康接口正常,但 Python 连接失败
先确认使用的是正确端口:
curl http://127.0.0.1:9091/healthz
nc -zv 127.0.0.1 19530
9091 是健康检查接口,Python SDK 主要连接 19530,不能把 9091 填到 SDK 的连接地址中。远程连接失败时,还要检查安全组和 ss -lntp 的监听地址。
如果报客户端协议或 API 不兼容,检查服务端和客户端版本:
sudo docker compose images
python -c "import pymilvus; print(pymilvus.__version__)"
优先调整 PyMilvus 版本,不要在数据已经写入后随意降级 Milvus 服务端。
4. 插入或搜索时报维度错误
典型问题是集合定义为 768 维,但实际传入 1536 维,或者测试集合仍被旧程序使用。检查业务代码中的 embedding 输出长度:
print(len(vector))
并确认集合创建参数中的 dimension 与其完全一致。维度、距离类型和向量归一化策略应在建库前确定;修改维度通常需要新建集合并重新生成向量,不能通过修改一条配置直接转换已有数据。
5. 能插入但暂时搜索不到数据
先确认插入返回数量大于 0,再等待集合达到可搜索状态。可查看当前服务日志:
sudo docker compose logs --tail=200
测试脚本使用强一致性,适合首次验证。如果业务使用默认一致性级别,刚写入的数据可能不会在所有读取路径上立即可见。对于正式业务,应根据写入后立即查询、延迟可接受范围和并发情况选择一致性级别,而不是仅依据一次本地测试结果判断。
六、部署结果检查
完成首次验证后,建议保留以下验收证据:
| 验收项 | 检查方式 | 通过标准 |
|---|---|---|
| Compose 配置 | docker compose config | 配置可解析,无变量缺失 |
| 服务状态 | docker compose ps | etcd、MinIO、Milvus 持续运行 |
| 健康状态 | curl 127.0.0.1:9091/healthz | 返回成功结果 |
| 端口连通性 | nc -zv 127.0.0.1 19530 | 19530 可连接 |
| SDK 连接 | Python MilvusClient | 能列出集合或创建集合 |
| 写入验证 | insert 返回值 | 写入数量与预期一致 |
| 检索验证 | search 返回值 | 已知最近向量排名符合预期 |
| 网络边界 | 云安全组和 ss | 仅必要端口对必要来源开放 |
| 数据持久化 | 重启后再次查询 | 未使用删除卷的情况下集合仍存在 |
可以在测试完成后进行一次非破坏性重启,验证 Compose 卷是否正常保留数据:
cd /opt/milvus/standalone
sudo docker compose restart
sleep 10
curl --fail --silent --show-error \
http://127.0.0.1:9091/healthz
重启期间会有短暂服务中断,应在没有业务流量或已做好切换的时间执行。重启完成后重新运行检索脚本或使用已知集合查询。如果测试脚本每次创建新集合,应另外保留集合名称,再执行查询验证。
七、回滚与清理检查项
首次部署失败时,优先选择保留数据的回滚方式:
cd /opt/milvus/standalone
sudo docker compose down
docker compose down 通常只停止并删除容器,不会自动删除 Compose 声明的数据卷。之后可以恢复此前备份的 Compose 文件,再检查配置并重新启动:
cp -a docker-compose.yml /tmp/docker-compose.failed.yml
cp -a docker-compose.yml.备份文件 docker-compose.yml
sudo docker compose config
sudo docker compose up -d
在执行版本回退前,要先确认卷中是否已经有业务数据。Milvus 服务端版本降级可能涉及数据格式和索引兼容问题,不能把“停止容器后换镜像”当作通用降级方案。生产数据应先使用经过验证的备份或存储快照,并遵循对应版本的升级、迁移路径。
以下命令具有删除数据风险,只适合确认数据全部为测试数据、并且准备重新初始化时使用:
cd /opt/milvus/standalone
sudo docker compose down -v
执行 down -v 前必须确认:
- 测试集合和向量不再需要;
- 没有其他项目共用该 Compose 项目的卷;
- 已保存当前 Compose 文件、版本号和必要日志;
- 云安全组或 UFW 规则已记录,清理后能够恢复;
- 不会把生产环境数据目录误当成测试目录。
最终验收应同时满足“容器健康、19530 可连接、Python 能写入和搜索、重启后数据仍在、依赖端口未暴露”这几项。只看到 Milvus 容器显示 Up,还不足以证明向量检索已经可用。
面向 Milvus 向量数据库部署,A5数据提供美国物理服务器及多地区服务器资源,产品覆盖 Xeon、AMD EPYC 等平台,部分美国 AMD 配置配备 DDR5 内存和 NVMe 存储,可为容器化服务、向量数据存储与检索任务提供硬件基础。美国服务器还包括 CN2 GIA 线路方案,适合结合面向美国用户的应用服务规划部署;香港、日本、新加坡等地区也提供不同配置,便于按业务覆盖区域安排相关服务资源。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/4449.html



