这次我们来看一个 LangChain 项目环境搭建的实战流程。这个流程的核心不是某个单一的模型，而是一套完整的、可复现的本地开发环境构建方案。如果你正在学习 LangChain，并希望在一个干净、隔离的虚拟机环境中，从零开始部署 Docker、Docker Compose 以及向量数据库 Milvus，那么这篇文章就是为你准备的。整个过程聚焦于实操，我们会一步步完成虚拟机克隆、系统配置、软件安装和服务启动，确保你最终能获得一个可用于 AI 应用开发的标准化环境。

本文的重点是“可复现”和“可操作”。我们将从一台基础的 Linux 虚拟机（例如 Ubuntu）开始，通过命令行完成所有必要组件的安装与配置。你会看到具体的命令、可能遇到的错误以及对应的解决方案。最终目标是成功启动一个 Milvus 单机版服务，为后续集成 LangChain 进行向量检索、构建 RAG（检索增强生成）应用打下坚实基础。

1. 核心能力速览

能力项 说明
项目类型 本地开发环境搭建与配置教程
技术栈 虚拟机 (VMware/VirtualBox) + Ubuntu + Docker + Docker Compose + Milvus
核心目标 构建一个干净、隔离的 LangChain 开发环境，并启动向量数据库 Milvus
硬件门槛 对宿主机 CPU 和内存有基本要求，需开启虚拟化支持。虚拟机本身资源建议 2核4G 以上。
启动方式 通过 Docker Compose 一键启动 Milvus 服务
主要功能 1. 虚拟机环境标准化配置
2. Docker 及 Docker Compose 安装
3. Milvus 单机版部署与启动
4. 服务状态验证与基本使用
适合场景 LangChain/RAG 应用本地开发、测试、学习；需要隔离的 AI 项目环境搭建

2. 适用场景与使用边界

这套环境搭建方案主要适合以下几类开发者：

  • LangChain 初学者 ：希望在一个纯净、无干扰的环境中系统学习 LangChain 及其生态工具。
  • AI 应用原型开发者 ：需要快速搭建包含向量数据库的后端服务，用于验证 RAG、智能体（Agent）等应用场景。
  • 团队协作与标准化 ：通过共享虚拟机镜像或配置脚本，确保团队所有成员拥有一致的开发环境，避免“在我机器上是好的”这类问题。

使用边界与注意事项：

  1. 性能限制 ：在虚拟机中运行 Docker 和 Milvus，性能会有一定损耗，不适合生产环境高并发、大数据量场景。主要用于开发和测试。
  2. 资源占用 ：同时运行宿主机系统、虚拟机、Docker 容器，对宿主机内存和 CPU 资源消耗较大。
  3. 数据持久化 ：需正确配置 Docker 卷（Volume）或绑定挂载，确保虚拟机重启后 Milvus 数据不丢失。
  4. 网络访问 ：确保虚拟机网络配置正确（如 NAT 或桥接），以便宿主机能够访问虚拟机内启动的 Milvus 服务端口。

3. 环境准备与前置条件

在开始之前，请确保你的宿主机满足以下条件：

  1. 宿主机操作系统 ：Windows 10/11, macOS 或 Linux。本文以 Windows 宿主机 + Ubuntu 虚拟机为例，但原理通用。
  2. 虚拟化支持已开启 ：这是运行虚拟机的基石。需要在计算机 BIOS/UEFI 设置中开启 Intel VT-x 或 AMD-V 虚拟化技术。
    • 如何检查（Windows） ：打开任务管理器 -> 性能 -> CPU，查看“虚拟化”是否显示“已启用”。
  3. 虚拟机软件 ：已安装 VMware Workstation、VMware Player 或 VirtualBox。本文示例使用 VMware。
  4. 基础虚拟机镜像 ：准备一个安装好的 Linux 虚拟机（如 Ubuntu 20.04/22.04 LTS）。建议使用 Minimal 或 Server 版本以减少资源占用。我们将以此为基础进行克隆和配置。
  5. 网络连接 ：虚拟机需要能访问互联网，以下载 Docker 和 Milvus 的安装包及镜像。

4. 克隆虚拟机与初始配置

为了避免污染原始镜像，我们首先克隆一份新的虚拟机用于本次环境搭建。

操作步骤：

  1. 在你的虚拟机管理软件（如 VMware）中，关闭原始 Ubuntu 虚拟机。
  2. 找到克隆功能（通常在虚拟机右键菜单或管理菜单中）。
  3. 选择“创建完整克隆”，为新虚拟机命名（例如 ubuntu-langchain-dev ）。
  4. 启动克隆好的新虚拟机，并使用账号密码登录。

