跳到主要内容

alternative

安装 Home Assistant 操作系统​

下载合适的镜像​

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

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

创建虚拟机​

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

建议最小配置：

  • 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（将 X.X.X.X 替换为虚拟机的 IP 地址）访问 Home Assistant。

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

安装 Home Assistant 容器版（Container）​

Synology NAS​

现在，Synology 通过 Container Manager 包支持容器管理，允许您无需命令行即可安装 Home Assistant。有关该包的详细信息（包括兼容性信息，如果您的 NAS 受支持），请参阅 https://www.synology.com/en-us/dsm/packages/ContainerManager。步骤如下：

  • 在 Synology NAS 上安装 Docker "Container Manager" 包

  • 启动 Container Manager 应用并转到 "Registry" 部分

  • 在注册表中找到 "homeassistant/home-assistant" 并点击 "Download"。选择 "stable" 标签。

  • 等待一段时间，直到您的 NAS 拉取完镜像

  • 转到 Container Manager 应用的 "Image" 部分

  • 点击 "Launch"

  • 在 "Network" 中选择 "Use same network as Docker Host" 并点击 Next

  • 选择您想要的容器名称（例如，"homeassistant"）

  • 如果需要，设置 "Enable auto-restart"

  • 点击 "Advanced Settings"。为确保 Home Assistant 显示正确的时区，转到 "Environment" 标签并点击加号，然后添加 variable = TZ 和 value = Asia/Shanghai，选择您的正确时区。点击 Save 退出 Advanced Settings。

  • 点击 Next

  • 在 "Volume Settings" 中点击 "Add Folder"，选择现有文件夹或添加新文件夹（例如，在 "docker" 共享文件夹中，添加名为 "homeassistant" 的新文件夹，然后在该新文件夹中添加另一个名为 "config" 的新文件夹），然后点击 Select。然后将 "mount path" 编辑为 "/config"。这配置了 Home Assistant 存储配置和日志的位置。

  • 确保选中 "Run this container after the wizard is finished" 并点击 Done

  • 您的 Docker 中的 Home Assistant 现在应该运行，并将从 Docker 主机的 8123 端口提供 Web 界面（这将是您的 Synology NAS IP 地址 - 例如 http://192.168.1.10:8123）

如果使用内置防火墙，您还必须将端口 8123 添加到允许列表中。这可以在 "Control Panel -> Security" 中找到，然后在 Firewall 标签中。点击 Firewall Profile 下拉框旁边的 "Edit Rules"。创建新规则并选择 "Custom" 作为 Ports 并添加 8123。根据需要编辑 Source IP 或保留默认的 "All"。Action 应保持为 "Allow"。

要使用 Z-Wave USB 设备进行 Z-Wave 控制，HA Docker 容器需要额外配置才能访问 USB 设备。虽然有多种方法可以做到这一点，但在撰写本文时，授予访问权限的最低权限方式只能通过终端执行。请参阅此页面以配置对 Synology NAS 的终端访问：

https://www.synology.com/en-global/knowledgebase/DSM/help/DSM/AdminCenter/system_terminal

提示

请参阅此页面了解如何通过 SSH 访问终端

按如下方式调整以下终端命令：

  • 将 /PATH_TO_YOUR_CONFIG 指向您要存储配置的文件夹 - 确保保留 :/config 部分

  • 将 /PATH_TO_YOUR_USB_STICK 替换为您的 USB 设备的路径（例如，对于大多数 Synology 用户为 /dev/ttyACM0）

  • 将 "Australia/Melbourne" 替换为您的时区。

在终端中运行它。

sudo docker run --restart always -d --name homeassistant -v /PATH_TO_YOUR_CONFIG:/config --device=/PATH_TO_YOUR_USB_STICK -e TZ=Asia/Shanghai --net=host ghcr.io/home-assistant/home-assistant:stable

通过按照此处的说明完成 Z-Wave 配置的其余部分。

