Home Assistant в Docker Compose: Сеть, Хранилище, Резервные копии

Если вы хотели начать работать с Home Assistant, это растущая экосистема, которая увлекательна и интересна. И если у вас уже есть домашняя лаборатория (как у большинства читателей здесь), у вас, скорее всего, уже есть инфраструктура для запуска контейнера Home Assistant в Docker. Используя Docker Compose, вы можете легко развернуть необходимые ресурсы HA. Однако здесь мы рассмотрим ключевые проектные решения, которые нужно принять. Они включают выбор сети, хранилища, резервного копирования, а также полный рабочий пример моего файла docker-compose.yml. Давайте начнём!

Почему Docker и Docker Compose для Home Assistant?

Контейнеризация Home Assistant, возможно, не была вариантом, о котором вы задумывались. В конце концов, можно легко купить готовые решения, такие как Home Assistant Green, Yellow или Blue, или даже использовать Raspberry Pi. Однако запуск в контейнере — отличный вариант, особенно если у вас уже есть Docker-хост или виртуальная среда (например, Proxmox), так как у вас уже есть необходимое оборудование.

Кроме того, у Docker Compose есть и другие преимущества. Код конфигурации можно хранить в Git и легко воссоздавать при необходимости. Также это помогает избежать проблем с зависимостями Python и другими сложностями на физическом хосте, который может использоваться для других задач.

Я уже использую Docker Compose для всех своих сервисов. Это также позволяет легко добавлять sidecar-контейнеры, такие как MQTT-брокеры или дашборды.

Проектные решения

При запуске Home Assistant в Docker с использованием Docker Compose необходимо принять несколько ключевых решений, особенно касающихся сети. Давайте сначала обсудим это.

Сеть

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

• Сеть host – Режим host предоставляет Home Assistant прямой доступ ко всем сетевым интерфейсам хоста. Это упрощает обнаружение устройств и интеграцию с такими протоколами, как mDNS или UPnP. Здесь вы жертвуете изоляцией ради лучшей обнаруживаемости устройств в Home Assistant.
• Сеть bridge – Режим bridge по умолчанию изолирует контейнер за виртуальным интерфейсом. В этой конфигурации необходимо пробросить каждый порт, который нужен Home Assistant, например, 8123 для веб-интерфейса. Режим bridge обеспечивает изоляцию, но может усложнить интеграции, зависящие от широковещательного трафика. Это можно решить с помощью sidecar-контейнеров, перенаправляющих mDNS и т. д.
• Сеть macvlan – Также можно использовать сеть macvlan в Docker. Macvlan создаёт виртуальный интерфейс, который делает контейнер физическим устройством в вашей сети. Home Assistant получает собственный IP в сегменте сети, поэтому, как и в режиме host, обнаружение работает «из коробки», а изоляция от хоста сохраняется. Недостаток в том, что некоторые хосты не могут взаимодействовать с macvlan-устройствами на том же физическом адаптере. Кроме того, эта конфигурация определённо добавляет сложности.

Хранилище

Home Assistant хранит конфигурацию YAML, базу данных SQLite (по умолчанию) и долгосрочную историю в постоянном хранилище Docker. Я предпочитаю следующие варианты:

• Bind mounts – Привязка директорий хоста, например, /srv/homeassistant/config, даёт прямой доступ к файлам для редактирования на хосте. Это просто, а резервное копирование может быть таким же лёгким, как копирование папки (подробнее об этом позже). Недостаток — возможные сложности с правами и проблемы с производительностью, если монтирование происходит по сети.
• Именованные тома (Named volumes) – Тома, управляемые Docker (например, /var/lib/docker/volumes/…), могут обеспечить немного лучшую производительность и автоматическую очистку. Однако доступ к данным требует взаимодействия через контейнер, например: docker run —rm -v volume:/data busybox.

На практике я чаще использую bind mounts. Они очень просты в настройке, и если ваше хранилище достаточно быстрое, проблем с производительностью не будет.

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

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

• Veeam Backup and Replication – Я использую агент для Linux для резервного копирования локальных файлов и образов виртуальных машин, на которых работает мой Docker-хост. Также есть бесплатная Community Edition.
• Duplicati – Это самоуправляемое решение для резервного копирования томов, которое позволяет сохранять данные контейнеров в отдельном хранилище.

Как управлять устройствами Zigbee

С Home Assistant есть несколько способов организации связи с устройствами Zigbee. Можно позволить Home Assistant общаться напрямую с устройствами через USB-адаптер или использовать sidecar-контейнеры. Давайте разберём оба варианта.

Контейнер Home Assistant с USB-адаптером Zigbee

Первый вариант — подключить USB-адаптер Zigbee напрямую к контейнеру Home Assistant и использовать встроенную интеграцию ZHA. В этой конфигурации контейнер Home Assistant обращается напрямую к /dev/ttyACM0 (или другому устройству, соответствующему вашему адаптеру).

Вы можете приобрести адаптер по этой ссылке (партнёрская ссылка Amazon): https://geni.us/zigbeeusbdongle1

Сопряжение новых ламп, датчиков и выключателей происходит через страницу «Интеграции». Достаточно нажать «Настроить» в разделе ZHA и позволить системе обнаружить устройства. Обновления прошивки для многих популярных адаптеров можно применять прямо из этого интерфейса.

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

