Vagrant 使用教程

目录

1. Vagrant 简介
2. 安装与配置
3. 核心命令
4. Vagrantfile 配置
5. 常用插件
6. 配套工具生态
7. 多机编排
8. 实战案例
9. 故障排查

---

一、Vagrant 简介

1.1 什么是 Vagrant

Vagrant 是一个用于构建和管理虚拟机开发环境的工具。通过简单的配置文件和命令，可以快速创建、配置和共享虚拟化环境。

flowchart TB A[Vagrant] --> B[虚拟机管理] A --> C[环境配置] A --> D[环境共享] B --> B1[VirtualBox] B --> B2[VMware] B --> B3[Hyper-V] B --> B4[Docker] B --> B5[云服务商] C --> C1[Vagrantfile] C --> C2[Provision] C --> C3[Box镜像] D --> D1[Vagrant Cloud] D --> D2[版本控制] D --> D3[团队协作]

1.2 核心概念

概念	说明	类比
Box	虚拟机基础镜像	Docker Image
Vagrantfile	环境配置文件	Dockerfile
Provider	虚拟化平台	Docker Engine
Provision	初始化配置脚本	Docker ENTRYPOINT
Guest	虚拟机（客户机）	Container
Host	宿主机	Host OS

1.3 Vagrant vs Docker

flowchart LR subgraph Vagrant V1[完整虚拟机] V2[独立内核] V3[适合复杂环境] V4[资源占用高] end subgraph Docker D1[容器化] D2[共享内核] D3[适合微服务] D4[轻量快速] end

特性	Vagrant	Docker
虚拟化级别	硬件级（VM）	操作系统级（容器）
启动速度	分钟级	秒级
资源隔离	完全隔离	进程级隔离
适用场景	开发环境、多OS测试	应用部署、微服务
GUI支持	✅ 完整支持	❌ 需额外配置
学习曲线	低	中等

---

二、安装与配置

2.1 安装流程

flowchart TD A[安装 Vagrant] --> B[安装虚拟化平台] B --> C[添加 Box] C --> D[初始化项目] D --> E[启动环境] B --> B1[VirtualBox - 免费] B --> B2[VMware - 付费] B --> B3[Hyper-V - Win10Pro+] C --> C1[官方 Boxes] C --> C2[自定义 Boxes] D --> D1[vagrant init] D --> D2[编辑 Vagrantfile]

2.2 下载安装

# macOS (使用 Homebrew)
brew install --cask vagrant
brew install --cask virtualbox

# Windows (使用 Chocolatey)
choco install vagrant
choco install virtualbox

# Linux (Ubuntu/Debian)
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install vagrant

2.3 验证安装

# 检查版本
vagrant --version

# 查看支持的命令
vagrant list-commands

# 查看当前状态
vagrant global-status

---

三、核心命令

3.1 命令速查表

mindmap root((Vagrant命令)) 生命周期 init[初始化] up[启动] halt[停止] reload[重启] destroy[销毁] suspend[挂起] resume[恢复] 状态管理 status[查看状态] global-status[全局状态] snapshot[快照管理] 连接访问 ssh[SSH连接] ssh-config[SSH配置] rdp[RDP连接] 配置管理 provision[重新配置] reload --provision[重启并配置] plugin[插件管理] Box管理 box add[添加Box] box list[列出Box] box remove[删除Box] box update[更新Box] box outdated[检查更新]

3.2 生命周期命令

命令	功能	常用选项
vagrant init	初始化项目，创建 Vagrantfile	[box-name]
vagrant up	启动/创建虚拟机	--provision, --no-provision
vagrant halt	关闭虚拟机	--force
vagrant reload	重启虚拟机	--provision
vagrant destroy	销毁虚拟机	--force, -f
vagrant suspend	挂起虚拟机	-
vagrant resume	恢复挂起的虚拟机	-

# 常用工作流
vagrant init ubuntu/jammy64    # 初始化 Ubuntu 22.04 项目
vagrant up                     # 启动虚拟机
vagrant ssh                    # SSH 登录
vagrant halt                   # 关机
vagrant destroy -f             # 强制销毁

