Home Assistant

Обзор

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

Главное отличие от Google Home, Alexa или Яндекс Умного дома в том, что логика живёт на своём сервере. Устройства продолжают работать, когда пропал интернет или производитель закрыл облачный сервис, а история состояний остаётся в локальной базе. Больше двух тысяч интеграций закрывают и локальные протоколы (Zigbee, Z-Wave, MQTT, ESPHome, Matter), и облачные API.

Рецепт запускает официальный вариант установки Container: один контейнер и один Docker volume с каталогом /config, панель на 127.0.0.1:8123. Это установка без Supervisor, поэтому add-ons, встроенное обновление из панели и автоматический поиск устройств в локальной сети недоступны — интеграции добавляются вручную по адресу устройства, а обновление делается сменой тега образа.

Оценка безопасности

Контейнер работает без privileged, host network и Docker socket, с no-new-privileges, а панель по умолчанию публикуется только на 127.0.0.1. Это сознательный отказ от удобства: официальная инструкция upstream предлагает network_mode: host и privileged: true, чтобы работали поиск устройств, Bluetooth и USB-адаптеры. Такой контейнер получает доступ ко всей сети хоста и почти все возможности root, поэтому в рецепт это не включено.

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

Отдельного внимания требует reverse proxy. Home Assistant отвергает проксированные запросы, пока в configuration.yaml не заданы use_x_forwarded_for и trusted_proxies. Если в trusted_proxies указать лишнюю подсеть, злоумышленник сможет подделать адрес клиента и обойти встроенную защиту от подбора пароля — в список попадает только адрес самого proxy.

Каталог /config хранит токены доступа, пароли интеграций и подробную историю жизни в доме. Архивы backup нужно шифровать и держать вне сервера.

Пошаговая инструкция

1. Проверьте сервер Ubuntu или Debian

Минимум: 2 CPU, 1 ГБ RAM и 8 ГБ на диске. Рекомендуется 2 ГБ RAM — расход растёт вместе с числом интеграций, а база истории занимает место пропорционально числу устройств. Нужны Ubuntu 22.04+ или Debian 12+ с Docker Engine и Docker Compose v2.24+. Отдельная база данных не требуется: по умолчанию Home Assistant пишет историю в SQLite внутри /config.

docker --version
docker compose version

2. Подготовьте файлы и переменные

Поместите compose.yaml, .env.example, backup.sh, restore.sh и каталог proxy в отдельный каталог:

mkdir -p ~/services/home-assistant
cd ~/services/home-assistant
cp .env.example .env
chmod 600 .env

В .env заданы:

• HOMEASSISTANT_VERSION — закреплённый тег образа, совпадает с номером релиза;
• HOMEASSISTANT_BIND — адрес, на котором публикуется панель, по умолчанию 127.0.0.1;
• HOMEASSISTANT_PORT — внешний порт панели, по умолчанию 8123;
• HOMEASSISTANT_CONFIG_VOLUME — volume с каталогом /config;
• TZ — часовой пояс, от него зависят автоматизации по времени и графики.

Все пользовательские данные лежат в одном volume: configuration.yaml, automations.yaml, база истории home-assistant_v2.db, каталог .storage с учётными записями, токенами и настройками интеграций. В каталоге рецепта данных не остаётся.

3. Запустите контейнер на VPS

docker compose pull
docker compose up -d
docker compose ps

Первый запуск дольше обычного: контейнер разворачивает /config и поднимает ядро. Дождитесь состояния healthy — healthcheck обращается к /manifest.json внутри контейнера:

docker compose logs --tail=50 home-assistant

С настройками по умолчанию наружу не смотрит ни один порт: панель привязана к 127.0.0.1. На VPS так и должно остаться — доступ дают либо через reverse proxy с HTTPS (шаг 6), либо через VPN, указав в HOMEASSISTANT_BIND адрес интерфейса VPN.

4. Пройдите мастер первичной настройки

Панель доступна только локально, поэтому пробросьте порт по SSH:

ssh -L 8123:127.0.0.1:8123 user@server.example

Откройте http://localhost:8123. Мастер создаёт первую учётную запись — она становится владельцем сервера. Задайте длинный пароль и сохраните его в менеджере паролей: сброс пароля возможен только правкой файлов в volume. Дальше мастер спросит название дома, местоположение и единицы измерения — от координат зависят автоматизации по закату и восходу.

