更新经验清单,新增2026-03-10团队架构/运维约定,最后更新日期调整至2026-03-10。

This commit is contained in:
Alex-larget
2026-03-10 12:54:41 +08:00
parent f1afeee5e0
commit 3e22e54f75
5 changed files with 463 additions and 1 deletions

View File

@@ -0,0 +1,77 @@
# 团队共享 经验记录 - 2026-03-10
## 在 Windows 上一键启动 macOS 虚拟机(“龙虾”智能体经验)
### 场景 / 问题
- 成员希望在 **Windows 10/11** 上通过 **Docker** 一键安装 macOS用于演示 / 测试。
- 实际上:
- **macOS 不能在 Docker 中运行**Docker 只跑 Linux 容器,没有合法的 macOS 镜像)。
- 唯一可行路径是:**WSL2 + Ubuntu + QEMU/KVM + OneClick-macOS-Simple-KVM**。
### 关键决策
1. **明确技术与法律边界**
- 不支持也不承诺在 Docker 中直接跑 macOS。
- 统一采用「**WSL2 + QEMU/KVM + OneClick**」这个方案,仅用于演示 / 测试。
2. **固定目录与流程约定**
- Windows 侧统一放在:`C:\Users\{USERNAME}\Mycontent\macos-vm`
- WSL 侧路径:`/mnt/c/Users/{USERNAME}/Mycontent/macos-vm`
- 内部结构:
- `OneClick-macOS-Simple-KVM/`
- `BaseSystem.dmg` / `BaseSystem.img`
- `macOS.qcow2`
3. **获取 OneClick 源码时优先走 zip而不是 git clone**
- 直接 `git clone` 很容易在国内网络环境下触发 `GnuTLS recv error (-110)` 等 TLS 超时。
- 统一约定使用:
- `https://codeload.github.com/notAperson535/OneClick-macOS-Simple-KVM/zip/refs/heads/master`
- 然后在 WSL 中:
- `curl + unzip` → 解压 → 重命名为 `OneClick-macOS-Simple-KVM`
4. **依赖安装与 KVM 检查**
- 在 Ubuntu-24.04 内安装:
- `qemu-system qemu-utils python3 python3-pip cpu-checker`
- 使用 `kvm-ok` 检查:
- 期望输出:`/dev/kvm exists` + `KVM acceleration can be used`
-`nested``N` 且需要嵌套虚拟化,使用 `.wslconfig` 打开 nested。
5. **下载 macOS Ventura 恢复镜像并生成 BaseSystem.img**
- 通过 `python3 fetch-macOS-v2.py -s ventura` 下载官方 Recovery 镜像。
-`RecoveryImage.dmg` 重命名为 `BaseSystem.dmg`,再用 `qemu-img convert` 生成 `BaseSystem.img`
- 验收标准:
- `BaseSystem.dmg` ≈ 678 MB
- `BaseSystem.img` ≈ 3.0 GB
6. **以 HEADLESS + VNC 方式启动 VM**
- 使用 `sudo HEADLESS=1 ./basic.sh` 启动 QEMU。
- 在 Windows 中确认 `127.0.0.1:5900` 端口监听。
- 统一告知使用 VNC 客户端连接 `localhost:5900`,再在图形界面内完成 macOS 安装向导。**用户环境已采用 TightVNC**,与 RealVNC Viewer 等方式等效。
7. **WSL 卡死与多 wsl 进程清理策略**
-`wsl --shutdown` 卡住、或者有大量 `wsl` 进程残留时:
- 使用 PowerShell `Get-Process wsl | Stop-Process -Force` 清理。
- 再执行 `wsl --shutdown` + `wsl -l -v` 验证状态恢复。
### 对应 Skill / 智能体
- 新建 Skill`.cursor/skills/lobster-macos-vm/SKILL.md`
- 技能名:`lobster-macos-vm`
- 智能体名(对外):**“龙虾”**
- 职责:当用户在 Windows 上提出安装 / 维护 macOS 虚拟机的需求时,统一按该 Skill 流程执行:
- 解释 Docker 不可用 → 切换到 WSL2 + QEMU 方案。
- 固定目录 → 下载 OneClick → 安装依赖 → 下载 Ventura → 生成 `BaseSystem.img` → HEADLESS 启动 → 引导 VNC 安装。
- 计划脚本化:
-`开发文档/服务器管理/scripts/lobster_macos_vm.py` 中实现一键部署脚本,封装上述流程,供“龙虾”及人类成员复用。
### 用户环境补充
- **VNC 客户端**:当前环境使用 **TightVNC** 连接 `localhost:5900`,已写入龙虾 Skill后续回复可一并推荐 TightVNC / RealVNC / TigerVNC 等。
### 适用角色
- 后端 / 运维:需要在本地或服务器上快速拉起 macOS VM 做兼容性验证或演示。
- 团队:对外说明 **“我们不支持 Docker macOS统一用龙虾方案”**。