3.3 连接命令

命令	功能	说明
vagrant ssh	SSH 连接到虚拟机	默认用户：vagrant
vagrant ssh [name]	连接到指定名称的多机环境	多机环境使用
vagrant ssh-config	输出 SSH 配置	可用于外部 SSH 客户端
vagrant rdp	RDP 连接（Windows Guest）	需要图形界面
vagrant powershell	PowerShell 远程连接	Windows Guest

# SSH 配置导出
vagrant ssh-config >> ~/.ssh/config

# 之后可以直接使用
ssh vagrant-vm-name

3.4 Box 管理命令

命令	功能	示例
vagrant box add	添加 Box	vagrant box add ubuntu/jammy64
vagrant box list	列出本地 Boxes	-
vagrant box remove	删除 Box	vagrant box remove ubuntu/jammy64
vagrant box update	更新 Box	-
vagrant box outdated	检查更新	-
vagrant box repackage	重新打包 Box	-

# 从本地文件添加 Box
vagrant box add my-box ./my-box.box

# 指定版本添加
vagrant box add ubuntu/jammy64 --box-version 20230101.0.0

# 从 URL 添加
vagrant box add my-box https://example.com/my-box.box

3.5 快照管理

# 创建快照
vagrant snapshot save [vm-name] snapshot-name

# 恢复快照
vagrant snapshot restore [vm-name] snapshot-name

# 列出快照
vagrant snapshot list [vm-name]

# 删除快照
vagrant snapshot delete [vm-name] snapshot-name

# 快速保存/恢复（push/pop）
vagrant snapshot push    # 快速保存
vagrant snapshot pop     # 快速恢复并删除

---

四、Vagrantfile 配置

4.1 基本结构

flowchart TB A[Vagrantfile] --> B[配置块] A --> C[虚拟机配置] A --> D[网络配置] A --> E[同步文件夹] A --> F[Provision] B --> B1[Vagrant.configure] C --> C1[vm.box] C --> C2[vm.hostname] C --> C3[vm.provider] C --> C4[vm.resources] D --> D1[端口转发] D --> D2[私有网络] D --> D3[公有网络] E --> E1[默认同步] E --> E2[自定义同步] F --> F1[Shell] F --> F2[Ansible] F --> F3[Chef] F --> F4[Puppet]

4.2 基础配置示例

# -*- mode: ruby -*-
# vi: set ft=ruby :

Vagrant.configure("2") do |config|
  # 基础镜像
  config.vm.box = "ubuntu/jammy64"
  config.vm.box_version = "20230101.0.0"
  config.vm.box_check_update = true
  
  # 主机名
  config.vm.hostname = "dev-server"
  
  # 虚拟机名称（VirtualBox中显示）
  config.vm.provider "virtualbox" do |vb|
    vb.name = "my-dev-vm"
  end
end

4.3 网络配置

Vagrant.configure("2") do |config|
  # 1. 端口转发（Port Forwarding）
  # 将宿主机的 8080 端口映射到虚拟机的 80 端口
  config.vm.network "forwarded_port", guest: 80, host: 8080
  
  # 自动纠正端口冲突
  config.vm.network "forwarded_port", guest: 80, host: 8080, auto_correct: true
  
  # 仅绑定到 localhost
  config.vm.network "forwarded_port", guest: 3306, host: 3306, host_ip: "127.0.0.1"
  
  # 2. 私有网络（Private Network）- Host-Only
  # 静态 IP
  config.vm.network "private_network", ip: "192.168.56.10"
  
  # DHCP 自动分配
  config.vm.network "private_network", type: "dhcp"
  
  # 3. 公有网络（Public Network）- Bridge
  # 桥接到默认网卡
  config.vm.network "public_network"
  
  # 桥接到指定网卡
  config.vm.network "public_network", bridge: "en0: Wi-Fi (AirPort)"
  
  # 桥接并指定 IP
  config.vm.network "public_network", ip: "192.168.1.100"
