Milvus 仓库测试体系实战指南:E2E 端到端测试与 Python 代码质量(Ruff)管理

原创2026-09-09 23:28:411,716 阅读
文章标签:向量数据库数据库分布式数据库云原生数据存储可观测性

Milvus 仓库测试体系实战指南:E2E 端到端测试与 Python 代码质量(Ruff)管理

导读

本文以 Milvus 开源仓库 tests/README_CN.md 为骨架,系统讲解仓库内置的测试与代码质量基础设施:如何在本地复现 E2E(端到端)测试的完整环境配置、依赖安装与运行流程,以及如何使用 Ruff 对 tests/ 下的全部 Python 代码(python_client、restful_client 等)执行 lint 与格式化,并做到与 CI 严格一致。读完本文,你将掌握 KinD + Helm 驱动的 K8s 化 E2E 测试链路,以及基于 BASE_REF 的"仅检查 PR 修改文件"的本地 CI 复现方法。


一、E2E Test 概览

Milvus 仓库将端到端测试集中放在 tests/ 目录下,测试脚本位于 tests/scripts/,核心入口为 e2e-k8s.sh。该脚本会依次完成:创建 KinD 集群、编译 Milvus 二进制与镜像、通过 Helm Chart 安装 Milvus、在 Docker 容器内以 pytest 并行执行测试用例、导出日志并清理环境。

从 e2e-k8s.sh 的源码结构看,测试流程被拆分为可独立跳过的若干阶段(SKIP_SETUP、SKIP_BUILD、SKIP_BUILD_IMAGE、SKIP_INSTALL、SKIP_TEST、SKIP_CLEANUP、SKIP_EXPORT_LOGS),支持 CPU 与 GPU(--gpu)两种构建模式,以及单集群 / 多集群(SINGLE_CLUSTER、MULTICLUSTER_SINGLE_NETWORK、MULTICLUSTER)三种拓扑,方便按需复用与排查。

1.1 配置清单

运行 E2E 测试前,需要先核对本机环境是否满足以下要求。

操作系统

操作系统 版本
CentOS 7.5 或以上
Ubuntu 16.04 或以上
Mac 10.14 或以上

硬件

硬件名称 建议配置
CPU x86_64 平台,Intel CPU Sandy Bridge 或以上;要求 CPU 指令集包含 SSE4_2、AVX、AVX2、AVX512(Milvus 核心 C++ 引擎的向量计算依赖这些指令集做 SIMD 加速)
内存 16 GB 或以上

软件

软件名称 版本
Docker 19.05 或以上
Docker Compose 1.25.5 或以上
jq 1.3 或以上
kubectl 1.14 或以上
helm 3.0 或以上
kind 0.10.0 或以上

补充说明:脚本在运行时会对缺失工具做自动降级处理——若系统找不到 kubectl、kind、helm,会分别下载指定版本到 $HOME/tool_cache/ 下并加入 PATH(详见 e2e-k8s.sh 中的 install_kubectl、install_kind、install_helm 逻辑,默认版本依次为 kubectl v1.20.2、kind v0.11.1、helm v3.5.4)。但 Docker 是硬性依赖:KinD 需要 Docker 来承载集群节点,脚本会先执行 docker info 检查,失败即报错退出。

1.2 安装依赖

检查 Docker 与 Docker Compose 状态

  1. 确认 Docker Daemon 正在运行:
$ docker info
  • 如果无法正常打印 Docker 相关信息,请先启动 Docker Daemon。
  • 要在没有 root 权限的情况下运行 Docker 命令,请将当前用户加入 docker 组:sudo usermod -aG docker $USER,然后退出终端并重新登录使更改生效。
  1. 确认 Docker Compose 版本:
$ docker compose version

docker compose version 1.25.5, build 8a1c60f6
docker-py version: 4.1.0
CPython version: 3.7.5
OpenSSL version: OpenSSL 1.1.1f  31 Mar 2020

安装 jq

jq 用于解析 kubectl / helm 输出的 JSON 数据,例如在 install_milvus.sh 中通过 jq .status.containerStatuses[0].restartCount 提取 Pod 重启次数。请按 jq 官方发布页提供的对应平台安装包安装,确保版本在 1.3 或以上。

安装 kubectl

kubectl 是操作 KinD 集群、检查 Service/Pod 状态的命令行工具,版本要求 1.14 或以上。可参考 Kubernetes 官方工具安装文档,按操作系统选择对应的安装方式。

安装 helm

helm 用于安装 Milvus Helm Chart,版本要求 3.0 或以上(脚本默认下载 v3.5.4)。安装后可通过 helm repo add zilliztech 添加 Milvus 官方 Chart 仓库。

