AdGuard Home в Docker Compose: готовый файл

MAATRIX

Pi-hole долго был дефолтным выбором для блокировки рекламы на уровне DNS, но у него есть ограничения: шифрование апстрим-запросов (DoH/DoT) требует отдельного cloudflared или stubby сбоку, а правила фильтрации не всегда гибкие. AdGuard Home решает обе проблемы из коробки — и разворачивается на VPS через Docker Compose за пять минут, если под рукой есть рабочий файл. Ниже — конфигурация, которую можно скопировать и запустить, плюс разбор настроек, которые обычно упускают в первый день.

Чем AdGuard Home отличается от Pi-hole

Формально обе системы делают одно и то же: перехватывают DNS-запросы, сверяют домен со списками блокировки и либо резолвят его как обычно, либо возвращают 0.0.0.0 / NXDOMAIN. Разница — в деталях реализации.

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

Готовый docker-compose.yml

Структура каталогов на сервере:

/opt/adguardhome/
├── work/     # база данных, статистика, логи
├── conf/     # конфигурация, списки фильтров
└── docker-compose.yml

Создаём каталоги и файл:

mkdir -p /opt/adguardhome/{work,conf}
cd /opt/adguardhome
nano docker-compose.yml

Сам файл:

services:
  adguardhome:
    image: adguard/adguardhome:latest
    container_name: adguardhome
    restart: unless-stopped
    volumes:
      - ./work:/opt/adguardhome/work
      - ./conf:/opt/adguardhome/conf
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "67:67/udp"       # DHCP, если планируете использовать
      - "68:68/tcp"
      - "68:68/udp"
      - "80:80/tcp"       # веб-интерфейс без TLS (можно закрыть позже)
      - "443:443/tcp"     # HTTPS-интерфейс / DoH
      - "443:443/udp"     # DoQ (DNS-over-QUIC)
      - "853:853/tcp"     # DNS-over-TLS
      - "3000:3000/tcp"   # первичная настройка (порт установки)
    cap_add:
      - NET_ADMIN

Пара нюансов, которые ломают запуск на свежем сервере:

• Порт 53 почти наверняка занят systemd-resolved. Проверьте: sudo ss -tulpn | grep :53. Если занят — либо отключите systemd-resolved (sudo systemctl disable --now systemd-resolved, затем прописать nameserver 127.0.0.1 в /etc/resolv.conf вручную или через resolvconf), либо оставьте только Docker-порты 53 и настройте резолвинг самой ОС через другой путь.
• Порты 80/443 конфликтуют, если на сервере уже висит Caddy или nginx как реверс-прокси для других сервисов. В этом случае веб-интерфейс AdGuard Home лучше пробросить на нестандартный порт, например 8080:80, и не открывать наружу вовсе — только через WireGuard-туннель.
• cap_add: NET_ADMIN нужен для корректной работы DHCP-функций; если DHCP не нужен, эту строку и связанные порты 67/68 можно убрать.

Запуск:

docker compose up -d

Первичная настройка идёт через порт 3000: http://<IP-сервера>:3000. После завершения мастера установки AdGuard Home сам переключается на порты 80/443 и порт 3000 больше не слушает — это ожидаемое поведение, а не баг.

Настройка после первого запуска

Мастер установки спросит:

1. Интерфейс для веб-панели и DNS-сервера — оставляйте 0.0.0.0, чтобы слушать все интерфейсы контейнера.
2. Логин и пароль администратора — задайте сразу сложный пароль, интерфейс без дополнительной защиты будет виден на 80/443.
3. DNS upstream по умолчанию — здесь стоит сразу заменить дефолтные серверы на DoH/DoT (см. следующий раздел), а не оставлять обычный UDP на 53.

После установки первым делом идите в Настройки → DNS-серверы и проверьте раздел Access Settings: по умолчанию AdGuard Home слушает на всех интерфейсах без ограничения по IP. Если сервер смотрит в интернет напрямую, а не только в приватную сеть, ограничьте Allowed clients подсетью вашего VPN — иначе сервер превращается в открытый DNS-резолвер, которым может воспользоваться кто угодно (классический вектор для DNS-амплификации).