初始系统配置（在克隆的虚拟机内执行）： 登录后，首先更新系统包列表并升级现有软件，这是一个好习惯。

# 更新软件包列表
sudo apt update

# 升级已安装的软件包
sudo apt upgrade -y

# 可选：安装一些常用工具，如网络工具、编辑器等
sudo apt install -y net-tools curl wget vim

5. 安装 Docker 引擎

Docker 是容器化运行 Milvus 的基础。我们将使用 Docker 官方提供的便捷脚本进行安装。

安装步骤：

  1. 下载并执行 Docker 安装脚本。
  2. 将当前用户加入 docker 组，以便无需 sudo 即可运行 Docker 命令。
# 1. 下载 Docker 安装脚本
curl -fsSL https://get.docker.com -o get-docker.sh

# 2. 执行安装脚本
sudo sh get-docker.sh

# 3. 安装完成后，将当前用户加入 docker 用户组
sudo usermod -aG docker $USER

# 4. 提示：为了使组更改生效，你需要**注销并重新登录**，或者重启虚拟机。
#    你可以先不重启，继续安装 Docker Compose，但后续运行 `docker` 命令可能仍需 `sudo`。
#    为了验证，可以尝试运行（如果提示权限错误，请先使用 sudo）：
sudo docker --version

常见问题排查：

  • curl: command not found ：先执行 sudo apt install -y curl 安装 curl。
  • 脚本执行失败 ：可能是网络问题。可以尝试使用国内镜像源，或者查阅 Docker 官方文档使用其他安装方式。
  • 用户组更改未生效 ：执行 newgrp docker 命令或重启虚拟机。

6. 安装 Docker Compose

Docker Compose 用于定义和运行多容器应用。Milvus 单机版依赖多个容器（如 etcd、MinIO），使用 Compose 可以一键管理。

安装步骤： 推荐从 Docker Compose 的 GitHub Release 页面直接下载二进制文件。

# 1. 确定要下载的版本，例如 v2.23.0。请查看 GitHub 最新版本。
COMPOSE_VERSION=v2.23.0

# 2. 下载 Docker Compose 二进制文件到 /usr/local/bin/docker-compose
sudo curl -L "https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 3. 赋予二进制文件可执行权限
sudo chmod +x /usr/local/bin/docker-compose

# 4. 创建软链接（可选，但可确保 `docker compose` 命令可用）
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

# 5. 验证安装
docker-compose --version
# 或使用新的 `docker compose` 命令格式
docker compose version

7. 安装与启动 Milvus 单机版

Milvus 提供了官方的 Docker Compose 配置文件，使得部署变得非常简单。

操作步骤：

  1. 创建专用目录并下载配置文件。
  2. 使用 Docker Compose 启动所有服务。
  3. 验证服务是否正常运行。
# 1. 创建一个工作目录，并进入该目录
mkdir -p ~/milvus-standalone && cd ~/milvus-standalone

# 2. 下载 Milvus 单机版的 Docker Compose 配置文件
# 注意：请从 Milvus 官方 GitHub 仓库获取最新版本的 compose 文件。
# 以下以较新的版本为例，下载前请确认版本号。
wget https://github.com/milvus-io/milvus/releases/download/v2.3.3/milvus-standalone-docker-compose.yml -O docker-compose.yml

# 3. 检查下载的 YAML 文件内容，确保其正确性（可选）
cat docker-compose.yml | head -20

# 4. 在后台启动所有服务（包括 Milvus, etcd, MinIO）
sudo docker compose up -d
# 如果你安装的是独立的 docker-compose 命令，也可以使用：
# sudo docker-compose up -d

# 5. 查看容器运行状态，确认所有服务状态均为 `running` 或 `healthy`
sudo docker compose ps
# 或
sudo docker-compose ps

命令输出解读： 执行 docker compose ps 后，你应该看到类似下面的输出，表明三个核心服务都已正常启动：

NAME                IMAGE                                          COMMAND                  SERVICE             CREATED             STATUS              PORTS
milvus-standalone   milvusdb/milvus:v2.3.3                        "/tini -- milvus run…"   milvus-standalone   10 seconds ago      Up 9 seconds        0.0.0.0:19530->19530/tcp, 0.0.0.0:9091->9091/tcp
milvus-etcd         quay.io/coreos/etcd:v3.5.5                    "etcd -advertise-cli…"   etcd                10 seconds ago      Up 9 seconds        2379-2380/tcp
milvus-minio        minio/minio:RELEASE.2023-03-20T20-16-18Z      "sh -c 'mkdir -p /da…"   minio               10 seconds ago      Up 9 seconds        0.0.0.0:9000->9000/tcp, 0.0.0.0:9001->9001/tcp

8. 功能测试与效果验证

服务启动后，我们需要验证 Milvus 是否真的可以访问并提供服务。

