Home Assistant в Docker Compose: готовый файл

MAATRIX

Home Assistant — самая массовая платформа умного дома: тысячи интеграций, полный контроль без облака производителя и без риска, что вендор закроет сервис и кирпичи вместо розеток окажутся у вас дома. Если вы уже держите пару контейнеров на VPS или планируете вынести умный дом с Raspberry Pi на что-то более надёжное, Docker Compose — самый быстрый способ поднять Home Assistant предсказуемо и с возможностью откатиться одной командой. Ниже — рабочий compose-файл, нюансы с сетью и Bluetooth, и что делать с бэкапами, чтобы конфиг не терялся при апдейтах.

Почему Docker, а не Home Assistant OS

У Home Assistant три основных способа установки: Home Assistant OS (полноценная ОС на отдельном устройстве или в виртуалке), Home Assistant Container (наш случай — Docker-образ поверх уже существующей ОС) и Home Assistant Core (голый Python-venv, для энтузиастов).

Container-вариант — компромисс между удобством и контролем:

• вы управляете хостовой ОС сами (обновления безопасности, firewall, другие сервисы рядом);
• Home Assistant не единственный жилец сервера — на том же VPS можно держать AdGuard Home, Zigbee2MQTT, Node-RED или мониторинг;
• нет Supervisor и магазина аддонов Home Assistant OS — аддоны придётся заменять отдельными контейнерами (тот же Zigbee2MQTT или Mosquitto ставятся вручную, но это не сложнее самого Home Assistant).

Если вам принципиально важен магазин аддонов "из коробки" — берите Home Assistant OS в виртуалке. Если вы уже привыкли жить в Docker Compose и хотите гибкости — Container подходит лучше.

Для этой связки вполне хватает 2 vCPU / 4 ГБ RAM — Home Assistant прожорлив по памяти при большом числе интеграций и долгой истории в базе, но для десятков устройств этого запаса достаточно с приличным запасом.

Готовый docker-compose.yml

Базовый вариант — только Home Assistant, сеть host (это критично для автообнаружения устройств по mDNS/SSDP — Sonoff, Shelly, Google Cast и подобные находятся в сети сами):

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:2026.8
    restart: unless-stopped
    privileged: true
    network_mode: host
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    environment:
      - TZ=Europe/Moscow

Что здесь важно:

• network_mode: host — без неё автообнаружение устройств почти не работает, а часть интеграций (HomeKit Bridge, Google Cast) в принципе требуют мультикаст в той же подсети;
• privileged: true нужен, если планируете пробрасывать USB-устройства (Zigbee/Z-Wave координатор) или использовать Bluetooth хоста — без физических устройств можно убрать и жить без него;
• /run/dbus:/run/dbus:ro — для интеграции Bluetooth через BlueZ хоста;
• тег образа лучше фиксировать конкретной версией (2026.8), а не stable — так вы обновляетесь осознанно, а не при каждом рестарте контейнера.

Создайте директорию для конфига перед первым запуском:

mkdir -p ~/homeassistant/config
cd ~/homeassistant
docker compose up -d

Первый запуск генерирует конфиг несколько минут — Home Assistant создаёт configuration.yaml, базу home-assistant_v2.db (SQLite) и структуру каталогов. Веб-интерфейс поднимется на порту 8123.

Расширенный вариант: с Mosquitto и Zigbee2MQTT

Если у вас Zigbee-устройства (датчики, розетки, реле) и координатор вроде Sonoff Zigbee 3.0 Dongle или ConBee II, добавьте MQTT-брокер и Zigbee2MQTT рядом:

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:2026.8
    restart: unless-stopped
    privileged: true
    network_mode: host
    volumes:
      - ./homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
    environment:
      - TZ=Europe/Moscow
    depends_on:
      - mosquitto

  mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto:2.0
    restart: unless-stopped
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log

  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt:latest
    restart: unless-stopped
    depends_on:
      - mosquitto
    volumes:
      - ./zigbee2mqtt/data:/app/data
      - /run/udev:/run/udev:ro
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    environment:
      - TZ=Europe/Moscow
    ports:
      - "8080:8080"

Для Mosquitto нужен минимальный конфиг mosquitto/config/mosquitto.conf:

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd

Пароль создаётся отдельно:

docker run --rm -v $(pwd)/mosquitto/config:/mosquitto/config eclipse-mosquitto:2.0 \
  mosquitto_passwd -c -b /mosquitto/config/passwd homeassistant СЛОЖНЫЙ_ПАРОЛЬ

Важный нюанс: /dev/ttyUSB0 в примере — типичный путь для USB Zigbee-координатора, но у вас он может отличаться (/dev/ttyACM0 и подобные), а главное — при перезагрузке хоста порядок USB-устройств не гарантирован. Надёжнее пробрасывать по стабильному пути через /dev/serial/by-id/... — посмотрите его командой ls -l /dev/serial/by-id/ и подставьте вместо /dev/ttyUSB0.