View File

@@ -25,6 +25,7 @@
| 2026-02-27 | 小程序、团队 | 最佳实践 | SKILL-小程序开发 §6、SKILL-管理端开发 §4.1 | 输入框 padding 用 view/div 包裹 |
| 2026-02-28 | 小程序、管理端 | 最佳实践 | miniprogram §6、admin §4.1 | input 边距口诀「外边包 view、内部 width 100%」match 弹窗已修正 |
| 2026-03-03 | 小程序 | 最佳实践 | miniprogram §8 | 我的页面卡片区边距 16rpx个人中心类页面布局规范 |
| 2026-03-10 | 团队 | 架构/运维约定 | lobster-macos-vm Skill | Windows 上统一使用 WSL2+QEMU+OneClick 的“龙虾”方案安装 macOS 虚拟机,禁止 Docker 直跑 macOS |
---
@@ -35,4 +36,4 @@
---
**最后更新**2026-03-03
**最后更新**2026-03-10

View File

@@ -0,0 +1,184 @@
---
name: lobster-macos-vm
description: 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/` 目录内执行:
```bash
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
```
仅当用户网络环境允许且确有需要时,才尝试:
```bash
git clone --depth 1 https://github.com/notAperson535/OneClick-macOS-Simple-KVM.git
```
出现 `GnuTLS recv error (-110)` 或 TLS 断开时,**不要重复 git clone**,改走 zip 方案。
4. **依赖安装与 KVM 检查**
`Ubuntu-24.04` 内执行:
```bash
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` 中写入:
```ini
[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` 之后重试。
5. **下载 macOS Ventura 恢复镜像并生成 BaseSystem.img**
`OneClick-macOS-Simple-KVM` 目录内:
```bash
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 起步)
6. **启动虚拟机headless + VNC: localhost:5900**
`OneClick-macOS-Simple-KVM` 目录内执行:
```bash
sudo HEADLESS=1 ./basic.sh
```
常见日志:
- ALSA / audio 报错(没有声卡驱动)→ **可以忽略**
- `BdsDxe: loading Boot0001 "UEFI QEMU HARDDISK QM00017"...` → 已经开始从虚拟硬盘启动
在 Windows 侧确认端口:
```powershell
Get-NetTCPConnection -LocalPort 5900 -State Listen
```
若监听正常,提示用户:
- 安装 VNC 客户端并连接 `localhost:5900`,进入 macOS 安装向导(磁盘工具抹盘 + 安装系统)。
- **常用 VNC 客户端**RealVNC Viewer、**TightVNC**用户环境已采用、TigerVNC 等均可,连接地址均为 `localhost:5900`
7. **WSL / 网络故障排查**
-`wsl` 进程过多、`wsl --shutdown` 卡死:
- 在 PowerShell 中执行:
```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` 方式安装发行版:
```powershell
wsl --install -d Ubuntu-24.04 --web-download
```
8. **Python 一键脚本lobster_macos_vm.py协同**
当仓库中存在 `开发文档/服务器管理/scripts/lobster_macos_vm.py` 时:
- 优先引导用户在 **PowerShell** 中执行:
```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`