end

4.4 同步文件夹

Vagrant.configure("2") do |config|
  # 默认同步（项目目录挂载到 /vagrant）
  # 禁用默认同步
  config.vm.synced_folder ".", "/vagrant", disabled: true
  
  # 基本同步
  config.vm.synced_folder "./data", "/var/www/data"
  
  # NFS 同步（Linux/Mac 性能更好）
  config.vm.synced_folder "./data", "/var/www/data", type: "nfs"
  
  # SMB 同步（Windows 推荐）
  config.vm.synced_folder "./data", "/var/www/data", type: "smb"
  
  # rsync 同步（单向，适合静态文件）
  config.vm.synced_folder "./src", "/var/www/src", type: "rsync",
    rsync__exclude: [".git/", "node_modules/"],
    rsync__args: ["--verbose", "--archive", "--delete", "-z"]
  
  # VirtualBox 共享文件夹（默认）
  config.vm.synced_folder "./data", "/var/www/data",
    owner: "www-data",
    group: "www-data",
    mount_options: ["dmode=775,fmode=664"]
end

4.5 Provider 配置

Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"
  
  # VirtualBox 配置
  config.vm.provider "virtualbox" do |vb|
    # 虚拟机名称
    vb.name = "dev-vm"
    
    # 内存（MB）
    vb.memory = "4096"
    
    # CPU 核心数
    vb.cpus = 2
    
    # 显存（MB）
    vb.customize ["modifyvm", :id, "--vram", "128"]
    
    # 启用 GUI
    vb.gui = true
    
    # 其他优化
    vb.customize ["modifyvm", :id, "--natdnshostresolver1", "on"]
    vb.customize ["modifyvm", :id, "--natdnsproxy1", "on"]
    vb.customize ["modifyvm", :id, "--ioapic", "on"]
  end
  
  # VMware 配置
  config.vm.provider "vmware_desktop" do |v|
    v.vmx["memsize"] = "4096"
    v.vmx["numvcpus"] = "2"
    v.vmx["displayName"] = "dev-vm"
  end
  
  # Hyper-V 配置
  config.vm.provider "hyperv" do |h|
    h.enable_virtualization_extensions = true
    h.linked_clone = true
    h.memory = 4096
    h.cpus = 2
  end
  
  # Docker 配置（轻量级）
  config.vm.provider "docker" do |d|
    d.image = "ubuntu:22.04"
    d.has_ssh = true
  end
end

4.6 Provision 配置

Vagrant.configure("2") do |config|
  # 1. Inline Shell
  config.vm.provision "shell", inline: <<-SHELL
    apt-get update
    apt-get install -y apache2
    systemctl enable apache2
    systemctl start apache2
  SHELL
  
  # 2. 外部脚本
  config.vm.provision "shell", path: "bootstrap.sh"
  
  # 3. 带参数的脚本
  config.vm.provision "shell" do |s|
    s.path = "bootstrap.sh"
    s.args = ["arg1", "arg2"]
    s.env = { "MY_VAR" => "value" }
  end
  
  # 4. Ansible
  config.vm.provision "ansible" do |ansible|
    ansible.playbook = "playbook.yml"
    ansible.inventory_path = "inventory"
    ansible.verbose = "v"
  end
  
  # 5. Ansible Local（在 Guest 上运行）
  config.vm.provision "ansible_local" do |ansible|
    ansible.playbook = "playbook.yml"
    ansible.install = true
    ansible.version = "latest"
  end
  
  # 6. Chef Solo
  config.vm.provision "chef_solo" do |chef|
    chef.cookbooks_path = "cookbooks"
    chef.add_recipe "apache"
  end
  
  # 7. Puppet
  config.vm.provision "puppet" do |puppet|
    puppet.manifests_path = "manifests"
    puppet.manifest_file = "default.pp"
  end
  
  # 8. Docker
  config.vm.provision "docker" do |d|
    d.run "nginx", args: "-p 80:80"
  end
  
  # 9. File 上传
  config.vm.provision "file", source: "./config", destination: "/tmp/config"
  
  # 10. 多阶段配置
  config.vm.provision "bootstrap", type: "shell", path: "bootstrap.sh"
  config.vm.provision "app", type: "shell", path: "app.sh", run: "never"
  # 手动运行：vagrant provision --provision-with app
