1. 项目概述为什么要在双系统环境下折腾 Milvus最近在做一个本地知识库的RAG项目向量数据库的选型自然落到了Milvus头上。我的主力开发机是Windows 10但很多AI和数据库生态的工具链在Linux下更友好、更稳定。为了兼顾日常办公和深度开发我在同一台机器上安装了Windows 10和Anolis OS 8一个兼容CentOS的国产Linux发行版双系统。这个配置带来的一个核心挑战就是如何在两个系统间高效、一致地部署和测试Milvus答案就是Docker。通过Docker我们可以在Windows和Anolis上获得近乎一致的运行环境极大地简化了部署和迁移的复杂度。本文记录的就是我在这套“混搭”环境里从零开始用Docker部署Milvus 2.3.4并成功用ATTU进行可视化管理全过程。无论你是想体验双系统开发还是单纯想在Windows或Linux上快速拉起一个Milvus服务这篇踩坑实录都能给你提供一条清晰的路径。2. 环境准备与核心思路拆解2.1 双系统与Docker的选型考量选择Windows 10 Anolis 8双系统主要是出于工作流分离的考虑。Windows用于文档处理、通讯以及一些仅支持Windows的软件Anolis 8则提供了一个纯净、稳定的Linux服务器环境更适合后端服务、数据库和容器化部署。Anolis 8作为CentOS的替代品其软件包管理和系统稳定性非常出色对于生产环境模拟很有帮助。而选择Docker来部署Milvus则是为了环境隔离和可复现性。Milvus的依赖相对复杂包括etcd、minio、pulsar等组件。通过Docker Compose我们可以一键拉起所有服务并且保证每次部署的组件版本和配置完全一致。更重要的是Docker Desktop for Windows的WSL 2后端让Windows下的容器体验几乎与原生Linux无异这为双系统下的统一操作奠定了基础。核心思路在Windows侧我们利用Docker Desktop基于WSL 2来运行Milvus的容器在Anolis 8侧我们直接安装Docker Engine和Docker Compose。两边的部署文件docker-compose.yml基本可以通用只需注意少数与宿主机相关的路径和网络配置差异。我们将以Anolis 8侧的部署作为主流程讲解因为其更接近生产环境同时会穿插说明Windows下的关键注意事项。2.2 基础环境配置清单在开始之前请确保你的环境满足以下要求Anolis OS 8系统已安装并可以正常启动。拥有一个具有sudo权限的用户。内存建议8GB以上Milvus运行会占用较多资源。磁盘空间充足用于存放Docker镜像和数据库数据。Windows 10版本为2004及以上家庭版需升级为专业版或企业版以启用Hyper-V和WSL 2。确保BIOS中已开启虚拟化技术Intel VT-x或AMD-V。安装并配置好WSL 2推荐使用Ubuntu发行版。安装Docker Desktop for Windows并设置其使用WSL 2作为后端。网络需要能够访问Docker Hub等容器镜像仓库。如果网络环境特殊请提前配置好镜像加速器。3. Anolis 8 侧 Docker 环境部署详解3.1 安装 Docker Engine 与 Docker ComposeAnolis 8 默认的软件源可能不包含最新版的Docker因此我们采用Docker官方提供的仓库进行安装。首先卸载旧版本如果有sudo yum remove docker \ docker-client \ docker-client-latest \ docker-common \ docker-latest \ docker-latest-logrotate \ docker-logrotate \ docker-engine安装必要的依赖包和配置仓库sudo yum install -y yum-utils sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo由于Anolis兼容CentOS这里我们使用CentOS的仓库地址。安装Docker Engine、命令行工具以及容器运行时containerdsudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin重要提示这里我们直接安装了Docker官方的docker-compose-plugin它提供了docker compose命令注意是空格不是横杠。这是新版本推荐的方式。如果你习惯使用独立的docker-compose脚本也可以另行安装但为了统一本文后续将使用docker compose命令。启动Docker服务并设置开机自启sudo systemctl start docker sudo systemctl enable docker验证安装是否成功sudo docker run hello-world如果能看到欢迎信息说明Docker引擎安装并运行正常。将当前用户加入docker组避免每次使用docker命令都需要sudosudo usermod -aG docker $USER执行此命令后你需要完全退出当前终端会话并重新登录用户组变更才会生效。3.2 配置 Docker 镜像加速与存储路径国内从Docker Hub拉取镜像速度可能较慢建议配置国内镜像加速器。这里以阿里云加速器为例你需要有自己的阿里云账号获取专属加速地址。编辑Docker守护进程配置文件sudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json -EOF { “registry-mirrors”: [“https://your-own-mirror.mirror.aliyuncs.com”], “exec-opts”: [“native.cgroupdriversystemd”], “log-driver”: “json-file”, “log-opts”: { “max-size”: “100m” }, “storage-driver”: “overlay2” } EOF请将“https://your-own-mirror.mirror.aliyuncs.com”替换为你从阿里云容器镜像服务控制台获取的加速器地址。native.cgroupdriversystemd是为了与Anolis 8的systemd更好地集成。默认情况下Docker的镜像、容器等数据存储在/var/lib/docker如果系统根目录空间不足可以修改存储路径。假设我们想将数据存放到/data/docker停止Docker服务sudo systemctl stop docker移动原有数据如果存在且重要sudo mv /var/lib/docker /data/创建软链接sudo ln -s /data/docker /var/lib/docker或者在上述daemon.json中直接添加“data-root”: “/data/docker”字段。配置完成后重新加载配置并重启Dockersudo systemctl daemon-reload sudo systemctl restart docker4. 部署 Milvus 2.3.4 集群4.1 获取与解析 Docker Compose 文件Milvus官方为单机测试提供了非常方便的Docker Compose部署文件。我们直接使用2.3.4版本对应的文件。首先创建一个工作目录并下载配置文件mkdir -p ~/milvus-standalone cd ~/milvus-standalone wget https://github.com/milvus-io/milvus/releases/download/v2.3.4/milvus-standalone-docker-compose.yml -O docker-compose.yml下载完成后强烈建议你先用文本编辑器如vim或nano打开这个docker-compose.yml文件浏览一遍。它定义了四个核心服务etcd用于元数据存储服务发现。minio用于对象存储存放插入Milvus的原始向量数据、索引文件等。standalone即Milvus单机版服务本身。attuMilvus的可视化管理工具本文后面会用到。理解这个文件的结构有助于后续排查问题。例如你可以看到各个服务的镜像标签、容器间的网络配置、端口映射、数据卷挂载等关键信息。4.2 启动 Milvus 服务集群在包含docker-compose.yml文件的目录下执行以下命令启动所有服务sudo docker compose up -d命令中的-d参数表示在后台运行detached mode。执行后Docker会开始从镜像仓库拉取所需的镜像etcd、minio、milvus、attu这个过程耗时取决于你的网速。拉取完成后会自动创建并启动容器。你可以使用以下命令查看容器状态sudo docker compose ps如果所有服务的状态STATUS都是“Up”则表示启动成功。也可以查看日志来监控启动过程# 查看所有服务的日志 sudo docker compose logs # 持续跟踪Milvus服务本身的日志 sudo docker compose logs -f standalone关键端口说明19530: Milvus服务的gRPC端口客户端如PyMilvus SDK通过此端口连接。9091: Milvus服务的HTTP端口用于健康检查和一些HTTP API。9000: MinIO服务的API端口。9090: MinIO服务的Web控制台端口。2379: etcd服务的客户端通信端口。3000: Attu Web界面的访问端口。确保这些端口在宿主机Anolis 8上没有其他程序占用。4.3 基础功能验证与连接测试服务启动后我们进行一个最简单的连接和集合创建测试以确保Milvus核心功能正常。首先进入Milvus服务容器内部使用其自带的milvus-cli工具sudo docker exec -it milvus-standalone /bin/bash在容器内部执行milvus-cli这会进入Milvus命令行交互界面。依次执行以下命令connect -h 127.0.0.1 -p 19530 create collection -c test_collection -f “id:INT64:pk” -f “vector:FLOAT_VECTOR:128” -f “title:VARCHAR:100” -p “id”connect: 连接本容器内的Milvus服务。create collection: 创建一个名为test_collection的集合包含三个字段一个INT64类型的主键字段id一个128维的浮点向量字段vector一个最大长度100的字符串字段title。分区键partition key设置为id字段。如果命令执行成功没有报错则说明Milvus服务运行正常可以接受基本的操作指令。输入exit退出milvus-cli再输入exit退出容器。5. 使用 ATTU 进行可视化管理和操作5.1 访问与登录 ATTU Web 界面在部署的Compose文件中已经包含了Attu服务。它会在后台自动启动。你只需要打开浏览器访问http://你的Anolis系统IP地址:3000。例如如果你的Anolis系统IP是192.168.1.100则访问http://192.168.1.100:3000。首次打开会看到登录界面。连接信息如下Address: 填写你的Milvus服务地址。这里是个关键点因为Attu容器和Milvus容器在同一个Docker网络内它们可以通过服务名standalone直接通信。所以这里应该填写standalone而不是127.0.0.1或宿主机IP。Port:19530Username/Password: Milvus默认没有启用用户名密码认证这两项留空即可。点击“Connect”如果一切正常你将成功进入ATTU的主界面。注意如果你在宿主机Anolis系统本身的浏览器中访问使用standalone作为地址是无效的因为standalone这个主机名只在Docker网络内部有效。此时你需要填写127.0.0.1或者宿主机的实际IP地址。这是容器网络与宿主机网络访问的区别务必理解。5.2 ATTU 核心功能实操指南登录成功后ATTU的界面非常直观。左侧是导航栏主要功能区包括Collections集合这里列出所有的集合。你可以点击“Create Collection”来通过图形界面创建集合定义字段、索引、分区键等比命令行更友好。我们之前创建的test_collection也会显示在这里。Data Query数据查询这是最重要的功能之一。你可以选择某个集合进行数据的“插入”Insert、“查询”Search和“删除”Delete。插入数据点击“Insert”可以手动输入或上传JSON/CSV文件来添加数据。你需要按照集合定义的字段格式来准备数据。对于向量字段需要输入一个JSON数组如[0.1, 0.2, ..., 0.128]。向量搜索点击“Search”这是Milvus的精华。你需要选择索引类型如果已创建索引。输入一个查询向量同样是一个JSON数组。选择度量类型如L2欧氏距离、IP内积。设置返回结果数量topK。 点击搜索下方会返回最相似的向量结果及其ID、距离分数。Index索引为集合的向量字段创建索引以加速搜索。常见的索引类型有FLAT暴力检索、IVF_FLAT、IVF_SQ8、HNSW等。创建索引需要指定nlist聚类中心数等参数ATTU提供了参数说明和默认值。System View系统视图可以查看Milvus集群的健康状态、节点信息、配置参数等对于监控很有帮助。实操建议在ATTU中重复一遍之前在CLI里做的“创建集合”操作感受图形化操作的便捷。然后尝试插入几条包含随机向量和文本的数据最后进行一次向量相似度搜索体验完整的流程。6. Windows 10 侧部署的特别注意事项在Windows 10上通过Docker Desktop部署Milvus流程与Anolis 8侧高度相似。主要区别和注意事项如下6.1 解决 Docker Desktop 启动失败与虚拟化问题如果你遇到“Docker Desktop failed to start because virtualisation support wasn‘t detected”错误请按以下步骤排查确认CPU虚拟化已开启重启电脑进入BIOS/UEFI设置通常是开机时按F2、Del、F10等键找到“Virtualization Technology”Intel VT-x或AMD-V选项确保其状态为“Enabled”。关闭 Hyper-V 和 Windows 沙盒如果不需要对于某些主板Hyper-V可能与BIOS虚拟化冲突。以管理员身份打开PowerShell运行Disable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All重启后检查。如果后续其他开发需要Hyper-V可以再开启。启用WSL 2WSL 2是Docker Desktop for Windows的推荐后端。以管理员身份打开PowerShell并运行wsl --install这个命令会默认安装Ubuntu发行版并启用WSL 2特性。你也可以通过wsl --list --online查看可用发行版用wsl --install -d 发行版名称安装指定版本。配置 Docker Desktop安装Docker Desktop后打开设置Settings在“General”中确保“Use the WSL 2 based engine”被勾选。在“Resources” - “WSL Integration”中启用你已安装的Linux发行版如Ubuntu的集成。这样可以在WSL子系统中直接使用docker命令。完成以上步骤后重启Docker Desktop通常可以解决问题。6.2 路径映射与文件权限的坑在Windows下编写docker-compose.yml文件时如果需要将宿主机目录挂载到容器内例如想持久化MinIO的数据路径写法需要注意。错误示例在docker-compose.yml中volumes: - C:\Users\YourName\milvus_data:/minio/data这种Windows绝对路径在Docker Desktop的上下文中可能无法被正确解析尤其是在使用WSL 2后端时。正确做法使用WSL中的路径如果你启用了WSL集成最好的方式是在WSL子系统中进行操作。打开WSL终端如Ubuntu在/home/yourname/下创建目录然后在docker-compose.yml中使用WSL路径如- /home/yourname/milvus_data:/minio/data。Docker Desktop可以无缝识别这些路径。使用相对路径将docker-compose.yml和数据目录放在同一个父目录下使用相对路径如- ./minio_data:/minio/data。这是最便携、最推荐的方式。如果需要映射Windows目录可以尝试使用/c/Users/YourName/milvus_data这种格式Git Bash风格但并非所有情况都稳定。建议优先采用方法1或2。文件权限问题Linux容器对挂载的卷有用户权限要求。如果你在Windows下创建了目录并挂载容器内的进程如MinIO可能因为没有写权限而启动失败。在WSL子系统中创建目录并确保其权限开放如chmod 777可以避免大部分问题。6.3 双系统间的数据共享与迁移思路在双系统环境下你可能希望Windows和Anolis都能访问同一份Milvus测试数据。由于两个系统文件格式不同直接共享磁盘分区可能较复杂。这里提供两个实用思路通过 Docker 镜像和导出/导入实现这是最干净的方式。在Anolis系统上使用docker commit或docker export将包含数据的容器如MinIO保存为镜像或文件包。然后将这个镜像文件复制到Windows系统使用docker load或docker import导入。这样可以在两个系统获得一模一样的数据环境。适合阶段性备份和迁移。使用网络存储或同步目录在家庭网络内可以搭建一个Samba或NFS服务器将数据目录放在这个网络存储上。然后在Windows和Anolis的docker-compose.yml中都将数据卷挂载指向这个网络路径如- /nfs/milvus_data:/minio/data。这样两个系统操作的就是同一份数据。这需要一定的网络配置知识。对于日常开发测试第一种镜像迁移的方法更简单可控。7. 常见问题排查与性能调优实录7.1 部署与启动常见问题问题1docker compose up -d后某个服务如standalone反复重启状态一直是Restarting。排查首先查看该容器的详细日志docker compose logs 服务名。常见原因有依赖服务未就绪Milvus依赖etcd和minio。可能是网络问题导致Milvus启动时无法连接它们。检查Compose文件中服务间的依赖关系depends_on并确保etcd和minio的日志显示启动成功。端口冲突宿主机19530或其他端口已被占用。使用netstat -tlnp | grep 端口号命令检查并停止冲突进程或修改Compose文件中的端口映射。内存不足Milvus standalone容器默认可能占用较大内存。检查宿主机可用内存或尝试在Compose文件中为standalone服务添加资源限制如mem_limit: 4g先保证它能启动。问题2ATTU 无法连接提示连接超时或拒绝。排查确认Milvus服务是否真的在运行docker compose ps查看standalone服务状态是否为Up。确认ATTU容器是否运行正常。最关键的一步检查连接地址。如果你在宿主机浏览器访问地址应为http://宿主机IP:3000连接Milvus的地址应填宿主机IP:19530。如果你在容器网络内部比如从另一个测试容器连接才填standalone:19530。这是最容易出错的地方。检查防火墙Anolis 8默认的firewalld或Windows防火墙可能阻止了3000或19530端口。使用sudo firewall-cmd --list-portsAnolis或在Windows防火墙中添加入站规则。问题3插入或搜索向量时客户端报错“collection not found”或“index not exist”。排查确认集合名称拼写无误且确实已创建成功。在ATTU界面或使用milvus-cli的list collections命令确认。进行搜索前必须为向量字段创建索引。在ATTU的“Index”页面为对应集合的向量字段创建索引如IVF_FLAT并执行“Load”操作将集合加载到内存。只有加载后的集合才能被搜索。7.2 基础性能调优建议对于单机部署的Milvus用于开发和测试以下几点调整可以提升体验调整 Docker 资源限制在Docker DesktopWindows/Mac或/etc/docker/daemon.jsonLinux中为Docker分配更多的CPU核心和内存。对于Milvus standalone建议至少分配4GB内存和2个CPU核心。优化 Milvus 配置Milvus的配置可以通过环境变量或修改配置文件进行覆盖。在docker-compose.yml中可以为standalone服务添加环境变量例如environment: - “common.retentionDuration432000” # 元数据保留时间秒 - “quotaAndLimits.enabletrue” - “quotaAndLimits.forceDenyfalse”更详细的配置项可以参考Milvus官方文档。对于测试环境主要关注内存相关的参数避免OOM内存溢出。索引类型选择FLAT索引最精确但速度慢适合向量数量少10万的场景。IVF_FLAT、IVF_SQ8或HNSW是更通用的选择需要在创建索引时指定nlist聚类中心数或M/efConstructionHNSW参数。一个简单的起点对于百万级数据nlist可以设置为sqrt(向量总数)左右。在ATTU创建索引时有参数说明和推荐值。批量插入数据通过SDK如PyMilvus插入数据时尽量使用批量插入每次插入几百到几千条而不是单条插入这可以极大提升数据导入效率。7.3 数据持久化与备份默认的Docker Compose配置中已经通过卷volumes将etcd、minio和Milvus的日志数据映射到了宿主机的匿名卷。为了更好的管理建议将其改为命名卷或绑定挂载到宿主机特定目录。修改docker-compose.yml中的卷定义示例volumes: # 将匿名卷改为命名卷 milvus-etcd-data: milvus-minio-data: milvus-logs: services: etcd: # ... volumes: - “milvus-etcd-data:/etcd_data” minio: # ... volumes: - “milvus-minio-data:/minio/data” standalone: # ... volumes: - “milvus-logs:/milvus/logs” - “milvus-logs:/milvus/data”这样即使删除容器数据卷依然存在。你可以使用docker volume ls查看和管理这些命名卷。备份策略定期备份的关键是MinIO中的数据存储桶和etcd中的元数据。可以编写脚本使用mcMinIO客户端命令备份存储桶并使用etcdctl工具备份etcd数据。将备份文件存储到宿主机其他安全位置或云存储。8. 从部署到应用一个简单的 Python 示例部署好Milvus后我们最终是要用程序来操作它的。这里给出一个在Anolis 8或Windows WSL中使用Python连接我们刚部署的Milvus并进行插入与搜索的极简示例。首先确保你的Python环境建议3.8已安装pymilvus库pip install pymilvus2.3.4然后创建测试脚本milvus_demo.pyfrom pymilvus import connections, Collection, FieldSchema, CollectionSchema, DataType, utility import random # 1. 连接到 Milvus 服务 # 注意如果Python脚本运行在宿主机host填‘127.0.0.1’如果运行在Docker网络内的另一个容器填‘standalone’ connections.connect(host‘127.0.0.1’, port‘19530’) # 2. 定义集合结构如果已存在可以跳过创建 collection_name “demo_collection” if not utility.has_collection(collection_name): fields [ FieldSchema(name“id”, dtypeDataType.INT64, is_primaryTrue, auto_idTrue), FieldSchema(name“title”, dtypeDataType.VARCHAR, max_length200), FieldSchema(name“embedding”, dtypeDataType.FLOAT_VECTOR, dim128) # 假设是128维向量 ] schema CollectionSchema(fields, description“Demo collection for search”) collection Collection(namecollection_name, schemaschema) print(f“Collection {collection_name} created.”) else: collection Collection(collection_name) print(f“Collection {collection_name} already exists.”) # 3. 创建索引仅需执行一次 index_params { “index_type”: “IVF_FLAT”, “metric_type”: “L2”, “params”: {“nlist”: 128} } # 为向量字段创建索引 collection.create_index(field_name“embedding”, index_paramsindex_params) print(“Index created.”) # 4. 加载集合到内存搜索前必须加载 collection.load() print(“Collection loaded.”) # 5. 准备并插入一些随机数据 num_entities 1000 data [ [f“title_{i}” for i in range(num_entities)], # 标题 [[random.random() for _ in range(128)] for _ in range(num_entities)] # 随机向量 ] # 注意id字段是自增的所以不需要提供 mr collection.insert([data[0], data[1]]) print(f“{num_entities} entities inserted. Inserted ids: {mr.primary_keys[:5]}...”) # 打印前5个ID # 6. 执行向量相似度搜索 search_vectors [[random.random() for _ in range(128)]] # 一个随机查询向量 search_params {“metric_type”: “L2”, “params”: {“nprobe”: 10}} # nprobe是搜索时访问的聚类中心数 results collection.search( datasearch_vectors, anns_field“embedding”, paramsearch_params, limit5, # 返回最相似的5条结果 output_fields[“title”, “id”] # 同时返回这些字段 ) # 7. 打印搜索结果 for i, hits in enumerate(results): print(f“Search results for query {i}:”) for hit in hits: print(f“ id: {hit.id}, title: {hit.entity.get(‘title’)}, distance: {hit.distance}”) # 8. 清理可选删除集合 # utility.drop_collection(collection_name) # print(f“Collection {collection_name} dropped.”)运行这个脚本python milvus_demo.py如果一切顺利你将看到集合创建、索引构建、数据插入和搜索的完整过程输出。这个例子展示了PyMilvus SDK的基本用法你可以在此基础上构建更复杂的应用如结合LangChain、构建RAG系统等。通过这个从系统准备、Docker部署、可视化操作到客户端编程的完整闭环你应该已经掌握了在混合操作系统环境下驾驭Milvus这项强大工具的基本能力。记住容器化部署的核心优势在于环境一致性无论是Windows下的快速原型验证还是Anolis/Linux下的稳定服务部署你都能拥有相同的体验。