树莓派5通过KVM虚拟机安装Home Assistant OS完整教程

之前写过一篇《树莓派5通过NVME固态硬盘安装Home Assistant》，当时是直接把 HAOS 写入固态硬盘，树莓派启动之后就只能运行 Home Assistant 了。

后来又想让这台树莓派同时运行旁路由，例如 iStoreOS，如果继续使用裸机安装的方式就不太方便了。

折腾了一圈，最终采用了下面这套方案：

这样既可以保留完整的 HAOS、Supervisor 和应用商店，又不会占用整台树莓派，后面还可以继续安装其他虚拟机。

这里完整记录一下安装过程，顺便把中间踩到的几个坑也写下来~

1. 环境说明

我这里使用的硬件和系统如下：

最终的网络结构是：

虚拟机通过网桥直接接入局域网，因此主路由会把 HAOS 当成一台单独的设备，并给它分配独立的局域网 IP。

2. 安装KVM和libvirt

首先更新软件包：

安装虚拟化组件：

启动 libvirt：

把当前用户加入 libvirt 和 kvm 用户组：

执行之后需要退出当前 SSH，再重新登录，否则用户组不会立即刷新。

重新连接后检查：

正常应该能看到：

接着检查硬件虚拟化：

我这里关键项目全部是 PASS：

再检查 QEMU 支持的加速器：

输出：

看到 kvm 就说明树莓派的硬件虚拟化已经可以正常使用了。

测试一下 libvirt：

如果显示一个空表格，没有权限报错，就是正常的：

3. 配置br0物理网桥

这一步比较关键。

如果直接使用 libvirt 默认的 NAT 网络，HAOS 会被藏在宿主机后面，不方便局域网设备发现、广播和访问。

所以这里把树莓派的有线网卡 eth0 加入 br0 网桥，让虚拟机直接接入家庭局域网。

PS：修改网桥的时候，有线网络可能会短暂断开。最好提前连接好树莓派的 Wi-Fi，或者安装 Tailscale，通过备用地址操作，避免把自己关在门外~

先查看网卡：

我这里原来的地址是：

查看有线网卡的 MAC 地址：

我这里是：

下面的配置需要把这个地址替换成你自己的。

3.1 备份Netplan配置

3.2 创建网桥配置

这里让 br0 使用了原来 eth0 的 MAC 地址，这样主路由通常还会继续分配原来的 IP。

修改配置文件权限：

如果执行 netplan generate 时提示其他 YAML 文件权限太宽，也可以统一修改：

检查语法：

没有输出就说明语法正常。

然后应用配置：

注意一定要带 sudo，否则可能会报：

3.3 检查网桥

正确结果类似：

其中 eth0 不再有自己的 IP，而是作为 br0 的物理端口。

bridge link 应该显示：

测试网络：

我这里最终的默认路由是：

因为 br0 的 metric 更小，所以优先走有线；Wi-Fi 只是备用。

3.4 br0显示NO-CARRIER的解决方法

我第一次应用配置后，出现了下面这种情况：

也就是网桥创建了，但是 eth0 仍然被旧的 NetworkManager 配置占用，没有真正加入 br0。

先查看连接：

我这里同时存在：

需要先通过 Wi-Fi 或 Tailscale 登录，然后切换连接：

再次检查：

当看到：

以及：

就说明桥接成功了。

建议重启一次，确认配置可以持久保存：

4. 创建libvirt桥接网络

宿主机的 br0 配置完成后，还需要在 libvirt 中定义一个桥接网络。

创建配置文件：

导入：

检查：

正常显示：

查看具体配置：

输出类似：

后面创建虚拟机时，网卡就使用：

5. 下载HAOS虚拟机镜像

这里要注意，虚拟机不能下载树莓派5专用的：

应该下载：

因为宿主机和虚拟机都是 ARM64，所以需要使用 Generic AArch64 QCOW2 镜像。

本文安装时使用的是：

这里的版本号以自己下载时的实际版本为准。后面命令中的 18.1 也要替换成对应版本。

官方下载地址：

由于树莓派直接从 GitHub 下载可能比较慢，我这里是在电脑上下载好，然后通过 scp 传到树莓派：

6. 解压并扩容HAOS磁盘

创建虚拟机目录：

解压镜像：

如果系统提示没有 unxz 命令，可以先安装：

移动到 libvirt 目录：

原镜像比较小，我这里把虚拟磁盘扩容到了 64GB：

设置权限：

查看镜像：

我这里显示：

说明镜像正常。

7. 创建HAOS虚拟机

执行：

几个重要参数：

表示创建 ARM64 虚拟机。

让虚拟机直接使用树莓派的 CPU 特性。

分配 4GB 内存。

让虚拟机直接接入前面创建的物理网桥。

明确关闭 Secure Boot。

Home Assistant 的 Generic AArch64 镜像需要使用 UEFI 启动，并且要关闭 Secure Boot。这里最好明确写出来，不要只使用简单的 --boot uefi。

创建完成后设置开机自动启动：

查看虚拟机：

正常显示：

查看虚拟网卡：

正常应该看到：

8. 查看HAOS控制台

进入虚拟机控制台：

如果没有马上显示内容，可以按一次回车。

退出控制台使用：

正常启动后会看到：

