Home Assistant в Proxmox: установка HAOS без скриптов и проброс Zigbee

Вы импортировали образ Home Assistant, нажали Start — и получили UEFI Shell вместо умного дома. Или всё заработало, но после перезагрузки исчез Zigbee-адаптер. Обе проблемы часто связаны с настройками VM, а не с Home Assistant.

Ниже — ручная установка Home Assistant OS в виртуальную машину Proxmox VE на x86-64. Она подходит, если Proxmox уже установлен и вы можете открыть консоль хоста. Мы не будем запускать сторонний скрипт с правами root: параметры останутся видны в интерфейсе.

Что выбрать: HAOS или Home Assistant Container

HAOS включает управляемую ОС, Supervisor и установку приложений через интерфейс Home Assistant. Home Assistant Container предполагает, что Docker, соседние службы и обновления ОС вы обслуживаете самостоятельно. Контейнер внутри LXC добавляет ещё один слой настройки устройств и прав.

Для VM с обычным домашним набором интеграций начните с 2 vCPU, 4 ГБ RAM и диска 32–64 ГБ на SSD. Это пример, а не обещание вместить сюда видеоархив и распознавание речи. Официальный минимум для виртуальной установки — 2 vCPU и 2 ГБ RAM; образ берите в разделе KVM/Proxmox на сайте Home Assistant.

Если у вас ARM-плата, этот x86-образ не подойдёт. Для другого сценария есть отдельный материал о Home Assistant Container на Orange Pi Zero 3; команды создания VM из этой статьи к нему не относятся.

1. Подготовьте образ и свободный VMID

Скачайте QCOW2-образ по официальной ссылке и распакуйте архив. На вход импорту нужен файл .qcow2, а не .xz. Передайте его на Proxmox по SFTP/SCP в каталог с достаточным свободным местом.

В примере используем VMID 120 и хранилище local-lvm. Проверьте, что номер свободен, а хранилище существует и поддерживает диски VM. Если у вас ZFS или Directory storage, его имя будет другим.

Сначала полезно посмотреть состояние хоста:

qm list
pvesm status

Не удаляйте существующую VM ради совпадения с номером из инструкции.

2. Создайте пустую виртуальную машину

В мастере Create VM задайте имя homeassistant и свободный номер. Выберите установку без ISO. Для этой схемы используем:

• Machine: q35;
• BIOS: OVMF (UEFI);
• EFI Disk: на выбранном хранилище;
• Pre-Enroll keys: выключено для этой HAOS VM;
• SCSI Controller: VirtIO SCSI single;
• Network: VirtIO на bridge, подключённом к домашней LAN, часто vmbr0.

Home Assistant OS требует UEFI. Настройка EFI относится к гостевой VM: менять Secure Boot физического сервера ради неё не нужно. Устройство виртуальных дисков, OVMF и USB-проброс описаны в руководстве Proxmox VE.

На шаге диска не создавайте новый диск, если мастер позволяет. Если он уже создан, удалять его можно только после проверки, что это пустой диск новой VM. EFI Disk оставьте: он хранит параметры прошивки и не заменяет системный диск HAOS.

3. Импортируйте QCOW2 и подключите его

Откройте Shell самого узла Proxmox. Подставьте полный путь к распакованному файлу:

qm disk import 120 /root/haos_ova.qcow2 local-lvm

Название haos_ova.qcow2 здесь условное: у скачанного образа обычно есть номер версии. Используйте фактическое имя файла. В старых инструкциях встречается команда qm importdisk — проверьте доступный синтаксис вашей версии через справку qm.

После окончания импорта откройте Hardware у VM. Там должен появиться Unused Disk. Выберите его, нажмите Edit и подключите как SCSI0. Не запускайте повторный импорт только потому, что диск ещё не появился в Boot Order: импорт и подключение — два разных действия.

В Options → Boot Order включите и поставьте первым SCSI0 с образом HAOS. EFI Disk первым загрузочным диском ставить не надо. Затем запустите VM и откройте Console.

4. Найдите адрес и завершите первый запуск

Посмотрите IP в консоли HAOS или списке DHCP-клиентов роутера. Откройте http://IP-АДРЕС:8123. Имя homeassistant.local удобно, но зависит от mDNS и не обязано работать через VLAN или удалённое подключение.

Первый запуск может потребовать загрузки компонентов. Пока консоль показывает подготовку, смотрите её сообщения, а не перезапускайте VM каждые полминуты. Проверьте доступ к DNS и интернету, если загрузка явно остановилась.

Закрепите DHCP-адрес за MAC виртуального сетевого адаптера. Затем включите Start at boot в Proxmox. Если MQTT и другие зависимости находятся в соседних VM, предусмотрите их порядок запуска.

5. Пробросьте Zigbee-координатор

Остановите новую VM, откройте Hardware → Add → USB Device и выберите физический адаптер. При одном экземпляре удобно сопоставление по Vendor/Device ID. Если подключены два одинаковых устройства, эти идентификаторы совпадут: используйте привязку к физическому порту и подпишите разъёмы.

После старта убедитесь, что адаптер виден в Home Assistant. Для интеграции используйте стабильный путь /dev/serial/by-id/…, когда он доступен, вместо случайного /dev/ttyUSB0. Один координатор должен обслуживаться одним процессом: не отдавайте его одновременно ZHA и Zigbee2MQTT.

Выбор стека вынесен в сравнение ZHA и Zigbee2MQTT. Если у вас Sonoff, отдельно проверьте модель и тип радиочипа по руководству для Sonoff USB Dongle Plus.

USB-удлинитель позволяет отнести радио от корпуса сервера и источников помех. После настройки проверьте отдельно перезапуск HAOS и полную перезагрузку Proxmox. Миграция VM на другой узел не переносит подключённый USB-адаптер физически.

Что проверять при ошибках

UEFI Shell: импортированный диск подключён? SCSI0 включён в Boot Order? Выбрана OVMF? Образ распакован и предназначен для x86-64 KVM? EFI Disk и системный диск не перепутаны?

Нет IP: сетевой адаптер подключён к правильному bridge? На нём есть физический интерфейс LAN? Работает DHCP? Для начала используйте простую LAN без дополнительного VLAN-тега.

Адрес есть, интерфейс не открывается: посмотрите состояние HAOS в консоли, попробуйте прямой IP и проверьте правила между клиентом и VM.

Zigbee исчез после reboot: проверьте наличие устройства на хосте, правило USB-проброса и путь внутри гостя. Если устройство есть, но порт занят, ищите второй процесс, который пытается открыть координатор.

Если после установки вы подключаете устройства нового стандарта, используйте диагностику Matter и Thread в Home Assistant: USB-проброс Zigbee и доступность Matter по IPv6 проверяются отдельно.

Перед переносом рабочего дома

Сделайте встроенную резервную копию Home Assistant и скачайте её на другой компьютер. Отдельно сохраните ключ шифрования, если он используется. Затем создайте backup всей VM на хранилище вне её системного диска. Пошаговый следующий этап — подключение Proxmox Backup Server и пробное восстановление VM.

При восстановлении старой конфигурации не запускайте две одинаковые системы в рабочей сети одновременно: автоматизации могут отработать дважды. Тестовую копию сначала загружайте с отключённой сетью и без радиокоординатора.

Установка завершена, когда HAOS загружается после перезапуска хоста, сохраняет адрес, видит координатор и у вас есть копия, которую можно восстановить. Только после этого переносите повседневные автоматизации.