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

MAATRIX

Homarr собирают месяцами: десятки плиток, категории, виджеты, интеграции с Docker, Portainer, Uptime Kuma и *arr-стеком — каждая со своим API-ключом. Если дашборд стоит без бэкапа, а сервер падает или диск сыпется, восстанавливать всё это руками — не пять минут, особенно интеграции, где ключи давно забыты и лежат только в самом Homarr. Ниже — что именно нужно бэкапить, почему один файл в этой схеме важнее самой базы, и как поднять Homarr на новом сервере так, чтобы сохранённые пароли интеграций расшифровались, а не потребовали ввода заново.

Что теряете без бэкапа и что вообще хранит Homarr

Начиная с версии 1.x Homarr хранит всё состояние в SQLite-базе внутри смонтированного тома, а не в разрозненных JSON-файлах, как было в ранних версиях. Внутри этой базы — доски (boards), плитки-приложения со ссылками, категории и их расположение на сетке, настройки виджетов (погода, календарь, RSS) и, отдельной таблицей, сохранённые интеграции: адреса и зашифрованные API-токены Portainer, Sonarr/Radarr, Proxmox и всего, что вы подключали.

Рядом с базой лежат:

• Иконки — если вы загружали кастомные иконки вручную, а не брали из встроенной библиотеки dashboard-icons по названию сервиса.
• SECRET_ENCRYPTION_KEY — переменная окружения, а не файл в томе. Именно этим ключом Homarr шифрует токены интеграций перед записью в базу. Без него база физически цела, но расшифровать сохранённые пароли невозможно.

При потере сервера без бэкапа вы теряете не просто список ссылок — это можно восстановить за полчаса руками. Теряются часы настройки виджетов, layout досок под конкретные группы пользователей и, главное, все интеграционные токены, которые придётся генерировать заново в каждом подключённом сервисе.

Где физически лежат данные: тома и ключ шифрования

Типовой docker-compose.yml для Homarr монтирует данные в отдельную директорию на хосте — в статье про установку Homarr это ./data:

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:latest
    container_name: homarr
    restart: unless-stopped
    environment:
      - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
    volumes:
      - ./data/configs:/app/data/configs
      - ./data/icons:/app/public/icons
      - ./data/data:/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "7575:7575"

Обратите внимание, что ключ вынесен в переменную ${SECRET_ENCRYPTION_KEY} — она должна подтягиваться из .env-файла рядом с compose-файлом, а не быть вписана в YAML в открытом виде, если вы держите репозиторий с конфигом в git. Проверить, где физически лежит база SQLite, проще всего прямо из контейнера:

docker exec homarr find /data /app/data -maxdepth 3 -type f 2>/dev/null

Обычно это db.sqlite (или файл с похожим именем) где-то под /data. Если у вас более старая установка Homarr (0.x), конфигурация вместо базы хранится JSON-файлами в /app/data/configs — логика бэкапа та же (архивировать весь том целиком), просто состав файлов внутри другой. Определить версию можно в интерфейсе (Settings → About) или по логам при старте контейнера.

SECRET_ENCRYPTION_KEY — секрет отдельно от базы

Это единственная часть конфигурации Homarr, которую бэкап тома не покрывает — она не хранится в файлах, а передаётся контейнеру через окружение. Если вы бэкапите только ./data и переустанавливаете Homarr на новом сервере с новым, случайно сгенерированным ключом, произойдёт следующее: доски, плитки и категории восстановятся нормально (они не шифруются), а вот все интеграции покажут ошибку подключения или пустые поля — расшифровать токены старым файлом новым ключом невозможно.

Значит, ключ нужно бэкапить отдельно и столь же аккуратно, как сам сервер:

cat .env | grep SECRET_ENCRYPTION_KEY

Практичный вариант — держать .env в том же архиве, что и данные (см. ниже), плюс отдельно сохранить ключ в менеджере паролей. Если ключ всё же потерян, а база — нет, доски и ссылки не пропадут, но интеграции придётся переподключать: заново генерировать API-токены в Portainer/Sonarr/Radarr и вводить их в Homarr вручную.

Ручной бэкап: том данных плюс .env

Полный снимок Homarr — это архив тома данных и файла с переменными окружения. Контейнер желательно на секунду остановить, чтобы SQLite не писал в базу во время копирования:

cd ~/homarr
docker compose stop homarr
tar -czf ~/homarr-backup-$(date +%F).tar.gz data/ .env docker-compose.yml
docker compose start homarr

