Milvus 仓库测试体系实战指南:E2E 端到端测试与 Python 代码质量(Ruff)管理
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 状态
- 确认 Docker Daemon 正在运行:
$ docker info
- 如果无法正常打印 Docker 相关信息,请先启动 Docker Daemon。
- 要在没有
root权限的情况下运行 Docker 命令,请将当前用户加入docker组:sudo usermod -aG docker $USER,然后退出终端并重新登录使更改生效。
- 确认 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); - 已认证
ghCLI(可通过gh auth status确认);若未认证或没有匹配的 remote,BASE_REF为空,此时未显式指定会直接报错退出(_require-base-reftarget),避免静默地在错误范围内运行。
三、小结与速查
| 任务 | 命令 |
|---|---|
| 查看 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。若后续仓库更新默认版本或新增参数,请以对应文件的实际内容为准。