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

MAATRIX

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

Что бэкапить в Home Assistant: config, .storage и recorder

Если вы ставили Home Assistant в варианте Container (без Supervisor) по инструкции про установку Home Assistant на VPS, у вас есть один смонтированный каталог — обычно /opt/homeassistant/config — и внутри него лежит вообще всё состояние системы. Разберём по частям, что там критично, а что переживёт потерю без последствий.

Главная ловушка — каталог .storage/. Это не служебный мусор, а JSON-файлы с реестром сущностей (core.entity_registry), устройств, зон, авторизацией (auth, auth_provider.homeassistant) и конфигурацией самих интеграций (core.config_entries) — включая токены OAuth для облачных сервисов. Потеряв его, вы не потеряете сами интеграции (они переустановятся через мастер), но потеряете все ручные правки: переименованные сущности, скрытые из интерфейса объекты, кастомные области, а пользователей придётся заводить заново.

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

Самый быстрый вариант, которого достаточно для домашней установки без строгих SLA — снять tar со всего каталога config, исключив то, что не нужно из таблицы выше:

mkdir -p /mnt/backup/homeassistant

tar --exclude='config/home-assistant.log*' \
    --exclude='config/tts' \
    --exclude='config/deps' \
    --exclude='config/image' \
    -czf /mnt/backup/homeassistant/ha-$(date +%F).tar.gz \
    -C /opt/homeassistant config

Recorder-базу (home-assistant_v2.db) специально не исключаем в этом варианте — SQLite-файл небольшой на старте, но растёт с историей: если у вас recorder настроен без ограничения purge_keep_days, за год-два база может занять заметный объём. Проверить размер:

du -sh /opt/homeassistant/config/home-assistant_v2.db

Если файл вырос сильно и история для вас некритична — добавьте его в исключения и настройте purge_keep_days в configuration.yaml, чтобы recorder сам не разрастался бесконечно.

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

Автоматизация через restic: дедупликация, шифрование и офсайт

Голый tar на постоянной основе быстро съедает диск — каждый архив хранит полную копию. Для регулярных бэкапов удобнее restic: дедупликация экономит место между прогонами, а шифрование защищает архив с токенами и паролями, даже если он окажется на чужом сервере. Подробная установка и работа с restic разобрана отдельно — в статье про бэкап и восстановление restic, здесь — только применение к Home Assistant.

Инициализация репозитория (один раз):

export RESTIC_REPOSITORY=/mnt/backup-disk/homeassistant-restic
export RESTIC_PASSWORD_FILE=/root/.restic-ha-pass
restic init

Сам бэкап:

restic backup /opt/homeassistant/config \
  --tag homeassistant \
  --exclude='/opt/homeassistant/config/tts' \
  --exclude='/opt/homeassistant/config/deps' \
  --exclude='/opt/homeassistant/config/image' \
  --exclude='/opt/homeassistant/config/home-assistant.log*'

Recorder-базу здесь можно оставить включённой в бэкап без особого риска — restic снимает снапшот файла на момент чтения, и даже если база в моменте изменится, следующий инкрементальный прогон досошлёт разницу. Если хотите подстраховаться максимально надёжно, добавьте в скрипт короткую паузу recorder перед снятием бэкапа через сервис Home Assistant (recorder.disable / recorder.enable в автоматизации или через REST API) — для большинства домашних инсталляций это избыточно, но на сервере с интенсивной записью может иметь смысл.

Для офсайта — то есть копии не на том же диске, где крутится сам сервер, — направьте RESTIC_REPOSITORY на отдельный сервер по SFTP вместо локального пути. Требования к такому серверу под архив (диск, RAM, тарифы по локациям) разобраны в статье про VPS для бэкапов и архива. Локальный бэкап на том же диске защищает только от ошибки в конфиге или неудачного обновления — не от отказа самого диска или сервера целиком.

Автоматизация: скрипт и systemd timer

Собираем всё в один скрипт и вешаем на таймер — надёжнее cron тем, что видно статус выполнения через systemctl и легко получить журнал ошибок:

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

CONFIG_DIR=/opt/homeassistant/config

export RESTIC_REPOSITORY=/mnt/backup-disk/homeassistant-restic
export RESTIC_PASSWORD_FILE=/root/.restic-ha-pass

restic backup "$CONFIG_DIR" \
  --tag homeassistant \
  --exclude="$CONFIG_DIR/tts" \
  --exclude="$CONFIG_DIR/deps" \
  --exclude="$CONFIG_DIR/image" \
  --exclude="$CONFIG_DIR/home-assistant.log*"

restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

chmod +x /usr/local/bin/homeassistant-backup.sh

Unit и таймер:

# /etc/systemd/system/homeassistant-backup.service
[Unit]
Description=Home Assistant config backup

