adguardteam/adguardhomeСетевой DNS-сервер для блокировки рекламы и трекеров
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="doc/adguard_home_darkmode.svg">
<img alt="AdGuard Home" src="https://raw.githubusercontent.com/adguardteam/adguardhome/HEAD/doc/adguard_home_lightmode.svg" width="300px">
</picture>
</p>
<h3 align="center">Центр защиты конфиденциальности для вас и ваших устройств</h3>
<p align="center">
Бесплатный и открытый DNS-сервер, блокирующий рекламу и трекеры на уровне всей сети.
</p>
<p align="center">
<a href="https://adguard.com/">AdGuard.com</a> |
<a href="https://github.com/AdguardTeam/AdGuardHome/wiki">Wiki</a> |
<a href="https://reddit.com/r/Adguard">Reddit</a> |
<a href="https://twitter.com/AdGuard">Twitter</a> |
<a href="https://t.me/adguard_en">Telegram</a>
<br/><br/>
<a href="https://codecov.io/github/AdguardTeam/AdGuardHome?branch=master">
<img src="https://img.shields.io/codecov/c/github/AdguardTeam/AdGuardHome/master.svg" alt="Покрытие кода"/>
</a>
<a href="https://goreportcard.com/report/AdguardTeam/AdGuardHome">
<img src="https://goreportcard.com/badge/github.com/AdguardTeam/AdGuardHome" alt="Go Report Card"/>
</a>
<a href="https://hub.docker.com/r/adguard/adguardhome">
<img alt="Загрузки Docker" src="https://img.shields.io/docker/pulls/adguard/adguardhome.svg?maxAge=604800"/>
</a>
<br/>
<a href="https://github.com/AdguardTeam/AdGuardHome/releases">
<img src="https://img.shields.io/github/release/AdguardTeam/AdGuardHome/all.svg" alt="Последний релиз"/>
</a>
<a href="https://snapcraft.io/adguard-home">
<img alt="adguard-home" src="https://snapcraft.io/adguard-home/badge.svg"/>
</a>
</p>
<br/>
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/50912/75b58bd07af3852625f8a4c6dfbf07c7f281e120d337633eeb4c2e811c1ed179/82936e9a5e4a5b2b650ca95d6f19299c2e9342465d4e6d5be3928c763f4766ef-display-v1.webp" width="800"/>
</p>
<hr/>
AdGuard Home — это сетевое программное обеспечение для блокировки рекламы и трекинга. После настройки оно охватывает ВСЕ ваши домашние устройства, и для этого не требуется никакое клиентское ПО.
Оно работает как DNS-сервер, который перенаправляет отслеживающие домены в «черную дыру», не позволяя вашим устройствам подключаться к этим серверам. Оно основано на программном обеспечении, которое мы используем для наших публичных серверов [AdGuard DNS], и у них много общего кода.
[AdGuard DNS]: https://adguard-dns.io/
- [Начало работы](#getting-started)
- [Автоматическая установка (Linux/Unix/MacOS/FreeBSD/OpenBSD)](#automated-install-linux-and-mac)
- [Альтернативные методы](#alternative-methods)
- [Руководства](#guides)
- [API](#api)
- [Сравнение AdGuard Home с другими решениями](#comparison)
- [Чем это отличается от публичных серверов AdGuard DNS?](#comparison-adguard-dns)
- [Сравнение AdGuard Home с Pi-Hole](#comparison-pi-hole)
- [Сравнение AdGuard Home с традиционными блокировщиками рекламы](#comparison-adblock)
- [Известные ограничения](#comparison-limitations)
- [Как собрать из исходников](#how-to-build)
- [Предварительные требования](#prerequisites)
- [Сборка](#building)
- [Участие в разработке](#contributing)
- [Тестирование нестабильных версий](#test-unstable-versions)
- [Сообщение об ошибках](#reporting-issues)
- [Помощь с переводами](#translate)
- [Другое](#help-other)
- [Проекты, использующие AdGuard Home](#uses)
- [Благодарности](#acknowledgments)
- [Конфиденциальность](#privacy)
## <a href="#getting-started" id="getting-started" name="getting-started">Начало работы</a>
### <a href="#automated-install-linux-and-mac" id="automated-install-linux-and-mac" name="automated-install-linux-and-mac">Автоматическая установка (Linux/Unix/MacOS/FreeBSD/OpenBSD)</a>
Чтобы установить с помощью `curl`, выполните следующую команду:```sh
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v
```
Чтобы установить с помощью `wget`, выполните следующую команду:```sh
wget --no-verbose -O - https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v
```
Для установки с помощью `fetch` выполните следующую команду:```sh
fetch -o - https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v
```
Скрипт также принимает некоторые параметры:
- `-c <channel>` для использования указанного канала;
- `-r` для переустановки AdGuard Home;
- `-u` для удаления AdGuard Home;
- `-v` для подробного вывода.
Обратите внимание, что параметры `-r` и `-u` являются взаимоисключающими.
### <a href="#alternative-methods" id="alternative-methods" name="alternative-methods">Альтернативные способы</a>
#### <a href="#manual-installation" id="manual-installation" name="manual-installation">Установка вручную</a>
Пожалуйста, прочитайте статью **[Getting Started][wiki-start]** в нашей Wiki, чтобы узнать, как установить AdGuard Home вручную и как настроить ваши устройства для его использования.
#### <a href="#docker" id="docker" name="docker">Docker</a>
Вы можете использовать наш официальный Docker-образ на [Docker Hub].
#### <a href="#snap-store" id="snap-store" name="snap-store">Snap Store</a>
Если вы используете **Linux,** существует безопасный и простой способ установить AdGuard Home: получить его из [Snap Store].
[Docker Hub]: https://hub.docker.com/r/adguard/adguardhome
[Snap Store]: https://snapcraft.io/adguard-home
[wiki-start]: https://adguard-dns.io/kb/adguard-home/getting-started/
### <a href="#guides" id="guides" name="guides">Руководства</a>
Смотрите нашу [Wiki][wiki].
[wiki]: https://github.com/AdguardTeam/AdGuardHome/wiki
### <a href="#api" id="api" name="api">API</a>
Если вы хотите интегрироваться с AdGuard Home, вы можете использовать наш [REST API][openapi]. Кроме того, вы можете использовать этот [python-клиент][pyclient], который можно использовать для создания [интеграции AdGuard Home с Home Assistant][assistant-integration].
[assistant-integration]: https://www.home-assistant.io/integrations/adguard/
[openapi]: https://github.com/AdguardTeam/AdGuardHome/tree/master/openapi
[pyclient]: https://pypi.org/project/adguardhome/
## <a href="#comparison" id="comparison" name="comparison">Сравнение AdGuard Home с другими решениями</a>
### <a href="#comparison-adguard-dns" id="comparison-adguard-dns" name="comparison-adguard-dns">Чем это отличается от публичных DNS-серверов AdGuard?</a>
Запуск собственного сервера AdGuard Home позволяет вам делать гораздо больше, чем использование публичного DNS-сервера. Это совершенно другой уровень. Убедитесь сами:
- Выбирайте, что именно сервер блокирует и разрешает.
- Следите за активностью вашей сети.
- Добавляйте свои собственные пользовательские правила фильтрации.
- **Самое главное — это ваш собственный сервер, и только вы им управляете.**
### <a href="#comparison-pi-hole" id="comparison-pi-hole" name="comparison-pi-hole">Чем AdGuard Home отличается от Pi-Hole</a>
На данный момент у AdGuard Home много общего с Pi-Hole. Оба блокируют рекламу и трекеры с помощью так называемого метода «DNS-синхолинга» (DNS sinkholing), и оба позволяют настраивать, что блокируется.
> [!NOTE]
> Мы не собираемся останавливаться на достигнутом. DNS-синхолинг — неплохая отправная точка, но это только начало.
AdGuard Home предоставляет множество функций «из коробки», без необходимости устанавливать и настраивать дополнительное программное обеспечение. Мы хотим, чтобы всё было настолько просто, чтобы даже обычные пользователи могли настроить его с минимальными усилиями.
> [!NOTE]
> Некоторые из перечисленных функций можно добавить в Pi-Hole, установив дополнительное программное обеспечение или вручную используя SSH-терминал и перенастроив одну из утилит, из которых состоит Pi-Hole. Однако, по нашему мнению, это нельзя считать полноценной функцией Pi-Hole.
| Функция | AdGuard Home | Pi-Hole |
|-------------------------------------------------------------------------|-------------------|-----------------------------------------------------------|
| Блокировка рекламы и трекеров | ✅ | ✅ |
| Настройка списков блокировки | ✅ | ✅ |
| Встроенный DHCP-сервер | ✅ | ✅ |
| HTTPS для интерфейса администратора | ✅ | Частично, но вам нужно будет вручную настроить lighttpd |
| Зашифрованные вышестоящие DNS-серверы (DNS-over-HTTPS, DNS-over-TLS, DNSCrypt) | ✅ | ❌ (требуется дополнительное программное обеспечение) |
| Кроссплатформенность | ✅ | ❌ (не нативно, только через Docker) |
| Работа в качестве сервера DNS-over-HTTPS или DNS-over-TLS | ✅ | ❌ (требуется дополнительное программное обеспечение) |
| Блокировка фишинговых и вредоносных доменов | ✅ | ❌ (требуются нестандартные списки блокировки) |
| Родительский контроль (блокировка взрослых доменов) | ✅ | ❌ (требуются нестандартные списки блокировки) |
| Принудительный безопасный поиск в поисковых системах | ✅ | ❌ |
| Конфигурация для каждого клиента (устройства) | ✅ | ✅ |
| Настройки доступа (выбор, кто может использовать DNS AdGuard Home) | ✅ | ❌ |
| Работа [без привилегий root][wiki-noroot] | ✅ | ❌ |
[wiki-noroot]: https://adguard-dns.io/kb/adguard-home/getting-started/
### <a href="#comparison-adblock" id="comparison-adblock" name="comparison-adblock">Чем AdGuard Home отличается от традиционных блокировщиков рекламы</a>
Зависит от обстоятельств.
DNS-синхолинг способен блокировать большой процент рекламы, но ему не хватает гибкости и мощности традиционных блокировщиков рекламы. Вы можете получить хорошее представление о разнице между этими методами, прочитав [эту статью][blog-adaway], в которой сравнивается AdGuard для Android (традиционный блокировщик рекламы) с блокировщиками на уровне hosts-файла (которые по своим возможностям почти идентичны DNS-блокировщикам). Такого уровня защиты достаточно для некоторых пользователей.
Кроме того, использование DNS-блокировщика может помочь блокировать рекламу, трекинг и аналитические запросы на других типах устройств, таких как SmartTV, умные колонки или другие виды IoT-устройств (на которые нельзя установить традиционные блокировщики рекламы).
### <a href="#comparison-limitations" id="comparison-limitations" name="comparison-limitations">Известные ограничения</a>
Вот несколько примеров того, что нельзя заблокировать с помощью блокировщика на уровне DNS:
- реклама на YouTube, Twitch;
- спонсируемые посты в Facebook, Twitter, Instagram.
По сути, любая реклама, у которой общий домен с контентом, не может быть заблокирована блокировщиком на уровне DNS.
Есть ли шанс справиться с этим в будущем? DNS никогда не будет достаточно для этого. Наш единственный вариант — использовать прокси для блокировки контента, как это делается в автономных приложениях AdGuard. Мы собираемся [добавить][issue-1228] поддержку этой функции в AdGuard Home в будущем. К сожалению, даже в этом случае всё ещё будут ситуации, когда этого окажется недостаточно или потребуется довольно сложная настройка.
[blog-adaway]: https://adguard.com/blog/adguard-vs-adaway-dns66.html
[issue-1228]: https://github.com/AdguardTeam/AdGuardHome/issues/1228
## <a href="#how-to-build" id="how-to-build" name="how-to-build">Как собрать из исходного кода</a>
### <a href="#prerequisites" id="prerequisites" name="prerequisites">Предварительные требования</a>
Запустите `make init`, чтобы подготовить среду разработки.
Для сборки AdGuard Home вам понадобится:
- [Go](https://golang.org/dl/) версии 1.25 или новее;
- [Node.js](https://nodejs.org/en/download/) версии 24.10.0 или новее;
- [npm](https://www.npmjs.com/) версии 10.8 или новее;
### <a href="#building" id="building" name="building">Сборка</a>
Откройте терминал и выполните следующие команды:```sh
git clone https://github.com/AdguardTeam/AdGuardHome
cd AdGuardHome
make
```
> [!WARNING]
> Нестандартный флаг `-j` в настоящее время не поддерживается, поэтому сборка с `make -j 4` или настройка вашей `MAKEFLAGS` на включение, например, `-j 4`, скорее всего, нарушит процесс сборки. Если ваша `MAKEFLAGS` действительно настроена таким образом, и вы не хотите её менять, вы можете переопределить её, выполнив `make -j 1`.
Чтобы узнать о других командах, обратитесь к [`Makefile`][src-makefile].
#### <a href="#building-cross" id="building-cross" name="building-cross">Сборка для другой платформы</a>
Вы можете собрать AdGuard Home для любой ОС/архитектуры, которую поддерживает Go. Для этого укажите переменные окружения `GOOS` и `GOARCH` в качестве макросов при запуске `make`.
Например:```sh
env GOOS='linux' GOARCH='arm64' make
```
или:```sh
make GOOS='linux' GOARCH='arm64'
```
#### <a href="#preparing-releases" id="preparing-releases" name="preparing-releases">Подготовка релизов</a>
Вам понадобится [`snapcraft`], чтобы подготовить сборочный релиз. После установки выполните следующую команду:```sh
make build-release CHANNEL='...' VERSION='...'
```
См. [документацию по цели `build-release`][targ-release].
#### <a href="#docker-image" id="docker-image" name="docker-image">Docker-образ</a>
Выполните `make build-docker`, чтобы собрать Docker-образ локально (тот, который мы публикуем в DockerHub). Обратите внимание, что для сборки нашего официального образа мы используем [Docker Buildx][buildx].
Возможно, вам потребуется подготовиться перед использованием этих сборок:
- (только для Linux) Установите Qemu: ```sh
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes --credential yes
```
- Подготовьте сборщик: ```sh
docker buildx create --name buildx-builder --driver docker-container --use
```
См. [документацию по цели `build-docker`][targ-docker].
#### <a href="#debugging-the-frontend" id="debugging-the-frontend" name="debugging-the-frontend">Отладка фронтенда</a>
Когда вам нужно отладить фронтенд без перекомпиляции продакшен-версии каждый раз, например, чтобы проверить, как ваши метки будут выглядеть на форме, вы можете запустить сборку фронтенда в среде разработки.
1. В отдельном терминале выполните: ```sh
( cd ./client/ && env NODE_ENV='development' npm run watch )
```
2. Запустите ваш бинарный файл `AdGuardHome` с флагом `--local-frontend`, который указывает AdGuard Home игнорировать встроенные файлы фронтенда и использовать файлы из каталога `./build/`.
3. Теперь любые изменения, которые вы вносите в каталог `./client/`, будут перекомпилированы и появятся в веб-интерфейсе. Убедитесь, что вы отключили кэш браузера, чтобы гарантированно получить перекомпилированную версию.
[`snapcraft`]: https://snapcraft.io/
[buildx]: https://docs.docker.com/buildx/working-with-buildx/
[src-makefile]: https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/Makefile
[targ-docker]: https://github.com/AdguardTeam/AdGuardHome/tree/master/scripts#build-dockersh-build-a-multi-architecture-docker-image
[targ-release]: https://github.com/AdguardTeam/AdGuardHome/tree/master/scripts#build-dockersh-build-a-multi-architecture-docker-image
#### <a href="#e2e-frontend-tests" id="e2e-frontend-tests" name="e2e-frontend-tests">End-to-End (E2E) тесты фронтенда</a>
AdGuard Home использует [Playwright](https://playwright.dev) для E2E-тестирования. Тесты находятся в `tests/e2e`.
**Запуск тестов:**
- `npm run test:e2e` – запуск всех тестов (headless).
- `npm run test:e2e:interactive` – запуск тестов в интерактивном режиме.
- `npm run test:e2e:debug` – запуск тестов в режиме отладки.
- `npm run test:e2e:codegen` – генерация нового тестового кода.
**Установка:**
1. Выполните `npm install`, чтобы установить зависимости.
2. Выполните `npx playwright install`, чтобы установить необходимые браузеры.
> **Предупреждение:** Playwright загрузит и установит собственные бинарные файлы браузеров для тестирования, которые могут отличаться от браузеров, установленных в вашей системе.
## <a href="#contributing" id="contributing" name="contributing">Участие в разработке</a>
Вы можете форкнуть этот репозиторий, внести свои изменения и [отправить pull request][pr]. Пожалуйста, не забудьте следовать нашим [правилам оформления кода][guide].
Обратите внимание, что мы не ожидаем, что участники будут одновременно вносить вклад и в UI, и в серверную часть программы. В идеале сначала реализуется серверная часть, то есть конфигурация, API и сама функциональность. Часть UI может быть реализована позже, в отдельном pull request, другим человеком.
[guide]: https://github.com/AdguardTeam/CodeGuidelines/
[pr]: https://github.com/AdguardTeam/AdGuardHome/pulls
### <a href="#test-unstable-versions" id="test-unstable-versions" name="test-unstable-versions">Тестирование нестабильных версий</a>
Вы можете использовать два канала обновления:
- `beta`: бета-версии AdGuard Home. Более или менее стабильные версии, обычно выпускаются каждые две недели или чаще.
- `edge`: самая новая версия AdGuard Home из ветки разработки. Новые обновления публикуются в этот канал ежедневно.
Установить нестабильную версию можно тремя способами:
1. [Snap Store]: ищите каналы `beta` и `edge`.
2. [Docker Hub]: ищите теги `beta` и `edge`.
3. Автономные сборки. Используйте автоматизированный скрипт установки или найдите доступные сборки [в Wiki][wiki-platf].
Скрипт для установки бета-версии: ```sh
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -c beta
```
Скрипт для установки edge-версии: ```sh
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -c edge
```
[wiki-platf]: https://github.com/AdguardTeam/AdGuardHome/wiki/Platforms
### <a href="#reporting-issues" id="reporting-issues" name="reporting-issues">Сообщить о проблемах</a>
Если вы столкнулись с какой-либо проблемой или у вас есть предложение, перейдите на [эту страницу][iss] и нажмите кнопку «New issue». Пожалуйста, внимательно следуйте инструкциям в форме обращения и не забудьте сначала поискать похожие проблемы (дубликаты).
[iss]: https://github.com/AdguardTeam/AdGuardHome/issues
### <a href="#translate" id="translate" name="translate">Помощь с переводами</a>
Если вы хотите помочь с переводами AdGuard Home, узнайте больше о переводе продуктов AdGuard [в нашей базе знаний][kb-trans]. Вы можете внести свой вклад в [проект AdGuardHome на CrowdIn][crowdin].
[crowdin]: https://crowdin.com/project/adguard-applications/en#/adguard-home
[kb-trans]: https://kb.adguard.com/en/general/adguard-translations
### <a href="#help-other" id="help-other" name="help-other">Прочее</a>
Ещё один способ внести вклад — [поискать проблемы][iss-help] с меткой `help wanted`, спросить, свободна ли проблема, и отправить PR с исправлением ошибки или реализацией функции.
[iss-help]: https://github.com/AdguardTeam/AdGuardHome/issues?q=is:issue+is:open+label:%22help+wanted%22
## <a href="#uses" id="uses" name="uses">Проекты, использующие AdGuard Home</a>
Обратите внимание, что эти проекты не связаны с AdGuard, а созданы сторонними разработчиками и поклонниками.
- [AdGuard Home Remote](https://apps.apple.com/app/apple-store/id1543143740): iOS-приложение от [Joost](https://rocketscience-it.nl/).
- [Python library](https://github.com/frenck/python-adguardhome) от [@frenck](https://github.com/frenck).
- [Home Assistant add-on](https://github.com/hassio-addons/addon-adguard-home) от [@frenck](https://github.com/frenck).
- [OpenWrt LUCI app](https://github.com/kongfl888/luci-app-adguardhome) от [@kongfl888](https://github.com/kongfl888) (изначально от [@rufengsuixing](https://github.com/rufengsuixing)).
- [AdGuardHome sync](https://github.com/bakito/adguardhome-sync) от [@bakito](https://github.com/bakito).
- [Терминальный мониторинг трафика в реальном времени и статистика для вашего экземпляра AdGuard Home](https://github.com/Lissy93/AdGuardian-Term) от [@Lissy93](https://github.com/Lissy93)
- [AdGuard Home на роутерах GLInet](https://forum.gl-inet.com/t/adguardhome-on-gl-routers/10664) от [Gl-Inet](https://gl-inet.com/).
- [Приложение для Cloudron](https://git.cloudron.io/cloudron/adguard-home-app) от [@gramakri](https://github.com/gramakri).
- [Asuswrt-Merlin-AdGuardHome-Installer](https://github.com/jumpsmm7/Asuswrt-Merlin-AdGuardHome-Installer) от [@jumpsmm7](https://github.com/jumpsmm7), также известный как [@SomeWhereOverTheRainBow](https://www.snbforums.com/members/somewhereovertherainbow.64179/).
- [Библиотека Node.js](https://github.com/Andrea055/AdguardHomeAPI) от [@Andrea055](https://github.com/Andrea055/).
- [Расширение для браузера](https://github.com/satheshshiva/Adguard-Home-Browser-Ext) от [@satheshshiva](https://github.com/satheshshiva/).
- [Шаблон Zabbix для AdGuard Home](https://github.com/diasdmhub/AdGuard_Home_Zabbix_Template) от [@diasdmhub](https://github.com/diasdmhub).
- [Пакет Chocolatey](https://community.chocolatey.org/packages/adguardhome/) от [niks255](https://community.chocolatey.org/profiles/niks255).
- [Приложение в магазине приложений ZimaOS](https://www.zimaspace.com/zimaos/app-store/app/org.icewhale.adguardhome) от [CasaOS Team](https://casaos.zimaspace.com/).
## <a href="#acknowledgments" id="acknowledgments" name="acknowledgments">Благодарности</a>
Это программное обеспечение было бы невозможно без:
- [Go](https://golang.org/dl/) и его библиотек:
- [gcache](https://github.com/bluele/gcache)
- [miekg's dns](https://github.com/miekg/dns)
- [go-yaml](https://github.com/go-yaml/yaml)
- [service](https://godoc.org/github.com/kardianos/service)
- [dnsproxy](https://github.com/AdguardTeam/dnsproxy)
- [urlfilter](https://github.com/AdguardTeam/urlfilter)
- [Node.js](https://nodejs.org/) и его библиотек:
- [React.js](https://reactjs.org)
- [Tabler](https://github.com/tabler/tabler)
- И многих других пакетов Node.js.
- [данные whotracks.me](https://github.com/cliqz-oss/whotracks.me)
Возможно, вы видели, что [CoreDNS] упоминался здесь ранее, но мы перестали использовать его в AdGuard Home.
Полный список всех используемых пакетов Node.js можно найти в файле [`client/package.json`][src-packagejson].
[CoreDNS]: https://coredns.io
[src-packagejson]: https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/client/package.json
## <a href="#privacy" id="privacy" name="privacy">Конфиденциальность</a>
Наша главная идея заключается в том, что именно вы должны контролировать свои данные. Поэтому вполне естественно, что AdGuard Home не собирает никакой статистики использования и не обращается к веб-сервисам, если вы сами этого не настроили. Также доступна [полная политика конфиденциальности][privacy], в которой описан каждый бит данных, который *теоретически может быть отправлен* AdGuard Home.
[privacy]: https://adguard.com/en/privacy/home.html