Установка HACS на Home Assistant: пошаговая инструкция

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

1Кратко

• HACS — это пользовательская интеграция из GitHub, а не часть официальной поставки: код в нём централизованно не проверяется, ответственность за него на вас.
• Способ установки зависит от типа вашего Home Assistant: для OS и Supervised используется дополнение (приложение) «Get HACS», для Container и Core — скрипт загрузки в терминале.
• После установки нужен полный перезапуск ядра, затем добавление интеграции HACS и авторизация на GitHub по одноразовому коду.
• Нужна бесплатная учётная запись GitHub и доступ Home Assistant к GitHub из вашей сети.
• Перед установкой чужих компонентов делайте резервную копию, а после обновлений ядра проверяйте журнал на ошибки пользовательских интеграций.

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

2Что такое HACS и чем он отличается от встроенных интеграций

У Home Assistant есть собственный каталог интеграций: они проверяются разработчиками и входят в состав ядра. Есть и дополнения (add-ons, в новых версиях — «приложения») — отдельные программы вроде MQTT-брокера или файлового редактора. HACS — третий слой: он берёт код из публичных GitHub-репозиториев авторов-энтузиастов. Это пользовательские компоненты (custom components).

Источник	Что это	Кто проверяет	Примеры
Встроенные интеграции	Часть ядра Home Assistant	Команда проекта	Zigbee Home Automation, MQTT, мобильное приложение
Дополнения (приложения)	Отдельные программы рядом с ядром	Официальный магазин проверяется, сторонние репозитории — нет	Mosquitto broker, редактор файлов, терминал
HACS	Пользовательские компоненты из GitHub	Базовая проверка структуры репозитория, код не аудируется	Сторонние интеграции, карточки, темы

Через HACS обычно ставят:

• Интеграции — поддержку устройств и сервисов, которых нет в ядре, либо альтернативные версии существующих интеграций.
• Дашборд-ресурсы — пользовательские карточки и элементы интерфейса (в старых версиях раздел назывался «Frontend» или «Lovelace»).
• Темы — оформление интерфейса.
• Прочие категории — шаблоны, скрипты Python, приложения AppDaemon и NetDaemon. Состав зависит от версии HACS.

3Что понадобится перед установкой

• Работающий Home Assistant. Тип установки (OS, Supervised, Container, Core) определяет только способ получения HACS.
• Учётная запись GitHub: HACS обращается к GitHub за списком репозиториев и обновлениями, без авторизации не работает. Аккаунт бесплатный.
• Доступ к GitHub с самого Home Assistant. В некоторых сетях он нестабилен — см. раздел ошибок.
• Для Container и Core — доступ к терминалу сервера; для OS и Supervised — доступ к магазину дополнений.
• Резервная копия: Настройки > Система > Резервные копии (название пункта могло измениться).

Если вы не уверены, какой у вас тип установки, посмотрите Настройки > О программе: там указан способ установки. Правильно определить его важно, потому что от этого зависит путь, а попытка выполнить команды Container на Home Assistant OS ничего не даст.

4Какой способ установки HACS выбрать

Тип установки	Рекомендуемый способ	Нужен терминал	Особенность
Home Assistant OS	Дополнение (приложение) «Get HACS» из репозитория HACS	Нет	Запустите, прочитайте журнал и следуйте подсказкам
Supervised	То же дополнение «Get HACS»	Нет	Работает как на OS
Container (Docker)	Скрипт загрузки внутри контейнера	Да	Нужно зайти в контейнер командой docker exec
Core (Python)	Скрипт загрузки под пользователем Home Assistant	Да	Запускайте от того пользователя, под которым работает ядро

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

Для этих вариантов в документации HACS основной путь — отдельное дополнение, которое скачивает HACS за вас. Терминал не нужен.

1. Откройте магазин дополнений: Настройки > Дополнения > Магазин дополнений (в новых версиях — «Приложения»).
2. Через меню с тремя точками в правом верхнем углу откройте «Репозитории» и добавьте адрес репозитория дополнения «Get HACS» из документации HACS. Точный адрес берите на странице загрузки на hacs.xyz: так вы не скопируете чужой.
3. Обновите страницу магазина, найдите «Get HACS», нажмите «Установить», затем «Запустить».
4. Откройте журнал дополнения: в нём будет сообщение об успешной установке и дальнейшие указания.
5. Перезапустите Home Assistant полностью: Настройки > Система, кнопка питания в правом верхнем углу, пункт перезапуска.

Если вам привычнее терминал, на OS и Supervised можно использовать тот же скрипт, что и для Container, через дополнение «Terminal & SSH». Но это второстепенный путь, и рекомендации разработчиков HACS меняются, поэтому сначала пробуйте дополнение.

