2025.3.4
首页 ▸ Installation ▸

Linux

安装 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. 启动虚拟机。
  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 Container

以下说明适用于在您自己管理的容器环境中安装 Home Assistant ContainerHome Assistant Container 是 Home Assistant Core 的独立容器化安装。任何 OCI 兼容的运行时都可以使用，但文档重点是 Docker。 [Learn more]。可以使用任何 OCI 兼容的运行时，但本指南将重点介绍使用 Docker 进行安装。

Note

此安装方法无法使用附加组件。如果您想使用附加组件，则需要使用其他安装方法。推荐的方法是 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more]。请查看安装类型概述表以了解差异。

Important

先决条件 本指南假设您已经设置了操作系统并安装了容器运行时（如 Docker）。

如果您使用 Docker，则需要至少版本 19.03.9，理想情况下使用更高版本，以及 libseccomp 2.4.2 或更新版本。Docker Desktop 无法使用，您必须使用 Docker Engine。

平台安装

使用 Docker 安装非常简单。调整以下命令，使：

  • /PATH_TO_YOUR_CONFIG 指向您要存储配置并运行它的文件夹。请确保保留 :/config 部分。

  • MY_TIME_ZONE 是 tz 数据库名称，例如 TZ=America/Los_Angeles。

  • D-Bus 是可选的，但如果您计划使用 Bluetooth 集成则是必需的。

    docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=MY_TIME_ZONE \
  -v /PATH_TO_YOUR_CONFIG:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

    # if this returns "Image is up to date" then you can stop here
docker pull ghcr.io/home-assistant/home-assistant:stable

    # stop the running container
docker stop homeassistant

    # remove it from Docker's list of containers
docker rm homeassistant

    # finally, start a new one
docker run -d \
  --name homeassistant \
  --restart=unless-stopped \
  --privileged \
  -e TZ=MY_TIME_ZONE \
  -v /PATH_TO_YOUR_CONFIG:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

    一旦 Home Assistant Container 运行，您应该可以使用 http://<host>:8123 访问 Home Assistant（将 替换为系统的主机名或 IP）。您可以继续 onboarding。

      Onboarding

    重启 Home Assistant

    如果您更改了配置，则必须重启服务器。为此，您有 3 个选项。

    1. 在 Home Assistant UI 中，转到 设置 > 系统 并点击 重启 按钮。
    2. 您可以转到 开发者工具 > 操作，选择 homeassistant.restart 并选择 执行操作。
    3. 从终端重启。
    docker restart homeassistant

    docker compose restart

    Docker compose

    Tip

    docker compose 应该已经安装在您的系统上。如果没有，您可以手动安装它。

    随着 Docker 命令变得越来越复杂，切换到 docker compose 可能更可取，并支持在失败或系统重启时自动重启。创建一个 compose.yml 文件：

      services:
    homeassistant:
      container_name: homeassistant
      image: "ghcr.io/home-assistant/home-assistant:stable"
      volumes:
        - /PATH_TO_YOUR_CONFIG:/config
        - /etc/localtime:/etc/localtime:ro
        - /run/dbus:/run/dbus:ro
      restart: unless-stopped
      privileged: true
      network_mode: host

    通过以下命令启动:

    docker compose up -d

    一旦 Home Assistant Container 运行，您应该可以使用 http://<host>:8123 访问 Home Assistant（将 替换为系统的主机名或 IP）。您可以继续 onboarding。

      Onboarding

    暴露设备

    为了使用 Zigbee 或其他需要访问设备的集成，您需要将适当的设备映射到容器中。确保运行容器的用户具有访问 /dev/tty* 文件的正确权限，然后将设备映射添加到您的容器指令中：

    docker run ... --device /dev/ttyUSB0:/dev/ttyUSB0 ...

    services:
  homeassistant:
    ...
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0

    优化

    Home Assistant Container 使用替代的内存分配库 jemalloc 来实现更好的内存管理和 Python 运行时加速。

    由于使用的 jemalloc 配置可能会在某些具有大于 4K 页面大小的硬件（如某些特定的 ARM64 架构 SoC）上导致问题，可以通过传递环境变量 DISABLE_JEMALLOC 来禁用它，例如：

    docker run ... -e "DISABLE_JEMALLOC=true" ...

    services:
  homeassistant:
  ...
    environment:
      DISABLE_JEMALLOC: true

    错误信息 <jemalloc>: Unsupported system page size 是一个已知的指示器。

    安装 Home Assistant Core

    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 界面时，可能会遇到 无法访问此网站 的错误。这种情况只会发生在第一次。后续的重启会快得多。

    安装 Home Assistant Supervised

    Caution

    这种运行 Home Assistant 的方式对您的要求最高。它也有严格的要求需要您遵守。

    除非您真的需要这种安装类型，否则您应该安装 Home Assistant OS（这也可以是虚拟机），或者Home Assistant 容器。

    1. 首先确保您理解要求。
    2. 这种安装方法有非常严格的要求，例如，它只支持 Debian（而 Ubuntu、Armbian、Raspberry Pi OS 不支持）。因此，请确保您理解上述第1步中的要求。
    3. 然后前往home-assistant/supervised-installer进行设置。

    一旦 Home Assistant SupervisedHome Assistant Supervised 是完整的 Home Assistant 生态系统，没有 Home Assistant 操作系统。 [Learn more] 安装完成并且可以访问 Home Assistant，您就可以继续 onboarding 了。

      Onboarding

    疑难解答

    无法访问前端

    症状：您无法在浏览器中打开Home Assistant页面。如果您没有使用Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more]，原因可能是访问限制。

    在较新的Linux发行版中，对主机的访问非常有限。这意味着您无法访问在主机外部运行的Home Assistant前端。

    要解决此问题，您需要为TCP流量打开机器的防火墙，允许访问8123端口。做到这一点的方法将根据您的操作系统和已安装的防火墙而有所不同。以下是一些建议，可以尝试。Google是你在这里的好帮手。

    对于UFW系统（例如，Debian）：

    sudo ufw allow 8123/tcp