end

---

五、常用插件

5.1 插件管理命令

# 安装插件
vagrant plugin install vagrant-plugin-name

# 卸载插件
vagrant plugin uninstall vagrant-plugin-name

# 更新插件
vagrant plugin update
vagrant plugin update vagrant-plugin-name

# 列出已安装插件
vagrant plugin list

# 插件修复
vagrant plugin repair

# 重新安装插件
vagrant plugin expunge --reinstall

5.2 推荐插件列表

flowchart TB A[Vagrant插件] --> B[效率工具] A --> C[云服务商] A --> D[功能增强] A --> E[开发工具] B --> B1[vagrant-vbguest] B --> B2[vagrant-cachier] B --> B3[vagrant-proxyconf] C --> C1[vagrant-aws] C --> C2[vagrant-azure] C --> C3[vagrant-google] C --> C4[vagrant-digitalocean] D --> D1[vagrant-hostmanager] D --> D2[vagrant-hostsupdater] D --> D3[vagrant-triggers] D --> D4[vagrant-reload] E --> E1[vagrant-scp] E --> E2[vagrant-rsync-back] E --> E3[vagrant-omnibus] E --> E4[vagrant-berkshelf]

效率工具类

插件	功能	安装命令
vagrant-vbguest	自动更新 VirtualBox Guest Additions	vagrant plugin install vagrant-vbguest
vagrant-cachier	包管理器缓存（apt/yum等），加速重建	vagrant plugin install vagrant-cachier
vagrant-proxyconf	自动配置代理	vagrant plugin install vagrant-proxyconf

# vagrant-cachier 配置示例
Vagrant.configure("2") do |config|
  if Vagrant.has_plugin?("vagrant-cachier")
    config.cache.scope = :box
    config.cache.auto_detect = true
    config.cache.enable :apt
    config.cache.enable :yum
    config.cache.enable :gem
    config.cache.enable :npm
  end
  
  # vagrant-vbguest 配置
  if Vagrant.has_plugin?("vagrant-vbguest")
    config.vbguest.auto_update = true
    config.vbguest.no_remote = false
  end
  
  # vagrant-proxyconf 配置
  if Vagrant.has_plugin?("vagrant-proxyconf")
    config.proxy.http = "http://proxy.company.com:8080"
    config.proxy.https = "http://proxy.company.com:8080"
    config.proxy.no_proxy = "localhost,127.0.0.1,.company.com"
  end
end

网络/主机管理类

插件	功能	安装命令
vagrant-hostmanager	管理 /etc/hosts 文件，实现主机名解析	vagrant plugin install vagrant-hostmanager
vagrant-hostsupdater	自动更新 hosts 文件	vagrant plugin install vagrant-hostsupdater

# vagrant-hostmanager 配置
Vagrant.configure("2") do |config|
  config.hostmanager.enabled = true
  config.hostmanager.manage_host = true
  config.hostmanager.manage_guest = true
  config.hostmanager.ignore_private_ip = false
  config.hostmanager.include_offline = true
  
  config.vm.define "web" do |web|
    web.vm.hostname = "web.example.com"
    web.vm.network "private_network", ip: "192.168.56.10"
  end
  
  config.vm.define "db" do |db|
    db.vm.hostname = "db.example.com"
    db.vm.network "private_network", ip: "192.168.56.11"
  end
end

云服务商类

插件	云服务商	安装命令
vagrant-aws	Amazon AWS	vagrant plugin install vagrant-aws
vagrant-azure	Microsoft Azure	vagrant plugin install vagrant-azure
vagrant-google	Google Cloud	vagrant plugin install vagrant-google
vagrant-digitalocean	DigitalOcean	vagrant plugin install vagrant-digitalocean

