Установка HACS в Home Assistant на Supervised и Docker

HACS (Home Assistant Community Store) — это сообщественный магазин для Home Assistant. Эта инструкция показывает, как установить HACS на Supervised Home Assistant (HASS OS) и на не-Supervised установку в Docker на Linux. Приведены пошаговые команды, чек-листы, план отката и распространённые ошибки с решениями.

Что такое HACS в одну строку

HACS — это плагин-менеджер для Home Assistant, позволяющий легко находить, устанавливать и обновлять кастомные интеграции, темы и frontend-карты.

Содержание

• Установка на Supervised Home Assistant (HASS OS / Linux)
• Установка на не-Supervised Home Assistant (Docker на Linux)
• Как устанавливать интеграции и темы через HACS
• Чек-листы и SOP
• Отладка и типичные ошибки
• Безопасность, совместимость и GDPR-примечания
• Краткое резюме

Установка HACS на Supervised Home Assistant Server (HASS OS / Linux)

Перед началом

• Убедитесь, что у вас есть доступ администратора к Home Assistant.
• Имейте активный аккаунт GitHub (он понадобится для авторизации HACS).
• Сделайте резервную копию конфигурации Home Assistant (snapshot) перед установкой.

Шаги

1. Войдите в интерфейс Home Assistant.
2. Перейдите в Settings > Add-Ons.
3. Нажмите кнопку ADD-ON STORE.
4. В поле поиска найдите add-on “Terminal & SSH”.
5. В списке результатов кликните по Terminal & SSH, затем нажмите Install.

6. После установки нажмите Start, затем OPEN WEB UI. Откроется терминал.
7. В открытом терминале выполните команды:

cd /config
wget -O - https://get.hacs.xyz | bash -

8. Скрипт скачает HACS в каталог /config.

9. Перейдите в Developer Tools и нажмите Restart, чтобы перезапустить Home Assistant.
10. После перезапуска откройте Settings > Devices & Services и нажмите ADD INTEGRATION.
11. Найдите HACS в списке интеграций и кликните по ней.

12. Отметьте необходимые опции и нажмите Submit. Система выдаст URL и код.
13. Перейдите по этому URL и войдите через GitHub для авторизации HACS. Если аккаунта нет — зарегистрируйтесь.
14. На странице авторизации вставьте код, который показан в Home Assistant, и нажмите Authorize HACS.
15. Вернитесь в интерфейс Home Assistant и нажмите Submit.
16. Если всё прошло успешно, увидите экран Success. Выберите комнату (room) и нажмите Finish.

17. Перейдите в Settings > Devices & Services, откройте HACS и нажмите Options или Configure. Укажите имя и, при необходимости, Number of releases to show.

18. Включите обнаружение AppDaemon и NetDaemon, если используете эти платформы, и нажмите Submit.

Важно

Если при настройке что-то идёт не так, Home Assistant вернёт вас к экрану конфигурации. В этом случае проверьте логи и повторите шаги установки.

Установка HACS на не-Supervised Home Assistant (Docker на Linux)

Отличие

В Docker-контейнере нет встроенного Add-On store, поэтому установка HACS выполняется из каталога с конфигурацией Home Assistant.

Шаги

1. Откройте SSH/терминал на хосте, где запущен Docker.
2. Перейдите в директорию, где смонтирован volume конфигурации Home Assistant. Пример:

cd /home/UserName/docker/home-assistant

3. Запустите скрипт установки HACS:

wget -O - https://get.hacs.xyz | bash -

4. Скрипт установит HACS в текущую директорию (ту самую, где у вас файлы конфигурации).
5. Выполните перезагрузку контейнера или хоста:

sudo reboot

или перезапустите только Docker-контейнер:

docker restart 

6. После перезагрузки войдите в веб-интерфейс Home Assistant.
7. Перейдите в Settings > Devices & Services > Add Integration и установите HACS как в разделе для Supervised.
8. Завершите авторизацию через GitHub (вставьте код и подтвердите доступ).

Важно

Если HACS не появляется в списке интеграций после перезагрузки, проверьте права доступа к файлам в каталоге конфигурации и логи Home Assistant для ошибок импорта.

Установка кастомных интеграций и тем через HACS

1. В боковом меню кликните HACS, затем выберите Integrations или Frontend в зависимости от нужного типа.

2. Нажмите Explore & Download Repositories.
3. Введите название или ключевое слово в строке поиска и найдите нужный репозиторий.

Пример: Tapo Controller — интеграция для управления камерами TP-Link Tapo.

4. Нажмите на репозиторий, затем Download.
5. После установки большинства интеграций нужно перезапустить Home Assistant: Developer Tools > Restart.
6. Для frontend-тем и карт переходите в HACS > Frontend и устанавливайте компоненты. Затем очистите кэш браузера и перезагрузите страницу (Ctrl+F5).

Рекомендуемые интеграции и карты

• Mushroom card — стильные контролы и кнопки.
• Scheduler card — планировщик на основе правил.
• Mini Media Player — кастомная карточка для медиаплееров.
• Frigate — локальный NVR с детекцией объектов (требует мощного CPU/GPU).
• Alexa Media Player — интеграция с устройствами Echo и Fire TV.
• SmartThinQ LGE Sensor — управление умной техникой LG.
• Local Tuya — локальное управление устройствами Tuya.

Чек-лист перед установкой

• Резервная копия (snapshot) Home Assistant.
• Доступ администратора в интерфейсе HA.
• Аккаунт GitHub для авторизации HACS.
• Достаточно свободного места в каталоге конфигурации.
• Проверены права доступа к файлам конфигурации (UID/GID при Docker).

