Как установить HACS (Home Assistant Community Store) на Home Assistant

Введение

HACS (Home Assistant Community Store) расширяет возможности Home Assistant за счёт сообщества: кастомные интеграции, интерфейсные карты, темы и плагины. Это удобный способ быстро добавить поддержку устройств, которых нет в официальном репозитории, или улучшить пользовательский интерфейс.

Определение: HACS — менеджер пакетов и каталог сообщества для Home Assistant. Он использует GitHub для хранения репозиториев и авторизации через ваш GitHub‑аккаунт.

Кому пригодится: домашним энтузиастам, интеграторам, администраторам умного дома и разработчикам, которым нужно больше возможностей, чем даёт базовая установка Home Assistant.

Важно: HACS не замещает официальные интеграции и требует правильной авторизации через GitHub. Ниже — пошаговые инструкции, а также разделы с рекомендациями по безопасности, откату и тестами.

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

Следуйте этим шагам, если ваш Home Assistant работает в режиме Supervised (например, HASS OS на Raspberry Pi) или в Linux с контролируемым Supervisor.

1. В веб‑интерфейсе Home Assistant откройте Настройки > Дополнения.
2. Нажмите кнопку Магазин дополнений (ADD‑ON STORE) и найдите дополнение Terminal & SSH.
3. В результатах поиска выберите дополнение Terminal & SSH и нажмите Установить.

4. После установки нажмите Запустить и затем Открыть веб‑интерфейс (OPEN WEB UI). Откроется терминал в браузере.
5. В терминале выполните команды:

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

6. Команда скачает и установит HACS в директорию config.

7. Перейдите в Инструменты разработчика (Developer Tools) и нажмите Перезагрузить (Restart), чтобы перезапустить сервер Home Assistant.
8. После перезагрузки откройте Настройки > Устройства и сервисы (Devices & Services) и нажмите Добавить интеграцию (Add Integration).
9. В поиске введите «HACS» и выберите найденную интеграцию.

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

17. Нажмите Опции (Options) или Настроить (Configure) и задайте имя интеграции и количество релизов для отображения в поле Number of releases to show.

18. Включите обнаружение AppDaemon и NetDaemon, если вы планируете использовать соответствующие расширения, и нажмите Отправить.

Примечание: если что‑то пойдёт не так, вас вернёт на экран конфигурации — можно повторить шаги авторизации и настройки.

Установить HACS на не‑supervised Home Assistant Server (Docker на Linux)

Если Home Assistant запущен в Docker без Supervisor, установка дополнений через UI недоступна, поэтому HACS устанавливают вручную в директории, смонтированной в контейнер.

1. Через SSH откройте терминал и перейдите в каталог, где смонтирован ваш Home Assistant. Пример:

cd /home/UserName/docker/home-assistant

2. Выполните команду для скачивания и установки HACS:

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

3. Скрипт установит HACS в директорию, где расположен volume Home Assistant.
4. Перезагрузите систему или контейнер:

sudo reboot

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

docker restart 

5. Откройте веб‑интерфейс Home Assistant, войдите и перейдите в Настройки > Устройства и сервисы > Добавить интеграцию.
6. Найдите и выберите HACS, следуйте шагам авторизации через GitHub, как в инструкции для Supervised.
7. После успешной авторизации перезапустите Home Assistant или соответствующий контейнер, чтобы интеграция стала активной.

Совет: убедитесь, что права доступа к файловой системе и UID/GID контейнера позволяют записывать в папку с конфигурацией.

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

После того как HACS настроен, вы сможете искать и устанавливать репозитории сообщества.

1. В боковой панели нажмите HACS, затем выберите Интеграции.

2. Нажмите Обзор и загрузка репозиториев (Explore & Download Repositories).
3. Найдите нужную интеграцию, например Tapo Controller — для интеграции камер TP‑Link Tapo.

4. Откройте репозиторий и нажмите Скачать (Download).
5. После установки перезагрузите Home Assistant через Инструменты разработчика > Перезагрузить.
6. Чтобы установить визуальные карточки и темы, выберите HACS > Frontend и установите нужные карты и темы.

Рекомендуемые интеграции и frontend‑пакеты:

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

Эти примеры помогут расширить функционал Home Assistant, но помните: репозитории сообщества имеют разный уровень поддержки и качества.

Чек-листы и роли

Чек‑лист для администратора перед установкой HACS:

• Резервная копия папки конфигурации /config (сохранить snapshot или скопировать папку).
• Обновлённый Home Assistant до актуальной стабильной версии.
• Доступ к SSH или терминалу и права записи в папку конфигурации.
• GitHub аккаунт готов к OAuth‑авторизации.
• План отката (как восстановить конфигурацию из бэкапа).

Чек‑лист для пользователя (быстрая проверка после установки):

• HACS виден в разделе Интеграции.
• Можно открыть HACS > Integrations и HACS > Frontend.
• Установленные пакеты видимы и не вызывают ошибок в логе.

Роли и обязанности:

• Администратор: выполняет установку, бэкапы, откат, обновления.
• Разработчик/энтузиаст: тестирует сторонние интеграции, вносит изменения.
• Пользователь/домакин: использует готовые интерфейсные элементы и сценарии.

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

Проверьте, что HACS установлен и настроен:

• HACS отображается в списке Интеграций.
• Авторизация GitHub завершена без ошибок.
• Можно установить и удалить интеграцию из HACS без критических ошибок в логах.
• Интерфейсные карты (frontend) загружаются корректно и элементы отображаются на dashboard.

Когда HACS может не сработать

• Нет доступа в интернет (HACS использует GitHub для загрузки репозиториев).
• Недостаточные права на файловую систему для записи в /config.
• На не‑supervised инстансах неправильно смонтирован volume Docker.
• Ограничения корпоративного прокси, блокирующего доступ к GitHub.

Если столкнулись с проблемой, проверьте логи Home Assistant (Supervisor / Core logs) и логи контейнера Docker.

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

• Ручная установка: клонирование репозитория в папку custom_components и копирование frontend файлов. Подходит, если вы не хотите использовать OAuth или сторонние менеджеры.
• Официальные адд‑оны: если нужная функциональность есть в официальном репозитории Supervisor, лучше использовать его.
• Docker‑образ с предустановленным набором интеграций: для готовых сборок и развертывания в тестовой среде.

Плюс HACS: удобство управления и обновлений. Минус: зависимость от GitHub и репозиториев третьих сторон.

Руководство по откату и инцидентам

Если после установки HACS или интеграции появились ошибки:

1. Откат через резервную копию конфигурации: восстановите /config из сохранённого бэкапа.
2. Удалите проблемный компонент через HACS > Installed или вручную удалите папку из custom_components.
3. Перезагрузите Home Assistant и проверьте логи на наличие ошибок.
4. Если Home Assistant не запускается, используйте последнюю рабочую конфигурацию из snapshot или резервной копии.

Сценарий для экстренного восстановления:

• Шаг 1: остановить контейнер/сервер.
• Шаг 2: переименовать текущую папку /config в /config_broken.
• Шаг 3: восстановить из резервной копии в /config.
• Шаг 4: запустить сервер/контейнер и проверить доступность интерфейса.

Безопасность и приватность

Рекомендации по безопасности при использовании HACS:

• Ограничьте доступ к веб‑интерфейсу Home Assistant (VPN, бренмауэр, двухфакторная аутентификация).
• При авторизации через GitHub разрешайте только минимально необходимый доступ.
• Не устанавливайте репозитории из неизвестных источников без проверки кода.
• Регулярно обновляйте Home Assistant и установленные HACS‑компоненты.

Приватность: HACS использует GitHub для авторизации и получения репозиториев. Не храните в публичных репозиториях секреты, токены или пароли.

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

1. Установить простую frontend‑карту (например, Mushroom card) и убедиться, что она отображается на dashboard.
2. Установить интеграцию устройства (например, Tapo Controller) и проверить, что устройство появляется в Entities и управляется.
3. Удалить установленный пакет и убедиться, что удаление прошло корректно без ошибок в логах.
4. Перезагрузить Home Assistant и проверить, что HACS автоматически подтянул установленные репозитории.

Критерии успеха: интерфейсные элементы работают, устройства управляются, в логах нет критических ошибок.

Короткая методология внедрения HACS в существующую систему

1. Подготовка: бэкап, проверка прав доступа, обновление Home Assistant.
2. Установка HACS по сценарию (Supervised или Docker).
3. Авторизация через GitHub и базовая настройка.
4. Установка одной‑двух проверенных интеграций/тем.
5. Тестирование и мониторинг логов в течение 24–48 часов.
6. Пошаговое расширение функционала и документирование изменений.

Советы по миграции и совместимости

• Перед обновлением HACS проверьте совместимость установленных кастомных интеграций с версией Home Assistant.
• Для Docker‑инстансов убедитесь, что volume с /config подключён и владельцем файлов является пользователь, под которым работает контейнер.
• Храните список установленных пакетов (README или файл inventory) для быстрой миграции на новый хост.

Часто задаваемые вопросы

Q: Нужен ли GitHub‑аккаунт для HACS?
A: Да — для авторизации и доступа к приватным/публичным репозиториям HACS использует OAuth GitHub.

Q: Можно ли использовать HACS офлайн?
A: Нет. HACS требует доступа к GitHub для загрузки и обновления репозиториев.

Q: Что делать, если интеграция из HACS ломает систему?
A: Удалите проблемную интеграцию через HACS или вручную, восстановите конфигурацию из бэкапа.

Сводка

HACS — удобный способ расширить Home Assistant за счёт проектов сообщества: интеграций, карт и тем. Выбор сценария установки зависит от типа инстанса (Supervised или Docker). Перед установкой сделайте бэкап, обеспечьте доступ к GitHub и следуйте рекомендациям по безопасности. Используйте чек‑листы и тесты для безопасного развёртывания.

В заключение: HACS даёт мощные возможности, но требует осторожности при выборе сторонних репозиториев и регулярного обновления.