# qemu-docker

**Repository Path**: wei17173/qemu-docker

## Basic Information

- **Project Name**: qemu-docker
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-09-13
- **Last Updated**: 2025-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

特性 ✨
- 基于 Web 的查看器，可以直接从浏览器控制机器
- 支持 .iso, .img, .qcow2, .vhd, .vhdx, .vdi, .vmdk 和 .raw 磁盘格式
- 高性能选项（如 KVM 加速、内核模式网络、IO 线程等）以实现接近原生速度

使用方法 🐳
通过 Docker Compose：

```yaml
services:
  qemu:
    container_name: qemu
    image: qemux/qemu-docker
    environment:
      BOOT: "https://dl-cdn.alpinelinux.org/alpine/v3.19/releases/x86_64/alpine-virt-3.19.1-x86_64.iso" 
    devices:
      - /dev/kvm
    cap_add:
      - NET_ADMIN
    ports:
      - 8006:8006
    stop_grace_period: 2m
```

通过 Docker CLI：

```bash
docker run -it --rm -e "BOOT=http://example.com/image.iso"  -p 8006:8006 --device=/dev/kvm --cap-add NET_ADMIN qemux/qemu-docker
```

通过 Kubernetes：

```bash
kubectl apply -f kubernetes.yml
```

常见问题解答 💬
如何使用它？
非常简单！按照以下步骤操作：

1. 将 BOOT 环境变量设置为您想要安装的任何磁盘镜像的 URL。
2. 启动容器，并使用您的网络浏览器连接到端口 8006。
3. 您将看到屏幕，现在可以使用键盘和鼠标安装您选择的操作系统。
4. 享受您的全新机器，别忘了给这个仓库点个赞！

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

```yaml
volumes:
  - /var/qemu:/storage
```

将示例路径 /var/qemu 替换为您希望的存储文件夹。

如何更改磁盘大小？
要将默认大小 16 GB 扩展，可以在 compose 文件中添加 DISK_SIZE 设置，并将其设置为您首选的容量：

```yaml
environment:
  DISK_SIZE: "128G"
```

提示：这也可以用来在不丢失任何数据的情况下将现有磁盘调整为更大的容量。

如何引导本地镜像？
您可以直接使用本地镜像文件，完全跳过下载过程，通过在 compose 文件中绑定它：

```yaml
volumes:
  - /home/user/example.iso:/boot.iso
```

这样您可以提供一个 boot.iso、boot.img 或 boot.qcow2 文件。

注意：在这种情况下，BOOT 变量的 URL 将被忽略。

如何引导 ARM 镜像？
您可以使用 qemu-arm 来运行基于 ARM64 的镜像。

如何引导 Windows？
使用 dockur/windows 替代，因为它包含了安装期间所需的所有驱动程序，以及其他许多特性。

如何引导 macOS？
使用 dockur/macos 替代，因为它使用了所有正确的设置，并自动下载安装文件。

如何在没有 VirtIO 驱动程序的情况下引导？
默认情况下，机器使用 virtio-scsi 驱动器以提高性能，尽管大多数 Linux 内核都包含了这种设备所需的驱动程序，但其他操作系统可能并非如此。

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

```yaml
environment:
  DISK_TYPE: "blk"
```

提示：如果仍然无法启动，您可以将值设置为 ide 以模拟 IDE 驱动器，这种驱动器速度慢但不需要驱动程序，并且与几乎所有系统兼容。

如何更改 CPU 或 RAM 的数量？
默认情况下，容器将被允许使用最多 1 个 CPU 核心和 1 GB 的 RAM。

如果您想调整这个数量，可以使用以下环境变量指定所需的数量：

```yaml
environment:
  RAM_SIZE: "4G"
  CPU_CORES: "4"
```

如何验证我的系统是否支持 KVM？
要验证您的系统是否支持 KVM，请运行以下命令：

```bash
sudo apt install cpu-checker
sudo kvm-ok
```

如果您从 kvm-ok 收到错误，表明 KVM 加速无法使用，请检查：

- 您的 BIOS 中是否启用了虚拟化扩展（Intel VT-x 或 AMD SVM）。
- 您是否运行的是支持它们的操作系统，如 Linux 或 Windows 11（macOS 和 Windows 10 则不幸不支持）。
- 如果您在虚拟机内部运行容器，请启用“嵌套虚拟化”。
- 您是否不使用云提供商，因为它们大多数不允许其 VPS 的嵌套虚拟化。

如果没有收到 kvm-ok 的任何错误，但容器仍然抱怨 /dev/kvm 缺失，可能需要在 compose 文件中添加 privileged: true（或在运行命令中添加 --privileged），以排除任何权限问题。

如何为容器分配个别 IP 地址？
默认情况下，容器使用桥接网络，与主机共享 IP 地址。

如果您想为容器分配个别 IP 地址，可以创建一个 macvlan 网络，如下所示：

```bash
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 文件更改为如下所示：

```yaml
services:
  qemu:
    container_name: qemu
    ..<snip>..
    networks:
      vlan:
        ipv4_address: 192.168.0.100

networks:
  vlan:
    external: true
```

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

重要提示：由于 macvlan 的设计不允许两者之间的通信，这个 IP 地址将无法从 Docker 主机访问。如果这是一个问题，您需要创建第二个 macvlan 作为解决方案。

VM 如何从我的路由器获取 IP 地址？
配置容器以使用 macvlan 后，VM 可以通过从路由器请求 IP 地址，像真正的 PC 一样成为您家庭网络的一部分。

要启用此模式，请在您的 compose 文件中添加以下行：

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

注意：在这种模式下，容器和 VM 将各自拥有独立的 IP 地址。

如何添加多个磁盘？
要创建额外的磁盘，请像这样修改您的 compose 文件：

```yaml
environment:
  DISK2_SIZE: "32G"
  DISK3_SIZE: "64G"
volumes:
  - /home/example:/storage2
  - /mnt/data/example:/storage3
```

如何传递磁盘？
可以通过在 compose 文件中添加它们来直接传递磁盘设备：

```yaml
devices:
  - /dev/sdb:/disk1
  - /dev/sdc:/disk2
```

使用 /disk1 如果您希望它成为您的主驱动器，并使用 /disk2 及更高编号来添加它们作为辅助驱动器。

如何传递 USB 设备？
要传递 USB 设备，首先通过 lsusb 命令查找其供应商和产品 ID，然后在 compose 文件中像这样添加它们：

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

如何为 QEMU 提供自定义参数？
您可以创建 ARGUMENTS 环境变量，在运行时为 QEMU 提供额外的参数：

```yaml
environment:
  ARGUMENTS: "-device usb-tablet"
```

支持哪些镜像格式？
BOOT URL 接受以下任何格式的文件：

扩展名	格式
.img	Raw
.raw	Raw
.iso	Optical
.qcow2	QEMU
.vmdk	VMware
.vhd	VirtualPC
.vhdx	Hyper-V
.vdi	VirtualBox
提示：它还接受 .img.gz, .qcow2.xz, .iso.zip 等许多其他格式，因为它会自动解压缩文件。