安装 kind

kind(Kubernetes in Docker)用于在本地以 Docker 容器方式拉起 Kubernetes 集群,版本要求 0.10.0 或以上。安装完成后,e2e-k8s.sh 默认使用 kindest/node:v1.20.2 作为集群节点镜像(可通过 --node-image 覆盖)。

1.3 运行 E2E Test

在完成上述依赖安装后,进入 tests/scripts 目录直接执行入口脚本即可:

$ cd tests/scripts
$ ./e2e-k8s.sh

Getting help

你可以执行以下命令获取帮助:

$ ./e2e-k8s.sh --help

从 e2e-k8s.sh 的帮助文本可以提取完整的可选参数,按需组合可显著加速本地迭代(例如跳过编译阶段直接测试已构建的镜像):

参数 作用 默认值
--node-image 指定 KinD 节点 Docker 镜像 kindest/node:v1.20.2
--kind-config 指定 KinD 集群配置(如启用特定 K8s 特性) 空
--build-command 指定 Milvus 编译命令 CPU:make install use_disk_index=ON;GPU:make gpu-install
--install-extra-arg 传给 helm install 的额外参数(如 --set 覆盖 values) 空
--test-extra-arg 传给 pytest 的额外参数(如 --tags=L0) 空
--test-timeout E2E 测试超时时间(秒) 不限制
--topology 集群拓扑:SINGLE_CLUSTER / MULTICLUSTER_SINGLE_NETWORK / MULTICLUSTER SINGLE_CLUSTER
--topology-config 多集群拓扑配置文件 build/config/topology/multicluster.json
--skip-setup 跳过 KinD 集群创建 关
--skip-build 跳过 Milvus 二进制编译 关
--skip-build-image 跳过 Milvus Docker 镜像构建 关
--skip-install 跳过 Helm Chart 安装 关
--skip-test 跳过 E2E 测试执行 关
--skip-export-logs 跳过 kind export logs 关
--disable-kind 不创建 KinD 集群(连接已有集群) 关
--manual 手动模式:环境就绪后暂停,等待按键再退出 关
--gpu 以 GPU 模式构建并测试 关

1.4 运行链路背后的实现细节

  • 集群创建:非多集群模式下调用 setup_kind_cluster,同时脚本默认启动一个本地 registry 容器(kind-registry:5000),将构建出的 Milvus 镜像推送到该 registry 供集群节点拉取(PULL_POLICY=IfNotPresent)。
  • 镜像安装:install_milvus.sh 会先卸载同名旧 release(milvus-testing)并清理相关 PVC,然后执行 helm install --wait --timeout 800s。默认以独立(standalone)模式安装(cluster.enabled=false、pulsar.enabled=false、etcd.replicaCount=1、minio.mode=standalone);当 MILVUS_CLUSTER_ENABLED=true 时则启用集群模式(pulsar.broker.replicaCount=2)。安装失败时会抓取相关 Pod 的 events 辅助排障。
  • 测试执行:e2e.sh 会根据 Service 类型(LoadBalancer / NodePort / ClusterIP)自动探测 Milvus 服务地址与端口(默认 127.0.0.1:19530,必要时自动 port-forward),随后通过 docker compose run pytest 在 tests/docker 定义的 pytest 容器内执行 pytest -n 6 --host ... --port ...(PARALLEL_NUM 默认 6),测试工作目录为 /milvus/tests/python_client。
  • 环境清理:非 manual 模式下脚本正常结束时由 --skip-cleanup 控制是否清理 KinD 集群。

二、Python 代码质量(Ruff)

2.1 配置与覆盖范围

Ruff 配置位于 tests/ruff.toml,覆盖 tests/ 下所有 Python 代码,具体包括 python_client/、restful_client/、restful_client_v2/、benchmark/、scripts/ 等子目录。各子目录的运行时依赖仍通过各自的 requirements.txt 管理,Ruff 只负责静态检查与格式化,不介入依赖管理。

从 tests/ruff.toml 的源码可以确认关键配置项:

  • 行宽:line-length = 120;
  • 目标 Python 版本:target-version = "py312";
  • 启用规则集:E(pycodestyle 错误)、F(pyflakes)、W(pycodestyle 警告)、I(isort 导入排序)、UP(pyupgrade 现代语法升级);
  • 忽略规则:E501(行过长交由 formatter 处理)、E741(测试代码中常见的 l/I/O 歧义变量名)、F841(测试有意保留调用结果)、UP031(printf 风格格式化属于纯风格改写,且部分场景与 % (...) 元组不等价);
  • per-file-ignores:__init__.py 忽略 F401(未使用的导入,常见于重导出场景),conftest.py 额外忽略 F811(重复定义,pytest fixture 场景常见);
  • 格式化风格:双引号 quote、空格缩进、line-ending = "auto"。

