Vagrant
Vagrant 是一个流行的本地虚拟化工具,可以按照声明式的方式创建本地虚拟机。
Pigsty 需要 Linux 环境运行,您可以使用 Vagrant 轻松在本地创建 Linux 虚拟机进行测试。
当前推荐并验证的基线为 Rocky Linux 9.8 / 10.2、Debian 12.15 / 13.6,以及 Ubuntu 22.04.5 / 24.04.4 / 26.04.0;Vagrant 的大版本别名会映射到对应的固定 Box 版本。
安装依赖
首先,确保您的系统中已经安装了 Vagrant 和虚拟机软件(VirtualBox, libvirt,Hyper-V,Parallel,……)。
在 MacOS 上,您可以使用 Homebrew 一键安装 vagrant 与 virtualbox; 在 Linux 上,您可以使用 VirtualBox 或 vagrant-libvirt 作为虚拟机管理软件; 在 Windows 专业版上,可以使用 VirtualBox 与 Hyper-V 作为提供商。
创建虚拟机
使用 Pigsty 提供的 make 快捷方式创建虚拟机:
您可以使用变体别名指定不同的操作系统镜像:
可用的操作系统后缀:8(EL8)、9(EL9)、10(EL10)、12(Debian 12.15)、13(Debian 13.6)、22(Ubuntu 22.04.5)、24(Ubuntu 24.04.4)、26(Ubuntu 26.04.0)
构建环境
您还可以使用以下别名创建 Pigsty 构建环境,这些模板不会替换基础镜像:
规格配置
Pigsty 在 vagrant/spec/ 目录下提供了多种预定义的虚拟机规格:
| 模板 | 节点数 | 规格 | 说明 | 别名 |
|---|---|---|---|---|
| meta.rb | 1 节点 | 2c4g x 1 | 单节点开发箱 | Devbox |
| dual.rb | 2 节点 | 1c2g x 2 | 双节点环境 | |
| trio.rb | 3 节点 | 1c2g x 3 | 三节点环境 | |
| full.rb | 4 节点 | 2c4g + 1c2g x 3 | 4 节点完整沙箱 | Sandbox |
| deci.rb | 10 节点 | 混合 | 10 节点环境 | |
| simu.rb | 20 节点 | 混合 | 20 节点生产仿真环境 | Simubox |
| minio.rb | 4 节点 | 1c2g x 4 + 磁盘 | MINIO(Silo)测试环境 | |
| citus.rb | 13 节点 | 混合 | Citus 协调节点与 6 组双副本 Worker | |
| oss.rb | 7 节点 | 2c2g x 7 | 7 平台 OSS 构建环境 | |
| pro.rb | 7 节点 | 2c2g x 7 | 7 平台 PRO 构建环境 | |
| rpm.rb | 2 节点 | 1c2g x 2 | 2 节点 EL 构建环境 | |
| deb.rb | 5 节点 | 1c2g x 5 | 5 节点 Deb 构建环境 | |
| all.rb | 7 节点 | 1c2g x 7 | 7 节点全量构建环境 |
每个规格文件包含一个描述虚拟机节点的 Specs 变量。例如,full.rb 包含 4 节点沙箱的定义:
当前 Vagrant 模板会为每台虚拟机显式置备 32 GB 主系统盘。普通节点另外创建一个数据盘,容量由规格中的 disk 指定、未指定时为 128 GB;
名称以 minio 开头的对象存储节点则创建四块 32 GB 数据盘并挂载到 /data1 至 /data4。
这些磁盘依赖 Vagrant 的实验性 disks 功能:使用仓库 Makefile 时已自动导出 VAGRANT_EXPERIMENTAL=disks,直接运行 vagrant 时需自行设置。
simu 规格详情
simu.rb 提供了一个 20 节点的生产环境仿真配置:
- 3 x infra 节点(
meta1-3):4c16g - 2 x haproxy 节点(
proxy1-2):1c2g - 4 x minio 节点(
minio1-4):1c2g - 5 x etcd 节点(
etcd1-5):1c2g - 6 x pgsql 节点(
pg-src-1-3,pg-dst-1-3):2c4g
配置脚本
使用 vagrant/config 脚本可以根据规格和选项生成最终的 Vagrantfile:
镜像别名
config 脚本支持多种镜像别名:
| 发行版 | 别名 | Vagrant Box |
|---|---|---|
| Rocky 8 | el8, rocky8, r8 | cloud-image/rocky-8 |
| Rocky 9 | el9, rocky9, el, r9 | cloud-image/rocky-9 |
| Rocky 10 | el10, rocky10, r10 | cloud-image/rocky-10 |
| Debian 12 | d12, debian12, deb12 | cloud-image/debian-12 |
| Debian 13 | d13, debian13, deb13 | cloud-image/debian-13 |
| Ubuntu 22.04.5 | u22, ubuntu22, ubuntu2204 | cloud-image/ubuntu-22.04 |
| Ubuntu 24.04.4 | u24, ubuntu24, ubuntu2404, ubuntu | cloud-image/ubuntu-24.04 |
| Ubuntu 26.04.0 | u26, ubuntu26, ubuntu2604 | cloud-image/ubuntu-26.04 |
| AlmaLinux 8 | alma8 | cloud-image/almalinux-8 |
| AlmaLinux 9 | alma9 | cloud-image/almalinux-9 |
| AlmaLinux 10 | alma10 | cloud-image/almalinux-10 |
| RHEL 8 / 9 | rhel8, rhel9 | generic/rhel8, generic/rhel9 |
| Oracle Linux 8 / 9 | oracle8, oracle9 | generic/oracle8, generic/oracle9 |
历史别名 d11/debian11/deb11 与 u20/ubuntu20/ubuntu2004 仍可在脚本映射表中看到,但当前会被显式拒绝,不属于支持镜像。
资源缩放
您可以使用环境变量 VM_SCALE 来调整资源倍数,默认值为 1:
例如,使用 VM_SCALE=4 配置 meta 规格,会将默认的 2c4g 调整为 8c16g:
simu 和 deci 规格不支持资源缩放,scale 参数会被自动重置为 1,因为其资源配置已经针对仿真场景优化。
虚拟机管理
vagrant/Makefile 提供了一系列快捷方式来管理虚拟机;以下命令在该目录中执行:
SSH 密钥
Pigsty Vagrant 模板默认使用您的 ~/.ssh/id_rsa[.pub] 作为虚拟机的 SSH 密钥。
在开始之前,请确保您有一个有效的 SSH 密钥对。如果没有,可以使用以下命令生成:
支持的镜像
标准 EL、Debian、Ubuntu、AlmaLinux 镜像矩阵使用 Vagrant Cloud 上的 cloud-image/* Box;显式的 RHEL / Oracle Linux 直连别名使用 generic/* Box。当前配置脚本对 VirtualBox、libvirt 以及 amd64、arm64 使用同一套 cloud-image/* 名称映射;具体 Box 载荷是否可用仍由 Vagrant Cloud 在运行时解析。
VirtualBox 与 libvirt 使用同一套映射。vagrant/config 会为所有受支持的 cloud-image/* 镜像写入下表中的已验证版本,以保证 amd64 与 arm64 环境可复现:
| 系统 | Vagrant Box | 源码版本策略 |
|---|---|---|
| Rocky 8 | cloud-image/rocky-8 | 8.10.20240528.0 |
| Rocky 9 | cloud-image/rocky-9 | 9.8.20260525.0 |
| Rocky 10 | cloud-image/rocky-10 | 10.2.20260525.0 |
| Debian 12 | cloud-image/debian-12 | 20260806.2562.0 |
| Debian 13 | cloud-image/debian-13 | 20260810.2566.0 |
| Ubuntu 22.04 | cloud-image/ubuntu-22.04 | 20260810.0.0 |
| Ubuntu 24.04 | cloud-image/ubuntu-24.04 | 20260801.0.0 |
| Ubuntu 26.04 | cloud-image/ubuntu-26.04 | 20260731.0.0 |
| AlmaLinux 8 | cloud-image/almalinux-8 | 8.10.20260803 |
| AlmaLinux 9 | cloud-image/almalinux-9 | 9.8.20260810 |
| AlmaLinux 10 | cloud-image/almalinux-10 | 10.2.20260526.0 |
已停止支持但仍保留显式别名的 Debian 11 与 Ubuntu 20.04 也分别固定为 20260618.2513.0 与 20250624.0.0;generic/* 的 RHEL、Oracle Linux 与 CentOS 7 兼容实验镜像固定为其最后发布的 4.3.12。这些旧镜像不属于当前支持矩阵。
环境变量
您可以使用以下环境变量来控制 Vagrant 行为:
注意事项
使用较旧版本的 VirtualBox 作为 Vagrant 提供商时,需要额外配置才能使用 10.x.x.x CIDR 作为 Host-Only 网络:
第一次使用 Vagrant 启动特定操作系统时,会下载相应的 Box 镜像文件(通常 1-2 GB)。下载完成后,镜像会被缓存,后续创建虚拟机时会直接复用。
如果您使用 libvirt 作为提供商,可以使用 make info 查看虚拟机、网络和存储卷,使用 make nuke 强制销毁所有相关资源。