Milvus Builder 镜像技术文档

一、镜像概述和主要用途

概述

Milvus Builder 是一个预配置的 Docker 镜像，专为 Milvus 向量数据库及其生态组件的构建流程设计。该镜像集成了 Milvus 编译、打包所需的全套依赖环境（如编译器、系统库、构建工具链），并内置自动化构建脚本，旨在简化 Milvus 源码编译、自定义组件开发及版本定制的流程。

主要用途

• 快速编译 Milvus 核心源码（支持指定版本或分支）
• 构建 Milvus 生态插件（如存储引擎扩展、索引插件）
• 定制 Milvus 发行包（含特定配置或补丁）
• 集成到 CI/CD 流程，实现自动化构建与测试

二、核心功能和特性

1. 预配置构建环境

• 内置 GCC 11+、CMake 3.20+、Go 1.20+、Rust 1.60+ 等编译器
• 预安装 Milvus 核心依赖库（如 Protobuf、Arrow、RocksDB、OpenBLAS）
• 包含 Python 3.9+ 及 pip 依赖（用于构建 Python SDK 及工具链）

2. 多版本与分支支持

• 支持 Milvus v2.0+ 全系列版本构建，可指定 Git 分支或 Tag（如 v2.3.4、main 分支）
• 兼容 Milvus 社区版、企业版构建流程

3. 跨平台构建能力

• 支持 Linux x86_64、ARM64 架构构建
• 可生成多种部署格式（二进制包、Docker 镜像、RPM/DEB 包）

4. 构建效率优化

• 内置构建缓存机制（缓存依赖下载、中间编译产物）
• 并行编译支持（默认启用多线程构建，可通过参数调整）

5. 灵活定制能力

• 支持通过环境变量指定构建目标（如 server、sdk、all）
• 允许挂载自定义补丁或配置文件，覆盖默认构建逻辑

三、使用场景和适用范围

适用用户

• Milvus 源码开发者（需本地编译调试）
• 插件/扩展开发者（基于 Milvus 内核开发自定义功能）
• DevOps 工程师（集成到 CI/CD 流水线自动化构建）
• 企业级用户（定制 Milvus 版本，集成私有功能或安全补丁）

典型场景

1. 本地源码编译：开发者克隆 Milvus 源码后，无需手动配置依赖，直接通过镜像编译可执行文件。
2. 插件开发：基于 Milvus 源码开发自定义索引插件，利用镜像环境编译并测试兼容性。
3. CI/CD 集成：在 GitHub Actions 或 GitLab CI 中，使用该镜像自动构建特定分支的 Milvus 版本并推送至制品库。
4. 版本定制：指定 Milvus 基础版本，叠加企业内部补丁，构建私有发行包。

四、使用方法和配置说明

4.1 镜像获取

从 Docker Hub 或私有仓库拉取镜像：

# 从 Docker Hub 获取（默认 latest 标签，对应 Milvus 最新稳定版构建环境）
docker pull milvusdb/builder:latest

# 指定 Milvus 版本（如构建 Milvus v2.3.x 需使用对应 builder 版本）
docker pull milvusdb/builder:v2.3

4.2 基本构建流程

步骤 1：准备本地资源

• 源码目录：本地克隆 Milvus 源码（如 ~/milvus-src）
• 输出目录：用于存放构建产物（如 ~/milvus-build）

步骤 2：运行构建容器

通过 docker run 启动容器，挂载本地源码和输出目录，指定构建参数：

docker run -it --rm \
  -v ~/milvus-src:/workspace/milvus  # 挂载本地 Milvus 源码到容器内工作目录  
  -v ~/milvus-build:/output         # 挂载输出目录，存放构建产物  
  -e MILVUS_VERSION=v2.3.4          # 指定 Milvus 版本（若源码无 Tag，需手动指定）  
  -e BUILD_TARGET=server            # 构建目标：server（服务端）、sdk（SDK）、all（全部）  
  milvusdb/builder:latest  

4.3 核心配置参数

环境变量（Environment Variables）

挂载目录（Volumes）

4.4 高级用法示例

示例 1：构建 Milvus 服务端 Docker 镜像

docker run -it --rm \
  -v ~/milvus-src:/workspace/milvus \
  -v ~/milvus-build:/output \
  -v /var/run/docker.sock:/var/run/docker.sock  # 挂载 Docker 套接字，用于在容器内构建镜像  
  -e BUILD_TARGET=server \
  -e OUTPUT_FORMAT=docker \
  -e MILVUS_VERSION=v2.3.4 \
  milvusdb/builder:latest  

说明：需挂载宿主机 Docker 套接字（/var/run/docker.sock），使容器内构建的镜像可直接推送到宿主机 Docker 环境。

示例 2：通过 docker-compose 集成到 CI/CD 流程

创建 docker-compose.build.yml：

version: '3.8'
services:
  milvus-builder:
    image: milvusdb/builder:v2.3
    volumes:
      - ./milvus-src:/workspace/milvus  # 源码目录（CI 中通常为工作区目录）
      - ./output:/output               # 产物输出目录
      - ./cache:/cache                 # 缓存目录（CI 中可持久化缓存加速构建）
    environment:
      - MILVUS_VERSION=v2.3.4
      - BUILD_TARGET=all
      - OUTPUT_FORMAT=package
      - ENABLE_CACHE=true
    command: /bin/bash -c "cd /workspace/milvus && ./build.sh"  # 执行自定义构建脚本

运行命令：

docker-compose -f docker-compose.build.yml up

五、注意事项

1. 源码完整性：挂载的源码目录需包含完整 Milvus 源码（包括子模块，建议通过 git clone --recursive 拉取）。
2. 版本兼容性：builder 镜像版本需与 Milvus 源码版本匹配（如构建 v2.2.x 需使用 milvusdb/builder:v2.2）。
3. 资源需求：构建过程消耗较多 CPU 和内存，建议宿主机配置 ≥4 核 CPU、8GB 内存，否则可能因资源不足失败。
4. 缓存清理：若需重新构建（如切换分支），建议清理缓存目录（~/.milvus-cache）或设置 ENABLE_CACHE=false。

六、镜像维护与更新

• 镜像版本与 Milvus 主版本同步（如 v2.3 对应 Milvus v2.3.x 系列），通过 milvusdb/builder:<version> 拉取特定版本。
• 基础依赖（如编译器、系统库）更新将通过 latest 标签滚动发布，建议生产环境固定版本标签（如 v2.3）以避免兼容性问题。
• 问题反馈：通过 Milvus GitHub Issues 提交构建相关问题。