View File

@@ -0,0 +1,37 @@
@echo off
chcp 65001 >nul
title 一键启动 macOS 虚拟机 + TightVNC
echo ========================================
echo 一键启动 macOS 虚拟机(龙虾方案)
echo ========================================
echo.
set "VM_DIR=%USERPROFILE%\Mycontent\macos-vm\OneClick-macOS-Simple-KVM"
if not exist "%VM_DIR%\basic.sh" (
echo [错误] 未找到虚拟机目录: %VM_DIR%
echo 请先运行龙虾安装流程完成首次部署。
pause
exit /b 1
)
echo [1] 在新窗口启动 macOS 虚拟机8G 内存 / 4 核)...
start "macOS 虚拟机 - 勿关此窗口" wsl -d Ubuntu-24.04 -e bash -lc "cd /mnt/c/Users/%USERNAME%/Mycontent/macos-vm/OneClick-macOS-Simple-KVM && sudo HEADLESS=1 ./basic.sh"
echo [2] 等待约 10 秒后自动打开 TightVNC Viewer 连接 localhost:5900 ...
timeout /t 10 /nobreak >nul
set "TVN=%ProgramFiles%\TightVNC\tvnviewer.exe"
if not exist "%TVN%" set "TVN=%ProgramFiles(x86)%\TightVNC\tvnviewer.exe"
if exist "%TVN%" (
start "" "%TVN%" localhost::5900
echo [3] 已启动 TightVNC Viewer连接 localhost:5900
) else (
echo [3] 未找到 TightVNC请手动打开 VNC 客户端连接: localhost:5900
)
echo.
echo 虚拟机在「macOS 虚拟机 - 勿关此窗口」中运行,关闭该窗口会关闭虚拟机。
echo 本窗口可以关闭。
echo ========================================
pause

View File

