ghcr.io/qemus/qemu:7.50

QEMU

用于通过QEMU运行虚拟机的Docker容器。

特性 ✨

• 在Docker容器内运行虚拟机
• 支持几乎所有磁盘和镜像格式
• 基于Web的虚拟机控制查看器
• 借助KVM加速实现接近原生的性能
• 可自定义CPU、内存和存储分配
• 硬件加速的OpenGL、Vulkan和vDRM图形
• 支持内存气球技术的动态内存分配
• USB直通和主机文件夹共享
• 支持NAT、用户模式、macvlan和macvtap网络
• 自动下载主流Linux发行版

使用方法 🐳

Docker Compose:

services:
  qemu:
    image: qemux/qemu
    container_name: qemu
    environment:
      BOOT: "mint"
    devices:
      - /dev/kvm
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    ports:
      - 8006:8006
    volumes:
      - ./qemu:/storage
    restart: always
    stop_grace_period: 2m

Docker CLI:

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:

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

GitHub Codespaces:

要求 ⚙️

• Linux主机上的Docker或Podman，需支持KVM。
• Windows 11上的Docker Desktop或Podman (Desktop)，需启用嵌套虚拟化。

[!IMPORTANT] Linux、macOS和Windows 10上的Docker Desktop目前不向容器提供KVM访问权限，因此不受支持。

常见问题 💬

如何使用？

非常简单！步骤如下：

• 将BOOT变量设置为您要安装的操作系统。
• 启动容器并使用Web浏览器连接到8006端口。
• 通过基于Web的查看器完成安装。

享受您的新机器，别忘了给这个仓库点星！

如何选择操作系统？

您可以使用BOOT环境变量指定要下载的操作系统：

environment:
  BOOT: "mint"

从以下值中选择：

如何使用自定义镜像？

如果您想下载未在上述列表中的操作系统，可以将BOOT变量设置为镜像的URL：

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

BOOT URL接受以下格式的文件：

它还接受.img.gz、.qcow2.xz、.iso.zip等文件，因为会自动解压压缩文件。

或者，您可以通过在compose文件中绑定本地镜像文件直接使用：

volumes:
  - ./example.iso:/boot.iso

通过这种方式，您可以提供/boot.iso、/boot.img或/boot.qcow2文件。此时BOOT的值将被忽略。

如何更改存储位置？

要更改存储位置，请在compose文件中包含以下绑定挂载：

volumes:
  - ./qemu:/storage

将示例路径./qemu替换为所需的存储文件夹或命名卷。

如何更改磁盘大小？

要扩展默认的64 GB大小，请在compose文件中添加DISK_SIZE设置并将其设置为您偏好的容量：

environment:
  DISK_SIZE: "128G"

这也可用于将现有磁盘调整为更大容量而不会丢失数据。但是，您需要在操作系统内手动扩展磁盘分区，因为添加的磁盘空间将显示为未分配。

如何更改CPU或RAM数量？

默认情况下，VM允许使用2个CPU核心和2 GB RAM。

如果要调整此设置，可以使用以下环境变量指定所需数量：

environment:
  RAM_SIZE: "8G"
  CPU_CORES: "4"

如何与主机共享文件？

要与主机共享文件，首先确保客户机操作系统已编译或作为内核模块提供9pfs支持。如果是这样，在compose文件中添加以下卷：

volumes:
  - ./example:/shared

然后启动容器并在客户机中执行以下命令：

mount -t 9p -o trans=virtio shared /mnt/example

现在主机上的./example目录将作为/mnt/example在客户机中可用。

如何启用音频？

音频默认处于禁用状态。要将音频流式传输到浏览器，请添加以下环境变量：

environment:
  AUDIO: "Y"

然后在Web查看器的“设置”→“高级”下启用音频。仅当启用此选项时流才会激活，因此在其他情况下不会使用额外带宽。

如何引导ARM64镜像？

您可以使用qemu-arm容器运行基于ARM64的镜像。

如何引导Windows？

请改用dockur/windows，因为它包含安装过程中所需的所有驱动程序以及许多其他功能。

如何引导macOS？

请改用dockur/macos，因为它使用所有正确的设置并自动下载安装文件。

如何不使用UEFI引导？

默认情况下，机器将启用UEFI引导。如果您的操作系统不支持UEFI，可以使用传统BIOS引导：

environment:
  BOOT_MODE: "legacy"

如何不使用VirtIO驱动引导？

默认情况下，机器使用virtio-scsi驱动器以获得性能，尽管大多数Linux内核都捆绑了此设备所需的驱动程序，但其他操作系统可能并非如此。

如果您的机器无法检测到硬盘，可以修改compose文件以使用virtio-blk：