Если Home Assistant физически стоит не рядом с координатором (например, координатор остался дома, а Home Assistant вынесен на VPS), проброс USB напрямую не сработает — здесь либо zigbee2mqtt остаётся на локальной машине рядом с координатором и публикует данные в MQTT, к которому Home Assistant на VPS подключается удалённо через VPN, либо используется сетевой Zigbee-координатор (ESP32 с прошивкой zigbee-to-mqtt по TCP).

Сеть: host vs bridge и удалённый доступ

Сеть host — не единственный вариант, но самый простой для автообнаружения. Минус — контейнер занимает все порты хоста напрямую, конфликты возможны с другими сервисами (тот же порт 8080, который просит Zigbee2MQTT).

Если Home Assistant стоит на VPS без локальных умных устройств рядом (то есть все интеграции облачные — погода, уведомления, датчики через облачные API производителей), сеть host не обязательна — можно работать через bridge с явным пробросом порта 8123.

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

• WireGuard до сервера и доступ к 8123 только через VPN-туннель — самый надёжный вариант, никакого публичного порта не требуется;
• reverse-proxy с TLS (Traefik или nginx) с доступом только по HTTPS и, желательно, с ограничением по IP или Basic Auth перед Home Assistant;
• Cloudflare Tunnel — не открывает порты вообще, трафик идёт наружу через исходящее соединение.

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

Часовой пояс, база данных и производительность

Правильный TZ в environment — не косметика: расписания, автоматизации по времени суток и логика "восход/закат" в Home Assistant считаются от таймзоны контейнера. Если забыть TZ, контейнер живёт в UTC, и автоматизация "включить свет в 19:00" сработает не тогда, когда вы ожидаете.

По умолчанию Home Assistant пишет историю в SQLite-файл home-assistant_v2.db внутри /config. При активном доме (десятки сенсоров, обновления раз в несколько секунд) база быстро растёт и начинает тормозить дашборд History и Logbook. Два практичных шага:

1. Ограничьте recorder в configuration.yaml — исключите шумные сущности (сенсоры с частым обновлением, которые не нужны в истории):

recorder:
  purge_keep_days: 10
  exclude:
    domains:
      - automation
    entities:
      - sensor.uptime

1. При росте нагрузки вынесите базу в PostgreSQL — отдельным контейнером, с параметром db_url в том же блоке recorder. Для десятков устройств это обычно избыточно, но если счёт устройств идёт на сотни (или используется Frigate с частой записью событий) — SQLite на постоянной записи станет узким местом раньше, чем CPU.

Обновление и откат версии

Обновление Home Assistant Container — это смена тега образа и пересоздание контейнера:

# Обновляем: правим image: в docker-compose.yml на новую версию
docker compose pull homeassistant
docker compose up -d homeassistant

Перед крупным обновлением (особенно минорной версии вида 2026.9.0 → 2026.10.0) стоит прочитать breaking changes в release notes — Home Assistant меняет формат конфигов интеграций чаще, чем хотелось бы, и часть автоматизаций может потребовать правки YAML после апдейта.

Откат — обратная операция: возвращаете старый тег в compose-файле и пересоздаёте контейнер. Но откат образа не откатывает базу и конфиг, если формат уже успел мигрировать при апдейте — поэтому бэкап конфига перед каждым апдейтом обязателен, а не опционален.

Бэкапы: что и как сохранять

Всё состояние Home Assistant Container живёт в одной директории — ./config (или ./homeassistant/config в расширенном варианте). Внутри неё: configuration.yaml и связанные YAML-файлы, база home-assistant_v2.db, каталог .storage с UI-настройками (зоны, пользователи, интеграции, добавленные через интерфейс), логи и кэш.

Минимальный скрипт для бэкапа перед апдейтом:

#!/bin/bash
STAMP=$(date +%Y%m%d-%H%M%S)
docker compose stop homeassistant
tar -czf ~/backups/ha-config-$STAMP.tar.gz -C ~/homeassistant config
docker compose start homeassistant

Останавливать контейнер на секунду при бэкапе стоит, чтобы не поймать SQLite-файл в момент записи — иначе есть небольшой риск получить повреждённую копию базы. Для регулярных автоматических бэкапов на отдельное хранилище (не на тот же диск, где крутится сам сервер) удобно использовать restic или BorgBackup — если у вас уже настроен BorgBackup на сервере, добавить туда каталог Home Assistant — вопрос одной строчки в списке источников.

Отдельно у Home Assistant есть встроенный механизм Backups (Settings → System → Backups) — он умеет собирать конфиг в архив по расписанию и класть его в локальное хранилище или облако через соответствующую интеграцию. Для небольшой установки этого может хватить, но полагаться только на него без внешней копии рискованно — при выходе из строя диска сервера пропадёт и сам архив.

Частые вопросы