HACS: установка, настройка и безопасное обновление пользовательских интеграций Home Assistant

Когда я впервые столкнулся с Home Assistant, меня покорила его философия: всё локально, всё под контролем, никаких облаков. Но очень скоро я упёрся в потолок — стоковый HASS из коробки умеет далеко не всё. Хочется подключить нестандартный датчик, добавить красивую карточку на дашборд или интегрировать умную технику, которой нет в официальном каталоге. И тут на сцену выходит HACS — Home Assistant Community Store.

По сути, это менеджер пользовательских интеграций, который открывает дверь в мир Open Source-сообщества. Сегодня я расскажу, как установить HACS, настроить его и — что самое важное — безопасно обновлять интеграции, чтобы не сломать свой умный дом.

Зачем нужен HACS?

Официальный Home Assistant включает несколько сотен интеграций. Но сообщество развивается быстрее. Новые устройства, нестандартные протоколы, экспериментальные фичи — всё это появляется сначала в HACS. С помощью HACS вы получаете доступ к:

• Пользовательским интеграциям — компоненты, которых нет в официальном репозитории.
• Карточкам для Lovelace — визуальные элементы для дашборда (mini-graph-card, button-card, mushroom и другие).
• Темам оформления — меняйте внешний вид интерфейса до неузнаваемости.
• Автоматизациям и скриптам — готовые решения от сообщества, которые можно переиспользовать.

Без HACS Home Assistant — это хорошая, но ограниченная система. С HACS — это практически безграничная платформа для творчества.

Подготовка к установке

Прежде чем ставить HACS, убедитесь, что ваша система соответствует требованиям:

• Home Assistant 2024.1 или новее (я рекомендую всегда использовать актуальную версию).
• У вас есть доступ к интерфейсу с правами администратора.
• Установлен Git (в большинстве дистрибутивов HAOS он уже есть, но проверить не помешает).

Если вы используете Home Assistant в Docker-контейнере или в виртуальном окружении, убедитесь, что у вас есть доступ к файловой системе контейнера.

Установка HACS

Шаг 1: Скачиваем HACS

Самый надёжный способ — скачать архив с GitHub. Заходим на страницу релизов:

# Скачиваем последний релиз HACS
wget https://github.com/hacs/integration/releases/latest/download/hacs.zip

Если вы работаете с Home Assistant OS (HAOS), можно выполнить команду прямо из терминала аддона. Если нет — скачайте архив на компьютер и перенесите его на свой сервер через SCP или Samba.

Шаг 2: Распаковываем в директорию custom_components

# Создаём директорию custom_components, если её нет
mkdir -p /config/custom_components

# Распаковываем архив
unzip hacs.zip -d /config/custom_components/hacs

# Удаляем архив, чтобы не мусорить
rm hacs.zip

Важно: структура должна быть такой — /config/custom_components/hacs/. Если вы положите файлы неправильно, Home Assistant просто не увидит интеграцию.

Шаг 3: Перезапускаем Home Assistant

# Перезапуск через CLI (если у вас HAOS)
ha core restart

Или просто перезагрузите Core через интерфейс: Настройки → Система → Перезагрузка.

Шаг 4: Добавляем интеграцию в интерфейсе

Теперь заходим в Настройки → Устройства и службы → Добавить интеграцию и ищем HACS.

Home Assistant предложит авторизоваться через GitHub. Это необходимо для того, чтобы HACS мог скачивать репозитории от вашего имени. Создайте персональный токен на GitHub:

1. Зайдите на https://github.com/settings/tokens
2. Нажмите Generate new token.
3. Дайте ему имя (например, hacs) и выберите scope public_repo.
4. Скопируйте токен и вставьте его в Home Assistant.

После этого HACS появится в боковом меню. Поздравляю, вы сделали первый шаг!

Настройка HACS

Первичная настройка

После установки зайдите в HACS и дайте ему немного времени — он подтянет каталог репозиториев. В интерфейсе вы увидите несколько разделов:

• Интеграции — пользовательские компоненты.
• Фронтенд — карточки и темы для Lovelace.
• Автоматизации — готовые скрипты и автоматизации.
• Скачать — список загруженных репозиториев.