Архив получается компактным — обычно несколько мегабайт, если иконок загружено немного. Если Homarr настроен на подключение к внешней PostgreSQL вместо встроенного SQLite (такой вариант поддерживается для более серьёзных развёртываний с несколькими репликами), базу бэкапьте отдельным дампом, а не файлом тома:

docker exec -t homarr-postgres pg_dump -U homarr -d homarr | gzip > ~/homarr-db-$(date +%F).sql.gz

Для подавляющего большинства установок на одном VPS используется встроенный SQLite, и файлового архива тома вместе с .env достаточно — отдельный дамп БД в этом случае не нужен, tar уже включает файл базы.

Автоматизация бэкапов и хранение вне сервера

Ручной архив полезен перед рискованными изменениями (обновление на мажорную версию, чистка интеграций), но как единственная стратегия не работает — про него забывают. Рабочая схема — cron-скрипт, который останавливает контейнер на секунду, архивирует данные и сразу увозит архив на другой сервер или в объектное хранилище.

Скрипт /usr/local/bin/homarr-backup.sh:

#!/usr/bin/env bash
set -euo pipefail

SRC_DIR="/home/deploy/homarr"
DATE=$(date +%F)
DEST="/root/homarr-backup-${DATE}.tar.gz"

cd "$SRC_DIR"
docker compose stop homarr
tar -czf "$DEST" data/ .env docker-compose.yml
docker compose start homarr

# отправка на удалённое хранилище
rclone copy "$DEST" remote:homarr-backups/

# чистим локальные архивы старше 14 дней
find /root -name 'homarr-backup-*.tar.gz' -mtime +14 -delete

В cron — раз в сутки, ночью, когда никто не смотрит дашборд:

0 4 * * * /usr/local/bin/homarr-backup.sh >> /var/log/homarr-backup.log 2>&1

Настройку самого rclone для облачного хранилища разбирали в статье про бэкап и восстановление через rclone. Если на сервере уже крутится несколько сервисов и хочется единой системы бэкапов с дедупликацией и версионированием, а не набора отдельных tar-архивов, посмотрите в сторону BorgBackup — для одного Homarr это, пожалуй, избыточно, но если тот же скрипт архивирует ещё десяток контейнеров на машине, единый подход удобнее. Общая логика организации бэкапов на сервере — в статье про автоматические бэкапы с нуля, а если вы уже настроили бэкап Docker-томов для других контейнеров на этом VPS — Homarr встраивается в ту же схему, она описана в статье про бэкап Docker volume.

Главное правило то же, что и для любого бэкапа: копия должна лежать не на том сервере, где крутится сам Homarr. Если архив остаётся локально и диск умирает вместе с сервером, бэкап пропадает вместе с оригиналом.

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

Порядок действий, если старый сервер недоступен и Homarr нужно поднять с нуля:

1. Разверните новый VPS с Docker — быстрее всего через установку Docker с нуля на Ubuntu 24.04.
2. Заберите архив из хранилища:

   rclone copy remote:homarr-backups/homarr-backup-2026-08-30.tar.gz .

1. Распакуйте архив в структуру, идентичную исходной:

   mkdir -p ~/homarr && cd ~/homarr
   tar -xzf ~/homarr-backup-2026-08-30.tar.gz

В архиве уже лежат data/, .env и docker-compose.yml — проверьте, что .env содержит тот же SECRET_ENCRYPTION_KEY, что был на старом сервере. Если он утерян и восстановлен из отдельного места (менеджер паролей), впишите его вручную в .env перед запуском.

1. Поднимите контейнер:

   docker compose up -d
   docker compose logs -f homarr

1. Проверьте интеграции. Откройте дашборд, зайдите в Settings → Integrations — если ключ шифрования совпал с исходным, все подключённые сервисы (Portainer, Sonarr и остальные) покажут рабочий статус без повторного ввода токенов. Если вместо статуса ошибка авторизации на всех интеграциях сразу — почти наверняка ключ не совпадает, а не проблема с самими сервисами.
2. Обновите обратный прокси, если он указывал на IP старого сервера — перенастройте Caddy или nginx на новый адрес, иначе домен продолжит смотреть в пустоту.
3. Проверьте Docker-сокет, если вы используете интеграцию со статусами контейнеров — на новом сервере состав контейнеров другой, и часть плиток может первое время показывать «not found», пока Homarr не переиндексирует список.

Если это была не полная миграция, а восстановление после локального сбоя (диск, случайное удаление тома) на том же сервере — шаги те же, только пункт 1 не нужен: просто распаковываете архив на прежнее место и поднимаете docker compose up -d.

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