fnvtk/soul-yongping
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
991e17698c48be92c4cf6cb5fca73ee283efffa7
soul-yongping/.cursor/skills/lobster-macos-vm/SKILL.md

6.5 KiB
Raw Blame History

name, description
name description
lobster-macos-vm Automates provisioning and troubleshooting of macOS virtual machines on Windows using WSL2, QEMU/KVM, and the OneClick-macOS-Simple-KVM project. Use when the user mentions 龙虾, macOS 虚拟机, 一键安装苹果系统 on Windows, or needs to re-deploy the Ventura/Sonoma VM.

龙虾（lobster-macos-vm）

专门负责：在 Windows 10/11 上，通过 WSL2 + Ubuntu + QEMU/KVM + OneClick-macOS-Simple-KVM 自动拉起一台 macOS 虚拟机（Ventura 为默认），并处理常见网络 / WSL / KVM 问题。

触发场景

  • 用户提到：“龙虾”、“苹果系统虚拟机”、“Windows 上跑 macOS”、“一键安装 macOS 虚拟机”
  • 用户需要：在 Windows 上演示 / 测试 macOS，而不是 Docker 容器
  • 用户遇到：WSL 安装失败、0x80072ee2 网络错误、kvm-ok、nested 配置问题、git clone TLS 超时、OneClick 项目下载问题

核心能力

  1. 环境检测与前置说明

    • 明确告诉用户：macOS 不能在 Docker 里运行，必须用 WSL2 + 虚拟机。
    • 检查：
      • wsl -l -v → 是否有 Ubuntu-24.04，是否为 Version 2
      • docker --version 仅作背景信息，不作为必需条件
    • 若缺失 WSL2：
      • 指导用户在管理员 PowerShell中执行：
        • wsl --install
        • 重启后执行 wsl --install -d Ubuntu-24.04 --web-download（必要时）

  2. 固定部署目录约定

    • 所有与 macOS VM 相关的文件，统一放到：
      • Windows 路径：C:\Users\{USERNAME}\Mycontent\macos-vm
      • WSL 路径：/mnt/c/Users/{USERNAME}/Mycontent/macos-vm
    • 该目录下结构：
      • OneClick-macOS-Simple-KVM/（从 GitHub 下载的项目）
      • BaseSystem.dmg / BaseSystem.img
      • macOS.qcow2
      • 可能还有 OneClick.zip 等临时文件

  3. 获取 OneClick 源码（优先 zip，退而求其次 git）

优先使用 codeload.zip，避免长时间 git clone TLS 超时：

  • 在 macos-vm/ 目录内执行：
sudo apt-get update -qq
sudo apt-get install -y curl unzip
rm -rf OneClick-macOS-Simple-KVM OneClick.zip
curl -L --retry 8 --retry-delay 2 --connect-timeout 20 --max-time 600 \
  -o OneClick.zip \
  https://codeload.github.com/notAperson535/OneClick-macOS-Simple-KVM/zip/refs/heads/master
unzip -q OneClick.zip
mv OneClick-macOS-Simple-KVM-master OneClick-macOS-Simple-KVM

仅当用户网络环境允许且确有需要时，才尝试：

git clone --depth 1 https://github.com/notAperson535/OneClick-macOS-Simple-KVM.git

出现 GnuTLS recv error (-110) 或 TLS 断开时，不要重复 git clone，改走 zip 方案。

  1. 依赖安装与 KVM 检查

在 Ubuntu-24.04 内执行：

sudo apt-get update -qq
sudo apt-get install -y qemu-system qemu-utils python3 python3-pip cpu-checker
kvm-ok

预期输出：

  • INFO: /dev/kvm exists
  • KVM acceleration can be used

若 nested 为 N 但 kvm-ok 正常：

  • 提示用户在 C:\Users\{USERNAME}\.wslconfig 中写入：
[wsl2]
nestedVirtualization=true
kernel=C:\\Users\\{USERNAME}\\bzImage
debugConsole=true
pageReporting=true
kernelCommandLine=intel_iommu=on iommu=pt kvm.ignore_msrs=1 kvm-intel.nested=1 kvm-intel.ept=1 kvm-intel.emulate_invalid_guest_state=0 kvm-intel.enable_shadow_vmcs=1 kvm-intel.enable_apicv=1

