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

MAATRIX

AdGuard Home держит на себе весь DNS-трафик сети: списки фильтров, кастомные правила, клиентов, а часто и DHCP. Если сервер с ним упадёт без бэкапа, вы не просто теряете рекламный фильтр — у части устройств в сети вообще пропадёт разрешение имён, а если был поднят DHCP, начнутся конфликты адресов. Ниже — что именно копировать, как это автоматизировать и как восстановиться без сюрпризов.

Что нужно бэкапить в AdGuard Home

AdGuard Home хранит состояние в двух местах, и оба важны по-разному.

Конфиг — файл AdGuardHome.yaml. В нём всё, что вы настраивали руками: upstream DNS-серверы, DNS-over-HTTPS/DNS-over-TLS параметры, список подключённых фильтров и их URL, пользовательские правила блокировки, клиенты (client-specific настройки), пользователи веб-интерфейса с хешами паролей, настройки DHCP-сервера, пути к TLS-сертификатам. Потеря этого файла — это потеря часа-двух работы по настройке с нуля.

Рабочая директория (data/ при обычной установке, или смонтированный work/ в Docker):

Практический вывод: обязательно бэкапить AdGuardHome.yaml, желательно — stats.db, leases.db и sessions.db, а filters/ можно смело исключать из архива — это экономит место и время, кэш перекачается сам за первые минуты после старта.

Если вы уже пользовались Pi-hole и переходите на AdGuard Home ради DoH/DoT из коробки и более гибких правил — логика бэкапа похожая, но набор файлов и формат конфига другой, экспорт из Pi-hole сюда напрямую не переносится.

Где лежат файлы в зависимости от способа установки

Bare-metal установка (через официальный curl-скрипт AdGuard Home):

/opt/AdGuardHome/AdGuardHome.yaml
/opt/AdGuardHome/data/

Сервис управляется встроенным менеджером, обычно как systemd-юнит AdGuardHome.service.

Docker-развёртывание (образ adguard/adguardhome), типичный docker-compose.yml:

services:
  adguardhome:
    image: adguard/adguardhome
    container_name: adguardhome
    restart: unless-stopped
    volumes:
      - ./conf:/opt/adguardhome/conf
      - ./work:/opt/adguardhome/work
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "3000:3000/tcp"

Здесь конфиг лежит в ./conf/AdGuardHome.yaml, а рабочая директория — в ./work/data/. Если вы монтировали именованные Docker-тома вместо bind-mount, посмотрите путь на хосте через docker volume inspect <имя_тома> — общие принципы работы с бэкапом volume разобраны в статье про бэкап Docker volume, там же — типичные грабли с правами доступа.

Ручной бэкап: минимальная команда

Для bare-metal установки, останавливая сервис на несколько секунд ради консистентного снапшота (AdGuard Home пишет в stats.db и querylog.json почти непрерывно, поэтому копия "на лету" теоретически может захватить файл в момент записи):

systemctl stop AdGuardHome
tar czf /root/backups/adguardhome-$(date +%Y%m%d-%H%M).tar.gz \
  -C /opt/AdGuardHome AdGuardHome.yaml data/stats.db data/leases.db data/sessions.db
systemctl start AdGuardHome

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

Для Docker-развёртывания то же самое, но с остановкой контейнера:

docker compose stop adguardhome
tar czf /root/backups/adguardhome-$(date +%Y%m%d-%H%M).tar.gz \
  -C /opt/adguardhome conf/AdGuardHome.yaml work/data/stats.db work/data/leases.db work/data/sessions.db
docker compose start adguardhome

Если простой сервиса недопустим даже на секунды (например, DNS для продакшен-инфраструктуры), можно копировать без остановки — риск повреждения stats.db/querylog.json в момент записи невелик, а AdGuardHome.yaml перезаписывается только при сохранении настроек через веб-интерфейс, что происходит редко. В критичных случаях смотрите в сторону снапшотов файловой системы (LVM snapshot, ZFS snapshot) — они дают консистентность без простоя.

Автоматизация: скрипт и cron с ротацией

Ручной бэкап хорош один раз, но нужен регулярный. Вот рабочий скрипт с ротацией старых копий и опциональным шифрованием:

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

SRC_CONF="/opt/AdGuardHome/AdGuardHome.yaml"
SRC_DATA="/opt/AdGuardHome/data"
DEST="/root/backups/adguardhome"
KEEP_DAYS=14
STAMP=$(date +%Y%m%d-%H%M%S)
ARCHIVE="$DEST/adguardhome-$STAMP.tar.gz"

mkdir -p "$DEST"

systemctl stop AdGuardHome
tar czf "$ARCHIVE" \
  -C "$(dirname "$SRC_CONF")" "$(basename "$SRC_CONF")" \
  -C "$SRC_DATA" stats.db leases.db sessions.db
systemctl start AdGuardHome

# опционально: шифрование через gpg с симметричным паролем из переменной окружения
if [ -n "${BACKUP_PASSPHRASE:-}" ]; then
  gpg --batch --yes --passphrase "$BACKUP_PASSPHRASE" -c "$ARCHIVE"
  rm -f "$ARCHIVE"
  ARCHIVE="$ARCHIVE.gpg"
fi

# ротация: удалить архивы старше KEEP_DAYS
find "$DEST" -name 'adguardhome-*.tar.gz*' -mtime +"$KEEP_DAYS" -delete

