adguardteam/adguardhome네트워크 전역의 광고 및 트래커를 차단하는 DNS 서버
무료 오픈 소스, 강력한 네트워크 전역 광고 및 추적기 차단 DNS 서버.
AdGuard.com |
Wiki |
Reddit |
Twitter |
Telegram
AdGuard Home은 광고와 추적을 차단하는 네트워크 전체 소프트웨어입니다. 설정을 마치면 집 안의 모든 기기를 보호하며, 이를 위해 클라이언트 측 소프트웨어가 필요하지 않습니다.
추적 도메인을 "블랙홀"로 다시 라우팅하여 기기가 해당 서버에 연결되지 않도록 하는 DNS 서버로 작동합니다. 이는 공용 AdGuard DNS 서버에 사용하는 소프트웨어를 기반으로 하며, 둘은 많은 코드를 공유합니다.
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>
AdGuard Home을 수동으로 설치하고 기기를 구성하는 방법을 알아보려면 Wiki의 **[시작하기][wiki-start]** 문서를 읽어 보세요.
#### <a href="#docker" id="docker" name="docker">Docker</a>
[Docker Hub]에서 공식 Docker 이미지를 사용할 수 있습니다.
#### <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 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">공용 AdGuard DNS 서버와 어떻게 다른가요?</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 sinkholing” 방식으로 광고와 추적기를 차단하며, 차단 대상을 사용자 지정할 수 있습니다.
> [!NOTE]
> 우리는 여기서 멈추지 않을 것입니다. DNS sinkholing은 나쁜 출발점은 아니지만, 이는 시작에 불과합니다.
AdGuard Home은 추가 소프트웨어를 설치하고 구성할 필요 없이 많은 기능을 기본 제공합니다. 일반 사용자도 최소한의 노력으로 설정할 수 있을 만큼 단순하게 만들고자 합니다.
> [!NOTE]
> 나열된 기능 중 일부는 추가 소프트웨어를 설치하거나 SSH 터미널을 수동으로 사용하고 Pi-Hole을 구성하는 유틸리티 중 하나를 재구성하여 Pi-Hole에 추가할 수 있습니다. 그러나 우리의 의견으로는 이를 Pi-Hole의 기능으로 정당하게 간주할 수 없습니다.
| Feature | AdGuard Home | Pi-Hole |
|-------------------------------------------------------------------------|-------------------|-----------------------------------------------------------|
| 광고 및 추적기 차단 | ✅ | ✅ |
| 차단 목록 사용자 지정 | ✅ | ✅ |
| 내장 DHCP 서버 | ✅ | ✅ |
| 관리 인터페이스용 HTTPS | ✅ | 일부 가능하지만 lighttpd를 수동으로 구성해야 합니다 |
| 암호화된 DNS 업스트림 서버(DNS-over-HTTPS, DNS-over-TLS, DNSCrypt) | ✅ | ❌ (추가 소프트웨어 필요) |
| 크로스 플랫폼 | ✅ | ❌ (기본 지원이 아니며 Docker로만 가능) |
| DNS-over-HTTPS 또는 DNS-over-TLS 서버로 실행 | ✅ | ❌ (추가 소프트웨어 필요) |
| 피싱 및 악성 도메인 차단 | ✅ | ❌ (기본이 아닌 차단 목록 필요) |
| 자녀 보호 (성인 도메인 차단) | ✅ | ❌ (기본이 아닌 차단 목록 필요) |
| 검색 엔진에 세이프서치 강제 | ✅ | ❌ |
| 클라이언트(기기)별 구성 | ✅ | ✅ |
| 액세스 설정 (AGH DNS를 사용할 수 있는 사람 선택) | ✅ | ❌ |
| [루트 권한 없이 실행][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 sinkholing은 상당한 비율의 광고를 차단할 수 있지만, 기존 광고 차단기의 유연성과 강력함은 부족합니다. 이 방법들 간의 차이에 대해 좋은 인상을 얻으려면 [이 문서][blog-adaway]를 읽어 보세요. 이 문서는 AdGuard for Android(기존 광고 차단기)와 hosts 수준 광고 차단기(기능이 DNS 기반 차단기와 거의 동일)를 비교합니다. 이 수준의 보호만으로도 충분한 사용자도 있습니다.
또한 DNS 기반 차단기를 사용하면 스마트 TV, 스마트 스피커 또는 기타 IoT 기기와 같은 다른 유형의 기기에서 광고, 추적 및 분석 요청을 차단하는 데 도움이 될 수 있습니다(기존 광고 차단기를 설치할 수 없는 기기).
### <a href="#comparison-limitations" id="comparison-limitations" name="comparison-limitations">알려진 제한 사항</a>
DNS 수준 차단기로 차단할 수 없는 몇 가지 예는 다음과 같습니다:
- YouTube, Twitch 광고;
- Facebook, Twitter, Instagram 스폰서 게시물.
기본적으로 콘텐츠와 도메인을 공유하는 모든 광고는 DNS 수준 차단기로 차단할 수 없습니다.
향후 이를 처리할 가능성이 있나요? DNS만으로는 이 작업을 수행하기에 충분하지 않습니다. 우리의 유일한 옵션은 독립형 AdGuard 애플리케이션에서 하는 것처럼 콘텐츠 차단 프록시를 사용하는 것입니다. 우리는 향후 AdGuard Home에 이 기능 지원을 [추가할 예정][issue-1228]입니다. 불행히도, 이 경우에도 충분하지 않거나 상당히 복잡한 구성이 필요한 경우가 여전히 있을 것입니다.
[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/) v1.25 이상;
- [Node.js](https://nodejs.org/en/download/) v24.10.0 이상;
- [npm](https://www.npmjs.com/) v10.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을 확인하여 다른 명령어에 대해 알아보세요.
Go가 지원하는 모든 OS/ARCH용으로 AdGuard Home을 빌드할 수 있습니다. 이렇게 하려면 make를 실행할 때 GOOS 및 GOARCH 환경 변수를 매크로로 지정하세요.
예를 들어:```sh env GOOS='linux' GOARCH='arm64' make
또는:```sh
make GOOS='linux' GOARCH='arm64'
릴리스 빌드를 준비하려면 snapcraft가 필요합니다. 설치가 완료되면 다음 명령을 실행하세요:```sh
make build-release CHANNEL='...' VERSION='...'
`build-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
build-docker 타깃 문서를 참조하세요.
매번 프로덕션 버전을 다시 컴파일하지 않고 프론트엔드를 디버깅해야 할 때(예: 폼에서 라벨이 어떻게 보이는지 확인하려는 경우), 개발 환경에서 프론트엔드 빌드를 실행할 수 있습니다.
별도의 터미널에서 다음을 실행합니다: ```sh ( cd ./client/ && env NODE_ENV='development' npm run watch )
AdGuardHome 바이너리를 --local-frontend 플래그와 함께 실행하세요. 이 플래그는 AdGuard Home이 내장 프론트엔드 파일을 무시하고 ./build/ 디렉터리의 파일을 사용하도록 지시합니다.
이제 ./client/ 디렉터리에서 변경한 내용이 다시 컴파일되어 웹 UI에서 사용할 수 있게 됩니다. 실제로 다시 컴파일된 버전을 가져오려면 브라우저 캐시를 반드시 비활성화하세요.
AdGuard Home은 E2E 테스트에 Playwright를 사용합니다. 테스트는 tests/e2e에 있습니다.
테스트 실행:
npm run test:e2e – 모든 테스트 실행(헤드리스).npm run test:e2e:interactive – 대화형으로 테스트 실행.npm run test:e2e:debug – 디버그 모드로 테스트 실행.npm run test:e2e:codegen – 새 테스트 코드 생성.설정:
npm install을 실행하여 의존성을 설치합니다.npx playwright install을 실행하여 필요한 브라우저를 설정합니다.경고: Playwright는 테스트용 자체 브라우저 바이너리를 다운로드하여 설치하며, 이는 시스템에 설치된 브라우저와 다를 수 있습니다.
이 저장소를 포크하여 변경하고 풀 리퀘스트를 제출해 주세요. 다만 코드 가이드라인을 반드시 준수해 주시기 바랍니다.
참고로, 프로그램의 UI와 백엔드 부분을 동시에 기여할 필요는 없습니다. 이상적으로는 백엔드 부분(즉, 구성, API 및 기능 자체)이 먼저 구현되어야 합니다. UI 부분은 나중에 다른 사람이 별도의 풀 리퀘스트로 구현할 수 있습니다.
사용할 수 있는 업데이트 채널은 두 가지입니다:
beta: AdGuard Home의 베타 버전. 비교적 안정적인 버전으로, 보통 2주마다 또는 더 자주 릴리스됩니다.
edge: 개발 브랜치의 AdGuard Home 최신 버전. 새로운 업데이트가 매일 이 채널에 푸시됩니다.
불안정 버전을 설치하는 방법은 세 가지가 있습니다:
[Snap Store]: beta 및 edge 채널을 찾아보세요.
[Docker Hub]: beta 및 edge 태그를 찾아보세요.
독립 실행형 빌드. 자동 설치 스크립트를 사용하거나 [Wiki][wiki-platf]에서 사용 가능한 빌드를 찾아보세요.
베타 버전 설치 스크립트: ```sh curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -c beta
엣지 버전 설치 스크립트: ```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 번역에 도움을 주고 싶다면 [Knowledge Base][kb-trans]에서 AdGuard 제품 번역에 대해 자세히 알아보세요. [CrowdIn의 AdGuardHome 프로젝트][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>
기여할 수 있는 또 다른 방법은 `help wanted`로 표시된 [이슈][iss-help]를 찾아 해당 이슈를 진행해도 되는지 문의한 후, 버그를 수정하거나 기능을 구현하는 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): [Joost](https://rocketscience-it.nl/)가 만든 iOS 앱.
- [Python 라이브러리](https://github.com/frenck/python-adguardhome) - [@frenck](https://github.com/frenck) 제작.
- [Home Assistant 애드온](https://github.com/hassio-addons/addon-adguard-home) - [@frenck](https://github.com/frenck) 제작.
- [OpenWrt LUCI 앱](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) 제작.
- [GLInet 라우터의 AdGuard Home](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) aka [@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/) 제작.
- [AdGuard Home용 Zabbix 템플릿](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이 어떤 사용 통계도 수집하지 않고, 사용자가 직접 구성하지 않는 한 어떤 웹 서비스도 사용하지 않는 것은 당연한 일입니다. AdGuard Home이 *이론상 전송될 수 있는* 모든 내용을 담은 [전체 개인정보 보호정책][privacy]도 확인하세요.
[privacy]: https://adguard.com/en/privacy/home.html