6Установка HACS в Home Assistant Container и Core

Здесь нужен терминал. В документации HACS это отдельная короткая процедура.

Container (Docker)

Подключитесь к контейнеру командой вида docker exec -it homeassistant bash. Имя контейнера у вас может быть другим — посмотрите его в выводе docker ps. Убедитесь, что вы находитесь в каталоге с configuration.yaml, обычно это /config, затем выполните скрипт загрузки:

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

Core

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

Скрипт определяет каталог конфигурации, создаёт custom_components/hacs и распаковывает туда файлы. По завершении выводится сообщение об успехе. Перед запуском любого скрипта из интернета привыкайте открывать адрес в браузере и читать текст: он короткий. Если копируете команду из статьи, убедитесь, что в ней обычные дефисы: типографские тире, подставленные редакторами, ломают команду.

Ручная установка

В документации HACS описана и ручная распаковка архива из релизов проекта в custom_components/hacs. Результат тот же, но на ручном пути проще ошибиться в структуре папок, поэтому используйте его, только если скрипт недоступен. Итоговая структура должна быть такой: внутри custom_components/hacs лежит файл manifest.json и остальные файлы компонента, а не вложенная папка с архивом.

7Перезапуск Home Assistant

Пользовательские компоненты подхватываются только после полной перезагрузки ядра. Быстрой перезагрузки конфигурации недостаточно. Дождитесь, пока интерфейс снова откроется, — это занимает от десятков секунд до пары минут. Затем очистите кэш браузера или обновите страницу сочетанием Ctrl+F5: иногда интерфейс не показывает новые элементы из-за устаревшего кэша.

8Добавьте интеграцию HACS и авторизуйтесь через GitHub

1. Откройте Настройки > Устройства и службы и нажмите «Добавить интеграцию».
2. В поиске введите HACS и выберите найденную интеграцию. Если её нет, очистите кэш браузера и убедитесь, что ядро действительно перезапускалось после установки.
3. Появится список условий. Прочитайте и отметьте пункты, если согласны: там говорится, что HACS неофициален и чужой код вы ставите на свой риск.
4. Нажмите «Отправить». HACS покажет код и ссылку на страницу активации устройства на GitHub (обычно github.com/login/device).
5. Войдите в учётную запись GitHub и введите показанный код. Подтвердите доступ приложения HACS, внимательно прочитав, какие права запрашиваются.
6. Вернитесь в Home Assistant и дождитесь завершения. При необходимости выберите область (Area) для сервиса или пропустите этот шаг.

Код действует ограниченное время. Если не успели, начните заново — HACS выдаст новый. После успешного входа в боковой панели появится пункт «HACS». Если его нет, обновите страницу и проверьте, что у вашей роли есть права администратора.

9Где HACS хранит токен GitHub и как его отозвать

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

• Резервные копии Home Assistant содержат этот токен, поэтому храните их так же аккуратно, как пароли.
• Если вы переносите Home Assistant на другое устройство, HACS потребует повторной авторизации либо восстановится из копии вместе с токеном.
• Если токен утёк или вы удалили HACS, отзовите доступ в настройках GitHub, в разделе авторизованных приложений.

10Первые шаги в HACS и установка компонентов

При первом открытии HACS несколько минут загружает данные о репозиториях. Не прерывайте процесс. Затем появится главная страница со списком категорий.

1. Откройте HACS и выберите категорию, например «Интеграции».
2. Найдите компонент через поиск или отфильтруйте список.
3. Откройте страницу репозитория. Прочитайте описание, посмотрите дату последнего обновления и число звёзд на GitHub.
4. Нажмите кнопку загрузки (в разных версиях «Скачать» или «Download»), выберите версию, если предлагается.
5. Для интеграций перезапустите Home Assistant и добавьте её в «Устройствах и службах». Для карточек и тем после загрузки обновите страницу браузера; иногда ресурс нужно добавить на дашборд вручную — это указано на странице репозитория.

11Репозитории для Home Assistant: как добавить свой источник

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

1. В HACS откройте меню с тремя точками в правом верхнем углу и выберите «Пользовательские репозитории». Если пункта нет, загляните в меню настроек HACS: интерфейс вашей версии мог измениться.
2. В поле «Репозиторий» вставьте адрес в формате https://github.com/автор/название.
3. В списке «Категория» выберите тип содержимого: интеграция, тема, дашборд-ресурс и так далее. Неверная категория — частая причина ошибки при добавлении.
4. Нажмите «Добавить». Репозиторий появится в поиске и ставится как обычный компонент.

