Бэкап и восстановление ESPHome

MAATRIX

ESPHome превращает YAML-файл в прошивку для ESP8266/ESP32 — удобно, пока дашборд жив. А если диск с конфигами умирает без бэкапа, вы теряете не прошивки (они уже залиты на устройства и работают), а возможность их менять: обновить логику, поправить сенсор, накатить OTA-апдейт. Без исходных YAML и, что критичнее, без ключей шифрования API и OTA-паролей часть датчиков по квартире превращается в чёрные ящики, до которых достучаться можно только физически, с USB-кабелем в руках. Разберём, что именно нужно копировать, как это автоматизировать и как поднять дашборд на новом сервере так, чтобы все устройства продолжили отзываться как ни в чём не бывало.

Что бэкапить в ESPHome: конфиги, secrets и ключи API

ESPHome-дашборд, где бы он ни крутился — на Raspberry Pi, в аддоне Home Assistant или в отдельном Docker-контейнере на VPS, — хранит всё состояние в одном каталоге, обычно /config внутри контейнера или ~/esphome при локальной установке через pip. Внутри него не всё одинаково важно:

Ключевой момент, который часто упускают: api_encryption_key и ota_password в secrets.yaml — это не второстепенные пароли, а единственный способ достучаться до уже прошитого устройства по сети. Прошивка, залитая на ESP32 полгода назад, использует именно те ключи, что были в YAML на момент компиляции. Потеряв secrets.yaml без резервной копии, вы не потеряете работающий датчик — он продолжит слать данные, если знает, куда, — но потеряете возможность обновить его прошивку удалённо, пока не подключитесь к нему физически по USB.

Простой бэкап: архив конфигов вручную

Для домашней установки без строгих требований к RPO достаточно tar с исключением тяжёлого и легко пересобираемого кэша:

tar --exclude='.esphome/build' \
    --exclude='.esphome/platformio' \
    --exclude='.esphome/temp' \
    -czf esphome-backup-$(date +%F).tar.gz \
    -C /opt/esphome/config .

Если ESPHome установлен как аддон Home Assistant, каталог обычно лежит в /usr/share/hassio/addons/data/<addon_slug>/ или доступен через Samba/SSH-аддон как /addon_configs/<slug>_esphome/. Проверить точный путь проще всего командой docker inspect для контейнера аддона:

docker inspect addon_a0d7b954_esphome | grep -A3 '"Mounts"'

Скопируйте архив за пределы устройства, на котором крутится дашборд — на VPS, в облако или хотя бы на NAS. Локальная копия на том же диске, что и оригинал, бэкапом не считается: она умирает вместе с диском.

Автоматизация: cron и офсайт-копия на отдельном сервере

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

# /etc/cron.d/esphome-backup
0 4 * * * root /usr/local/bin/esphome-backup.sh >> /var/log/esphome-backup.log 2>&1

#!/usr/bin/env bash
# /usr/local/bin/esphome-backup.sh
set -euo pipefail

SRC=/opt/esphome/config
DEST=/var/backups/esphome
DATE=$(date +%F)

mkdir -p "$DEST"
tar --exclude='.esphome/build' --exclude='.esphome/platformio' \
    -czf "$DEST/esphome-$DATE.tar.gz" -C "$SRC" .

find "$DEST" -name 'esphome-*.tar.gz' -mtime +14 -delete

# перенос на удалённый сервер бэкапов
rsync -az "$DEST/esphome-$DATE.tar.gz" backup-user@remote-host:/backups/esphome/

Каталог с конфигами ESPHome весит обычно единицы-десятки мегабайт (без .esphome/build), так что для него хватит минимального VPS, который вы держите отдельно от основного домашнего сервера именно ради изоляции — если сгорит роутер или диск на месте, копия останется цела. Если у вас уже стоит restic в Docker Compose для других сервисов, добавить туда каталог ESPHome — минутное дело: один дополнительный --include в существующем джобе снепшотов, версионирование и дедупликация достаются бесплатно.

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

Если сервер с дашбордом умер целиком, поднять ESPHome заново — вопрос нескольких минут при наличии архива. Разворачиваем контейнер:

# docker-compose.yml
services:
  esphome:
    image: ghcr.io/esphome/esphome
    container_name: esphome
    volumes:
      - ./config:/config
    environment:
      - USERNAME=admin
      - PASSWORD=changeme
    network_mode: host
    restart: unless-stopped

Перед первым запуском распаковываем архив в ./config:

mkdir -p esphome/config
tar -xzf esphome-backup-2026-08-20.tar.gz -C esphome/config
docker compose up -d

network_mode: host важен для автоматического обнаружения устройств через mDNS — без него дашборд не увидит узлы в локальной сети сам, придётся добавлять их вручную по IP. После старта откройте веб-интерфейс: если secrets.yaml и .esphome/storage/ восстановились из архива, все устройства должны появиться в списке со статусом online — дашборд опрашивает их напрямую по сети, а не хранит состояние сам.

Если ESPHome у вас работает как часть более крупной инсталляции умного дома вместе с Home Assistant, логично поднимать оба сервиса на одном VPS и бэкапить их синхронно — по схеме бэкапа Home Assistant это делается тем же cron-джобом, просто с двумя каталогами в архиве вместо одного.

Переподключение устройств: ключи, OTA и что делать, если Wi-Fi сменился

Восстановленный дашборд обнаруживает устройства по mDNS-имени (<node_name>.local), а не по IP, поэтому смена адреса роутером не страшна. Дальше два сценария:

• Secrets.yaml восстановлен и совпадает с тем, что зашито в устройстве. OTA-обновление и логи в реальном времени работают сразу — можно нажать «Install» на любом узле и залить новую прошивку по воздуху.
• Secrets.yaml утрачен или изменён (например, вы сгенерировали новые ключи вместо восстановления старых). Дашборд увидит устройство в сети, но api_encryption_key не совпадёт — подключение по API и OTA-заливка не пройдут. В логах контейнера будет ошибка расшифровки handshake.

Во втором случае устройство не превращается в кирпич — оно продолжает работать по прошитой логике и слать данные туда, куда указано в YAML на момент компиляции. Но обновить его удалённо уже нельзя. Единственный путь — физическое переподключение по USB-UART и заливка новой прошивки локально через esphome run <name>.yaml --device /dev/ttyUSB0, либо, если устройство настроено с wifi: ap: (fallback-точка доступа), можно подключиться к её SSID и перепрошить по Wi-Fi без USB — но пароль от этой точки доступа тоже лежит в том самом secrets.yaml, который вы, по условию сценария, потеряли. Отсюда вывод: бэкап secrets.yaml для ESPHome не менее критичен, чем бэкап самих YAML устройств — без него часть парка превращается в задачу с паяльником вместо задачи на пять минут в браузере.

Если бэкапа нет: восстановление без исходников

Не всё потеряно даже без архива. Три пути:

1. Прочитать конфигурацию с самого устройства. Начиная с относительно свежих версий ESPHome дашборд умеет получать текущую YAML-конфигурацию напрямую с работающего узла через API (кнопка «Edit» на устройстве в веб-интерфейсе достаёт то, что реально зашито). Это не восстанавливает комментарии и структуру пакетов, но возвращает рабочую точку отсчёта.
2. Пересобрать вручную по списку entities. Если устройство подключено к Home Assistant, в реестре сущностей видно все его сенсоры, пины и типы компонентов — по ним YAML восстанавливается вручную за 10–20 минут на устройство, что терпимо для пары узлов и болезненно для парка из полусотни датчиков.
3. Сгенерировать новые ключи и перепрошить с нуля. Если устройство доступно физически (или через фолбэк-точку доступа), проще принять потерю старой логики, написать YAML заново и залить с новыми api_encryption_key/ota_password, сразу сохранив их в бэкапящийся secrets.yaml — чтобы в следующий раз такого разбора не потребовалось.

Ориентируйтесь на то, что путь 1 работает не для всех типов компонентов и не гарантирует байт-в-байт совпадение с оригиналом — относитесь к нему как к черновику для сверки, а не как к полноценному восстановлению.

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