qemux/qemu

QEMU Docker镜像

概述

QEMU Docker镜像是一个在容器中运行虚拟机的解决方案，通过Docker容器化技术简化虚拟机的部署与管理。该镜像提供Web界面控制，支持多种磁盘格式，并集成KVM加速、内核模式网络等高性能特性，适合快速搭建隔离的虚拟机环境，适用于开发测试、操作系统学习等场景。

核心功能

• Web界面控制：直接通过浏览器访问虚拟机屏幕，使用键盘和鼠标进行操作
• 多磁盘格式支持：兼容.iso、.img、.qcow2、.vhd、.vhdx、.vdi、.vmdk及.raw等格式
• 高性能配置：支持KVM加速、内核模式网络、IO线程等选项，实现接近原生的运行速度

使用方法

Docker Compose部署

yaml
services:
  qemu:
    image: qemux/qemu
    container_name: qemu
    environment:
      BOOT: "mint"  # 指定要安装的操作系统
    devices:
      - /dev/kvm    # KVM设备，用于硬件加速
      - /dev/net/tun  # 网络隧道设备
    cap_add:
      - NET_ADMIN   # 添加网络管理权限
    ports:
      - 8006:8006   # Web界面端口映射
    volumes:
      - ./qemu:/storage  # 存储目录挂载
    restart: always
    stop_grace_period: 2m  # 停止宽限期

Docker CLI部署

bash
docker run -it --rm --name qemu -e "BOOT=mint" -p 8006:8006 \
  --device=/dev/kvm --device=/dev/net/tun --cap-add NET_ADMIN \
  -v "${PWD:-.}/qemu:/storage" --stop-timeout 120 docker.io/qemux/qemu

Kubernetes部署

shell
kubectl apply -f https://raw.githubusercontent.com/qemus/qemu/refs/heads/master/kubernetes.yml

Github Codespaces

https://github.com/codespaces/badge.svg]([***]

配置说明

环境变量

卷挂载

• /storage: 虚拟机存储目录，用于存放磁盘镜像等数据，建议通过宿主机目录或命名卷挂载
• /boot.iso、/boot.img、/boot.qcow2: 本地镜像文件挂载，挂载后BOOT变量将被忽略

设备与权限

• --device=/dev/kvm: 启用KVM硬件加速（需宿主机支持）
• --device=/dev/net/tun: 启用网络隧道
• --cap-add=NET_ADMIN: 添加网络管理权限，支持网络配置

常见问题（FAQ）

如何使用该镜像？

非常简单，步骤如下：

1. 设置BOOT变量指定要安装的操作系统
2. 启动容器并通过浏览器访问8006端口
3. 在Web界面中使用键盘和鼠标安装操作系统

如何选择操作系统？

通过BOOT环境变量指定要下载的操作系统，例如：

yaml
environment:
  BOOT: "mint"

支持的操作系统及大小如下表：

如何使用自定义镜像？

有两种方式使用自定义镜像：

1. 通过URL下载：将BOOT变量设置为镜像文件的URL，支持.iso、.img等格式及压缩文件（会自动解压），例如：

   yaml
   environment:
     BOOT: "https://dl-cdn.alpinelinux.org/alpine/v3.19/releases/x86_64/alpine-virt-3.19.1-x86_64.iso"
   

2. 本地文件挂载：将本地镜像文件挂载到容器中，例如：

   yaml
   volumes:
     - ./example.iso:/boot.iso  # 或/boot.img、/boot.qcow2
   

   此时BOOT变量将被忽略。

如何修改存储位置？

通过卷挂载修改存储目录，例如：

yaml
volumes:
  - ./自定义目录:/storage  # 将./自定义目录替换为宿主机实际目录或命名卷

如何调整磁盘大小？

通过DISK_SIZE环境变量设置磁盘大小（默认64G），例如：

yaml
environment:
  DISK_SIZE: "128G"  # 支持增大现有磁盘，不会丢失数据

[!TIP] 此参数也可用于扩容现有磁盘，且不会导致数据丢失。

如何调整CPU或内存？

默认分配2核CPU和2GB内存，可通过以下环境变量调整：

yaml
environment:
  RAM_SIZE: "8G"   # 内存大小，如"4G"、"8G"
  CPU_CORES: "4"   # CPU核心数，如"2"、"4"

如何启动ARM64镜像？

使用https://github.com/qemus/qemu-arm/%E5%AE%B9%E5%99%A8%E8%BF%90%E8%A1%8CARM64%E6%9E%B6%E6%9E%84%E7%9A%84%E9%95%9C%E5%83%8F%E3%80%82

如何启动Windows？