注意：要在 Synology NAS 上的 Docker 中更新 Home Assistant，您只需执行以下操作：

  • 转到 "Container Manager" 应用并转到 "Image" 部分
  • 在 Image 中找到 "homeassistant/home-assistant" 并点击 "Update"。
  • 等待系统消息/通知出现，表示下载已完成（没有进度条）
  • 转到 "Container" 部分
  • 如果容器正在运行，请停止它
  • 右键点击它并选择 "Action"->"Reset"。您不会丢失任何数据，因为所有文件都存储在您的配置目录中
  • 再次启动容器 - 它将使用新的 Home Assistant 镜像启动

注意：要在 Synology NAS 上重启 Home Assistant，您只需执行以下操作：

  • 转到 "Container Manager" 应用并转到 "Container" 部分
  • 右键点击它并选择 "Action"->"Restart"。
备注

如果您想在 Synology Docker 上的 Home Assistant 中使用 USB 蓝牙适配器或 Z-Wave USB 设备，这些说明不会正确配置容器以访问 USB 设备。要在 Synology Docker Home Assistant 上配置这些设备，您可以按照 Phil Hawthorne 提供的此处的说明进行操作。

QNAP NAS​

QNAP 的 QTS 支持 Docker，允许您无需命令行即可使用 Docker 安装 Home Assistant。有关该包的详细信息（包括兼容性信息，如果您的 NAS 受支持），请参阅 https://www.qnap.com/solution/container_station/en/index.php

步骤如下：

  • 在 Qnap NAS 上安装 "Container Station" 包
  • 启动 Container Station 并转到 "Create Container" 部分
  • 使用 Docker Hub 搜索镜像 "homeassistant/home-assistant" 并点击 "Install"。注意您 NAS 的 CPU 架构。对于 ARM CPU 类型，正确的镜像是 "homeassistant/armhf-homeassistant"
  • 选择 "stable" 版本并点击下一步
  • 选择您想要的容器名称（例如，"homeassistant"）
  • 点击 "Advanced Settings"
  • 在 "Shared Folders" 中点击 "Volume from host" > "Add"，选择现有文件夹或添加新文件夹。挂载点必须是 /config，这样 Home Assistant 将使用它来存储配置和日志。
  • 在 "Network" 中选择 Network Mode 为 "Host"
  • 为确保 Home Assistant 显示正确的时区，转到 "Environment" 标签并点击加号，然后添加 variable = TZ 和 value = Asia/Shanghai，选择您的正确时区
  • 点击 "Create"
  • 等待一段时间，直到您的 NAS 创建完容器
  • 您的 Docker 中的 Home Assistant 现在应该运行，并将从 Docker 主机的 8123 端口提供 Web 界面（这将是您的 Qnap NAS IP 地址 - 例如 http://192.xxx.xxx.xxx:8123

注意：要在 Qnap NAS 上的 Docker 中更新 Home Assistant，您只需删除容器和镜像，然后重新执行步骤（不要删除 "config" 文件夹）。

社区说明​

请注意，一些用户报告在 ARM QNAP 系统（例如 TS-233）上使用 Container Station 3 创建 Home Assistant 容器时遇到问题。一个可能的解决方法是基于 YAML 文件的 "Docker compose" 方法（请参阅 "Docker compose" 部分）。在 QNAP Container Station 3 UI 中，可以通过转到 "Applications" 部分并点击 "Create" 来访问此功能。然后会提示您输入 YAML 代码，可以从 "Docker compose" 部分显示的代码中复制。请注意以两种方式修改此代码：首先，添加第一行 "version: '3'"；其次，将文本 "/PATH_TO_YOUR_CONFIG" 替换为您 NAS 系统上的有效路径，例如 "/share/Container/HomeAssistant/config"。

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

开始运行：

docker compose up -d

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

Exposing devices​

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

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

Optimizations​

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

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

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

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

Community provided guides​

更多安装指南可以在我们的社区论坛上找到。

这些社区指南按原样提供。其中一些安装方法比上述方法更有限。由于平台的限制，某些集成可能无法工作。