2025.3.4
首页 ▸ Installation ▸

Windows

安装 Home Assistant 操作系统

下载合适的镜像

下载后，解压镜像。如果镜像是 ZIP 文件，请解压缩。

如果您已经运行了受支持的虚拟机管理程序，请按照本指南操作。如果您不熟悉虚拟机，请直接在 Home Assistant Yellow、Raspberry Pi 或 ODROID 上安装 Home Assistant OS。

创建虚拟机

将设备镜像加载到您的虚拟机管理程序中。（注意：您可以自由分配任意数量的资源给虚拟机，请根据您的附加需求分配足够的资源）。

最低推荐配置：

  • 2 GB 内存
  • 32 GB 存储
  • 2vCPU

如果您的使用需要更多资源，所有这些都可以扩展。

虚拟机管理程序特定配置

  1. 创建一个新的虚拟机。
  2. 选择类型 Linux 和版本 Linux 2.6 / 3.x / 4.x (64 位)。
  3. 在 硬件 下，选择内存量和 CPU 数量。然后选择 启用 EFI。
    • 确保 EFI 已启用。如果 EFI 未启用，HAOS 将无法启动。
  4. 在 硬盘 下，选择 使用现有的虚拟硬盘文件，选择上面解压的 VDI 文件。
  5. 然后转到 网络 > 适配器 1。选择 桥接适配器 并选择您的网络适配器。
    请注意，桥接适配器 仅在有线以太网连接下工作。 在 VirtualBox 主机上使用 Wi-Fi 不受支持。
  6. 然后转到 音频 并选择 Intel HD Audio 作为音频控制器。

默认情况下，VirtualBox 不会 释放未使用的磁盘空间。要自动缩小 vdi 磁盘镜像，必须使用主机的终端启用 discard 选项：

VBoxManage storageattach <VM 名称> --storagectl "SATA" --port 0 --device 0 --nonrotational on --discard on

有关该命令的更多详细信息可以在这里找到。

  1. 下载上面的 .qcow2 镜像并解压。（在 Windows 中 全部解压）
  2. 将镜像存储在服务器上的 isos 共享中。
  3. 确保在 设置 > 虚拟机管理器 中启用了 启用虚拟机。
  4. 创建一个新的虚拟机：虚拟机 > 添加虚拟机。
  5. 选择类型 Linux 并为虚拟机命名和描述。
  6. 选择您希望虚拟机使用的 CPU 核心数并分配一些内存。
  7. 在 主虚拟磁盘位置 下，选择 手动 然后选择 qcow2 镜像。
  8. 在 虚拟机控制台键盘 下选择您的键盘语言。
  9. 在 网络源 下选择 br0。
  10. 在 网络模型 下选择 virtio。
  11. 选择您要传递给 Home Assistant 的任何 USB 设备，例如 Zigbee 或 Z-Wave 控制器。
  12. 取消选择 创建后启动虚拟机。
  13. 选择 创建。
  14. 选择新虚拟机的名称并选择磁盘的容量号。在这里，您可以根据需要扩展磁盘。默认值为 32 GB。
  15. 选择新虚拟机的图标并选择 使用控制台启动 (VNC)。
  1. 在 virt-manager 中创建一个新的虚拟机。
  2. 选择 导入现有磁盘镜像，提供上面 QCOW2 镜像的路径。
  3. 选择 通用默认 作为操作系统。
  4. 下载上面的 .qcow2 镜像并解压。（在 Windows 中 全部解压）
  5. 将镜像存储在服务器上的 isos 共享中。
  6. 确保在 设置 > 虚拟机管理器 中启用了 启用虚拟机。
  7. 创建一个新的虚拟机：虚拟机 > 添加虚拟机。
  8. 选择类型 Linux 并为虚拟机命名和描述。
  9. 选择您希望虚拟机使用的 CPU 核心数并分配一些内存。
  10. 在 主虚拟磁盘位置 下，选择 手动 然后选择 qcow2 镜像。
  11. 在 虚拟机控制台键盘 下选择您的键盘语言。
  12. 在 网络源 下选择 br0。
  13. 在 网络模型 下选择 virtio。
  14. 选择您要传递给 Home Assistant 的任何 USB 设备，例如 Zigbee 或 Z-Wave 控制器。
  15. 取消选择 创建后启动虚拟机。
  16. 选择 创建。
  17. 选择新虚拟机的名称并选择磁盘的容量号。在这里，您可以根据需要扩展磁盘。默认值为 32 GB。
  18. 选择新虚拟机的图标并选择 使用控制台启动 (VNC)。
  1. 在 virt-manager 中创建一个新的虚拟机。
  2. 选择 导入现有磁盘镜像，提供上面 QCOW2 镜像的路径。
  3. 选择 通用默认 作为操作系统。
  4. 勾选 在安装前自定义配置。
  5. 在 网络选择 下，选择您的网桥。
  6. 在自定义中选择 概述 > 固件 > UEFI x86_64: …。确保选择非安全启动版本的 OVMF（不包含 secure、secboot 等字样），例如 /usr/share/edk2/ovmf/OVMF_CODE.fd。
  7. 点击 添加硬件（左下角），然后选择 通道。
  8. 选择设备类型：unix。
  9. 选择名称：org.qemu.guest_agent.0。
  10. 最后，选择 开始安装（左上角）。