这里其实不用登录也可以直接使用 ha 命令。如果想进入系统 Shell，可以输入：

然后会进入：

常用命令例如：

查看虚拟机地址可以执行：

也可以进入 Shell 后执行：

我这里 HAOS 从主路由获取到的地址是：

9. 首次启动Home Assistant

浏览器访问：

或者尝试：

第一次启动时，HAOS 还需要下载并启动 Supervisor、Home Assistant Core 等组件，所以不会立刻出现初始化页面。

如果执行命令时出现：

先不要重启，通常只是系统还在初始化。

可以查看日志：

或者只看最后几十行：

如果日志里一直在拉取镜像，就继续等待。

我这里第一次初始化花的时间比较长，主要还是取决于访问 GitHub 和 GHCR 的速度。我大概等了2小时~

等网页出现创建账号的界面，就说明安装完成了~

10. 几个踩坑记录

10.1 virt-install提示必须指定osinfo

第一次创建时出现：

这是新版 virt-install 强制要求填写系统类型。

命令里添加：

即可。

如果系统里没有 linux2024，可以查看可选项：

也可以暂时使用：

10.2 启动后一直返回UEFI Boot Manager

我第一次启动时，固件能识别到：

但是按回车后又回到了 Boot Manager，无法真正启动系统。

最后发现是 UEFI 自动选择了带 Secure Boot 的固件。

重新创建虚拟机时加入：

之后就可以正常启动了。

所以这里不要只写：

最好明确关闭 Secure Boot，省得再踩一次坑。

10.3 netplan try无法测试网桥

执行：

可能提示：

这是因为 netplan try 无法自动回滚网桥的部分自定义参数。

确认 YAML 没问题后，直接执行：

即可。

10.4 br0创建了但没有网络

如果出现：

说明旧的 NetworkManager 连接还占用着 eth0。

查看连接：

然后停掉旧连接，启用：

最终必须满足：

否则虚拟机无法通过网桥正常联网。

10.5 virt-host-validate出现WARN或LXC FAIL

我这里执行 virt-host-validate 时，除了关键项目通过之外，还出现了几个提示：

这些提示不会影响当前的 HAOS 虚拟机。

只要下面几个关键项目是 PASS：

并且：

输出中包含 kvm，就可以继续安装。

LXC 部分的 FAIL 只影响 LXC 容器，不影响 QEMU/KVM 虚拟机。IOMMU 的警告则表示不适合做 PCIe 设备直通，但普通的 VirtIO 网卡、VirtIO 磁盘以及 USB 设备直通仍然可以正常使用。

10.6 HAOS能联网，但Core里面DNS解析失败

后面安装 Xiaomi Home 集成时，我还遇到过一个比较隐蔽的问题。

在 HAOS Shell 中执行 curl 可以正常访问外网，但是 Home Assistant Core 日志一直报：

进入 Core 容器测试后发现，所有域名都解析失败：

最后检查 HAOS 的有线连接配置，发现 DHCP 下发的 DNS 被忽略了：

当时显示：

也就是 ipv4.ignore-auto-dns 被设置成了 yes，但又没有手动配置 DNS。

恢复 DHCP DNS：

确认已经拿到 DNS：

我这里恢复后显示：

然后重启 HAOS 内部 DNS 和 Core：

测试 Supervisor DNS：

能够正常返回 IP 后，Core 里面的网络访问也恢复了。

这个问题和虚拟机本身没有直接关系，但如果以前手动改过 HAOS 的 DNS，后面又切回 DHCP，建议顺手检查一下 ipv4.ignore-auto-dns。

10.7 Raspberry Pi Power Supply Checker无法使用

HAOS改成运行在KVM虚拟机之后，原来的树莓派电源检测集成会提示：

这是正常现象，因为Home Assistant现在运行在QEMU/KVM提供的通用ARM虚拟硬件中，无法直接访问树莓派宿主机的固件和欠压检测接口。

这个集成可以直接删除，不会影响HAOS的其他功能。

需要检查树莓派真实供电状态时，应该在Debian宿主机执行：

正常结果为：

如果后续需要在Home Assistant中显示电源状态，可以在Debian宿主机定时读取该值，再通过MQTT发送给HAOS。

11. 常用管理命令

启动虚拟机：

正常关机：

强制关闭：

重启：

进入控制台：

查看运行状态：

查看虚拟机配置：

查看虚拟机网卡：

查看虚拟机磁盘：

启用开机启动：

取消开机启动：

查看开机启动状态：

12. 总结

OK，到这里，树莓派5上的 HAOS 虚拟机就安装完成了。

最终效果：

两者都通过 br0 接入局域网，互相独立。

相比直接把 HAOS 写入整个 NVME，这种方式稍微复杂一些，但是灵活性高了很多：

树莓派5的性能跑一个普通家庭使用的 HAOS 完全够用，剩余资源还可以继续部署一台轻量级的旁路由虚拟机。

中间最容易踩坑的地方主要有三个：

把这三个地方配置正确，后面基本就比较顺利了。

另外，如果后面遇到“HAOS宿主机能联网，但是Home Assistant Core里面解析不了域名”的情况，也要检查一下 HAOS 连接配置中的 ipv4.ignore-auto-dns。

记录一下，给准备在树莓派上使用虚拟机安装 Home Assistant OS 的朋友做个参考~