Сразу после мастера включите двухфакторную аутентификацию: аватар пользователя в левом нижнем углу → «Безопасность» → «Многофакторная аутентификация».

5. Доступ из локальной сети

Мобильным приложениям Home Assistant для Android и iOS нужен прямой адрес сервера в локальной сети. Укажите в .env конкретный адрес сервера и пересоздайте контейнер:

sed -i 's/^HOMEASSISTANT_BIND=.*/HOMEASSISTANT_BIND=192.168.1.10/' .env
docker compose up -d
docker compose port home-assistant 8123

Не ставьте 0.0.0.0: на VPS это откроет панель управления домом всему интернету. Ограничьте порт локальной подсетью:

sudo ufw allow from 192.168.1.0/24 to any port 8123 proto tcp

Автоматический поиск устройств в этом рецепте не работает: контейнер живёт в изолированной сети Compose и не видит широковещательные запросы mDNS, SSDP и DHCP. Интеграции добавляются вручную — «Настройки» → «Устройства и службы» → «Добавить интеграцию», с указанием IP-адреса устройства. Bluetooth и USB-адаптеры Zigbee или Z-Wave требуют проброса устройства в контейнер и в рецепт не включены.

6. Домен и HTTPS

Готовые примеры лежат в proxy/Caddyfile, proxy/nginx.conf и proxy/traefik.yaml, замените в них home.example.com своим доменом. Caddy получает сертификат автоматически, пример Nginx предполагает сертификат Certbot, Traefik использует resolver letsencrypt. Интерфейс работает через WebSocket: в примере Nginx за это отвечают заголовки Upgrade и Connection, без них панель останется пустой.

Home Assistant по умолчанию отвергает проксированные запросы. Добавьте в configuration.yaml блок http с адресом своего proxy:

docker compose exec home-assistant vi /config/configuration.yaml

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1

В trusted_proxies попадает только адрес самого proxy. Лишняя подсеть в этом списке позволяет подделать адрес клиента и обойти защиту от подбора пароля (документация http). Если proxy работает в контейнере, укажите адрес его сети Docker, а не 127.0.0.1. Проверьте конфигурацию и перезапустите сервер:

docker compose exec home-assistant python -m homeassistant --script check_config -c /config
docker compose restart home-assistant

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

Резервное копирование

Данные лежат в volume home-assistant-config. Скрипт останавливает контейнер на время архивации: история пишется в SQLite, и копия работающей базы получается рассогласованной.

chmod +x backup.sh restore.sh
./backup.sh

Архив появится в ./backups. Он содержит токены доступа, пароли интеграций и историю состояний дома, поэтому храните копию вне сервера и в зашифрованном виде.

У самого приложения есть встроенный механизм: «Настройки» → «Система» → «Резервные копии». Он складывает архивы в /config/backups, то есть внутрь того же volume, и защищает от ошибочной правки конфигурации, но не от потери сервера. Скрипт и встроенные копии дополняют друг друга.

Восстановление

Восстановление полностью заменяет содержимое volume выбранным архивом:

./restore.sh ./backups/home-assistant-YYYYMMDDTHHMMSSZ.tar.gz
docker compose ps

Перед распаковкой скрипт создаёт страховочную копию текущих данных. Версия образа в .env должна совпадать с той, при которой создавался архив: старая версия не обязана понимать файлы .storage, обновлённые новой.

Обновление

Релизы выходят раз в месяц и регулярно содержат несовместимые изменения интеграций. Обязательно прочитайте раздел Backward-incompatible changes в release notes своей версии, затем:

./backup.sh
sed -i 's/^HOMEASSISTANT_VERSION=.*/HOMEASSISTANT_VERSION=2026.9.0/' .env
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 home-assistant

Обновление из панели управления в этом варианте установки недоступно: без Supervisor версию задаёт тег образа. Кнопка обновления Home Assistant Core в интерфейсе не появится.

Откат

Верните прежнее значение HOMEASSISTANT_VERSION в .env и выполните docker compose pull и docker compose up -d. Работает это не всегда: при обновлении Home Assistant переносит файлы .storage и схему базы истории на новый формат, а обратной миграции нет. Если старая версия не поднимается, восстановите архив, созданный перед обновлением:

./restore.sh ./backups/home-assistant-YYYYMMDDTHHMMSSZ.tar.gz
docker compose up -d

Отдельной внешней базы данных у рецепта нет, все миграции ограничены содержимым volume.