virt-install --name haos --description "Home Assistant OS" --os-variant=generic --ram=4096 --vcpus=2 --disk <QCOW2 文件路径>,bus=scsi --controller type=scsi,model=virtio-scsi --import --graphics none --boot uefi

如果您有 USB 适配器要连接，需要添加选项 --hostdev busID.deviceId。您可以通过 lsusb 命令发现这些 ID。例如，如果 lsusb 输出为：

   Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
   Bus 003 Device 004: ID 30c9:0052 Luxvisions Innotech Limited Integrated RGB Camera
   Bus 003 Device 003: ID 1a86:55d4 QinHeng Electronics SONOFF Zigbee 3.0 USB Dongle Plus V2
   Bus 003 Device 002: ID 06cb:00fc Synaptics, Inc. 
   Bus 003 Device 005: ID 8087:0033 Intel Corp. 
   Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
   Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
   Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

您可以在 Bus 003 Device 003 处识别 Sonoff 适配器。因此安装虚拟机的命令将变为：

virt-install --name haos --description "Home Assistant OS" --os-variant=generic --ram=4096 --vcpus=2 --disk <QCOW2 文件路径>,bus=scsi --controller type=scsi,model=virtio-scsi --import --graphics none --boot uefi --hostdev 003.003

请注意，此配置（总线 003，设备 003）只是一个示例，您的适配器可能位于其他总线和/或具有其他设备 ID。 请使用 lsusb 检查您的 USB 适配器的正确 ID。

  1. 启动 VMware Workstation 并选择 创建新的虚拟机。
    • 注意：下面设置的确切名称和位置取决于 VMware 版本。此过程基于版本 17。
  2. 选择 我稍后安装操作系统，然后选择 Linux > 其他 Linux 5.x 内核 64 位。
  3. 为虚拟机命名，home-assistant，并定义一个易于访问的存储位置，例如 C:\home-assistant。
  4. 指定磁盘大小并选择 将虚拟磁盘存储为单个文件。
  5. 选择 自定义硬件。
  6. 定义虚拟机允许使用的内存量和 CPU 核心数。
  7. 删除 新 CD/DVD 条目。它不会被使用。
  8. 连接以太网电缆并确保它已连接到您的网络。
  9. 在 网络适配器 下，选择 桥接：直接连接到物理网络。
    • 确保 复制物理网络连接状态 未被选中。
    • 选择 配置适配器。
    • 确保所有虚拟适配器和蓝牙设备都被取消选择。
    • 选择您的主机网络适配器。很可能是列表中的前 2 个复选框之一：
      • 选择用于以太网的适配器。
      • 这些适配器的确切名称取决于您的硬件。
  10. 在向导的最后，选择 完成。

编辑虚拟机设置

  1. 在 Windows 资源管理器中，导航到新创建的虚拟机的存储位置，例如在 C:\home-assistant 下。
  2. 删除 home-assistant.vmdk 文件。
  3. 在 Downloads 文件夹中，找到 haos_ova_xx.x.vmdk 文件。
    • 如果您尚未解压存档，请解压它。
    • 在文件夹内找到 .vmdk 文件并将其重命名为 home-assistant.vmdk。
    • 将文件（不是解压的文件夹）粘贴到 C:\home-assistant 文件夹中。
  4. 右键单击 .vmx 文件并选择 打开方式 > 记事本。
  5. 在 .encoding 下，添加一行。输入 firmware = "efi"。
  6. 现在继续下一步以启动您的虚拟机。
    • 如果您看到有关侧信道缓解措施的消息，请选择 确定。
    • 如果您看到 .vmdk 文件未找到的消息，在第 3 步中，您可能粘贴了文件夹而不是文件。请重复第 3 步。

⚠️ Hyper-V 不支持 USB

  1. 创建一个新的虚拟机。
  2. 选择 第 2 代。
  3. 选择 连接 > 您的桥接虚拟交换机。
  4. 选择 使用现有虚拟硬盘 并选择上面的 VHDX 文件。