Если DNS должен обслуживать не только локальную сеть, а устройства, подключённые через VPN, посмотрите статью про настройку WireGuard на Ubuntu 24.04 — связка WireGuard + AdGuard Home как единый DNS для всех устройств в туннеле работает без дополнительных костылей: просто укажите IP контейнера как DNS в конфиге клиента.

DNS-over-HTTPS и DNS-over-TLS: включаем шифрование апстрима

Главное преимущество AdGuard Home перед связкой Pi-hole + cloudflared — упростить именно эту часть. В разделе Настройки → DNS-серверы → Upstream DNS servers можно сразу указать зашифрованные апстримы вместо обычного plaintext DNS:

# DNS-over-HTTPS
https://dns.cloudflare.com/dns-query
https://dns.google/dns-query

# DNS-over-TLS
tls://1.1.1.1
tls://8.8.8.8

# DNS-over-QUIC
quic://dns.adguard-dns.com:853

AdGuard Home сам определяет протокол по префиксу URL — никаких дополнительных контейнеров не нужно. Это закрывает канал между сервером и апстрим-резолвером от простого перехвата на сетевом уровне (провайдер, промежуточный роутер), хотя сам факт того, что вы обращаетесь к конкретному DoH-серверу, всё ещё виден по SNI, если не используется дополнительное шифрование транспорта.

Отдельно включите DNS-over-HTTPS для клиентов (не путать с апстримом) в разделе Encryption Settings, если хотите, чтобы устройства сами подключались к вашему AdGuard Home по HTTPS, а не обычным DNS-портом 53 — это защищает от подмены DNS на уровне локальной сети или Wi-Fi точки. Для этого нужен валидный TLS-сертификат на домен, который смотрит на ваш сервер; проще всего выпустить его через Caddy с автоматическим SSL или Let's Encrypt и указать пути к сертификату и ключу прямо в настройках AdGuard Home.

Гибкие правила фильтрации: списки, регулярки, клиенты

Список фильтров задаётся в разделе Фильтры → Списки DNS-блокировок. Из коробки включён AdGuard DNS filter, но полезно добавить ещё несколько:

https://adguardteam.github.io/HostlistsRegistry/assets/filter_1.txt   # AdGuard Base
https://adguardteam.github.io/HostlistsRegistry/assets/filter_2.txt   # AdAway
https://adguardteam.github.io/HostlistsRegistry/assets/filter_59.txt  # Anti-tracking

Собственные правила пишутся в разделе Кастомные правила фильтрации. Синтаксис совместим с форматом uBlock Origin/AdBlock Plus и поддерживает regex:

||doubleclick.net^
||*.ads.example.com^
/^banner[0-9]+\.example\.net$/
@@||analytics.example.com^$important   # разрешить конкретный домен вопреки блокировкам выше

Отличие от Pi-hole здесь принципиальное: Pi-hole в базовой конфигурации работает по точному совпадению домена или wildcard через отдельный список regex.list, а в AdGuard Home regex-правила — часть общего синтаксиса фильтров без переключения между режимами.

Клиентские профили (Клиенты → Добавить клиента) позволяют выдавать разные наборы правил разным устройствам по IP или MAC-адресу — например, отключить блокировку соцсетей для рабочего ноутбука, но оставить жёсткую фильтрацию для остальной сети. Это удобно, если на одном сервере DNS обслуживает и домашнюю сеть через VPN, и тестовый стенд, где фильтры мешают.

Резервное копирование и обновление

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

cd /opt/adguardhome
tar czf adguardhome-backup-$(date +%F).tar.gz work conf

Если на сервере уже используется контейнерное бэкап-решение, конфигурацию AdGuard Home можно включить в общий пайплайн — например, через restic в Docker Compose, направив его на тот же каталог /opt/adguardhome.

Обновление образа — стандартная процедура для Compose:

docker compose pull
docker compose up -d

Перед крупным обновлением (смена мажорной версии) стоит проверить changelog на GitHub-репозитории проекта — AdGuard Home развивается активно, и изредка меняется формат конфигурационного файла AdGuardHome.yaml; сам он при обновлении обычно мигрируется автоматически, но резервная копия перед апдейтом дешевле, чем разбор проблем после.

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