# AWS 配置示例
Vagrant.configure("2") do |config|
  config.vm.box = "dummy"
  config.vm.provider :aws do |aws, override|
    aws.access_key_id = ENV['AWS_ACCESS_KEY_ID']
    aws.secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
    aws.session_token = ENV['AWS_SESSION_TOKEN']
    aws.keypair_name = "my-keypair"
    
    aws.ami = "ami-0c55b159cbfafe1f0"
    aws.region = "us-east-1"
    aws.instance_type = "t2.micro"
    aws.security_groups = ["sg-12345678"]
    aws.subnet_id = "subnet-12345678"
    aws.associate_public_ip = true
    
    override.ssh.username = "ubuntu"
    override.ssh.private_key_path = "~/.ssh/my-keypair.pem"
  end
end

开发工具类

插件	功能	安装命令
vagrant-scp	SCP 文件传输	vagrant plugin install vagrant-scp
vagrant-triggers	自定义触发器（v2.1.0+已内置）	内置
vagrant-reload	重启 provision	vagrant plugin install vagrant-reload
vagrant-omnibus	安装 Chef	vagrant plugin install vagrant-omnibus
vagrant-berkshelf	Chef 依赖管理	vagrant plugin install vagrant-berkshelf

# vagrant-scp 使用示例
vagrant scp file.txt :/home/vagrant/           # 上传到虚拟机
vagrant scp :/home/vagrant/file.txt ./         # 下载到宿主机
vagrant scp file.txt web:/home/vagrant/        # 多机环境指定机器

---

六、配套工具生态

6.1 完整开发环境栈

flowchart TB subgraph 基础设施层 V[Vagrant] VB[VirtualBox/VMware] end subgraph 配置管理层 A[Ansible] C[Chef] P[Puppet] S[Shell Script] end subgraph 应用层 D[Docker] K[K8s] DB[(Database)] WS[Web Server] end subgraph 工具链 GIT[Git] TF[Terraform] PK[Packer] VL[Vagrant Landrush] end V --> VB V --> A V --> C V --> P V --> S A --> D C --> DB S --> WS V -.-> GIT V -.-> TF V -.-> PK

6.2 Packer - 镜像构建

Packer 是 HashiCorp 出品的工具，用于自动化构建虚拟机镜像。

// packer.json - 构建 Vagrant Box
{
  "builders": [{
    "type": "virtualbox-iso",
    "guest_os_type": "Ubuntu_64",
    "iso_url": "https://releases.ubuntu.com/22.04/ubuntu-22.04-live-server-amd64.iso",
    "iso_checksum": "sha256:...",
    "ssh_username": "vagrant",
    "ssh_password": "vagrant",
    "shutdown_command": "echo 'vagrant' | sudo -S shutdown -P now",
    "disk_size": 20480
  }],
  "provisioners": [{
    "type": "shell",
    "script": "setup.sh"
  }],
  "post-processors": [{
    "type": "vagrant",
    "output": "ubuntu-22.04.box"
  }]
}

# 构建 Box
packer build packer.json

# 添加到 Vagrant
vagrant box add my-ubuntu ./ubuntu-22.04.box

6.3 Terraform + Vagrant 工作流

flowchart LR A[开发环境] -->|Vagrant| B[本地验证] B --> C[镜像打包] C -->|Packer| D[生产镜像] D --> E[生产环境] E -->|Terraform| F[AWS/Azure/GCP]

6.4 推荐配套工具

工具	用途	与 Vagrant 关系
Packer	构建标准化镜像	制作自定义 Box
Terraform	基础设施即代码	生产环境部署
Ansible	配置管理	Vagrant provisioner
Docker	容器化	Vagrant provider
Git	版本控制	管理 Vagrantfile
Makefile	任务自动化	简化 Vagrant 命令

6.5 Makefile 集成示例

# Makefile
.PHONY: up down ssh provision clean status