创建后，转到 设置 > 安全 并取消选择 启用安全启动。

启动您的虚拟机

  1. 启动虚拟机。
  2. 观察 Home Assistant 操作系统的启动过程。
  3. 完成后，您将能够在 homeassistant.local:8123 访问 Home Assistant。如果您运行的是较旧的 Windows 版本或具有更严格的网络配置，您可能需要通过 homeassistant:8123 或 http://X.X.X.X:8123（将 X.X.X.X 替换为您的虚拟机的 IP 地址）访问 Home Assistant。

帮助我们改进 Home Assistant

您刚刚安装了 Home Assistant 吗？Home Assistant 团队希望与您交流，了解安装过程的情况。

立即帮助

安装并可以访问 Home Assistant 操作系统后，您可以继续完成入门设置。

  Onboarding

安装 Home Assistant Core

安装 WSL

要在 Windows 上安装 Home Assistant CoreHome Assistant Core 是 Home Assistant 本身的核心。它是一个 Python 程序，支持每种安装类型，但可以独立安装。 [Learn more]，您需要使用 Windows Subsystem for Linux (WSL)。请按照 WSL 安装说明 并从 Windows 商店安装 Ubuntu。

作为替代方案，可以在 Linux 虚拟机中安装 Home Assistant OS。不支持直接在 Windows 上运行 Home Assistant CoreHome Assistant Core 是 Home Assistant 本身的核心。它是一个 Python 程序，支持每种安装类型，但可以独立安装。 [Learn more]。

Caution

这是一个高级安装过程，某些步骤可能因系统而异。考虑到这种安装类型的性质，我们假设您可以处理本文档与您使用的系统配置之间的细微差异。如有疑问，请考虑使用 其他安装方法，因为它们可能更适合您。

先决条件

本指南假设您已经设置好操作系统并安装了 Python 3.13（包括 python3-dev 包）或更新版本。

安装依赖项

在开始之前，请确保您的系统已完全更新，本指南中的所有软件包都使用 apt 安装，如果您的操作系统没有 apt，请寻找替代方案。

sudo apt-get update
sudo apt-get upgrade -y

安装依赖:

sudo apt-get install -y python3 python3-dev python3-venv python3-pip bluez libffi-dev libssl-dev libjpeg-dev zlib1g-dev autoconf build-essential libopenjp2-7 libtiff6 libturbojpeg0-dev tzdata ffmpeg liblapack3 liblapack-dev libatlas-base-dev

上述列出的依赖项可能会有所不同或缺失，具体取决于您的系统或个人使用 Home Assistant 的情况。

创建账户

为 Home Assistant Core 添加一个名为 homeassistant 的账户。 由于此账户仅用于运行 Home Assistant Core，因此添加了额外的参数 -rm 来创建一个系统账户并创建主目录。

sudo useradd -rm homeassistant

创建虚拟环境

首先，我们将为 Home Assistant Core 的安装创建一个目录，并将所有者更改为 homeassistant 账户。

sudo mkdir /srv/homeassistant
sudo chown homeassistant:homeassistant /srv/homeassistant

接下来是为 Home Assistant Core 创建并切换到虚拟环境。这将使用 homeassistant 账户来完成。

sudo -u homeassistant -H -s
cd /srv/homeassistant
python3 -m venv .
source bin/activate

激活虚拟环境后（注意提示符会变为 (homeassistant) homeassistant@raspberrypi:/srv/homeassistant $），您需要运行以下命令来安装所需的 Python 包。

python3 -m pip install wheel

安装完所需的 Python 包后，现在可以安装 Home Assistant Core 了！

pip3 install homeassistant==2025.3.4

故障排除：如果您在环境中没有看到上述版本的 Home Assistant 包，请确保您已安装正确的 Python 版本，如先决条件中所述。

首次启动 Home Assistant Core。这将为您完成安装，自动在 /home/homeassistant 目录中创建 .homeassistant 配置目录，并安装任何基本依赖项。

hass

您现在可以通过 Web 界面访问您的安装，地址为 http://homeassistant.local:8123。

如果此地址无法访问，您也可以尝试 http://localhost:8123 或 http://X.X.X.X:8123（将 X.X.X.X 替换为您机器的 IP 地址）。

Note

当您第一次运行 hass 命令时，它将下载、安装并缓存必要的库/依赖项。此过程可能需要 5 到 10 分钟。在此期间，当您访问 Web 界面时，可能会遇到 无法访问此网站 的错误。这种情况只会发生在第一次。后续的重启会快得多。