通用 x86-64

安装 Home Assistant 操作系统

如果您想轻松开始使用 Home Assistant 或者几乎没有 Linux 经验，请遵循本指南。

在您的 x86-64 硬件上配置 BIOS

要启动 Home Assistant OS，BIOS 需要启用 UEFI 启动模式并禁用安全启动。以下截图来自第 7 代 Intel NUC 系统。BIOS 菜单在您的系统上可能看起来不同。但是，选项应该仍然存在并且名称相似。

1. 要进入 BIOS，启动您的 x86-64 硬件并重复按 F2 键（在某些系统上可能是 Del、F1 或 F10）。

2. 确保启用 UEFI 启动模式。

3. 禁用安全启动。

4. 保存更改并退出。

BIOS 配置现已完成。

将 HAOS 写入您的 x86-64 硬件

接下来，您需要将 Home Assistant 操作系统映像写入 启动介质，这是您的 x86-64 硬件在运行 Home Assistant 时将从中启动的介质。

通常，使用内部介质如 S-ATA 硬盘、S-ATA SSD、M.2 SSD 或不可移动的 eMMC 作为 x86-64 启动介质。或者，可以使用外部介质如 USB SSD，但不推荐。

要在您的 x86-64 硬件上写入 HAOS 映像，有两种不同的方法：

方法 1（推荐）：从 USB 闪存驱动器启动 Ubuntu 并从那里安装 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more]。它也适用于带有内部硬盘的笔记本电脑和 PC。

方法 2：使用此方法，您可以直接从您的常规计算机将 Home Assistant 操作系统磁盘映像写入启动介质。步骤稍微复杂一些。如果您有不可移动的内部介质（例如因为您使用的是笔记本电脑）或没有必要的适配器（例如 USB 到 S-ATA 适配器），请改用方法 1。

方法 1：通过从 USB 闪存驱动器启动 Ubuntu 安装 HAOS

所需材料

• 计算机
• 目标 x86-64 硬件，您想在其上安装 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] (HAOS)
• USB 闪存驱动器（USB 拇指驱动器即可，大小至少为 4 GB）
• 互联网连接

通过从 USB 闪存驱动器启动 Ubuntu 安装 HAOS

1. 注意：此过程将把 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] 写入您的设备。
   • 这意味着您将丢失所有数据以及之前安装的操作系统。
   • 在执行此过程之前备份您的数据。
2. 在 USB 闪存驱动器上创建 实时操作系统：
   • 按照 Ubuntu 桌面说明 将 Ubuntu Desktop iso 文件写入 USB 设备。
3. 将 USB 闪存驱动器插入您想运行 Home Assistant 的系统。
   • 启动实时操作系统。
   • 您可能需要调整启动顺序或使用 F10（根据 BIOS 的不同，可能是不同的 F 键）选择 USB 闪存驱动器作为启动设备。
4. 当提示时，确保选择 试用 Ubuntu。这将在 USB 闪存设备上运行 Ubuntu。
   • 系统随后将启动 Ubuntu。
   • 将您的系统连接到网络并确保它可以访问互联网。
5. 在 Ubuntu 中，打开浏览器并打开当前文档页面，以便您可以按照步骤操作。
   • 从那里，下载映像。

• 计算机
• 目标 x86-64 硬件，您想在其上安装 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] (HAOS)
• USB 闪存驱动器（USB 拇指驱动器即可，大小至少为 4 GB）
• 互联网连接

通过从 USB 闪存驱动器启动 Ubuntu 安装 HAOS

1. 注意：此过程将把 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] 写入您的设备。
   • 这意味着您将丢失所有数据以及之前安装的操作系统。
   • 在执行此过程之前备份您的数据。
2. 在 USB 闪存驱动器上创建 实时操作系统：
   • 按照 Ubuntu 桌面说明 将 Ubuntu Desktop iso 文件写入 USB 设备。
3. 将 USB 闪存驱动器插入您想运行 Home Assistant 的系统。
   • 启动实时操作系统。
   • 您可能需要调整启动顺序或使用 F10（根据 BIOS 的不同，可能是不同的 F 键）选择 USB 闪存驱动器作为启动设备。
4. 当提示时，确保选择 试用 Ubuntu。这将在 USB 闪存设备上运行 Ubuntu。
   • 系统随后将启动 Ubuntu。
   • 将您的系统连接到网络并确保它可以访问互联网。
5. 在 Ubuntu 中，打开浏览器并打开当前文档页面，以便您可以按照步骤操作。
   • 从那里，下载映像。