并执行 wsl --shutdown 之后重试。

  1. 下载 macOS Ventura 恢复镜像并生成 BaseSystem.img

在 OneClick-macOS-Simple-KVM 目录内：

cd /mnt/c/Users/{USERNAME}/Mycontent/macos-vm/OneClick-macOS-Simple-KVM
chmod +x *.sh *.py
[ -f macOS.qcow2 ] || qemu-img create -f qcow2 macOS.qcow2 64G
python3 fetch-macOS-v2.py -s ventura
[ -f RecoveryImage.dmg ] && mv RecoveryImage.dmg BaseSystem.dmg
qemu-img convert BaseSystem.dmg -O raw BaseSystem.img
ls -lah BaseSystem.* macOS.qcow2

成功标志：

  • BaseSystem.dmg ≈ 678 MB
  • BaseSystem.img ≈ 3.0 GB
  • macOS.qcow2 已存在（几十 KB 起步）
  1. 启动虚拟机（headless + VNC: localhost:5900）

在 OneClick-macOS-Simple-KVM 目录内执行：

sudo HEADLESS=1 ./basic.sh

常见日志：

  • ALSA / audio 报错（没有声卡驱动）→ 可以忽略
  • BdsDxe: loading Boot0001 "UEFI QEMU HARDDISK QM00017"... → 已经开始从虚拟硬盘启动

在 Windows 侧确认端口：

Get-NetTCPConnection -LocalPort 5900 -State Listen

若监听正常，提示用户：

  • 安装 VNC 客户端并连接 localhost:5900，进入 macOS 安装向导（磁盘工具抹盘 + 安装系统）。
  • 常用 VNC 客户端：RealVNC Viewer、TightVNC（用户环境已采用）、TigerVNC 等均可，连接地址均为 localhost:5900。
  1. WSL / 网络故障排查
  • 若 wsl 进程过多、wsl --shutdown 卡死：
    • 在 PowerShell 中执行：
Get-Process -Name wsl -ErrorAction SilentlyContinue | Stop-Process -Force
wsl --shutdown
wsl -l -v
  • 若 wsl --install 报 0x80072ee2 或无法访问 raw.githubusercontent.com：
    • 提醒用户这是 网络 / DNS 问题，可尝试：
      • 切换 DNS 到 8.8.8.8
      • 使用合规代理 / VPN
      • 使用 --web-download 方式安装发行版：
wsl --install -d Ubuntu-24.04 --web-download
  1. Python 一键脚本（lobster_macos_vm.py）协同

当仓库中存在 开发文档/服务器管理/scripts/lobster_macos_vm.py 时：

  • 优先引导用户在 PowerShell 中执行：
python C:\Users\{USERNAME}\Mycontent\macos-vm\lobster_macos_vm.py
  • 该脚本应负责：
    • 检查 / 安装 WSL2 + Ubuntu-24.04（必要时提示用户重启）
    • 确保 C:\Users\{USERNAME}\Mycontent\macos-vm 目录存在
    • 在 WSL 内下载 OneClick 源码 zip、解压到固定目录
    • 安装 QEMU / Python 依赖并检查 kvm-ok
    • 下载 Ventura 恢复镜像并生成 BaseSystem.img
    • 启动 sudo HEADLESS=1 ./basic.sh
    • 输出清晰的步骤说明（包括如何用 VNC 连接）

使用示例

  • 用户说：「龙虾，帮我在这台 Windows 上一键装一个 macOS 虚拟机，用来演示」

    • 按上述步骤依次执行：环境检测 → 创建 macos-vm 目录 → 下载 OneClick → 安装依赖 → 下载 Ventura → 生成 BaseSystem.img → 启动虚拟机，并提醒用户用 VNC 连 localhost:5900 完成图形安装。

  • 用户说：「龙虾，之前的 macOS 虚拟机挂了，重装一遍」

    • 复用相同目录和镜像文件，必要时重新下载 BaseSystem.dmg，再启动 HEADLESS=1 ./basic.sh。