跳到主要内容

第1节 安装 Home Assistant 操作系统

本节以 Windows + VMware Workstation 为例，介绍如何在虚拟机中安装 Home Assistant 操作系统（HAOS）。完成后，拥有一台运行 HAOS 的虚拟机，可通过浏览器访问其管理界面，为第 2 节的初始化做好准备。

1. 关于 Home Assistant 的安装方式​

Home Assistant 官方提供两种安装类型：

  • Home Assistant Operating System（以下简称 HAOS）：官方推荐。这是一个为 Home Assistant 定制的极简操作系统，集成了 Home Assistant 核心与应用（Apps）系统。可直接安装在树莓派、Mini PC 等硬件上，也可运行在虚拟机中。
  • Home Assistant Container：以 Docker 容器方式运行 Home Assistant 核心。需自行准备 Linux 系统和 Docker 环境，并手动处理更新。Container 安装不含应用系统，ESPHome 需作为独立 Docker 容器与 HA 容器并列运行。

本教程中的 ESPHome 以 Home Assistant 应用的形式运行，这是入门最直接的方式，因此以 HAOS 为例展开。

HAOS 可部署在树莓派、x86-64 主机或虚拟机中。本教程选用 Windows + VMware Workstation Pro 17 的虚拟机方案：无需额外硬件，备份与回滚只需复制磁盘文件。若使用 VirtualBox、Hyper-V 等平台，操作思路一致。

其他部署目标

如需直接安装在树莓派等单板机上，或通过容器/其他虚拟机平台安装，请参阅 Home Assistant 官方安装文档 并选择对应平台。

2. 下载 Home Assistant OS 镜像​

打开 Home Assistant 官网 Windows 安装页，在 DOWNLOAD THE APPROPRIATE IMAGE 一节找到 VMware Workstation (.vmdk)，点击下载。

下载得到压缩包（通常为 .zip），请解压后得到 .vmdk 文件。

Home Assistant 官网下载页面

3. 创建 Home Assistant 虚拟机​

备注

以下设置的具体名称和位置会因 VMware 版本而异，本教程基于 VMware Workstation Pro 17。

  1. 启动 VMware Workstation，选择创建新的虚拟机。

    创建新的虚拟机

  2. 选择"典型（推荐）"后，进入下一步。

    选择典型配置

  3. 选择"稍后安装操作系统"，然后选择操作系统类型为 Linux → 版本 其他 Linux 5.x 内核 64 位。

    稍后安装操作系统
    选择 Linux 类型

  4. 为虚拟机设置名称，并指定一个方便查找的存储路径，例如 E:\HA_VMware。后续替换磁盘镜像时需要回到这个目录。

    备注

    建议名称不要包含空格或中文，避免后续替换 vmdk 时文件名出现不一致问题。本教程示例使用 Home_Assistant。

    设置虚拟机名称与路径

  5. 设置虚拟磁盘大小，推荐 32 GB 以上，并选择"将虚拟磁盘存储为单个文件"。

    备注

    此处创建的空白虚拟磁盘后续会被替换为 HAOS 镜像，因此磁盘大小不会直接生效，但保持 32 GB 是为了让 VMware 在虚拟机配置层面预留足够空间。

    设置虚拟磁盘大小

4. 自定义硬件配置​

  1. 创建虚拟机完成后，点击自定义硬件。

    自定义硬件

  2. 调整硬件资源：

    • 内存：至少 2 GB，推荐 4 GB。HA 应用装得越多越吃内存。
    • 处理器：至少 2 个核心。可以适当增加核心数，以加快构建固件的速度。
    • 删除"新 CD/DVD 驱动器"条目（HAOS 镜像方式不需要光盘引导）。
    调整内存与处理器

  3. 网络适配器配置为桥接模式。

    桥接模式与 NAT 模式的差异

    两种模式都能让虚拟机联网，差异在于虚拟机在网络中的位置：

    • 桥接模式：虚拟机直接挂在物理局域网上，与主机和 ESP32 处于同一子网。可通过 homeassistant.local 访问 HA，后续 ESP32 设备的 mDNS 自动发现也能直接生效。
    • NAT 模式：虚拟机位于 VMware 自建的子网中。需要通过虚拟机的 IP 地址访问 HA（homeassistant.local 在主机网络中无法解析）。

    本教程以桥接模式为例，可直接对应后续章节的操作。若已在使用 NAT 模式，相应调整访问方式即可。

    在网络适配器选项中：

    • 选择"桥接模式：直接连接到物理网络"
    • 取消勾选"复制物理网络连接状态"
    • 点击"配置适配器"，仅勾选实际使用的物理网卡：
      • 用网线连接路由器时，勾选有线以太网卡
      • 仅有 Wi-Fi 时，勾选无线网卡
      • 取消勾选所有虚拟适配器（VMware Virtual Ethernet Adapter 等）和蓝牙 PAN 设备
    网络适配器配置为桥接