@@ -0,0 +1,163 @@
"""
lobster_macos_vm.py
“龙虾” 一键脚本:在 Windows 10/11 上,通过 WSL2 + Ubuntu-24.04 + QEMU/KVM
和 OneClick-macOS-Simple-KVM 自动准备 macOS 虚拟机Ventura
使用方式(在 Windows PowerShell 中):
python C:\\Users\\<USERNAME>\\Mycontent\\macos-vm\\lobster_macos_vm.py
注意:
- 需要管理员权限安装 WSL2如果此前未安装
- 脚本不会替你点 macOS 图形安装向导,只会把虚拟机和 VNC 端口拉起来。
"""
import os
import subprocess
import sys
from pathlib import Path
def run(cmd, check=True):
"""在 Windows Shell 中运行命令,并在失败时抛异常。"""
print(f"[lobster] RUN: {cmd}")
result = subprocess.run(cmd, shell=True)
if check and result.returncode != 0:
raise RuntimeError(f"命令执行失败exit {result.returncode}{cmd}")
return result.returncode
def ensure_wsl_installed():
"""检测 WSL 是否可用,不负责安装(安装通常需要手工 + 重启)。"""
try:
subprocess.run("wsl -l -v", shell=True, check=True,
stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
except subprocess.CalledProcessError:
print(
"[lobster] 检测到 WSL 尚未可用请以管理员权限运行wsl --install然后重启电脑后再运行本脚本。"
)
sys.exit(1)
def ensure_ubuntu_distro():
"""确保存在 Ubuntu-24.04 发行版(不强制版本号,只要有 Ubuntu 即可继续)。"""
proc = subprocess.run(
"wsl -l -v", shell=True, capture_output=True, text=True, check=False
)
if proc.returncode != 0:
print(proc.stdout)
print(proc.stderr)
raise RuntimeError("wsl -l -v 执行失败,无法检测发行版。")
lines = proc.stdout.splitlines()
ubuntu_exists = any("Ubuntu" in line for line in lines)
if not ubuntu_exists:
print(
"[lobster] 未发现 Ubuntu 发行版,请以管理员权限运行:\n"
" wsl --install -d Ubuntu-24.04 --web-download\n"
"安装完成、重启并完成 Ubuntu 初始化后,再运行本脚本。"
)
sys.exit(1)
def wsl_path(win_path: Path) -> str:
"""将 Windows 路径转换为 WSL 路径(简单 C: -> /mnt/c 映射)。"""
drive = win_path.drive.replace(":", "").lower()
rel = win_path.as_posix().split(":/")[-1] if ":/" in win_path.as_posix() else win_path.as_posix().split(":")[-1]
# 去掉开头的 /
if rel.startswith("/"):
rel = rel[1:]
return f"/mnt/{drive}/{rel.replace(' ', '\\ ')}"
def run_in_wsl(bash_script: str):
"""把一段 bash 脚本送进 WSL 执行。"""
cmd = f"wsl -e bash -lc \"set -e; {bash_script}\""
return run(cmd)
def main():
username = os.environ.get("USERNAME") or os.environ.get("USER")
if not username:
raise RuntimeError("无法获取当前 Windows 用户名USER/USERNAME")
# 1. 检查 WSL / Ubuntu
print("[lobster] 第 1 步:检查 WSL / Ubuntu 环境...")
ensure_wsl_installed()
ensure_ubuntu_distro()
# 2. 创建固定目录 C:\Users\<USERNAME>\Mycontent\macos-vm
base_dir = Path(f"C:/Users/{username}/Mycontent/macos-vm")
base_dir.mkdir(parents=True, exist_ok=True)
print(f"[lobster] 使用目录:{base_dir}")
wsl_base = wsl_path(base_dir)
# 3. 在 WSL 中下载 OneClick 源码 zip 并解压
print("[lobster] 第 2 步:下载 OneClick 源码 zip 并解压...")
bash_download = f"""
cd {wsl_base}
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 900 \\
-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
"""
run_in_wsl(bash_download)
# 4. 安装 QEMU / Python / cpu-checker并检查 KVM
print("[lobster] 第 3 步:安装 QEMU / Python / cpu-checker并检查 KVM...")
bash_deps = f"""
cd {wsl_base}/OneClick-macOS-Simple-KVM
sudo apt-get update -qq
sudo apt-get install -y qemu-system qemu-utils python3 python3-pip cpu-checker
kvm-ok || true
"""
run_in_wsl(bash_deps)
# 5. 下载 macOS Ventura 恢复镜像并生成 BaseSystem.img / macOS.qcow2
print("[lobster] 第 4 步:下载 macOS Ventura 恢复镜像并生成 BaseSystem.img...")
bash_fetch = f"""
cd {wsl_base}/OneClick-macOS-Simple-KVM
chmod +x *.sh *.py || true
[ -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 || true
qemu-img convert BaseSystem.dmg -O raw BaseSystem.img
ls -lah BaseSystem.* macOS.qcow2
"""
run_in_wsl(bash_fetch)
# 6. 启动虚拟机HEADLESS + VNC 5900
print("[lobster] 第 5 步:启动 macOS 虚拟机HEADLESS + VNC: localhost:5900...")
bash_start = f"""
cd {wsl_base}/OneClick-macOS-Simple-KVM
sudo HEADLESS=1 ./basic.sh
"""
# 不阻塞当前 PowerShell用 wslrelay/wsl 后台端口监听,由用户自己关
subprocess.Popen(
f"wsl -e bash -lc \"{bash_start}\"",
shell=True,
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
)
print("\n[lobster] 已尝试启动 macOS 虚拟机。")
print("请确保已经安装 VNC Viewer如 RealVNC")
print("在 VNC Viewer 中连接localhost:5900")
print("随后在图形界面中完成磁盘抹盘和 macOS 安装向导即可。")
if __name__ == "__main__":
try:
main()
except KeyboardInterrupt:
print("\n[lobster] 收到中断,已停止。")
except Exception as e:
print(f"\n[lobster] 发生错误:{e}")
sys.exit(1)