qemu-user-static 镜像文档

镜像概述

qemu-user-static 是一个基于 QEMU 和 binfmt_misc 的 Docker 镜像，用于在单一主机架构上运行不同架构的 Linux 容器。通过配置系统的 binfmt_misc 机制，该镜像允许主机自动识别并执行其他架构的程序，从而实现跨架构容器的无缝运行。

核心功能和特性

• 多架构支持：当前支持 amd64、arm64 和 riscv64 主机架构
• binfmt_misc 配置：通过简单命令即可配置系统，启用对其他架构程序的自动执行支持
• 便捷版本检查：提供直接查看 QEMU 版本的方式，便于验证环境配置

使用场景

• 开发者在本地开发环境中测试多架构容器应用
• CI/CD 流程中构建和运行跨架构容器镜像
• 需要在单一主机上运行不同架构 Linux 程序的场景

使用方法和配置说明

配置系统以支持多架构容器

执行以下命令配置系统，启用对多架构程序的支持（根据使用的容器工具选择对应命令）：

使用 Podman：

bash
podman run --rm --pull always --privileged docker.io/songdongsheng/qemu-user-static --reset -p yes

使用 Docker：

bash
docker run --rm --pull always --privileged songdongsheng/qemu-user-static --reset -p yes

参数说明：

• --rm：容器退出后自动删除
• --pull always：始终拉取最新版本镜像
• --privileged：需要特权模式以配置 binfmt_misc
• --reset：重置现有 binfmt_misc 配置
• -p yes：持久化配置，重启后仍生效

检查 QEMU 版本

执行以下命令检查当前使用的 QEMU 版本：

bash
podman run --rm -it --entrypoint /usr/bin/qemu-$(uname -m)-static docker.io/songdongsheng/qemu-user-static --version

示例输出：

qemu-x86_64 version 9.2.0 (Debian 1:9.2.0+ds-2)
Copyright (c) 2003-2024 Fabrice Bellard and the QEMU Project developers

说明：$(uname -m) 会自动获取当前主机架构，确保执行对应架构的 QEMU 二进制文件。