Home Assistant без USB-адаптера и sidecar-контейнеры

Если вы хотите изолировать трафик Zigbee или использовать его для нескольких сервисов, можно отказаться от прямого подключения USB и вместо этого запустить sidecar-контейнеры рядом с Home Assistant. Обычно это выглядит так:

Контейнер Zigbee2MQTT

zigbee2mqtt:
  image: koenkk/zigbee2mqtt:latest
  restart: unless-stopped
  network_mode: homenet
  devices:
    - /dev/ttyACM0:/dev/ttyACM0
  volumes:
    - /srv/zigbee2mqtt/data:/app/data
  environment:
    - MQTT_SERVER=mosquitto

Контейнер MQTT-брокера (Mosquitto)

mosquitto:
  image: eclipse-mosquitto:latest
  restart: unless-stopped
  network_mode: homenet
  ports:
    - "1883:1883"
  volumes:
    - /srv/mosquitto/config:/mosquitto/config:ro
    - /srv/mosquitto/data:/mosquitto/data

Как работают sidecar-контейнеры? Zigbee2MQTT слушает USB-адаптер, преобразует сообщения устройств в JSON и публикует их в MQTT-брокер. Home Assistant получает эти сообщения через интеграцию MQTT.

Зачем нужна эта дополнительная сложность? Преимущество в поддержке большего количества устройств. Новые или нестандартные устройства Zigbee часто сначала появляются в Zigbee2MQTT. Кроме того, вы можете подключить Node-RED, пользовательские скрипты или дашборды напрямую к тем же MQTT-топикам. Вы жертвуете простотой ради гибкости и дополнительных возможностей.

Выбирайте прямое подключение USB, если вам важна простота. Используйте sidecar-контейнеры, если вам нужна максимальная гибкость и доступ к сети Zigbee из нескольких сервисов.

Создание файла Docker Compose

Ниже приведён аннотированный пример моего файла docker-compose.yml. Вы можете адаптировать теги образов, пути к томам и имена сетей под свою среду. В примере показаны:

• MQTT-брокер (eclipse-mosquitto)
• Zigbee2MQTT или deCONZ для устройств Zigbee
• InfluxDB и Grafana для долгосрочного хранения метрик и дашбордов

Если вам не нужны sidecar-контейнеры и вы используете USB-адаптер, просто удалите их из конфигурации.

version: '3.8'
services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    user: "1001:1001"
    restart: unless-stopped
    network_mode: "service:proxy" # подключение к sidecar-контейнеру Traefik для SSL
    depends_on:
      - mosquitto
    volumes:
      - /srv/homeassistant/config:/config:rw
      - homeassistant_db:/config/home-assistant_v2.db
    environment:
      - TZ=America/Chicago
    secrets:
      - api_key
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8123/api/health || exit 1"]
      interval: 1m
      timeout: 10s
      retries: 3
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETUID
      - SETGID

  mosquitto:
    image: eclipse-mosquitto:latest
    container_name: mosquitto
    restart: unless-stopped
    networks:
      homenet:
    volumes:
      - /srv/mosquitto/config:/mosquitto/config:ro
      - /srv/mosquitto/data:/mosquitto/data
      - /srv/mosquitto/log:/mosquitto/log
    ports:
      - "1883:1883"

  influxdb:
    image: influxdb:2.6
    container_name: influxdb
    restart: unless-stopped
    networks:
      homenet:
    volumes:
      - influxdb_data:/var/lib/influxdb2
    environment:
      - INFLUXDB_ADMIN_USER=admin
      - INFLUXDB_ADMIN_PASSWORD_FILE=/run/secrets/influxdb_admin_password
    secrets:
      - influxdb_admin_password
    ports:
      - "8086:8086"

  grafana:
    image: grafana/grafana:9.5
    container_name: grafana
    restart: unless-stopped
    networks:
      homenet:
    volumes:
      - grafana_data:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD_FILE=/run/secrets/grafana_admin_password
    secrets:
      - grafana_admin_password
    ports:
      - "3000:3000"

networks:
  homenet:
    driver: macvlan
    driver_opts:
      parent: eth0
    ipam:
      config:
        - subnet: 192.168.1.0/24
          gateway: 192.168.1.1

volumes:
  homeassistant_db:
  influxdb_data:
  grafana_data:

Добавление SSL-сертификатов

Вы можете легко добавить SSL-сертификаты в конфигурацию контейнера Home Assistant. Я рекомендую два решения:

Обновление без простоя

Для обновления Home Assistant я загружаю последний образ и перезапускаю контейнер с помощью команд Docker Compose:

docker compose pull homeassistant
docker compose up -d homeassistant

Заключение

Надеюсь, эта статья о проектировании Home Assistant в Docker Compose поможет тем, кто хочет развернуть Home Assistant в своей сети. Это мощное решение, которое объединяет умные устройства в настраиваемой и безопасной среде. Использование Docker — мой предпочтительный способ запуска Home Assistant, так как у меня уже есть домашняя лаборатория с Docker. Понимая ключевые концепции (хранилище, сеть, резервное копирование), вы сможете создать надёжную систему. Напишите в комментариях, как у вас настроен Home Assistant. Используете ли вы контейнеры?