echo "Бэкап готов: $ARCHIVE"

Сохраните как /usr/local/bin/adguard-backup.sh, дайте права chmod +x, добавьте в cron:

# ежедневно в 4:10 ночи
10 4 * * * /usr/local/bin/adguard-backup.sh >> /var/log/adguard-backup.log 2>&1

Для Docker-варианта команды tar и остановки/старта заменяются на docker compose stop/start adguardhome и пути conf/, work/data/ соответственно — логика скрипта та же.

Если хочется полноценного версионирования вместо простых tar-архивов с ротацией по дате — присмотритесь к restic: он умеет дедупликацию, инкрементальные снапшоты и шифрование из коробки, и его несложно натравить прямо на /opt/AdGuardHome вместо самописного tar-скрипта.

Хранение копии вне сервера

Локальный архив в /root/backups/ защищает от «я случайно снёс конфиг», но не защищает от падения диска или потери сервера целиком. Бэкап должен улетать на другую машину или в объектное хранилище.

Простейший вариант — rclone в конец скрипта:

rclone copy "$ARCHIVE" remote:adguardhome-backups/ --min-age 1m

Настройка rclone под конкретное хранилище (S3-совместимое, Backblaze, другой сервер по SFTP) разобрана в статье про бэкап и восстановление через rclone — там же примеры конфигурации remote.

Правило «3-2-1» здесь избыточно для DNS-сервера, но «хотя бы одна копия не на этом же диске» — обязательно: скопируйте архив на соседнюю машину или в облако, это пять строк в конце скрипта, а спасает от полной потери настроек при отказе диска.

Восстановление из бэкапа

Восстановление AdGuard Home — это не «нажать кнопку», а последовательность из нескольких шагов, где легко ошибиться в порядке.

1. Установите AdGuard Home на новый/переустановленный сервер тем же способом, что был на исходном (официальный скрипт или Docker), но не запускайте первичную настройку через мастер — она создаст свежий AdGuardHome.yaml, который вы сейчас перезапишете.

1. Остановите сервис, если он уже запущен:

systemctl stop AdGuardHome

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

tar xzf adguardhome-20260828-0410.tar.gz -C /opt/AdGuardHome

Проверьте, что AdGuardHome.yaml оказался в /opt/AdGuardHome/, а stats.db, leases.db, sessions.db — в /opt/AdGuardHome/data/.

1. Проверьте владельца файлов. Если AdGuard Home запускается не от root (частая практика в systemd-юните с User=), после tar xzf от root файлы окажутся с неправильным владельцем и сервис не сможет в них писать:

chown -R adguardhome:adguardhome /opt/AdGuardHome

(имя пользователя зависит от того, как вы ставили сервис — проверьте systemctl cat AdGuardHome на строку User=).

1. Запустите сервис и проверьте DNS:

systemctl start AdGuardHome
dig @127.0.0.1 example.com

Если резолвинг работает и веб-интерфейс на порту 3000 (или том, что вы настраивали) открывается с вашими старыми настройками — восстановление прошло успешно.

1. Форсируйте обновление фильтров сразу после старта (Настройки → Списки фильтров → Обновить), так как кэш filters/ вы не копировали и первое обновление правил произойдёт по расписанию, а не мгновенно.

Для Docker — тот же порядок, но вместо systemctl используются docker compose down / docker compose up -d, а архив распаковывается в директории, смонтированные как conf/ и work/.

Частые ошибки при бэкапе и восстановлении

• Забыли остановить сервис перед копированием бэкап-архивом целиком поверх старого. Если восстанавливаете «живой» сервер, а не чистую установку, обязательно останавливайте AdGuard Home перед распаковкой — иначе процесс продолжит писать в старые файлы поверх ваших новых, и получите смесь из двух состояний.
• Восстановили только AdGuardHome.yaml, забыли про leases.db. Работать будет всё, кроме того, что DHCP-сервер (если он у вас включён в AdGuard Home) забудет, кому какой адрес выдал, и перевыдаст адреса заново при следующем DHCP-запросе от устройств. Обычно это безобидно, но если у вас в сети есть статическая привязка MAC → IP через DHCP-резервации, проверьте, что резервации сохранились именно в AdGuardHome.yaml (они там, а не в leases.db) — с ними всё будет в порядке.
• Восстановление на сильно другой версии AdGuard Home. Формат AdGuardHome.yaml со временем меняется, и при первом запуске новая версия сама мигрирует старый конфиг. Обычно это проходит гладко, но если версия бэкапа сильно старше установленной — сначала попробуйте на тестовом сервере.
• TLS-сертификаты для DNS-over-HTTPS/DoT прописаны в конфиге по абсолютным путям, которых на новом сервере просто нет (например, сертификаты Let's Encrypt лежали в /etc/letsencrypt/ на старой машине). После восстановления AdGuard Home упадёт с ошибкой чтения сертификата — либо перевыпустите их на новом сервере по тем же путям, либо поправьте пути в AdGuardHome.yaml вручную перед стартом.
• Права доступа после tar xzf от root, когда сервис работает от отдельного пользователя — самая частая причина «восстановил, а сервис не стартует» в первые пять минут после миграции. См. шаг 4 выше.
• Хранение единственной копии бэкапа на том же диске, где стоит сам AdGuard Home. Если рухнет диск — рухнет и бэкап вместе с ним. Синхронизация на удалённое хранилище — не опция, а обязательный шаг.

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