Debian LoongArch64 (loong64) 架构运行于QEMU 模拟器教程

# Debian LoongArch64 (loong64) 架构运行于 QEMU 模拟器教程

本教程旨在指导如何在常见的 Host 主机如x86_64架构的 Linux 系统上，使用 QEMU 模拟器（`qemu-system-loongarch64`）运行最新支持的 Debian LoongArch64（loong64）操作系统。

本教程结合了 [Debian Wiki Ports/loong64](https://wiki.debian.org/Ports/loong64) 的最新官方信息。

若需要快速地在Qemu模拟器上跑起来，推荐直接使用Debian提供的ISO镜像文件进行安装引导：https://cdimage.debian.org/images/ports/snapshots/2025-12-06/

---

## 一、 Debian LoongArch64 (loong64) 架构现状

根据 Debian Wiki 的官方定义与发展：
* **架构名称（DEB ARCH）**：`loong64`。
* **GNU Triplet / Multiarch 元组**：`loongarch64-linux-gnu`。
* **ABI 标准**：采用 **LP64D ABI**，兼容目前所有 LA64 核心微架构的设计模型。
* **上游工具链与内核支持**：Linux 内核自 `5.19`（2022年6月）起官方合入对 LoongArch 的支持；工具链自 `GCC 12` 起完成合并。
* **发布状态与镜像源**：目前 `loong64` 架构已被 debian-ports 接纳并持续构建（包覆盖率已超 95%），支持 `sid` (unstable) 以及正在开发中的 `trixie` (testing)。官方自 **2024年11月11日**起已开始提供正式的 `NETINST` 安装 ISO 镜像。

### 关于ABI: New World vs Old World
在开发和运行 LoongArch64 系统时，必须明确区分这两套不兼容的软件生态：
1. **旧世界（Old World, ABI 1.0）**：Loongson 早期闭源/过渡阶段的工具链，采用接近 MIPS 的风格。动态链接器路径为 `/lib64/ld.so.1`。代表系统有早期 Loongnix 20、银河麒麟、统信 UOS 早期版本等。
2. **新世界（New World, ABI 2.0 / LP64D）**：符合 Linux upstream 国际开源社区规范的标准。动态链接器路径为 `/lib64/ld-linux-loongarch-lp64d.so.1`。**Debian 官方端口（loong64）仅支持新世界生态。**

---

## 二、 准备宿主机环境 (Host Environment Setup)

在开始之前，我们需要在 Host 主机（以 Debian/Ubuntu 为例）上安装 QEMU 模拟器、用户态模拟加速工具以及制作文件系统的必需依赖包。

### 1. 安装核心软件包
在 Host 主机上打开终端，执行以下命令：
```bash
sudo apt update
sudo apt install -y \
    qemu-system-loongarch64 \
    qemu-user-static \
    binfmt-support \
    debootstrap \
    debian-ports-archive-keyring \
    parted \
    dosfstools \
    e2fsprogs
```

* **qemu-system-loongarch64**：LoongArch64 系统级硬件模拟器。
* **qemu-user-static**：用于在宿主机上透明运行 LoongArch64 用户的二进制文件（在 chroot 第二阶段编译安装时非常关键）。
* **debian-ports-archive-keyring**：用于验证 debian-ports 镜像源中的签名，因为 loong64 目前依然在 Ports 仓库中。

### 2. 获取 UEFI 固件 (EFI/BIOS)
要在 QEMU 中运行完整的虚拟机，需要 LoongArch64 的 UEFI 固件。Debian 官方提供了该固件包：
```bash
sudo apt install -y qemu-efi-loongarch64
```
安装完成后，UEFI 固件文件和变量模板存储在宿主机的如下路径：
* **固件文件**：`/usr/share/qemu-efi-loongarch64/QEMU_EFI.fd`

*(注意：若宿主机系统未包含此包，亦可直接从 Debian 仓库下载 deb 包手动解压，或通过 Fedora Koji 仓库获取 `edk2-loongarch64` 对应的固件文件)*

---

## 三、 自动化 Debian loong64 文件系统制作

为了在 QEMU 虚拟机中使用该系统，我们通常有两种方式准备根文件系统：
1. 使用官方的 NETINST ISO 镜像，通过 UEFI 启动逐步进行手动图形化/文本安装。
2. 使用 `debootstrap` 直接在宿主机快速构建一个干净的极简根文件系统（Rootfs）镜像。

下面提供一个自动化的文件系统制作脚本。脚本将创建一个 **4GB 磁盘镜像**，将其格式化为标准的单分区 `ext4`（适用于直出内核运行），自动进行两阶段 `debootstrap`，并在内部配置好基本的网络、APT源、DNS和 root 密码，最后安装最新的 `loong64` 官方内核并将其提取到宿主机目录。

### 脚本文件 `build_loong64_rootfs.sh` 
```
#!/bin/bash
# ==============================================================================
# 脚本名称：build_loong64_rootfs.sh
# 脚本功能：全自动构建适用于 QEMU 的 Debian loong64 (Sid/Unstable) 根文件系统镜像
# 作者：xiaoluoyuan@163.com
# ==============================================================================

set -x

# 配置参数
IMG_NAME="debian-loong64-rootfs.img"
IMG_SIZE="4G"
MOUNT_DIR="./debian-loong64-mount"
DEBIAN_MIRROR="http://ftp.kr.debian.org/debian-ports" # 亚洲的镜像源
# 备用官方源: "http://deb.debian.org/debian-ports"

# 检查权限
if [ "$EUID" -ne 0 ]; then
  echo "[-] 错误: 请使用 sudo 权限运行此脚本！"
  exit 1
fi

# 检查必要的宿主机工具
for cmd in qemu-img mkfs.ext4 debootstrap; do
  if ! command -v $cmd &> /dev/null; then
    echo "[-] 错误: 宿主机未检测到命令: $cmd，请先安装对应软件包。"
    exit 1
  fi
done

echo "[+] 1. 创建虚拟磁盘镜像: $IMG_NAME (大小: $IMG_SIZE)..."
#qemu-img create -f raw "$IMG_NAME" "$IMG_SIZE"

echo "[+] 2. 格式化磁盘为 ext4 文件系统..."
#mkfs.ext4 -F -L "rootfs" "$IMG_NAME"

echo "[+] 3. 挂载虚拟磁盘..."
mkdir -p "$MOUNT_DIR"
mount -o loop "$IMG_NAME" "$MOUNT_DIR"

# 注册退出清理钩子，确保脚本出错时正常卸载分区
cleanup() {
    echo "[*] 执行清理，卸载临时挂载点..."
    umount -l "$MOUNT_DIR/proc" 2>/dev/null || true
    umount -l "$MOUNT_DIR/sys" 2>/dev/null || true
    umount -l "$MOUNT_DIR/dev/pts" 2>/dev/null || true
    umount -l "$MOUNT_DIR/dev" 2>/dev/null || true
    umount -l "$MOUNT_DIR" 2>/dev/null || true
    rmdir "$MOUNT_DIR" 2>/dev/null || true
    echo "[+] 清理完毕！"
}
trap cleanup EXIT

echo "[+] 4. 开始第一阶段 debootstrap 引导系统构建..."
#debootstrap \
#    --arch=loong64 \
#    --verbose \
#    --merged-usr \
#    --foreign \
#    --include=debian-ports-archive-keyring,sudo,openssh-server,systemd-resolved \
#    unstable \
#    "$MOUNT_DIR" \
#    "$DEBIAN_MIRROR"

echo "[+] 5. 配置 QEMU 静态用户态翻译器..."
if [ -f "/usr/bin/qemu-loongarch64-static" ]; then
    cp /usr/bin/qemu-loongarch64-static "$MOUNT_DIR/usr/bin/"
elif [ -f "/usr/bin/qemu-loongarch64" ]; then
    cp /usr/bin/qemu-loongarch64 "$MOUNT_DIR/usr/bin/qemu-loongarch64-static"
else
    echo "[-] 警告: 未在宿主机发现 /usr/bin/qemu-loongarch64-static，第二阶段可能失败。"
fi

echo "[+] 6. 开始第二阶段 debootstrap (在 Chroot 环境内运行)..."
chroot "$MOUNT_DIR" /debootstrap/debootstrap --second-stage

echo "[+] 7. 写入基础配置文件 (Hostname, Fstab, Network, APT Source)..."
# 配置主机名
echo "debian-loong64" > "$MOUNT_DIR/etc/hostname"

# 配置 fstab (单分区挂载到根目录 /dev/vda)
cat <<EOF > "$MOUNT_DIR/etc/fstab"
# <file system> <mount point>   <type>  <options>       <dump>  <pass>
/dev/vda        /               ext4    defaults,errors=remount-ro 0       1
EOF

# 配置网卡 (使用 Systemd-networkd 管理)
mkdir -p "$MOUNT_DIR/etc/systemd/network"
cat <<EOF > "$MOUNT_DIR/etc/systemd/network/20-wired.network"
[Match]
Name=eth0

[Network]
DHCP=yes
EOF

# 配置默认 DNS
echo "nameserver 114.114.114.114" > "$MOUNT_DIR/etc/resolv.conf"

# 覆盖软件源配置，确保指向 debian-ports 的 unstable 和 unreleased 库
cat <<EOF > "$MOUNT_DIR/etc/apt/sources.list"
deb $DEBIAN_MIRROR unstable main unreleased
# deb-src $DEBIAN_MIRROR unstable main unreleased
EOF

echo "[+] 8. 挂载虚拟文件系统并安装 Linux 内核..."
mount -t proc /proc "$MOUNT_DIR/proc"
mount -t sysfs /sys "$MOUNT_DIR/sys"
mount -o bind /dev "$MOUNT_DIR/dev"
mount -o bind /dev/pts "$MOUNT_DIR/dev/pts"

# 更新并安装内核
chroot "$MOUNT_DIR" apt-get update
chroot "$MOUNT_DIR" apt-get install -y --no-install-recommends linux-image-loong64 locales
chroot "$MOUNT_DIR" apt-get --fix-broken install openssh-server

# 配置默认 locale
echo "en_US.UTF-8 UTF-8" > "$MOUNT_DIR/etc/locale.gen"
chroot "$MOUNT_DIR" locale-gen

# 设置默认 root 密码为 'root'
echo "[+] 9. 设置 Root 默认密码为 'root'..."
echo "root:root" | chroot "$MOUNT_DIR" chpasswd

# 启用 systemd 必要服务
chroot "$MOUNT_DIR" systemctl enable systemd-networkd
chroot "$MOUNT_DIR" systemctl enable systemd-resolved
chroot "$MOUNT_DIR" systemctl enable ssh

echo "[+] 10. 从镜像中将编译完成的内核与 initrd 拷贝至外部，用于直接引导..."
KERNEL_PATH=$(find "$MOUNT_DIR/boot" -name "vmlinuz-*" | grep -v "efi" | head -n 1)
INITRD_PATH=$(find "$MOUNT_DIR/boot" -name "initrd.img-*" | head -n 1)

if [ -n "$KERNEL_PATH" ] && [ -n "$INITRD_PATH" ]; then
    cp "$KERNEL_PATH" ./vmlinuz-loong64
    cp "$INITRD_PATH" ./initrd-loong64
    echo "[+] 成功导出内核文件: ./vmlinuz-loong64"
    echo "[+] 成功导出 Initrd 文件: ./initrd-loong64"
else
    echo "[-] 警告: 未能成功在根文件系统中找到内核镜像，请手动提取。"
fi

echo "[+] ==========================================================================="
echo "[+] 根文件系统镜像构建成功！"
echo "[+] 镜像位置: ./${IMG_NAME}"
echo "[+] 默认用户名/密码: root / root"
echo "[+] ==========================================================================="
```

### 使用方法

1. 将上述代码保存为 `build_loong64_rootfs.sh`。
2. 赋予执行权限并运行：
   ```bash
   chmod +x build_loong64_rootfs.sh
   sudo ./build_loong64_rootfs.sh
   ```

---

## 四、 虚拟机运行命令参数与运行引导

在有了文件系统 `debian-loong64-rootfs.img` 以及提前拉出的内核、固件之后，我们就可以编写运行脚本来启动虚拟机。

### 方案一：直出内核引导模式 (Direct Kernel Boot) - 推荐开发调试使用
该模式不依赖磁盘复杂的 UEFI 分区格式（如 FAT32 的 ESP 分区和引导项注册），而是利用 QEMU 模拟器的 `-kernel` 和 `-initrd` 命令行参数直接加载 Linux 引导，启动迅速且极易维护。

#### 通过直接指定 Kernel 和 Initrd 的方式运行 LoongArch64 Debian 虚拟机脚本
```bash
#!/bin/bash

qemu-system-loongarch64 \
    -m 4G \
    -smp 4 \
    -cpu la464 \
    -machine virt \
    -nographic \
    -kernel ./vmlinuz-loong64 \
    -initrd ./initrd-loong64 \
    -append "root=/dev/vda rw console=ttyS0 quiet" \
    -drive file=debian-loong64-rootfs.img,format=raw,if=virtio,id=disk0 \
    -netdev user,id=net0,hostfwd=tcp::2222-:22 \
    -device virtio-net-pci,netdev=net0
```

---

### 方案二：标准 UEFI 固件引导模式 (Full UEFI Boot)
当您需要模拟更真实的物理机启动流程（UEFI -> GRUB -> 操作系统引导）时，可以使用宿主机的 `qemu-efi-loongarch64` 固件。

> 💡 **提示**：在该模式下启动，文件系统磁盘镜像通常必须是分区的（包含一个 ESP 分区和一个 Rootfs 根分区）。如果您使用的是上文中通过脚本制作的 **无分区/平铺格式** 文件系统，需要参考标准物理机安装方式：挂载 `debian-testing-loong64-netinst.iso` 安装盘启动，并在 UEFI 下一步步完成分区。

#### 通过标准 UEFI BIOS 方式启动 LoongArch64 虚拟机脚本
```bash
#!/bin/bash

# 检查本地固件是否存在
EFI_FW="/usr/share/qemu-efi-loongarch64/QEMU_EFI.fd"
if [ ! -f "$EFI_FW" ]; then
    echo "[-] 错误: 未在系统上找到 UEFI 固件: $EFI_FW"
    echo "[*] 请确保已在宿主机上运行 'sudo apt install qemu-efi-loongarch64'"
    exit 1
fi

# 如果需要保存 UEFI NVRAM 变量，可从模板复制一份：
# cp /usr/share/qemu-efi-loongarch64/QEMU_VARS.fd ./qemu-loongarch_efivars.fd

qemu-system-loongarch64 \
    -m 4G \
    -smp 4 \
    -cpu la464 \
    -machine virt \
    -nographic \
    -bios "$EFI_FW" \
    -drive file=debian-loong64-rootfs.img,format=raw,if=virtio,id=disk0 \
    -netdev user,id=net0,hostfwd=tcp::2222-:22 \
    -device virtio-net-pci,netdev=net0
```

---

## 五、 虚拟机控制与后置登录配置

### 1. 终端交互快捷键
由于使用 `-nographic` 参数，宿主机终端直接充当了虚拟机的串口显示。
* 如果虚拟机因为某些原因意外卡死，请先按下 `Ctrl + a` 组合键，然后再按下 `x` 键。即可立即强制退出 QEMU 程序。
* 按下 `Ctrl + a`，然后按下 `c` 键可在 QEMU 实时控制器（Monitor）和虚拟机终端控制台之间切换。

### 2. 系统登录
系统正常启动到 login 提示符后，使用创建时内置的根账号进行登录：
* **Username**: `root`
* **Password**: `root`

### 3. SSH 连接到虚拟机
由于我们在启动脚本中配置了端口转发：`-netdev user,id=net0,hostfwd=tcp::2222-:22`，现在可以在宿主机的另一个终端内通过以下命令免密钥或通过密码登录虚拟机：
```bash
ssh root@localhost -p 2222
```


Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Debian LoongArch64 (loong64) 架构运行于QEMU 模拟器教程 #59

Debian LoongArch64 (loong64) 架构运行于 QEMU 模拟器教程

一、 Debian LoongArch64 (loong64) 架构现状

关于ABI: New World vs Old World

二、准备宿主机环境 (Host Environment Setup)

1. 安装核心软件包

2. 获取 UEFI 固件 (EFI/BIOS)

三、自动化 Debian loong64 文件系统制作

脚本文件 `build_loong64_rootfs.sh`

使用方法

四、虚拟机运行命令参数与运行引导

方案一：直出内核引导模式 (Direct Kernel Boot) - 推荐开发调试使用

通过直接指定 Kernel 和 Initrd 的方式运行 LoongArch64 Debian 虚拟机脚本

方案二：标准 UEFI 固件引导模式 (Full UEFI Boot)

通过标准 UEFI BIOS 方式启动 LoongArch64 虚拟机脚本

五、虚拟机控制与后置登录配置

1. 终端交互快捷键

2. 系统登录

3. SSH 连接到虚拟机

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Uh oh!

Debian LoongArch64 (loong64) 架构运行于QEMU 模拟器教程 #59

Description

Debian LoongArch64 (loong64) 架构运行于 QEMU 模拟器教程

一、 Debian LoongArch64 (loong64) 架构现状

关于ABI: New World vs Old World

二、 准备宿主机环境 (Host Environment Setup)

1. 安装核心软件包

2. 获取 UEFI 固件 (EFI/BIOS)

三、 自动化 Debian loong64 文件系统制作

脚本文件 build_loong64_rootfs.sh

使用方法

四、 虚拟机运行命令参数与运行引导

方案一：直出内核引导模式 (Direct Kernel Boot) - 推荐开发调试使用

通过直接指定 Kernel 和 Initrd 的方式运行 LoongArch64 Debian 虚拟机脚本

方案二：标准 UEFI 固件引导模式 (Full UEFI Boot)

通过标准 UEFI BIOS 方式启动 LoongArch64 虚拟机脚本

五、 虚拟机控制与后置登录配置

1. 终端交互快捷键

2. 系统登录

3. SSH 连接到虚拟机

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

二、准备宿主机环境 (Host Environment Setup)

三、自动化 Debian loong64 文件系统制作

脚本文件 `build_loong64_rootfs.sh`

四、虚拟机运行命令参数与运行引导

五、虚拟机控制与后置登录配置