qemux/qemu-arm

QEMU ARM64 Docker镜像文档

镜像概述与主要用途

QEMU ARM64 Docker镜像是一个基于QEMU的容器化解决方案，用于在Docker环境中运行ARM架构的虚拟机。该镜像支持Raspberry Pi 5等多种ARM设备，可通过容器化方式快速部署和管理ARM虚拟机，简化ARM架构操作系统的运行与测试流程。

核心功能与特性

• 基于Web的控制台：通过浏览器直接控制虚拟机，无需额外客户端工具
• 多磁盘格式支持：兼容.iso、.img、.qcow2、.vhd、.vhdx、.vdi、.vmdk及.raw等主流磁盘格式
• 高性能虚拟化：集成KVM加速、内核模式网络、IO线程等优化选项，实现接近原生的运行速度

使用场景与适用范围

• 开发与测试：在x86/x64主机上模拟ARM环境，进行ARM架构应用的开发调试
• 设备模拟：模拟Raspberry Pi等ARM设备，验证系统兼容性
• 操作系统体验：快速部署和测试Alma Linux、Ubuntu、Debian等ARM发行版
• 轻量级虚拟化：通过Docker简化ARM虚拟机的生命周期管理，适用于CI/CD流程或边缘计算场景

使用方法

通过Docker Compose部署

yaml
services:
  qemu:
    container_name: qemu
    image: docker.xuanyuan.run/qemux/qemu-arm
    environment:
      BOOT: "ubuntu"  # 指定预定义操作系统或镜像URL
    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=ubuntu" \
  -p 8006:8006 \
  --device=/dev/kvm \
  --device=/dev/net/tun \
  --cap-add NET_ADMIN \
  -v "${PWD:-.}/qemu:/storage" \
  --stop-timeout 120 \  # 对应stop_grace_period
  qemux/qemu-arm

其他部署方式

• Kubernetes：

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

• GitHub Codespaces：
  https://github.com/codespaces/badge.svg]([***]

核心功能与特性详情

基于Web的控制台

通过8006端口提供Web界面，支持键盘、鼠标直接交互，无需安装额外VNC客户端，简化虚拟机控制流程。

多磁盘格式支持

支持多种虚拟磁盘格式及压缩文件（自动解压）：

高性能虚拟化优化

• KVM加速：通过/dev/kvm设备直通，利用硬件虚拟化技术提升性能
• 内核模式网络：支持TUN/TAP设备及vhost-net加速，降低网络延迟
• IO线程：通过多线程IO处理提升磁盘读写性能
• 资源弹性配置：可动态调整CPU核心数、内存大小等资源参数

详细配置说明

环境变量配置

预定义操作系统（BOOT变量取值）

卷配置

设备与权限配置

网络配置

端口映射模式（默认）

通过宿主机端口转发访问虚拟机服务，适用于简单场景：

yaml
ports:
  - 8006:8006  # Web控制台
  - 2222:22    # SSH服务（guest 22端口映射到宿主机2222）

macvlan网络模式（独立IP）

为虚拟机分配独立IP（与宿主机同网段），需先创建macvlan网络：

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
networks:
  vlan:
    external: true
services:
  qemu:
    networks:
      vlan:
        ipv4_address: 192.168.0.100  # 分配的静态IP

虚拟机独立DHCP（推荐）

使虚拟机直接从路由器获取IP（需macvlan网络）：

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

存储与磁盘配置

多磁盘配置

通过环境变量定义从磁盘大小，并挂载对应存储卷：

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

磁盘扩容

通过修改DISK_SIZE为更大值实现无损扩容（仅支持扩容，不支持缩容）：

yaml
environment:
  DISK_SIZE: "128G"  # 从64G扩容到128G

使用场景与适用范围

开发测试环境

• 模拟ARM架构服务器，测试跨平台应用兼容性
• 快速部署多版本ARM Linux发行版，验证软件运行效果

边缘计算场景

• 在x86边缘节点上运行ARM虚拟机，兼容ARM架构的物联网应用
• 利用Docker编排能力，实现ARM虚拟机的批量部署与管理

学习与实验

• 无需物理ARM设备，通过Web控制台体验ARM操作系统
• 测试磁盘直通、USB设备转发等虚拟化高级特性

常见问题

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

1. 检查软件兼容性：

2. 在Linux系统中执行以下命令检查硬件支持：

bash
sudo apt install cpu-checker
sudo kvm-ok  # 输出 "KVM acceleration can be used" 表示支持

3. 若kvm-ok报错，需检查：
   • BIOS中是否启用虚拟化扩展（Intel VT-x/AMD SVM）
   • 若运行在虚拟机中，是否启用嵌套虚拟化
   • 云服务器通常不支持KVM（需使用纯QEMU模拟，性能较低）

如何引导Windows系统？

Windows ARM版需专用驱动支持，建议使用专用镜像：https://github.com/dockur/windows-arm

如何运行x86/x64架构镜像？

本镜像仅支持ARM架构，x86/x64镜像需使用https://github.com/qemus/qemu/

如何解决启动后屏幕黑屏问题？

• 若使用VGA: "virtio-gpu"，黑屏可能是因为guest未加载驱动，需等待系统启动完成
• 换回默认帧缓冲模式（删除VGA变量）可解决兼容性问题
• 检查宿主机是否分配足够内存（建议至少2GB）