建议使用https://github.com/dockur/windows%EF%BC%8C%E8%AF%A5%E9%95%9C%E5%83%8F%E5%8C%85%E5%90%AB%E5%AE%89%E8%A3%85%E6%89%80%E9%9C%80%E7%9A%84%E9%A9%B1%E5%8A%A8%E5%8F%8A%E6%9B%B4%E5%A4%9A%E5%8A%9F%E8%83%BD%E3%80%82

如何启动macOS？

建议使用https://github.com/dockur/macos%EF%BC%8C%E8%AF%A5%E9%95%9C%E5%83%8F%E5%B7%B2%E9%85%8D%E7%BD%AE%E6%AD%A3%E7%A1%AE%E7%9A%84%E8%AE%BE%E7%BD%AE%E5%B9%B6%E8%87%AA%E5%8A%A8%E4%B8%8B%E8%BD%BD%E5%AE%89%E8%A3%85%E6%96%87%E4%BB%B6%E3%80%82

如何禁用UEFI启动？

默认启用UEFI启动，若操作系统不支持，可通过BOOT_MODE变量切换为传统BIOS：

yaml
environment:
  BOOT_MODE: "legacy"

如何禁用VirtIO驱动？

默认使用virtio-scsi驱动以提高性能，若操作系统无法识别磁盘，可通过DISK_TYPE变量修改：

yaml
environment:
  DISK_TYPE: "blk"  # 或"ide"（兼容性好但速度慢）

如何验证系统是否支持KVM？

首先检查软件兼容性：

在Linux系统中，通过以下命令检查硬件支持：

bash
sudo apt install cpu-checker
sudo kvm-ok

若kvm-ok提示不支持KVM，需检查：

• BIOS中是否启用虚拟化扩展（Intel VT-x或AMD SVM）
• 若在虚拟机中运行，是否启用嵌套虚拟化
• 云服务器通常不支持嵌套虚拟化

如何暴露网络端口？

• 桥接网络：直接在ports中添加端口映射，例如- 2222:22将虚拟机22端口映射到宿主机2222端口
• 用户模式网络：需在USER_PORTS变量中指定端口，例如USER_PORTS: "22,80,443"

如何为容器分配独立IP？

创建macvlan网络使容器获得独立IP：

bash
docker network create -d macvlan \
  --subnet=192.168.0.0/24 \  # 替换为宿主机子网
  --gateway=192.168.0.1 \    # 替换为网关IP
  --ip-range=192.168.0.100/28 \  # IP范围
  -o parent=eth0 vlan        # 替换为宿主机网卡

在Compose文件中使用该网络：

yaml
services:
  qemu:
    ...
    networks:
      vlan:
        ipv4_address: 192.168.0.100  # 分配的IP

networks:
  vlan:
    external: true

[!IMPORTANT] 由于macvlan设计限制，容器IP无法从Docker宿主机直接访问，需创建第二个macvlan作为 workaround。

如何让虚拟机从路由器获取IP？

配置macvlan网络后，通过以下设置使虚拟机成为家庭网络的一部分（容器和虚拟机将有独立IP）：

yaml
environment:
  DHCP: "Y"
devices:
  - /dev/vhost-net
device_cgroup_rules:
  - 'c *:* rwm'

如何添加多个磁盘？

通过环境变量和卷挂载添加额外磁盘：

yaml
environment:
  DISK2_SIZE: "32G"  # 第二个磁盘大小
  DISK3_SIZE: "64G"  # 第三个磁盘大小
volumes:
  - ./存储目录2:/storage2  # 第二个磁盘存储目录
  - ./存储目录3:/storage3  # 第三个磁盘存储目录

如何直通物理磁盘？

通过devices挂载物理磁盘或分区：

yaml
devices:
  - /dev/sdb:/disk1  # 主磁盘
  - /dev/sdc1:/disk2 # 次要磁盘（/disk2及以上）

如何直通USB设备？

1. 通过lsusb命令获取设备的vendorid和productid（如0x1234:0x1234）
2. 在Compose文件中添加：

yaml
environment:
  ARGUMENTS: "-device usb-host,vendorid=0x1234,productid=0x1234"  # 替换为实际ID
devices:
  - /dev/bus/usb

如何与宿主机共享文件？

若客户机支持9pfs，可通过以下步骤共享文件：

1. 在Compose文件中添加卷挂载：

yaml
volumes:
  - ./共享目录:/shared  # ./共享目录为宿主机目录

2. 在客户机中执行挂载命令：

shell
mount -t 9p -o trans=virtio shared /mnt/共享目录  # /mnt/共享目录为客户机挂载点

如何传递自定义QEMU参数？

通过ARGUMENTS环境变量传递额外参数：

yaml
environment:
  ARGUMENTS: "-device usb-tablet"  # 示例：添加USB平板设备

若要查看完整QEMU命令行参数，启用调试模式：

yaml
environment:
  DEBUG: "Y"