environment:
  DISK_TYPE: "blk"

如果仍然无法引导，可以将值设置为ide以模拟IDE驱动器，虽然速度相对较慢，但不需要驱动程序且几乎与所有系统兼容。

如何暴露网络端口？

使用桥接网络时，可以通过将端口添加到compose文件来暴露端口。例如，如果要连接到机器的SSH服务，可以这样添加：

ports:
  - 2222:22

这将使主机上的2222端口重定向到虚拟机的22端口。

使用用户模式网络时（例如在Podman下运行时），还需要将这些端口添加到USER_PORTS变量，如下所示：

environment:
  USER_PORTS: "22,80,443"

如何为容器分配独立IP地址？

默认情况下，容器使用桥接网络，与主机共享IP地址。

如果要为容器分配独立IP地址，可以按如下方式创建macvlan网络：

docker network create -d macvlan \
  --subnet=192.168.0.0/24 \
  --gateway=192.168.0.1 \
  --ip-range=192.168.0.100/28 \
  -o parent=eth0 vlan

确保修改这些值以匹配您的本地子网。

创建网络后，将compose文件修改如下：

services:
  qemu:
    container_name: qemu
    .. ..
    networks:
      vlan:
        ipv4_address: 192.168.0.100

networks:
  vlan:
    external: true

这种方法的一个额外好处是您不再需要执行任何端口映射，因为所有端口默认都会暴露。

[!IMPORTANT] 由于macvlan的设计不允许Docker主机与容器之间通信，因此此IP地址无法从Docker主机访问。如果这是一个问题，您需要创建第二个macvlan作为解决方法。

如何让VM从路由器获取IP地址？

将容器配置为macvlan后，VM可以像真实PC一样从路由器请求IP，从而成为家庭网络的一部分。

要启用此模式（容器和VM将具有单独的IP地址），请在compose文件中添加以下行：

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

如何添加多个磁盘？

要创建额外的磁盘，请按如下方式修改compose文件：

environment:
  DISK2_SIZE: "32G"
  DISK3_SIZE: "64G"
volumes:
  - ./example2:/storage2
  - ./example3:/storage3

如何直通磁盘？

您可以通过以下方式将磁盘设备或分区直接添加到compose文件来实现直通：

devices:
  - /dev/sdb:/disk1
  - /dev/sdc1:/disk2

如果要将其作为主驱动器，请使用/disk1；使用/disk2及更高编号添加为辅助驱动器。

如何直通USB设备？

要直通USB设备，首先通过lsusb命令查找其供应商和产品ID，然后按如下方式添加到compose文件：

environment:
  ARGUMENTS: "-device usb-host,vendorid=0x1234,productid=0x1234"
devices:
  - /dev/bus/usb

如何启用GPU加速？

要使用Intel或AMD GPU启用硬件加速图形，请在compose文件中添加以下行：

environment:
  GPU: "Y"
devices:
  - /dev/dri

对于NVIDIA GPU，主机上必须安装NVIDIA Container Toolkit，并且GPU必须暴露给容器：

environment:
  GPU: "Y"
  NVIDIA_DRIVER_CAPABILITIES: "all"

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities:
            - gpu

GPU加速在Intel、AMD和NVIDIA GPU上提供硬件加速的OpenGL。

当在运行Linux 6.13或更新版本的主机上支持时，Vulkan加速也会自动启用，并且需要具有Venus支持的客户机，例如Linux 5.16或更新版本以及Mesa 24.2或更新版本。NVIDIA还需要570.86或更新版本的驱动程序。

如何启用动态内存分配？

默认情况下，VM在其整个生命周期内分配通过RAM_SIZE配置的全部RAM。

但是，如果您希望容器根据主机内存压力动态回收未使用的客户机RAM，可以启用内存气球技术。

如何为QEMU提供自定义参数？

您可以创建ARGUMENTS环境变量以在运行时为QEMU提供额外参数：

environment:
  ARGUMENTS: "-device usb-tablet"

如果要查看使用的完整命令行参数，可以设置：

environment:
  DEBUG: "Y"

这些是所有可用选项吗？

不是。有关所有支持设置的完整概述，请参阅环境变量页面。

如何验证KVM是否可用？

首先，确保您的平台和容器运行时满足上述要求。

在Linux主机上，安装cpu-checker并运行：

sudo apt install cpu-checker
sudo kvm-ok

正常配置应报告：

KVM acceleration can be used

您还可以验证KVM设备是否存在：

ls -l /dev/kvm

如果KVM不可用，请检查：

• 是否在BIOS或UEFI中启用了硬件虚拟化（Intel VT-x或AMD-V）。