qemu-startup

QEMU 虚拟机启动技能

此技能提供启动 QEMU 虚拟机的操作指南，支持串行控制台访问，尤其适用于涉及 ISO 启动、telnet 连接和无头运行的任务。

启动前检查（关键第一步）

在尝试任何 QEMU 操作之前，请系统地验证所有前提条件。跳过此步骤会导致反复失败。

工具可用性检查

规划方案之前，请确认可用的工具：

# Check QEMU installation
which qemu-system-x86_64 || which qemu-system-i386

# Check for process management tools (availability varies by environment)
which ps pkill pgrep kill 2>/dev/null

# Check for network diagnostic tools
which nc netstat ss lsof 2>/dev/null

# Check for telnet client
which telnet

根据环境中实际可用的工具调整策略。

KVM 可用性检查

切勿假设 KVM 可用。使用 -enable-kvm 之前先进行检查：

# Check if KVM module is loaded
ls /dev/kvm 2>/dev/null && echo "KVM available" || echo "KVM not available"

# Alternative check
grep -E '(vmx|svm)' /proc/cpuinfo > /dev/null && echo "CPU supports virtualization"

如果 KVM 不可用，请完全省略 -enable-kvm 标志，而不要让它导致失败。

资源验证

# Verify the ISO/disk image exists and is readable
ls -la /path/to/image.iso

# Check if the target port is already in use
# Use whichever tool is available:
nc -z localhost PORT 2>/dev/null && echo "Port in use"
# or
netstat -tuln | grep PORT
# or
ss -tuln | grep PORT

构造 QEMU 命令

先收集所有必要信息，再从一开始就构造正确的命令。

串行控制台访问的必要参数

无头运行并通过 telnet 访问串行控制台：

qemu-system-x86_64 \
    -m 512 \                           # Memory (adjust as needed)
    -cdrom /path/to/image.iso \        # Boot ISO
    -nographic \                       # No graphical output
    -serial telnet:localhost:PORT,server,nowait \  # Serial on telnet
    -monitor none                      # Disable QEMU monitor on stdio

常见参数陷阱

问题	原因	解决方案
出现 QEMU 监视器提示符，而非串行控制台	缺少 -monitor none，或 -nographic 设置冲突	明确添加 -monitor none
“端口已被占用”错误	之前的 QEMU 实例仍在运行	先清理现有进程
虚拟机在启动时挂起	系统不支持 KVM，却使用了 KVM 标志	移除 -enable-kvm
看不到任何输出	串行控制台配置不正确	确保 -serial 指向可访问的 telnet 端口

有条件地使用 KVM

# Build command conditionally
if [ -e /dev/kvm ]; then
    KVM_FLAG="-enable-kvm"
else
    KVM_FLAG=""
fi

qemu-system-x86_64 $KVM_FLAG -m 512 ...

进程管理和清理

幂等启动流程

启动新的 QEMU 实例之前，请确保不存在冲突进程：

# Find existing QEMU processes (use available tools)
ps aux | grep qemu | grep -v grep

# If pkill available:
pkill -f "qemu.*PORT" 2>/dev/null

# If only kill available, find PID first:
# Then: kill PID

# Wait briefly for port release
sleep 2

# Verify port is free before starting

后台进程跟踪

在后台运行 QEMU 时：

1. 启动后立即记录进程 ID
2. 如果使用 shell 作业控制，请保存后台作业标识符
3. 启动后确认进程确实正在运行
4. 跟踪当前生效的是哪次尝试或哪个进程

就绪状态验证

智能轮询（优于固定等待）

不要使用随意设定的 sleep 时长，而应轮询检查实际就绪状态：

# Poll for port availability with timeout
MAX_WAIT=60
WAITED=0
while ! nc -z localhost PORT 2>/dev/null; do
    sleep 2
    WAITED=$((WAITED + 2))
    if [ $WAITED -ge $MAX_WAIT ]; then
        echo "Timeout waiting for VM"
        exit 1
    fi
done
echo "Port is listening after ${WAITED}s"

连接验证

端口开始监听后，验证服务是否已实际就绪：

# Test telnet connection and look for expected output
# Use timeout to avoid hanging
timeout 10 telnet localhost PORT

# For automated verification, check for login prompt
echo "" | timeout 5 telnet localhost PORT 2>&1 | grep -i "login"

验证策略

分层验证方法

1. 进程验证：确认 QEMU 进程正在运行
2. 端口验证：确认 telnet 端口正在监听
3. 连接验证：确认 telnet 连接成功
4. 服务验证：确认出现预期输出（登录提示符、shell 等）

依次完成每一层验证，再继续后续操作，以避免误报。

状态核对

如果进行了多次启动尝试，请明确识别当前负责处理连接的进程：

# Find process listening on the port
lsof -i :PORT  # if available
# or
netstat -tlnp | grep PORT
# or
ss -tlnp | grep PORT

应避免的常见错误

1. 假设工具可用：使用 ps、pkill、ss、nc 之前，务必先检查它们是否可用
2. 过早使用 KVM：添加 -enable-kvm 之前，请检查 /dev/kvm 是否存在
3. 清理不彻底：重启之前，请确认进程已终止且端口已释放
4. 随意设置等待时间：使用带就绪检查的轮询，而非固定延迟
5. 进程状态不明确：跟踪哪个后台进程实际正在运行
6. 混淆监视器和串行控制台：请注意，仅使用 -nographic 可能会显示 QEMU 监视器；使用 -monitor none 可获得纯净的串行输出
7. 重复进行冗余验证：一次性设计好验证流程，并按步骤系统地执行

决策框架

Start
  │
  ├─► Pre-flight checks pass?
  │     No ──► Adapt approach based on available tools
  │     Yes ──► Continue
  │
  ├─► KVM available?
  │     No ──► Omit -enable-kvm flag
  │     Yes ──► Include -enable-kvm flag
  │
  ├─► Port already in use?
  │     Yes ──► Clean up existing processes, wait for port release
  │     No ──► Continue
  │
  ├─► Start QEMU with complete command
  │
  ├─► Poll for port readiness (with timeout)
  │
  ├─► Verify connection and expected output
  │
  └─► Confirm final state explicitly