linux

安装 Home Assistant 操作系统

下载适当的镜像

• VirtualBox(.vdi)
• KVM(.qcow2)

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

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

创建虚拟机

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

最低推荐分配：

• 2 GB 内存
• 32 GB 存储
• 2 个虚拟 CPU

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

虚拟机管理程序特定配置

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 name> --storagectl "SATA" --port 0 --device 0 --nonrotational on --discard on

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

启动您的虚拟机

1. 启动虚拟机。

2. 观察 Home Assistant 操作系统的启动过程。

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

安装并可以访问 Home Assistant 操作系统后，您可以继续进行初始化设置。

安装 Home Assistant 容器

以下说明适用于在您自己管理的容器环境中运行的 Home Assistant 容器安装。可以使用任何 OCI 兼容的运行时，但本指南将重点介绍使用 Docker 进行安装。

备注

此安装方法 无法使用附加组件。如果您想使用附加组件，需要使用其他安装方法。推荐的方法是 Home Assistant 操作系统。请查看 安装类型概述表 以了解差异。

提示

先决条件 本指南假设您已经设置了操作系统并安装了容器运行时（如 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 是可选的，但如果您计划使用 蓝牙集成 则是必需的。

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

一旦 Home Assistant 容器运行，您应该可以通过 http://<host>:8123（替换为系统的主机名或 IP）访问 Home Assistant。您可以继续进行初始化设置。

重启 Home Assistant

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

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

docker restart homeassistant

Docker compose

提示

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

Start it by running:

docker compose up -d

一旦 Home Assistant 容器运行，您应该可以通过 http://<host>:8123（替换为系统的主机名或 IP）访问 Home Assistant。您可以继续进行初始化设置。

暴露设备

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

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

优化

Home Assistant 容器使用替代内存分配库 jemalloc 进行更好的内存管理并加速 Python 运行时。

由于 jemalloc 配置使用的可以导致某些硬件上出现的问题，可以禁用通过传递环境变量 DISABLE_JEMALLOC 与任何值，例如：

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

错误消息 <jemalloc>: Unsupported system page size 是已知指示器。

安装 Home Assistant Core

警告

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

先决条件

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

安装依赖项

在开始之前，请确保您的系统完全更新，本指南中的所有包都使用 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 而有所不同或缺失。

创建账户

添加一个名为 homeassistant 的 Home Assistant Core 账户。由于此账户仅用于运行 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 地址）。

备注

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

安装 Home Assistant Supervised

警告

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

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

1. 首先确保您了解要求。
2. 这种安装方法有非常严格的要求，例如，它只支持 Debian（而 Ubuntu、Armbian、Raspberry Pi OS 不支持）。因此，请确保您了解上述第 1 步中的要求。
3. 然后前往 home-assistant/supervised-installer 进行设置。 一旦 Home Assistant Supervised 安装运行并且可以访问 Home Assistant，您可以继续进行初始化设置。

故障排除

无法访问前端

症状：您无法在浏览器中打开 Home Assistant 页面。如果您不使用 Home Assistant 操作系统，原因可能是访问限制。

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

要解决此问题，您需要为 TCP 流量打开机器的防火墙端口 8123。执行此操作的方法将根据您的操作系统和安装的防火墙而有所不同。以下是一些建议。Google 是您的好帮手。

对于 UFW 系统（例如 Debian）：

sudo ufw allow 8123/tcp