# 启动环境
up:
	vagrant up

# 关闭环境
down:
	vagrant halt

# 重启
restart:
	vagrant reload

# SSH 登录
ssh:
	vagrant ssh

# 重新配置
provision:
	vagrant provision

# 完全重建
rebuild:
	vagrant destroy -f && vagrant up

# 查看状态
status:
	vagrant status

# 清理
clean:
	vagrant destroy -f
	vagrant box prune

# 导出 Box
export:
	vagrant package --output my-box.box

# 多机环境指定机器
web:
	vagrant up web

db:
	vagrant up db

---

七、多机编排

7.1 多机环境配置

flowchart TB subgraph 多机环境 LB[Load Balancer<br/>192.168.56.10] W1[Web Server 1<br/>192.168.56.11] W2[Web Server 2<br/>192.168.56.12] DB[(Database<br/>192.168.56.20)] end User --> LB LB --> W1 LB --> W2 W1 --> DB W2 --> DB

Vagrant.configure("2") do |config|
  # Load Balancer
  config.vm.define "lb" do |lb|
    lb.vm.box = "ubuntu/jammy64"
    lb.vm.hostname = "lb"
    lb.vm.network "private_network", ip: "192.168.56.10"
    lb.vm.provider "virtualbox" do |vb|
      vb.memory = "512"
    end
    lb.vm.provision "shell", inline: <<-SHELL
      apt-get update
      apt-get install -y nginx
      # 配置负载均衡
      cat > /etc/nginx/conf.d/lb.conf <<EOF
upstream backend {
    server 192.168.56.11;
    server 192.168.56.12;
}
server {
    listen 80;
    location / {
        proxy_pass http://backend;
    }
}
EOF
      systemctl restart nginx
    SHELL
  end

  # Web Servers
  (1..2).each do |i|
    config.vm.define "web#{i}" do |web|
      web.vm.box = "ubuntu/jammy64"
      web.vm.hostname = "web#{i}"
      web.vm.network "private_network", ip: "192.168.56.1#{i}"
      web.vm.provider "virtualbox" do |vb|
        vb.memory = "1024"
      end
      web.vm.provision "shell", inline: <<-SHELL
        apt-get update
        apt-get install -y apache2
        echo "<h1>Web Server #{i}</h1>" > /var/www/html/index.html
        systemctl restart apache2
      SHELL
    end
  end

  # Database
  config.vm.define "db" do |db|
    db.vm.box = "ubuntu/jammy64"
    db.vm.hostname = "db"
    db.vm.network "private_network", ip: "192.168.56.20"
    db.vm.provider "virtualbox" do |vb|
      vb.memory = "2048"
    end
    db.vm.provision "shell", inline: <<-SHELL
      apt-get update
      apt-get install -y mysql-server
      mysql -e "CREATE DATABASE app_db;"
      mysql -e "CREATE USER 'app'@'%' IDENTIFIED BY 'password';"
      mysql -e "GRANT ALL ON app_db.* TO 'app'@'%';"
      sed -i 's/bind-address.*/bind-address = 0.0.0.0/' /etc/mysql/mysql.conf.d/mysqld.cnf
      systemctl restart mysql
    SHELL
  end
end

7.2 条件配置

Vagrant.configure("2") do |config|
  # 根据环境变量决定配置
  vm_memory = ENV['VM_MEMORY'] || "2048"
  vm_cpus = ENV['VM_CPUS'] || "2"
  
  config.vm.box = "ubuntu/jammy64"
  
  config.vm.provider "virtualbox" do |vb|
    vb.memory = vm_memory
    vb.cpus = vm_cpus
  end
  
  # 仅在特定机器上执行
  config.vm.define "web" do |web|
    web.vm.provision "shell", inline: "echo 'Web Server'"
  end
  
  config.vm.define "db", primary: true do |db|
    db.vm.provision "shell", inline: "echo 'Database Server'"
  end
  
  # 使用 autostart 控制默认启动
  config.vm.define "cache", autostart: false do |cache|
    cache.vm.box = "redis"
  end