8.1 验证服务健康状态

Milvus 提供了一个健康检查接口。

# 使用 curl 调用 Milvus 的健康检查 API
curl http://localhost:9091/healthz

如果返回 {"status":"OK"} ，则说明 Milvus 服务运行健康。

8.2 使用 Python 客户端进行连接测试

这是更贴近实际开发场景的验证方式。

  1. 在虚拟机内安装 Milvus Python SDK： 

    pip install pymilvus

    （如果未安装 pip，请先执行 sudo apt install -y python3-pip ）

  2. 创建测试脚本 test_connection.py ： 

    from pymilvus import connections, utility

# 1. 连接到本地的 Milvus 服务
print("正在连接 Milvus...")
connections.connect(host='127.0.0.1', port='19530')
print("连接成功！")

# 2. 检查服务器状态（可选，需要相应权限）
try:
    version = utility.get_server_version()
    print(f"Milvus 服务器版本: {version}")
except Exception as e:
    print(f"获取版本信息时出错（可能权限不足）: {e}")

# 3. 列出所有集合（数据库），初始应为空
collections = utility.list_collections()
print(f"当前集合列表: {collections}")

# 4. 断开连接
connections.disconnect()
print("测试完成，连接已断开。")

  3. 运行测试脚本： 

    python3 test_connection.py

    预期成功输出： 

    正在连接 Milvus...
连接成功！
Milvus 服务器版本: 2.3.3
当前集合列表: []
测试完成，连接已断开。

    如果看到“连接成功！”且没有报错，则证明 Milvus 向量数据库服务已完全就绪，可以接受客户端的操作指令。

9. 接口 API 与基本操作

Milvus 主要通过 gRPC 端口（默认 19530）和 HTTP 端口（默认 9091）提供服务。上一步的 Python SDK 是对这些接口的封装。对于更底层的测试或集成，你也可以直接使用其 RESTful API（部分管理功能）或各种语言的 SDK。

关键服务端口说明：

  • Milvus 服务 : 19530 (gRPC), 9091 (HTTP 健康检查与管理)
  • MinIO (对象存储) : 9000 (API), 9001 (Console)
  • etcd (元数据存储) : 2379 (客户端通信)

下一步可以尝试的 API 操作（通过 Python SDK）：

  1. 创建集合（Collection） ：相当于数据库的表。
  2. 创建索引（Index） ：为向量字段创建索引以加速搜索。
  3. 插入数据（Insert） ：向集合中插入向量数据和标量属性。
  4. 向量搜索（Search） ：执行近似最近邻（ANN）搜索。

这些操作是构建 RAG 应用的核心步骤，将在你后续集成 LangChain 时用到。

10. 资源占用与性能观察

在虚拟机中运行这套服务，了解其资源消耗很重要。

观察资源占用命令： 

# 查看所有运行中的容器资源占用情况
sudo docker stats

# 查看特定容器的详细资源使用（如 milvus-standalone）
sudo docker stats milvus-standalone

# 在虚拟机内查看整体系统资源（CPU、内存）
htop  # 如果未安装，先运行 `sudo apt install -y htop`
# 或使用
top

典型资源占用（仅供参考，实际因数据和查询而异）：

  • 空闲状态 ：启动后，三个容器总内存占用约 1.5GB - 2.5GB。
  • CPU 占用 ：空闲时接近 0%，执行插入或搜索任务时会显著升高。
  • 磁盘空间 ：Docker 镜像和卷会占用数 GB 空间。使用 docker system df 查看。

性能优化提示：

  1. 分配更多资源给虚拟机 ：如果宿主机资源充足，在虚拟机设置中增加 CPU 核心数和内存（如 4核8G），能明显提升 Milvus 处理速度。
  2. 使用 SSD 硬盘 ：将虚拟机磁盘文件放在宿主机 SSD 上，能极大改善 etcd 和 MinIO 的 I/O 性能。
  3. 调整 Milvus 配置 ：对于高级用户，可以修改 docker-compose.yml 中 Milvus 容器的启动参数，或挂载自定义的 server_config.yaml 来调整缓存大小、线程数等。

11. 常见问题与排查方法