[Service]
Type=oneshot
ExecStart=/usr/local/bin/homeassistant-backup.sh

# /etc/systemd/system/homeassistant-backup.timer
[Unit]
Description=Daily Home Assistant backup

[Timer]
OnCalendar=*-*-* 03:30:00
Persistent=true

[Install]
WantedBy=timers.target

systemctl daemon-reload
systemctl enable --now homeassistant-backup.timer
systemctl list-timers | grep homeassistant

Persistent=true доносит важную мелочь: если сервер был выключен или перезагружался в момент, на который назначен таймер, systemd выполнит пропущенный запуск сразу при следующей загрузке, а не будет ждать следующего дня. Отдельно стоит настроить уведомление о падении бэкапа — молчаливо не выполнившийся ExecStart обнаруживается обычно не сразу, а именно в момент, когда бэкап понадобился для восстановления.

Если параллельно пользуетесь встроенным разделом Backups в самом Home Assistant (Настройки → Система → Резервные копии) — это удобно для быстрого отката перед рискованным обновлением, но по умолчанию такие копии пишутся в тот же config/backups на том же диске, что и всё остальное. Как основной механизм защиты от отказа сервера он не годится ровно по той же причине, что и просто локальный tar, — не путайте "быстрый откат" с "бэкапом от отказа диска".

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

Порядок действий при переезде на новый сервер или после полной потери старого:

1. Поднимите базовое окружение. Установите Docker (шаги те же, что в статье про установку Home Assistant на VPS), создайте /opt/homeassistant и перенесите тот же docker-compose.yml, что использовался на прежнем сервере.

2. Восстановите config из restic до первого запуска контейнера:

export RESTIC_REPOSITORY=/mnt/backup-disk/homeassistant-restic
export RESTIC_PASSWORD_FILE=/root/.restic-ha-pass

mkdir -p /opt/homeassistant/config
restic restore latest --target /opt/homeassistant/config --path /opt/homeassistant/config

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

3. Проверьте права на файлы. После восстановления владелец файлов может не совпадать с тем, под кем работает процесс в контейнере:

chown -R 1000:1000 /opt/homeassistant/config   # UID контейнера уточните в вашем docker-compose.yml

4. Запустите и проверьте логи:

cd /opt/homeassistant
docker compose up -d
docker compose logs -f homeassistant

5. Откройте веб-интерфейс и проверьте: пользователи на месте (значит .storage/auth восстановился), сущности не переименовались обратно в автоматически сгенерированные имена (значит entity_registry на месте), автоматизации срабатывают. Если восстанавливали recorder-базу — история и логбук за прошлые периоды тоже будут доступны; если исключали её из бэкапа — история начнётся с нуля, это ожидаемо.

6. Проверьте интеграции с внешними токенами. Часть облачных сервисов инвалидирует токены доступа при длительном простое устройства — если после восстановления интеграция показывает ошибку авторизации, потребуется переавторизация через UI, это не связано с качеством бэкапа.

Типичные грабли при бэкапе и восстановлении

• Забыли secrets.yaml. Если вы ведёте automations.yaml и configuration.yaml в git отдельно от общего бэкапа, secrets.yaml часто намеренно не коммитят — и забывают включить его в файловый бэкап тоже. Без него конфиг не запустится вообще, откажет на первой же ссылке !secret.
• Бэкап только конфигурационных YAML-файлов, без .storage. Файлы вида automations.yaml — не единственное состояние системы: авторизация, реестр устройств и UI-дашборды в режиме "через интерфейс" (не YAML-режим) лежат в .storage и без него не восстановятся.
• Восстановление поверх уже проинициализированной установки. Если контейнер успел запуститься и пройти мастер первичной настройки до восстановления бэкапа, в .storage уже лежат новые файлы (новый auth, новый entity_registry) — простое копирование архива поверх может дать конфликт. Восстанавливайте в чистый, ещё не стартовавший каталог.
• Бэкап на том же диске, что и сама система. Резервная копия, лежащая рядом с оригиналом, не помогает при отказе диска или сервера целиком — нужна отдельная площадка, локальная или в другой локации.
• Ни разу не проверяли восстановление. Работающий backup не гарантирует работающий restore — стоит хотя бы раз в несколько месяцев поднимать тестовое восстановление на отдельном сервере, общий подход к такой проверке разобран в статье про восстановление базы данных из бэкапа на практике.
• Обновление сразу после восстановления на мажорную версию новее той, что была на момент бэкапа. Home Assistant применяет миграции .storage и recorder-базы последовательно — большой скачок версий иногда упирается в отсутствующие промежуточные миграции. Безопаснее сначала поднять ту же версию, что была на момент бэкапа, убедиться, что всё стартовало штатно, и только потом обновляться.

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