Подбирая компоненты, отдавайте предпочтение тем, у которых есть понятная документация, живая история коммитов и открытые, но не заброшенные обсуждения (issues).

12Безопасность и здравый смысл

Пользовательская интеграция работает внутри процесса Home Assistant и может получить доступ ко всему: к устройствам, токенам, учётным данным облачных сервисов. Соблюдайте несколько правил.

• Ставьте компоненты только из источников, которым доверяете, и читайте описание, а при возможности и код. Особенно осторожно относитесь к пользовательским репозиториям, добавленным вручную.
• Перед установкой нового компонента делайте резервную копию.
• Не ставьте десятки интеграций «на всякий случай»: каждый лишний компонент — источник ошибок при обновлениях.
• После крупных обновлений ядра проверяйте журнал на предупреждения о пользовательских компонентах: именно они чаще всего ломаются при смене версий.
• Если компонент давно не обновлялся, поищите альтернативу или встроенный аналог.
• Если после установки система не загружается, временно уберите папку нужной интеграции из custom_components и запустите ядро снова: так проще найти виновника.

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

Проблема	Причина	Решение
HACS не появляется в списке интеграций	Ядро не перезапускалось или файлы лежат не там	Проверьте наличие custom_components/hacs рядом с configuration.yaml, перезапустите ядро, очистите кэш браузера
Скрипт установки завершается ошибкой	Нет интернета или GitHub недоступен из вашей сети	Проверьте соединение из терминала; попробуйте позже или установите вручную из архива релиза
Скрипт не запускается на Windows-Docker или Core под Windows	Скрипт рассчитан на Linux-оболочку	Используйте ручную установку
Не проходит авторизация GitHub	Код истёк или введён неверно	Запустите добавление интеграции заново и введите новый код сразу
HACS сообщает о превышении лимита запросов	GitHub ограничивает число обращений к API	Подождите; лимит сбрасывается со временем. Не добавляйте много репозиториев разом
Репозиторий не добавляется как пользовательский	Неверная категория или структура не соответствует требованиям	Проверьте категорию и адрес, прочитайте требования HACS к структуре репозитория
Карточка скачана, но не видна на дашборде	Ресурс не добавлен или кэш браузера	Проверьте ресурсы дашбордов (в расширенном режиме) и обновите страницу с очисткой кэша
После обновления ядра интеграция перестала работать	Компонент несовместим с новой версией	Обновите его через HACS; если обновления нет, ищите форк или откатитесь из резервной копии

Отдельно про запросы вроде «home assistant hacks установка». За ними обычно стоит тот же HACS: название легко прочитать как «hacks», но у проекта правильное написание — HACS. Если в инструкции встречается что-то иное, убедитесь, что это тот самый магазин сообщества, а не сторонний «хак» неизвестного происхождения.

14Обновление и удаление HACS

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

Чтобы удалить HACS, сначала удалите его интеграцию в «Устройствах и службах», затем остановите Home Assistant и удалите каталог custom_components/hacs. Установленные через него компоненты останутся, но обновляться перестанут — если они не нужны, удалите и их. Доступ приложения отзовите в настройках GitHub.

15Чек-лист: как оценить компонент перед установкой

1. Откройте страницу проекта на GitHub и прочитайте файл README: у живого проекта есть описание установки и настроек.
2. Посмотрите дату последнего релиза и коммита. Если проект не обновлялся больше года, а Home Assistant за это время сменил много версий, риск несовместимости высок.
3. Загляните в раздел Issues: много свежих нерешённых жалоб на запуск — повод поискать альтернативу.
4. Проверьте, не дублирует ли компонент встроенную интеграцию: нередко то, что раньше требовало HACS, уже появилось в ядре.
5. Убедитесь, что автор указывает совместимость с вашей версией Home Assistant.
6. Устанавливайте по одному компоненту и проверяйте журнал после каждого, чтобы понимать, что именно вызвало проблему.

Для начала чаще всего берут не интеграции, а оформление: например, популярные наборы карточек для дашборда, такие как Mushroom, или темы. Они проще и реже вызывают конфликты, чем интеграции с доступом к устройствам.

16Итог

Чтобы установить HACS в Home Assistant, нужно выбрать способ под свой тип установки, перезапустить ядро, добавить интеграцию HACS и авторизоваться через GitHub. Дальше магазин сообщества открывает доступ к тысячам пользовательских интеграций, карточек и тем, а пользовательские репозитории позволяют подключать компоненты, которых нет в общем каталоге. Работайте осторожно: делайте резервные копии, ставьте только нужное и читайте описание проекта до загрузки. Если интерфейс или рекомендованный способ установки изменились, документация на hacs.xyz всегда актуальнее любой статьи.