end

---

八、实战案例

8.1 LAMP/LEMP 开发环境

# Vagrantfile - LEMP Stack
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"
  config.vm.hostname = "lemp-dev"
  
  # 网络
  config.vm.network "private_network", ip: "192.168.56.100"
  config.vm.network "forwarded_port", guest: 80, host: 8080
  config.vm.network "forwarded_port", guest: 443, host: 8443
  config.vm.network "forwarded_port", guest: 3306, host: 3306
  
  # 同步文件夹
  config.vm.synced_folder "./www", "/var/www/html", 
    owner: "www-data", 
    group: "www-data",
    mount_options: ["dmode=775,fmode=664"]
  
  # 资源
  config.vm.provider "virtualbox" do |vb|
    vb.name = "lemp-dev"
    vb.memory = "2048"
    vb.cpus = 2
  end
  
  # 启用缓存插件
  if Vagrant.has_plugin?("vagrant-cachier")
    config.cache.scope = :box
  end
  
  # Provision
  config.vm.provision "shell", inline: <<-SHELL
    # 更新系统
    export DEBIAN_FRONTEND=noninteractive
    apt-get update
    apt-get upgrade -y
    
    # 安装 Nginx
    apt-get install -y nginx
    systemctl enable nginx
    
    # 安装 MySQL
    apt-get install -y mysql-server
    systemctl enable mysql
    mysql -e "ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'root';"
    mysql -e "CREATE DATABASE IF NOT EXISTS dev_db;"
    
    # 安装 PHP
    apt-get install -y php8.1-fpm php8.1-mysql php8.1-curl php8.1-gd php8.1-mbstring php8.1-xml
    systemctl enable php8.1-fpm
    
    # 配置 Nginx
    cat > /etc/nginx/sites-available/default <<'EOF'
server {
    listen 80 default_server;
    root /var/www/html;
    index index.php index.html;
    
    location / {
        try_files $uri $uri/ =404;
    }
    
    location ~ \\.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
    }
}
EOF
    
    # 重启服务
    systemctl restart nginx
    systemctl restart php8.1-fpm
    
    # 安装 Composer
    curl -sS https://getcomposer.org/installer | php
    mv composer.phar /usr/local/bin/composer
    
    # 安装 Node.js
    curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
    apt-get install -y nodejs
    
    echo "LEMP Stack installed successfully!"
    echo "MySQL root password: root"
  SHELL
end

8.2 Docker 开发环境

# Vagrantfile - Docker Host
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"
  config.vm.hostname = "docker-host"
  
  config.vm.network "private_network", ip: "192.168.56.200"
  
  config.vm.provider "virtualbox" do |vb|
    vb.memory = "4096"
    vb.cpus = 2
  end
  
  # 使用 Docker provisioner
  config.vm.provision "docker" do |d|
    d.pull_images "nginx:latest"
    d.pull_images "mysql:8.0"
    d.pull_images "redis:latest"
    
    d.run "nginx",
      image: "nginx:latest",
      args: "-p 80:80 -v /vagrant/nginx:/etc/nginx/conf.d"
    
    d.run "mysql",
      image: "mysql:8.0",
      args: "-p 3306:3306 -e MYSQL_ROOT_PASSWORD=secret -v mysql_data:/var/lib/mysql"
    
    d.run "redis",
      image: "redis:latest",
      args: "-p 6379:6379"
  end
  
  # 安装 Docker Compose
  config.vm.provision "shell", inline: <<-SHELL
    curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
    chmod +x /usr/local/bin/docker-compose
  SHELL
end

8.3 Kubernetes 学习环境