Я рекомендую сразу включить обновления по расписанию. Для этого зайдите в Настройки HACS (иконка шестерёнки в правом верхнем углу) и включите опцию Автоматическое обновление. HACS будет проверять наличие новых версий каждые несколько часов.

Установка первой интеграции

Допустим, вы хотите установить популярную интеграцию для мониторинга качества воздуха. Заходим в Интеграции → Обзор, ищем нужный репозиторий и нажимаем Скачать.

# После скачивания интеграции потребуется перезапуск
# Home Assistant сам предложит это сделать

После перезапуска интеграция появится в списке доступных для настройки — точно так же, как если бы вы устанавливали её из официального каталога.

Безопасное обновление интеграций

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

Почему обновления могут сломать систему?

Пользовательские интеграции зависят от API Home Assistant, которое меняется с каждой версией. Разработчик мог забросить проект, и его код перестанет работать на новой версии HASS. Или наоборот — вы обновите интеграцию, а она окажется несовместимой с вашей конфигурацией.

Стратегия безопасного обновления

Я выработал для себя простой алгоритм:

1. Делаем резервную копию перед любым обновлением. Это аксиома, которую я повторяю в каждой статье про умный дом. Если вы ещё не настроили бэкапы — срочно исправляйтесь. У нас есть отличная статья про надёжный бэкап и восстановление Home Assistant.

2. Читаем changelog. Перед обновлением зайдите в репозиторий интеграции на GitHub и посмотрите, что изменилось. Если в описании есть слова «breaking changes» — будьте особенно осторожны.

3. Обновляем по одной интеграции. Не обновляйте всё подряд. Обновили одну — проверили, что всё работает — переходите к следующей.

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

Как обновлять через HACS

Обновления появляются в разделе HACS → Скачать с бейджем «Обновление доступно». Нажимаете кнопку Обновить, и HACS сам скачает новую версию.

# Если вы предпочитаете командную строку, можно обновить вручную:
cd /config/custom_components/название_интеграции
git pull

Но я рекомендую использовать встроенный механизм HACS — он проверяет целостность файлов и реже ошибается.

Откат к предыдущей версии

Если что-то пошло не так, HACS позволяет откатиться. Зайдите в Скачать → выберите интеграцию → Настройки → Переустановить. HACS спросит, какую версию вы хотите установить — выберите предыдущую.

# Альтернативный способ — вручную из GitHub
cd /config/custom_components/название_интеграции
git checkout <commit_hash>

Только не забудьте перезапустить Home Assistant после отката.

Типичные ошибки и их решение

Ошибка: «HACS не видит интеграцию после установки»

Чаще всего проблема в неправильной структуре каталогов. Проверьте, что файлы лежат в /config/custom_components/hacs/, а не /config/custom_components/hacs.zip или /config/hacs/.

Ошибка: «GitHub token не работает»

Убедитесь, что токен имеет scope public_repo. Если вы создавали токен давно, он мог истечь. Создайте новый и обновите в настройках HACS.

Ошибка: «Интеграция не загружается после обновления»

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

Проблема: HACS скачивает интеграцию, но она не появляется в списке

Перезапустите Home Assistant. Иногда после установки новой интеграции требуется полный перезапуск Core, а не просто перезагрузка интерфейса.

Проверка результата

После установки и настройки HACS важно убедиться, что всё работает корректно. Вот мой чек-лист:

1. HACS отображается в боковом меню — зайдите в раздел и убедитесь, что каталог загружается без ошибок.
2. Установите тестовую интеграцию — например, browser_mod (позволяет управлять браузерами на устройствах). Она простая и редко ломается.
3. Проверьте логи — зайдите в Настройки → Система → Журнал и убедитесь, что нет ошибок, связанных с HACS.
4. Проверьте обновления — нажмите кнопку «Проверить обновления» в HACS и убедитесь, что он находит новые версии.

# Пример конфигурации для browser_mod в configuration.yaml
browser_mod:
  - device: living_room_tablet

Если после установки интеграции вы видите её устройства в списке объектов — всё работает.

Заключение

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

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

А если вы только начинаете знакомство с Home Assistant и ещё не установили его — вот полное руководство по установке на Raspberry Pi.

Удачных экспериментов, и пусть ваш умный дом работает стабильно!