6. 在 Ubuntu 中，在左下角选择 显示应用程序。
7. 在应用程序中，搜索并打开 磁盘 并开始恢复 HAOS 映像：
   1. 在 磁盘 中，在左侧选择您要安装 HAOS 的内部磁盘设备。
   2. 在屏幕顶部，选择三个点 菜单并选择 恢复磁盘映像…。
   3. 选择您刚刚下载的映像。
   4. 选择 开始恢复…。
   5. 通过选择 恢复 进行确认。
      • 如果您收到 卸载文件系统错误 错误消息，提示 目标正忙：
      • 很可能您正在内部磁盘上运行 Ubuntu。相反，您需要在 U 盘上运行它。
        • 返回步骤 3 并在启动时确保选择 试用 Ubuntu（而不是 安装 Ubuntu）。
   6. 在分区概览中，您现在应该看到恢复操作正在进行中。
      • Home Assistant 操作系统现在正在您的系统上安装。
8. 一旦 Home Assistant 操作系统安装完成，关闭系统。
   • 一旦 Ubuntu 关闭，移除 USB 闪存驱动器（Ubuntu 会通知您何时可以移除）。
   • 您的 Home Assistant 服务器现已设置完成，您可以开始使用它。
   • 要使用它，请按照 启动您的通用 x86-64 中的说明进行操作。

方法 2：直接从启动介质安装 HAOS

所需材料

• 计算机
• 目标 x86-64 硬件，您想在其上安装 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] (HAOS)
• 启动介质
• 互联网连接

将映像写入您的启动介质

1. 注意：此过程将把 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] 写入您的设备。

   • 这意味着您将丢失所有数据以及之前安装的操作系统。
   • 在执行下一步之前备份您的数据。

2. 将 Home Assistant 启动介质（storage device）连接到您的计算机。

3. 下载并启动 Balena Etcher。在 Windows 上，您可能需要以管理员权限运行它。

4. 将映像下载到您的计算机。

   • 复制映像的 URL。
   • 如果下面有多个链接，请确保选择适合您 Generic x86-64 版本的正确链接。

https://github.com/home-assistant/operating-system/releases/download//haos_generic-x86-64-.img.xz

选择并复制 URL 或使用悬停时出现的“复制”按钮。

5. 将 URL 粘贴到浏览器中开始下载。
6. 解压刚刚下载的文件。
7. 选择 从文件刷写 并选择刚刚解压的镜像。
   • 不要使用 从 URL 刷写。在某些系统上无法正常工作。

8. 选择目标。 9. 选择要用于安装的启动介质 (storage device)。 10. 选择 刷写！ 开始写入镜像。

• 如果操作失败，请解压 .xz 文件并重试。
• 当 Balena Etcher 完成镜像写入后，您将看到确认信息。

启动您的 Generic x86-64

• 如果您使用第一种方法安装，请确保从系统中移除 USB 闪存驱动器。

• 如果您使用第二种方法安装，请将启动介质安装到您的 x86-64 硬件中。

1. 插入连接到网络和互联网的以太网电缆。
   • 注意：需要互联网连接，因为新安装的 Home Assistant OS 尚未包含所有 Home Assistant 组件。它会在首次启动时下载最新版本的 Home Assistant Core。
2. 启动系统。如果您的 Generic x86-64 系统连接了屏幕，大约一分钟后，控制台将显示 Home Assistant 欢迎横幅。

efibootmgr --create --disk /dev/<drivename> --part 1 --label "HAOS" \
   --loader '\EFI\BOOT\bootx64.efi'

\EFI\BOOT\bootx64.efi

3. 在桌面系统的浏览器中，几分钟后您就可以通过 homeassistant.local:8123 访问您的新 Home Assistant。

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

安装 Home Assistant Container

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

平台安装

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

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

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

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

  Install

  Update

  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 CLI

  Docker Compose

  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 CLI

  Docker Compose

  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 CLI

  Docker Compose

  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 来创建一个系统账户并创建主目录。 参数 -G dialout,gpio,i2c 将用户添加到 dialout、gpio 和 i2c 组。第一个组是使用 Z-Wave 和 Zigbee 控制器所必需的，而第二个组是与 GPIO 通信所必需的。

  sudo useradd -rm homeassistant -G dialout,gpio,i2c
  

  创建虚拟环境

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

  帮助我们改进翻译

  建议编辑此页面，或提供/查看此页面的反馈。

  编辑 提供反馈 查看已提交的反馈