SOP: Быстрая процедура установки HACS (короткая версия)

1. Резервная копия конфигурации.
2. Установка Terminal & SSH (если Supervised).
3. Запуск скрипта: wget -O - https://get.hacs.xyz | bash -
4. Restart Home Assistant.
5. Add Integration > HACS > авторизация через GitHub.
6. Настройка Options и включение обнаружения сервисов.

Пошаговый план отката (rollback)

1. Если HACS нарушил работу Home Assistant, зайдите в snapshot и восстановите последнюю рабочую конфигурацию.
2. Вручную удалите каталог custom_components/hacs из /config.
3. Перезапустите Home Assistant.
4. Если использовали Docker, проверьте права и пересоберите контейнер при необходимости.

Критерии приёмки

• HACS отображается в боковом меню.
• Интеграции из HACS устанавливаются и активны после перезапуска.
• Нет ошибок в логах, связанных с hacs или custom_components.

Отладка и типичные ошибки

1. HACS не отображается в интеграциях

   • Проверьте, что папка custom_components/hacs существует и содержит файлы.
   • Убедитесь, что файл hacs.json присутствует в каталоге config/.storage.
   • Просмотрите лог Home Assistant (Settings > System > Logs).

2. Ошибка авторизации GitHub

   • Убедитесь, что код авторизации введён корректно.
   • Проверьте, не блокируют ли доступ корпоративные прокси или VPN.

3. Права доступа в Docker

   • Проверьте владельца/права на файлы: UID/GID контейнера должны совпадать с владельцем файлов.
   • Команда: ls -la /home/UserName/docker/home-assistant

4. Некорректная работа Frontend-карт

   • Очистите кэш браузера и перезагрузите страницу.
   • Убедитесь, что версия браузера поддерживается.

5. Frigate или тяжёлые интеграции тормозят систему

   • Проверьте нагрузку CPU/GPU и доступную память.
   • Рассмотрите выделение отдельного устройства (NVR) или аппаратного ускорения.

Decision tree: когда использовать Supervised vs Docker

flowchart TD
  A[Есть HASS OS на Raspberry Pi?] -->|Да| B[Используйте Supervised: Add-On store доступен]
  A -->|Нет| C[Запущен Home Assistant в Docker?]
  C -->|Да| D[Устанавливайте HACS вручную в каталоге конфигурации]
  C -->|Нет| E[Проверьте тип установки: Core, OS, Supervised]
  E --> F[Следуйте документации вашей установки]

Совместимость и рекомендации

• HACS совместим с большинством версий Home Assistant, но рекомендуется обновлять HA до актуальной стабильной версии.
• Для тяжёлых интеграций (Frigate, ML-модули) нужен мощный хост или отдельный NVR.
• При использовании Home Assistant OS (HASS OS) большинство действий проще благодаря Add-On Store.

Безопасность и конфиденциальность

• HACS использует авторизацию через GitHub: сама авторизация проводится на стороне GitHub, HACS получает токен для доступа к API. Не выдавайте токен третьим лицам.
• Кастомные интеграции — код от сообщества. Избегайте сомнительных репозиториев и проверяйте исходный код перед установкой.
• Для корпоративных или критичных к безопасности установок рассмотрите ограничения на подключение внешних репозиториев.
• GDPR: HACS не обязателен для работы Home Assistant, но некоторые интеграции могут отправлять данные внешним сервисам. Изучайте политику конфиденциальности интеграций.

Тесты и критерии успеха после установки

• HACS виден в боковой панели и открывается без ошибок.
• Установка тестовой интеграции (например, Mushroom card) проходит без ошибок и отображается в интерфейсе.
• Перезапуск Home Assistant не приводит к потерям конфигурации.
• Проверены логи на отсутствие ошибок, связанных с hacs.

Роли и чек-листы

Администратор

• Создать snapshot и проверить восстановление.
• Убедиться в наличии GitHub-аккаунта.
• Выполнить установку и авторизацию HACS.

Продвинутый пользователь

• Проверить и оценить код кастомных интеграций.
• Настроить AppDaemon/NetDaemon discovery при необходимости.

Новичок

• Следовать пошаговой инструкции и делать backup перед началом.
• Устанавливать только популярные и проверенные интеграции.

Альтернативные подходы

• Если вы не хотите использовать HACS, интеграции можно установить вручную, скачивая репозитории в custom_components и добавляя конфигурацию в configuration.yaml. Это безопаснее в плане контроля кода, но менее удобно.
• Для сетевых камер и NVR можно использовать полноценные коробочные решения (например, отдельный сервер Frigate) вместо интенсивных локальных интеграций.

Когда HACS не подходит

• В строго регулируемых средах, где запрещено выполнение стороннего кода без аудита.
• Если у вас ограничённый хост (малый объём памяти/процессора), и вы не хотите перегружать систему тяжёлыми интеграциями.

Пути повышения зрелости установки (maturity levels)

• Уровень 1 — базовая установка HACS, установка 1–2 популярных интеграций.
• Уровень 2 — регулярные обновления, проверенные интеграции, автоматизация резервных копий.
• Уровень 3 — аудит кастомных интеграций, тесты, развертывание на отдельном хосте для тяжёлых нагрузок.

Краткое резюме

HACS даёт быстрый доступ к широкой базе интеграций и тем для Home Assistant. Для Supervised систем процесс проще благодаря Add-On Store, а в Docker необходимо запускать скрипт установки в каталоге конфигурации. Всегда делайте резервные копии и проверяйте права доступа. При проблемах используйте чек-листы, логи и план отката.

Важно

Устанавливайте только доверенные репозитории и следите за логами после каждого обновления.