5. 替换为 Home Assistant OS 磁盘镜像​

VMware 在创建虚拟机时会自动生成一个空白虚拟磁盘文件（.vmdk）。HAOS 是一个完整的系统镜像，已经包含了引导和文件系统，因此我们需要把这个空白磁盘文件删掉，换成第 2 节下载的 HAOS 镜像，并启用 EFI 引导。

  1. 在 VMware 库中右键新建的虚拟机 → 设置 → 硬盘，记下硬盘文件的完整路径（示例：E:\HA_VMware\Home_Assistant.vmdk）。

    编辑虚拟机设置
    打开虚拟机设置
    硬盘文件路径

  2. 关闭 VMware（或至少关闭该虚拟机的设置窗口），用文件管理器打开上一步的目录，删除其中的 Home_Assistant.vmdk 文件（即 VMware 自动生成的空白磁盘）。

    备注

    该文件名与创建虚拟机时指定的名称一致。本教程示例为 Home_Assistant.vmdk，请以该目录下实际的文件名为准。

    删除空白 vmdk

  3. 将第 2 节下载的 haos_ova_X.Y.vmdk 文件复制到该目录。

    复制 HAOS vmdk

  4. 将复制进来的 haos_ova_X.Y.vmdk 重命名为上一步删除的文件完全相同的名字——本教程示例中为 Home_Assistant.vmdk。

    注意

    文件名必须与 .vmx 配置中引用的名字完全一致（含连字符 / 下划线 / 大小写），否则虚拟机启动时会报告找不到磁盘文件。

    重命名 vmdk

  5. 在同目录下找到 Home_Assistant.vmx 文件，右键以记事本打开。在文件末尾追加一行：

    firmware = "efi"
    为什么要加 EFI

    HAOS 镜像构建为 EFI 引导，VMware 默认使用 BIOS 引导。若不切换为 EFI，虚拟机启动时屏幕会停在黑屏或 Operating System not found，没有进一步错误提示。

    编辑 .vmx 添加 EFI 引导
    EFI 引导行已加入

6. 启动虚拟机​

  1. 完成上述设置后，启动虚拟机。若弹出"侧通道缓解机制"提示，点击确定即可。

    启动虚拟机

  2. 观察 HAOS 启动过程。正常情况下屏幕会显示一系列引导日志，最终停留在 homeassistant login: 提示符，此时无需登录。

  3. 在与虚拟机同网络的电脑浏览器访问：

    http://homeassistant.local:8123
    首次访问需要等待

    首次启动时，HAOS 会从 GitHub Container Registry（ghcr.io）下载 Supervisor 与 HA 核心镜像（约 700 MB）。在国内访问可能耗时 5-15 分钟甚至更长（网路情况差时可能需要数小时），浏览器页面会停留在“正在准备 Home Assistant”。这是正常现象，请耐心等待，不要重启虚拟机。

    点击“显示详细信息 (See details)”按钮，可以看到下载进度。

    VMware 虚拟机窗口
    浏览器访问 Home Assistant
    homeassistant.local 解析失败时

    如果浏览器提示"无法访问此网站"，可能是 mDNS 在当前 Windows 或路由器环境下不工作。可通过 IP 地址访问，获取 IP 的两种方式任选其一：

    • 在 VMware 虚拟机窗口的 HAOS 启动画面中，IPv4 addresses 一行直接显示虚拟机 IP（形如 192.168.x.x/24，取斜杠前的部分）。
    • 在虚拟机窗口按 Enter 进入控制台，输入 ha network info，查看 ipv4 → address 字段。

    浏览器访问 http://<该 IP>:8123 即可。

  4. 等待初始化完成，浏览器会自动跳转到 Home Assistant 欢迎页。

    Home Assistant 欢迎页

7. 本节常见问题​

  • 虚拟机启动后黑屏 / Operating System not found：未启用 EFI。返回"替换为 HAOS 磁盘镜像"的最后一步，检查 .vmx 中是否写入了 firmware = "efi"。
  • 虚拟机报"找不到磁盘文件"：检查 vmdk 文件名是否与 .vmx 中 scsi0:0.fileName 引用的名字一致（区分连字符、下划线、大小写）。
  • 桥接网络下虚拟机无 IP：在 VMware 主菜单 → 编辑 → 虚拟网络编辑器 中确认 VMnet0 已桥接到正确的物理网卡。
  • homeassistant.local 无法解析：见 6-启动虚拟机 的备用方案。
  • "正在准备 Home Assistant"卡住超过 30 分钟：可能是 ghcr.io 镜像下载失败。可在 HAOS 控制台运行 ha core logs 查看具体错误，或尝试切换网络出口。

8. 参考链接​