tianon/qemu Docker镜像文档

1. 镜像概述和主要用途

tianon/qemu是一个基于QEMU的容器化镜像，旨在通过Docker环境快速部署和运行QEMU虚拟机。该镜像将QEMU虚拟化功能与Docker容器的便捷性结合，允许用户通过环境变量和命令行参数灵活配置虚拟机参数，无需在宿主机直接安装和配置QEMU。

主要用途：提供轻量级、可定制的虚拟机运行环境，适用于开发测试、系统模拟、操作系统安装调试等场景，尤其适合需要快速搭建隔离环境的用户。

源代码地址：[***]

2. 核心功能和特性

• KVM加速支持：通过--device /dev/kvm参数利用宿主机KVM设备，显著提升虚拟机运行性能（需宿主机支持KVM）。
• 环境变量配置：通过环境变量（如QEMU_HDA、QEMU_CPU）简化虚拟机核心参数配置，无需手动编写复杂QEMU命令。
• 灵活端口映射：默认自动映射22端口（SSH），同时支持通过QEMU_PORTS自定义映射其他TCP端口。
• 原生参数扩展：支持通过start-qemu <args>命令传递QEMU原生参数，满足高级配置需求（如图形界面、网络调试等）。
• UEFI启动支持：集成ovmf包，可通过--bios参数启用UEFI启动模式，支持现代操作系统引导。
• 用户模式网络：默认使用QEMU SLIRP用户网络栈，简化网络配置，无需手动配置桥接或NAT。

3. 使用场景和适用范围

• 开发测试环境：快速搭建不同操作系统（如Linux、Windows）的测试环境，验证应用兼容性。
• 系统模拟：模拟特定硬件架构或配置，测试系统启动流程、驱动兼容性等。
• 教学演示：在隔离容器中演示操作系统安装、网络配置等操作，避免影响宿主机环境。
• 容器化管理：将虚拟机纳入Docker容器生命周期管理，统一资源调度和部署流程。

4. 详细使用方法和配置说明

4.1 前置准备

1. 创建磁盘镜像：在宿主机创建QEMU磁盘文件（qcow2格式），用于虚拟机存储：

   $ touch /home/jsmith/hda.qcow2  # 或使用qemu-img创建指定大小：qemu-img create -f qcow2 /home/jsmith/hda.qcow2 100G
   

2. 准备安装介质：下载操作系统ISO文件（如Debian、Ubuntu安装镜像），存放于宿主机路径（如/home/jsmith/downloads/debian.iso）。

4.2 基本部署示例（docker run）

通过以下命令启动QEMU虚拟机容器（以安装Debian为例）：

$ docker run -it --rm \
    --device /dev/kvm \                  # 启用KVM加速（需宿主机支持KVM）
    --name qemu-container \              # 容器名称
    -v /home/jsmith/hda.qcow2:/tmp/hda.qcow2 \  # 挂载宿主机磁盘镜像到容器内
    -e QEMU_HDA=/tmp/hda.qcow2 \         # 指定虚拟机主磁盘路径（容器内路径）
    -e QEMU_HDA_SIZE=100G \              # 主磁盘大小（若磁盘文件未初始化，自动创建指定大小）
    -e QEMU_CPU=4 \                      # 分配CPU核心数
    -e QEMU_RAM=4096 \                   # 分配内存大小（MB）
    -v /home/jsmith/downloads/debian.iso:/tmp/debian.iso:ro \  # 挂载ISO安装介质（只读）
    -e QEMU_CDROM=/tmp/debian.iso \      # 指定CDROM设备路径（容器内）
    -e QEMU_BOOT='order=d' \             # 启动顺序（d: CDROM优先，c: 硬盘优先）
    -e QEMU_PORTS='2375 2376' \          # 自定义映射端口（空格分隔）
    tianon/qemu

4.3 docker-compose配置示例

创建docker-compose.yml文件，实现容器化部署编排：

version: '3'
services:
  qemu-vm:
    image: tianon/qemu
    container_name: qemu-container
    devices:
      - /dev/kvm  # 启用KVM加速
    volumes:
      - /home/jsmith/hda.qcow2:/tmp/hda.qcow2  # 虚拟机磁盘（宿主机路径:容器内路径）
      - /home/jsmith/downloads/debian.iso:/tmp/debian.iso:ro  # 安装ISO（只读）
    environment:
      - QEMU_HDA=/tmp/hda.qcow2
      - QEMU_HDA_SIZE=100G
      - QEMU_CPU=4
      - QEMU_RAM=4096
      - QEMU_CDROM=/tmp/debian.iso
      - QEMU_BOOT=order=d
      - QEMU_PORTS=2375 2376
    stdin_open: true  # 保持标准输入打开（交互模式）
    tty: true         # 分配伪终端（支持终端交互）
    restart: unless-stopped  # 可选：容器退出后自动重启（除非手动停止）

启动容器：

$ docker-compose up -d

4.4 配置参数说明

4.4.1 环境变量

4.4.2 端口映射规则

• 默认端口：无论QEMU_PORTS是否配置，容器自动映射22端口（SSH）到宿主机随机端口，可通过docker port qemu-container查看映射结果：

  $ docker port qemu-container
  22/tcp -> 0.0.0.0:49153  # 示例：宿主机49153端口映射到容器22端口
  

• 自定义端口：QEMU_PORTS指定的端口将额外映射到宿主机随机端口，例如QEMU_PORTS=2375 2376会映射2375和2376端口。

4.4.3 传递额外QEMU参数

如需使用QEMU原生参数（如字符界面、网络调试），可通过start-qemu <args>命令传递，例如启用字符界面（-curses）：

$ docker run -it --rm \
    --device /dev/kvm \
    -v /home/jsmith/hda.qcow2:/tmp/hda.qcow2 \
    -e QEMU_HDA=/tmp/hda.qcow2 \
    tianon/qemu start-qemu -curses  # 传递-curses参数启用字符界面

4.4.4 UEFI启动配置

镜像集成ovmf包（UEFI固件），启用UEFI启动需通过--bios参数指定固件路径：

$ docker run -it --rm \
    --device /dev/kvm \
    -v /home/jsmith/hda.qcow2:/tmp/hda.qcow2 \
    -e QEMU_HDA=/tmp/hda.qcow2 \
    tianon/qemu start-qemu --bios /usr/share/ovmf/OVMF.fd  # 使用UEFI固件

4.4.5 网络配置注意事项

• 默认网络：镜像默认使用QEMU用户模式网络栈（SLIRP），支持虚拟机访问外部网络，但宿主机访问虚拟机需通过端口映射。

• ICMP/Ping支持：用户模式网络默认禁用ICMP协议（ping命令），如需启用，需在容器启动时添加sysctl参数：

  $ docker run -it --rm \
      --device /dev/kvm \
      --sysctl net.ipv4.ping_group_range='0 2147483647' \  # 允许ping操作
      ...  # 其他参数（如环境变量、挂载）
      tianon/qemu
  

5. 注意事项

• KVM依赖：--device /dev/kvm需宿主机支持KVM（检查/dev/kvm是否存在），否则将回退到QEMU纯软件模拟，性能显著下降。

• 权限要求：容器需有权限访问/dev/kvm设备，建议将宿主机用户添加到kvm组（usermod -aG kvm $USER），避免使用--privileged。

• 磁盘性能：虚拟机磁盘文件（qcow2）的存储位置影响I/O性能，建议存放于SSD或高性能存储介质。