Vagrant 核心操作速查（Windows + Hyper-V）¶

用途：供 AI 助手快速查阅并指导/执行 Vagrant 操作。环境：Windows 宿主机 + Hyper-V provider。更新日期：2026-11-11 版本基线：Vagrant 2.4.9（核对日期 2026-11-11，来源：官网）

1. 核心概念¶

概念	说明
Vagrantfile	声明式环境描述文件（Ruby 语法），一个目录一个环境
Box	预打包的基础镜像，分 provider（hyperv / virtualbox / vmware 不通用）
Provider	底层虚拟化后端；本机固定用 `hyperv`
Provisioner	首次 `up` 时自动执行的配置脚本（shell / ansible / file）
state（`.vagrant/` 目录）	记录当前环境机器 ID 与状态，删除即"失联"

2. 常用命令速查¶

vagrant init generic/ubuntu2204          # 生成 Vagrantfile（可 --force 覆盖）
vagrant up --provider=hyperv             # 启动（Hyper-V 必须管理员终端）
vagrant status                           # 查看环境状态
vagrant ssh <name>                       # SSH 进入虚拟机（Windows 需 OpenSSH 客户端）
vagrant halt                             # 正常关机
vagrant reload                           # 重启（改了 Vagrantfile 后常用）
vagrant destroy [name|-f]                # 删除虚拟机（-f 免确认）
vagrant provision                        # 重新执行 provisioning
vagrant snapshot save <快照名>           # 保存快照
vagrant snapshot restore <快照名>        # 恢复快照（Hyper-V 下 SMB 共享偶发报错，可忽略）
vagrant snapshot list / delete <名>      # 列出 / 删除快照
vagrant global-status                    # 列出本机所有 Vagrant 环境（含 ID）
vagrant global-status --prune            # 清理失效条目
vagrant box list                         # 已下载的 box
vagrant box add <名称> --provider hyperv # 添加 box（务必指定 hyperv）
vagrant box remove <名称>                # 删除 box
vagrant box update                       # 更新 box
vagrant suspend / resume                 # 挂起 / 恢复（省内存）
vagrant port                             # 查看端口转发（Hyper-V 下不适用）
vagrant plugin list / install <插件>     # 插件管理

3. Vagrantfile 模板（Hyper-V + 多机，K8s 实验用）¶

Vagrant.configure("2") do |config|
  config.vm.box = "generic/ubuntu2204"
  config.vm.boot_timeout = 600

  # Hyper-V 全局设置（资源配置遵循 Roadmap §2.6：宿主机 256GB/80 线程的 60% 上限内）
  config.vm.provider "hyperv" do |h|
    h.memory = 8192
    h.cpus = 4
    # 关键：提前在 Hyper-V 管理器/PowerShell 里建好虚拟交换机，
    # 否则 up 时会交互式询问（阻塞 AI 自动化）
    h.vm_integration_services = { guest_service_interface: true }
  end

  # 统一 provision：装 Docker（国内镜像加速）
  config.vm.provision "shell", inline: <<-SHELL
    apt-get update -y
    curl -fsSL https://get.docker.com | sh
    usermod -aG docker vagrant
  SHELL

  # 多机定义
  (1..3).each do |i|
    config.vm.define "node#{i}" do |node|
      node.vm.hostname = "node#{i}"
      # 注意：Hyper-V 下不支持 private_network 静态 IP，Vagrantfile 中的
      # 网络配置会被忽略。IP 由 DHCP 分配，首次 up 时会输出实际 IP，
      # 也可用 PowerShell Get-VM | Get-VMNetworkAdapter 查询。
    end
  end
end

4. Hyper-V 特有的注意事项（重要）¶

管理员权限：vagrant up/destroy 等改变 VM 生命周期的命令必须在提权终端运行；vagrant ssh/status 不需要。
网络：
Vagrantfile 的 vm.network 在 Hyper-V 下基本被忽略，不能设静态 IP、不能自动建交换机。

提前用 PowerShell 建好交换机：

New-VMSwitch -Name "VagrantInternal" -SwitchType Internal
# NAT（如需外网）：
New-NetIPAddress -IPAddress 192.168.100.1 -PrefixLength 24 -InterfaceAlias "vEthernet (VagrantInternal)"
New-NetNat -Name "VagrantNAT" -InternalIPInterfaceAddressPrefix 192.168.100.0/24

首次 up 若弹出选择交换机的交互提示，会阻塞自动化——解决：提前 vagrant up 手动选一次，或使用 h.ip_address_timeout / 第三方插件。
Box 必须选 hyperv 版：generic/*、bento/* 系列有 hyperv 版；在 HCP Vagrant Registry（原 Vagrant Cloud）搜 provider: hyperv。
Box 本地化：HCP Vagrant Registry 已确认下线时间表——2026-10-01 起不能再新建 box，2026-12-31 后全部停运（仅影响注册表托管，不影响 Vagrant CLI 本身）。重要 box 提前 vagrant box add 下载到本地，必要时 vagrant package 打包自托管。另：Vagrant 2.4.0+ 的 box 支持 amd64/arm64 多架构，CLI 自动按宿主机架构匹配；可用 config.vm.box_architecture 控制（设 :auto 或指定架构）。
同步目录：Hyper-V 下默认用 SMB 共享（需要宿主机账号密码），速度一般；建议项目文件用 vagrant scp 插件或 git 中转，减少对 synced_folder 的依赖。

嵌套虚拟化（VM 里再跑 K8s/虚拟化实验才需要）：

Set-VMProcessor -VMName <VM名> -ExposeVirtualizationExtensions $true

查询 VM 实际 IP：

Get-VM | Where-Object State -eq 'Running' | Get-VMNetworkAdapter | Format-Table VMName, IPAddresses

5. 典型工作流¶

5.1 快速搭单机 Docker 实验环境¶

mkdir ~/lab && cd ~/lab
vagrant init generic/ubuntu2204
# 编辑 Vagrantfile（见第 3 节模板，删掉多机循环）
vagrant up --provider=hyperv
vagrant ssh

5.2 实验做坏了 → 重置¶

vagrant destroy -f && vagrant up --provider=hyperv

5.3 保存干净状态做基线¶

vagrant snapshot save clean-base   # 之后随时 vagrant snapshot restore clean-base

5.4 导出自制 box¶

vagrant package --output my-ubuntu.box
# 分发：vagrant box add my-ubuntu my-ubuntu.box --provider hyperv

6. 常见故障排查¶

现象	原因 / 处理
up 卡在选择交换机	提前建交换机；或用非交互方式预选
权限错误 (Access denied)	终端未提权
ssh 超时	box 内未装 openssh server（generic 系列自带）；调大 boot_timeout
找不到 hyperv 版 box	换 generic/* 或 bento/*，或本地打包
destroy 后 global-status 仍显示	`vagrant global-status --prune`
快照恢复后共享目录报错	Hyper-V 已知问题，guest 内实际可用，可忽略

7. AI 助手操作守则¶

修改环境只改 Vagrantfile，不散落执行一次性命令；改完执行 vagrant reload / vagrant provision。
涉及 VM 增删的命令必须在管理员终端执行，先检查 vagrant status。
需要 VM 的 IP 时，用 PowerShell Get-VMNetworkAdapter 查询，不要假设静态 IP。
每完成一个稳定的实验阶段，主动 vagrant snapshot save。
破坏性操作（destroy、删除 box/快照）先向用户确认。