Полное удаление

Сохранить данные: docker compose down. Удалить контейнер и все данные безвозвратно:

docker compose down
docker volume rm home-assistant-config
rm -rf ~/services/home-assistant

Отдельно отзовите доступ в мобильных приложениях и удалите сервер из их настроек: они хранят собственные долгоживущие токены. Если для устройств создавались облачные привязки у производителей, их нужно снять на стороне производителя.

Источники: установка в Container, настройка интеграции http, резервные копии и release notes.

Диагностика

За reverse proxy панель отдаёт 400: Bad Request

Home Assistant не доверяет заголовку X-Forwarded-For, пока это не разрешено явно. В configuration.yaml нужен блок http:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.18.0.1

Адрес в trusted_proxies — это адрес, с которого запрос приходит в контейнер, и он почти никогда не равен 127.0.0.1. Для proxy на хосте это адрес шлюза сети Docker, как в примере выше; для proxy в контейнере — его адрес в общей сети. Берите фактическое значение из лога, а не угадывайте:

docker compose logs --tail=50 home-assistant | grep -i forwarded

Не расширяйте список до всей подсети: любой, кто попадёт в неё, сможет подделать адрес клиента.

Панель открывается, но остаётся пустой

Интерфейс получает данные по WebSocket. Если proxy не пробрасывает upgrade, страница загружается и висит. В Nginx нужны заголовки:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Caddy и Traefik делают это сами. Проверить, что дело в proxy, можно обращением напрямую через SSH-туннель на 127.0.0.1:8123.

Контейнер не становится healthy

docker compose ps
docker inspect --format '{{json .State.Health}}' "$(docker compose ps -q home-assistant)"
docker compose logs --tail=100 home-assistant

Первый запуск занимает больше времени, чем последующие: start_period healthcheck равен 120 секундам. Если контейнер перезапускается по кругу, почти всегда виновата ошибка в configuration.yaml:

docker compose exec home-assistant python -m homeassistant --script check_config -c /config

Когда ядро не может прочитать конфигурацию, оно поднимается в recovery mode: панель работает, но интеграций и автоматизаций нет. Это видно в поле state ответа /api/config и в шапке интерфейса.

Устройства не находятся автоматически

Так и должно быть: контейнер работает в изолированной сети Compose и не получает широковещательные запросы mDNS, SSDP и DHCP, на которых построен поиск. Добавляйте интеграции вручную и указывайте IP-адрес устройства. Если автоматический поиск нужен, придётся перейти на network_mode: host — это даёт контейнеру доступ ко всей сети хоста, и такой вариант в рецепт не включён осознанно.

Забыт пароль владельца

В образе есть скрипт управления учётными записями. Остановите контейнер, чтобы не править базу под работающим сервером, и смените пароль:

docker compose stop home-assistant
docker compose run --rm home-assistant python -m homeassistant --script auth --config /config list
docker compose run --rm home-assistant python -m homeassistant --script auth --config /config change_password smoke НовыйПароль
docker compose start home-assistant

Перед правкой сделайте backup. Удалять файлы .storage/auth* не нужно: вместе с ними исчезнут все пользователи, токены мобильных приложений и привязки к устройствам.

База истории занимает десятки гигабайт

По умолчанию Home Assistant хранит историю 10 дней, но при большом числе датчиков файл home-assistant_v2.db всё равно растёт быстро. Ограничьте срок и исключите шумные сущности в configuration.yaml:

recorder:
  purge_keep_days: 7
  exclude:
    domains:
      - device_tracker
      - sun

Размер файла после правки уменьшится не сразу: место освобождает служба recorder.purge с параметром repack: true.

После обновления сломалась интеграция

Проверьте раздел Backward-incompatible changes в release notes своей версии: интеграции переезжают и меняют формат настроек. Быстрое решение — вернуть прежний тег в .env и выполнить docker compose up -d. Если старая версия не поднимается из-за уже выполненной миграции .storage, восстановите архив, созданный перед обновлением:

./restore.sh ./backups/home-assistant-YYYYMMDDTHHMMSSZ.tar.gz

Автоматизации срабатывают не в то время

Проверьте оба часовых пояса: контейнерный TZ из .env и пояс самого приложения в «Настройки» → «Система» → «Общие». Автоматизации по закату и восходу дополнительно зависят от координат, заданных при первичной настройке.

docker compose exec home-assistant date