2.2 常用命令

在 tests/ 目录下直接执行:

$ cd tests/
$ ruff check .                  # lint 检查
$ ruff check . --fix            # lint 检查并自动修复
$ ruff format .                 # 原地格式化
$ ruff format --check .         # 只检查不修改 (CI 友好)

启用的规则为 E、F、W、I、UP;目标 Python 版本为 3.12。

2.3 仅检查 PR 修改的文件(与 Python Lint CI 一致)

GitHub Actions workflow .github/workflows/python-lint.yaml 中的 job "Ruff (changed files only)" 只对 PR 修改的 tests/**/*.py 文件运行 ruff check 和 ruff format --check。从 workflow 源码可以看到:

  • 触发条件为 push/pull_request 且路径匹配 tests/**/*.py、tests/ruff.toml 或 workflow 自身;
  • 使用 tj-actions/changed-files@v46 检测变更文件集合,再通过 astral-sh/ruff-action@v4.0.0(版本锁定 0.15.11)分别执行 ruff check 与 ruff format --check --diff;
  • 另有一个始终运行的配置冒烟测试:对 tests/scripts 执行 ruff check --exit-zero,仅在 ruff 无法加载配置时报错,用于兜底配置文件的合法性。

直接对整个 tests/ 目录执行 ruff check . 往往过于粗糙——很多历史文件早于当前 lint 配置,会因为无关规则失败。因此要在本地精确复现 CI 这一步,推荐使用 tests/ 下的 Makefile:

$ cd tests/
$ make ci             # 对 PR 修改文件跑 ruff check + format --check(与 CI 等价)
$ make lint-fix       # 对 PR 修改文件跑 ruff check --fix
$ make format         # 对 PR 修改文件跑 ruff format
$ make help           # 显示所有 target 以及当前自动检测到的 BASE_REF

从 tests/Makefile 的实现看,其核心机制是:

  • RUFF_VERSION ?= 0.15.11:与 CI workflow 锁定的 ruff 版本保持一致;
  • RUFF := uvx ruff@$(RUFF_VERSION):通过 uvx(随 uv 分发)按需拉取并缓存对应版本的 ruff,避免本机全局安装版本漂移;
  • 变更文件集合通过 git diff --name-only --diff-filter=ACMR $(BASE_REF)...HEAD -- 'tests/**/*.py' 计算,采用三点 diff(从 merge-base 开始),与 CI 检测逻辑对齐。

BASE_REF 的自动检测与显式指定

BASE_REF 通过 gh pr view 从当前分支的开放 PR 中自动检测,流程为:解析 PR URL 得到 base <owner>/<repo>,再匹配本地 git remotes,得到形如 upstream/master、upstream/2.x,或(直接 clone 主仓库时)origin/main 的引用。该逻辑同样实现在 tests/Makefile 中。

如果当前分支没有开放 PR,必须显式设置 BASE_REF(Makefile 不再做任何猜测——base 选错会 diff 出无关 commit,导致检查范围失控):

$ make ci BASE_REF=upstream/master

使用前提:

  • 本地已安装 uv(提供 uvx);
  • 已认证 gh CLI(可通过 gh auth status 确认);若未认证或没有匹配的 remote,BASE_REF 为空,此时未显式指定会直接报错退出(_require-base-ref target),避免静默地在错误范围内运行。

三、小结与速查

任务 命令
查看 E2E 脚本帮助 cd tests/scripts && ./e2e-k8s.sh --help
运行完整 E2E 测试 cd tests/scripts && ./e2e-k8s.sh
跳过编译与镜像构建、仅测试 ./e2e-k8s.sh --skip-build --skip-build-image
GPU 模式 E2E ./e2e-k8s.sh --gpu
对 PR 变更文件做 lint + 格式检查 cd tests && make ci
指定 diff 基线 make ci BASE_REF=upstream/master
查看 ruff 规则与配置 阅读 tests/ruff.toml
查看 CI 中的 Python lint 步骤 阅读 .github/workflows/python-lint.yaml

本文所有命令与配置均以当前仓库实际内容为准:E2E 相关的参数说明、默认镜像与版本号来自 tests/scripts/e2e-k8s.sh 与 tests/scripts/install_milvus.sh,Ruff 的规则、忽略项与目标版本来自 tests/ruff.toml,make target 与 BASE_REF 机制来自 tests/Makefile。若后续仓库更新默认版本或新增参数,请以对应文件的实际内容为准。

登录后查看全文
milvus