问题现象 可能原因 排查方式 解决方案
docker compose up -d 失败，提示 Cannot connect to the Docker daemon Docker 服务未启动，或当前用户无权限。 运行 sudo systemctl status docker 查看服务状态。运行 groups 查看当前用户是否在 docker 组。 启动服务： sudo systemctl start docker 。将用户加入 docker 组后 务必注销重登或重启 。临时使用 sudo 。
Milvus 容器启动后很快退出（Exited） 端口冲突、内存不足、配置文件错误。 sudo docker compose logs milvus-standalone 查看容器日志。 sudo docker compose ps -a 查看退出状态码。 根据日志错误解决。常见于 19530 或 9091 端口被占用，可修改 docker-compose.yml 中的端口映射。确保虚拟机内存足够（>2GB）。
健康检查 curl http://localhost:9091/healthz 失败 Milvus 服务未完全启动或崩溃。 sudo docker compose logs milvus-standalone 查看详细启动日志。 等待片刻再试。检查日志中是否有明显的错误信息，如依赖的 etcd 连接失败。
Python 客户端连接超时 防火墙阻止、IP地址错误、服务未监听。 在虚拟机内运行 netstat -tlnp | grep 19530 检查端口监听状态。确认连接 IP 是 127.0.0.1 。 确保连接地址正确。如果是宿主机连接虚拟机，需确认虚拟机网络模式（如桥接），并使用虚拟机 IP，同时检查虚拟机防火墙（ sudo ufw status ）。
执行 docker compose 命令提示 command not found Docker Compose 未安装或未在 PATH 中。 检查 /usr/local/bin/docker-compose 是否存在且有执行权限。 重新执行安装步骤，或使用 sudo /usr/local/bin/docker-compose 指定全路径。也可安装 docker-compose-plugin 。
虚拟机无法上网 虚拟机网络配置问题。 在虚拟机内 ping 8.8.8.8 。检查虚拟机软件的网络设置（如 NAT 模式）。 确保虚拟机网络适配器已连接。在 VMware 中，可尝试“恢复默认设置”。

12. 最佳实践与使用建议

  1. 环境快照 ：在完成 Docker 和 Docker Compose 安装后，为虚拟机创建一个“快照”（Snapshot）。这样如果后续 Milvus 配置出错，可以快速回滚到这个干净的状态。
  2. 数据持久化 ：默认的 docker-compose.yml 通常已配置了匿名卷（volume）来持久化 etcd、MinIO 和 Milvus 的数据。你可以在宿主机上找到这些卷，或修改配置将其映射到虚拟机内明确的目录，便于备份。 
    # 示例：修改 docker-compose.yml 中的 volumes 部分，将数据挂载到主机路径
services:
  milvus-standalone:
    # ... 其他配置
    volumes:
      - ./volumes/milvus:/var/lib/milvus
  3. 服务管理 ：
    • 停止服务 ： sudo docker compose down
    • 停止并删除数据卷 ： sudo docker compose down -v (谨慎使用，会清空所有数据！)
    • 查看实时日志 ： sudo docker compose logs -f milvus-standalone
    • 重启服务 ： sudo docker compose restart
  4. 为生产环境准备 ：本文部署的是 Standalone 版，适用于开发测试。生产环境应考虑使用 Cluster 集群版，并配置独立的 MySQL/PGSQL 作为元数据存储，以及更可靠的对象存储服务。
  5. 与 LangChain 集成 ：环境就绪后，下一步就是在同一虚拟机或网络互通的其他机器上，安装 LangChain 及其 Milvus 集成包（ langchain-milvus ），开始构建你的 RAG 应用。

至此，你已经成功在克隆的虚拟机中配置了一个包含 Docker、Docker Compose 和 Milvus 的标准化 LangChain 开发环境。这个环境隔离性好，配置清晰，非常适合进行各种 AI 应用的实验和开发。接下来，你就可以专注于 LangChain 的代码编写和业务逻辑实现了。如果在后续集成中遇到连接问题，首先回头检查本指南中的验证步骤，确保 Milvus 这个基础服务是正常运行的。

# 虚拟机
Logo
码道开发者社区

码道开发者社区，聚焦华为云码道 CodeArts 代码智能体，沉淀 Agent、Skill、鸿蒙开发实战内容，供开发者查阅资料、交流技术、分享工程实践

更多推荐

cover

AI 已经能直接改设计稿了:Windows部署Penpot，接入Codex MCP实测

avatar 码道开发者社区

【AI 业务流架构师】AI 业务流架构师方法论：Agentic AI 范式转移与业务编排思维

2026 年，Anthropic CEO Dario Amodei 在 Code with Claude 大会上的一个判断广为流传：一个人运营一家十亿美元级公司的概率是 70%–80%。这句话听起来像科幻小说的设定，但它背后是一个正在发生的结构性变化——AI 把"执行"的成本压到了历史低点，同时把"编排"的价值推到了前台。这意味着我们需要一套新的思考框架，来回答两个问题：一个人如何拥有一个公司的产

avatar 码道开发者社区
cover

Codex CLI实战 从一句模糊需求到可执行可测试可验收的开发任务把“帮我优化一下”变成 Codex 能执行、团队能复核、测试能证明的工程任务

avatar 码道开发者社区