# Vagrantfile - K3s Cluster
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"
  
  # Master Node
  config.vm.define "master" do |master|
    master.vm.hostname = "k3s-master"
    master.vm.network "private_network", ip: "192.168.56.10"
    master.vm.provider "virtualbox" do |vb|
      vb.memory = "2048"
      vb.cpus = 2
    end
    
    master.vm.provision "shell", inline: <<-SHELL
      curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--node-ip 192.168.56.10" sh -
      mkdir -p /vagrant/kubeconfig
      cp /etc/rancher/k3s/k3s.yaml /vagrant/kubeconfig/config
      sed -i 's/127.0.0.1/192.168.56.10/' /vagrant/kubeconfig/config
      chmod 644 /vagrant/kubeconfig/config
    SHELL
  end
  
  # Worker Nodes
  (1..2).each do |i|
    config.vm.define "worker#{i}" do |worker|
      worker.vm.hostname = "k3s-worker#{i}"
      worker.vm.network "private_network", ip: "192.168.56.1#{i}"
      worker.vm.provider "virtualbox" do |vb|
        vb.memory = "1536"
        vb.cpus = 1
      end
      
      worker.vm.provision "shell", inline: <<-SHELL
        export K3S_URL=https://192.168.56.10:6443
        export K3S_TOKEN=$(cat /vagrant/kubeconfig/node-token 2>/dev/null || echo "")
        curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--node-ip 192.168.56.1#{i}" sh -
      SHELL
    end
  end
end

---

九、故障排查

9.1 常见问题速查

flowchart TD A[Vagrant问题] --> B[启动失败] A --> C[连接失败] A --> D[性能问题] A --> E[同步问题] B --> B1[VT-x未启用] B --> B2[Box下载失败] B --> B3[端口冲突] C --> C1[SSH密钥问题] C --> C2[网络配置错误] C --> C3[防火墙阻止] D --> D1[内存不足] D --> D2[CPU限制] D --> D3[磁盘IO慢] E --> E1[权限问题] E --> E2[路径问题] E --> E3[VirtualBox增强功能]

9.2 排查命令

# 查看详细日志
vagrant up --debug

# 检查虚拟机状态
vagrant status
vagrant global-status

# SSH 调试
vagrant ssh-config
vagrant ssh -- -vvv

# 查看 VirtualBox 日志
cat .vagrant/machines/default/virtualbox/logs/VBox.log

# 重新生成 SSH 密钥
vagrant destroy -f
rm -rf .vagrant
vagrant up

9.3 常见问题解决

问题	原因	解决
VT-x is disabled	BIOS 未启用虚拟化	进入 BIOS 启用 Intel VT-x 或 AMD-V
Connection timeout	SSH 连接失败	检查网络配置，尝试 vagrant reload
Mounting failed	共享文件夹挂载失败	安装/更新 VirtualBox Guest Additions
Port collision	端口被占用	修改 Vagrantfile 端口或使用 auto_correct
Box download slow	网络问题	使用国内镜像或代理

9.4 调试模式

Vagrant.configure("2") do |config|
  # 启用详细日志
  ENV['VAGRANT_LOG'] = 'debug'
  
  # 保持 GUI 窗口（排查启动问题）
  config.vm.provider "virtualbox" do |vb|
    vb.gui = true
  end
  
  # 禁用并行（多机调试）
  config.vm.provision "shell", inline: "echo 'debug'", 
    run: "always"
end

---

附录：常用 Box 镜像

Box 名称	系统	说明
ubuntu/jammy64	Ubuntu 22.04 LTS	官方推荐
ubuntu/focal64	Ubuntu 20.04 LTS	长期支持
debian/bullseye64	Debian 11	稳定版
centos/7	CentOS 7	企业级
centos/stream8	CentOS Stream 8	滚动更新
generic/alpine317	Alpine Linux 3.17	轻量级
generic/fedora37	Fedora 37	新特性
generic/arch	Arch Linux	滚动更新
generic/freebsd13	FreeBSD 13	BSD 系统
gusztavvargadr/windows-10	Windows 10	需授权
gusztavvargadr/windows-server	Windows Server	需授权

搜索 Boxes

# 官方仓库
https://app.vagrantup.com/boxes/search

# 命令行搜索
vagrant box search ubuntu

---

最后更新：2026年4月