Vagrant

使用 Vagrant 在本地创建虚拟机环境

Vagrant 是一个流行的本地虚拟化工具,可以按照声明式的方式创建本地虚拟机。

Pigsty 需要 Linux 环境运行,您可以使用 Vagrant 轻松在本地创建 Linux 虚拟机进行测试。


安装依赖

首先,确保您的系统中已经安装了 Vagrant 和虚拟机软件(VirtualBoxlibvirt,Hyper-V,Parallel,……)。

在 MacOS 上,您可以使用 Homebrew 一键安装 vagrant 与 virtualbox; 在 Linux 上,您可以使用 VirtualBox 或 vagrant-libvirt 作为虚拟机管理软件; 在 Windows 专业版上,可以使用 VirtualBox 与 Hyper-V 作为提供商。

brew install vagrant virtualbox ansible
# 安装 VirtualBox 后需要重启系统,并在系统偏好设置中允许其内核扩展。
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

创建虚拟机

使用 Pigsty 提供的 make 快捷方式创建虚拟机:

cd ~/pigsty

make meta       # 1 节点开发箱,用于快速上手、开发和测试
make full       # 4 节点沙箱,用于高可用测试和功能演示
make simu       # 20 节点仿真环境,用于生产环境模拟

# 其他不常用的规格
make dual       # 2 节点环境
make trio       # 3 节点环境
make deci       # 10 节点环境

您可以使用变体别名指定不同的操作系统镜像:

make meta9      # 使用 RockyLinux 9.7 创建单节点
make full12     # 使用 Debian 12.13 创建 4 节点沙箱
make simu24     # 使用 Ubuntu 24.04 创建 20 节点仿真环境
make full26     # 使用 Ubuntu 26.04 创建 4 节点沙箱

可用的操作系统后缀:8(EL8)、9(EL9)、10(EL10)、12(Debian 12)、13(Debian 13)、22(Ubuntu 22.04)、24(Ubuntu 24.04)、26(Ubuntu 26.04)

构建环境

您还可以使用以下别名创建 Pigsty 构建环境,这些模板不会替换基础镜像:

make oss        # 3 节点 OSS 构建环境
make pro        # 5 节点 PRO 构建环境
make rpm        # 3 节点 EL8/9/10 构建环境
make deb        # 4 节点 Debian12/13 Ubuntu22/24 构建环境
make all        # 7 节点全量构建环境

规格配置

Pigsty 在 vagrant/spec/ 目录下提供了多种预定义的虚拟机规格:

模板节点数规格说明别名
meta.rb1 节点2c4g x 1单节点开发箱Devbox
dual.rb2 节点1c2g x 2双节点环境
trio.rb3 节点1c2g x 3三节点环境
full.rb4 节点2c4g + 1c2g x 34 节点完整沙箱Sandbox
deci.rb10 节点混合10 节点环境
simu.rb20 节点混合20 节点生产仿真环境Simubox
minio.rb4 节点1c2g x 4 + 磁盘MinIO 测试环境
oss.rb3 节点1c2g x 33 节点 OSS 构建环境
pro.rb5 节点1c2g x 55 节点 PRO 构建环境
rpm.rb3 节点1c2g x 33 节点 EL 构建环境
deb.rb4 节点1c2g x 44 节点 Deb 构建环境
all.rb7 节点1c2g x 77 节点全量构建环境

每个规格文件包含一个描述虚拟机节点的 Specs 变量。例如,full.rb 包含 4 节点沙箱的定义:

# full: pigsty full-featured 4-node sandbox for HA-testing & tutorial & practices

Specs = [
  { "name" => "meta"   , "ip" => "10.10.10.10" ,  "cpu" => "2" ,  "mem" => "4096" ,  "image" => "cloud-image/ubuntu-24.04" },
  { "name" => "node-1" , "ip" => "10.10.10.11" ,  "cpu" => "1" ,  "mem" => "2048" ,  "image" => "cloud-image/ubuntu-24.04" },
  { "name" => "node-2" , "ip" => "10.10.10.12" ,  "cpu" => "1" ,  "mem" => "2048" ,  "image" => "cloud-image/ubuntu-24.04" },
  { "name" => "node-3" , "ip" => "10.10.10.13" ,  "cpu" => "1" ,  "mem" => "2048" ,  "image" => "cloud-image/ubuntu-24.04" },
]

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-3pg-dst-1-3):2c4g

配置脚本

使用 vagrant/config 脚本可以根据规格和选项生成最终的 Vagrantfile

cd ~/pigsty
vagrant/config [spec] [image] [scale] [provider]

# 示例
vagrant/config meta u24            # 使用 1 节点规格,Ubuntu 24.04 镜像
vagrant/config dual el9            # 使用 2 节点规格,RockyLinux 9.7 镜像
vagrant/config trio d12 2          # 使用 3 节点规格,Debian 12.13 镜像,双倍资源
vagrant/config full u22 4          # 使用 4 节点规格,Ubuntu 22.04 镜像,4 倍资源
vagrant/config simu u26 1 libvirt  # 使用 20 节点规格,Ubuntu 26.04 镜像,libvirt 提供商

镜像别名

config 脚本支持多种镜像别名:

发行版别名Vagrant Box
Rocky 8el8, rocky8, r8cloud-image/rocky-8
Rocky 9el9, rocky9, el, r9cloud-image/rocky-9
Rocky 10el10, rocky10, r10cloud-image/rocky-10
Debian 12d12, debian12, deb12cloud-image/debian-12
Debian 13d13, debian13, deb13cloud-image/debian-13
Ubuntu 22.04u22, ubuntu22, ubuntu2204cloud-image/ubuntu-22.04
Ubuntu 24.04u24, ubuntu24, ubuntu2404, ubuntucloud-image/ubuntu-24.04
Ubuntu 26.04u26, ubuntu26, ubuntu2604cloud-image/ubuntu-26.04
AlmaLinux 8alma8cloud-image/almalinux-8
AlmaLinux 9alma9cloud-image/almalinux-9
AlmaLinux 10alma10cloud-image/almalinux-10

资源缩放

您可以使用环境变量 VM_SCALE 来调整资源倍数,默认值为 1

VM_SCALE=2 vagrant/config meta     # 将 meta 规格的 CPU/内存资源翻倍

例如,使用 VM_SCALE=4 配置 meta 规格,会将默认的 2c4g 调整为 8c16g:

Specs = [
  { "name" => "meta" , "ip" => "10.10.10.10", "cpu" => "8" , "mem" => "16384" , "image" => "cloud-image/ubuntu-24.04" },
]

虚拟机管理

Pigsty 提供了一系列 Makefile 快捷方式来管理虚拟机:

make           # 等于 make start
make new       # 销毁现有虚拟机,创建新的虚拟机
make ssh       # 将虚拟机 SSH 配置写入 ~/.ssh/(创建后必须执行)
make dns       # 将虚拟机 DNS 记录写入 /etc/hosts(可选)
make start     # 启动虚拟机并配置 SSH(up + ssh)
make up        # 使用 vagrant up 启动虚拟机
make halt      # 关闭虚拟机(别名:down, dw)
make clean     # 销毁虚拟机(别名:del, destroy)
make status    # 显示虚拟机状态(别名:st)
make pause     # 暂停虚拟机(别名:suspend)
make resume    # 恢复虚拟机
make nuke      # 使用 virsh 销毁所有虚拟机和卷(仅 libvirt)
make info      # 显示 libvirt 信息(虚拟机、网络、存储卷)

SSH 密钥

Pigsty Vagrant 模板默认使用您的 ~/.ssh/id_rsa[.pub] 作为虚拟机的 SSH 密钥。

在开始之前,请确保您有一个有效的 SSH 密钥对。如果没有,可以使用以下命令生成:

ssh-keygen -t rsa -b 2048 -N '' -f ~/.ssh/id_rsa -q

支持的镜像

Pigsty v4.3 统一使用 Vagrant Cloud 上的 cloud-image/* Box,VirtualBox 与 libvirt 均提供 amd64 / arm64 架构版本。

VirtualBox

系统Vagrant Boxamd64 版本arm64 版本
Rocky 8cloud-image/rocky-88.10.20240528.08.10.20240528.0
Rocky 9cloud-image/rocky-99.7.20251123.29.7.20251123.2
Rocky 10cloud-image/rocky-1010.1.20251116.010.1.20251116.0
Debian 11cloud-image/debian-1120260419.2453.020260419.2453.0
Debian 12cloud-image/debian-1220260413.2447.020260413.2447.0
Debian 13cloud-image/debian-1320260413.2447.020260413.2447.0
Ubuntu 22.04cloud-image/ubuntu-22.0420260320.0.020260320.0.0
Ubuntu 24.04cloud-image/ubuntu-24.0420260323.0.020260323.0.0
Ubuntu 26.04cloud-image/ubuntu-26.0420260421.0.020260421.0.0
AlmaLinux 8cloud-image/almalinux-88.10.202604148.10.20260414
AlmaLinux 9cloud-image/almalinux-99.7.202604149.7.20260414
AlmaLinux 10cloud-image/almalinux-1010.1.20260414.010.1.20260414.0

libvirt

系统Vagrant Boxamd64 版本arm64 版本
Rocky 8cloud-image/rocky-88.10.20240528.08.10.20240528.0
Rocky 9cloud-image/rocky-99.7.20251123.29.7.20251123.2
Rocky 10cloud-image/rocky-1010.1.20251116.010.1.20251116.0
Debian 11cloud-image/debian-1120260419.2453.020260419.2453.0
Debian 12cloud-image/debian-1220260413.2447.020260413.2447.0
Debian 13cloud-image/debian-1320260413.2447.020260413.2447.0
Ubuntu 22.04cloud-image/ubuntu-22.0420260320.0.020260320.0.0
Ubuntu 24.04cloud-image/ubuntu-24.0420260323.0.020260323.0.0
Ubuntu 26.04cloud-image/ubuntu-26.0420260421.0.020260421.0.0
AlmaLinux 8cloud-image/almalinux-88.10.202604148.10.20260414
AlmaLinux 9cloud-image/almalinux-99.7.202604149.7.20260414
AlmaLinux 10cloud-image/almalinux-1010.1.20260414.010.1.20260414.0

环境变量

您可以使用以下环境变量来控制 Vagrant 行为:

export VM_SPEC='meta'              # 规格名称
export VM_IMAGE='cloud-image/rocky-9' # 镜像名称
export VM_SCALE='1'                # 资源缩放倍数
export VM_PROVIDER='virtualbox'    # 虚拟化提供商
export VAGRANT_EXPERIMENTAL=disks  # 启用实验性磁盘功能

注意事项


最后修改 2026-05-01: v4.3 docs update (25d20b5)