替代方案

安装 Home Assistant 操作系统

下载合适的镜像

• VirtualBox (.vdi)

• KVM/Proxmox (.qcow2)

• VMware ESXi/vSphere (.ova)

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

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

创建虚拟机

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

最低推荐配置：

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

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

虚拟机管理程序特定配置

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

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

   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

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

启动您的虚拟机

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 的 DSM 现在通过 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 = Europe/London，选择您的正确时区。点击 Save 退出高级设置。
• 点击 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 添加到允许列表中。这可以在 “控制面板 -> 安全” 中找到，然后转到防火墙选项卡。点击防火墙配置文件下拉框旁边的 “编辑规则”。创建新规则并选择 “自定义” 端口并添加 8123。如果需要，可以编辑源 IP 或保留默认的 “全部”。操作应保持为 “允许”。

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

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

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

• 将 /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=Australia/Melbourne --net=host ghcr.io/home-assistant/home-assistant:stable

完成 Z-Wave 的剩余配置，请按照此处的说明操作

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

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

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

• 打开 “Container Manager” 应用并转到 “Container” 部分
• 右键点击容器并选择 “Action”->“Restart”

QNAP NAS

QNAP 的 QTS 系统支持 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”，选择现有文件夹或添加新文件夹。“mount point” 必须为 /config，以便 Home Assistant 将其用于配置和日志
• 在 “Network” 中选择 Network Mode 为 “Host”
• 为确保 Home Assistant 显示正确的时区，请转到 “Environment” 选项卡，点击加号，然后添加 variable = TZ 和 value = Europe/London，选择您的正确时区
• 点击 “Create”
• 等待一段时间，直到 NAS 创建完容器
• 您的 Docker 中的 Home Assistant 现在应该运行，并将从 Docker 主机的 8123 端口提供 Web 界面（这将是您的 Qnap NAS IP 地址 - 例如 http://192.xxx.xxx.xxx:8123）

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

社区笔记

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

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

重启 Home Assistant

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

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

docker restart homeassistant

docker compose restart

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。

暴露设备

为了使用 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 是一个已知的指示器。

社区提供的指南

其他安装指南可以在我们的 社区论坛 找到。

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