AdguardTeam/AdGuardHome

무료 오픈 소스이며 강력한 네트워크 전체 광고 및 트래커 차단 DNS 서버입니다.

AdGuard.com |
Wiki |
Reddit |
Twitter |
Telegram

AdGuard Home은 광고와 추적을 차단하는 네트워크 전반의 소프트웨어입니다. 설정하면 모든 가정 장치를 커버하며, 이를 위해 클라이언트 측 소프트웨어가 필요하지 않습니다.

이것은 DNS 서버 역할을 하여 추적 도메인을 “블랙홀”로 재라우팅함으로써, 장치가 해당 서버에 연결되는 것을 방지합니다. 이는 우리가 공개 AdGuard DNS 서버용으로 사용하는 소프트웨어 기반이며, 둘 다 많은 코드를 공유합니다.

• 시작하기 (Getting Started)
• AdGuard Home과 다른 솔루션 비교
• 소스에서 빌드하는 방법
• 기여 (Contributing)
• AdGuard Home을 사용하는 프로젝트
• 감사의 글 (Acknowledgments)
• 개인 정보 보호 (Privacy)

curl로 설치하기

다음 명령어를 실행하세요:

curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v

wget으로 설치하기

다음 명령어를 실행하세요:

wget --no-verbose -O - https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v

fetch로 설치하기

다음 명령어를 실행하세요:

fetch -o - https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v

이 스크립트는 또한 몇 가지 옵션을 허용합니다:

-c <채널>: 지정된 채널을 사용합니다;
-r: AdGuard Home 재설치;
-u: AdGuard Home 제거;
-v: 상세 출력 (verbose output)입니다.

옵션 -r과 -u는 상호 배타적(mutually exclusive)임을 유의하세요.

AdGuard Home을 수동으로 설치하는 방법과 장치들을 이를 사용하도록 구성하는 방법을 알아보려면 Wiki의 시작하기 (Getting Started) 문서를 읽어보세요.

Docker Hub에서 공식 Docker 이미지를 사용할 수 있습니다.

Linux를 실행 중이라면, AdGuard Home을 설치하는 안전하고 쉬운 방법이 있습니다: Snap Store에서 받으세요.

Wiki를 확인하세요.

AdGuard Home과 통합하려면 REST API를 사용할 수 있습니다. 또는 AdGuard Home Hass.io Add-on을 빌드하는 데 사용되는 이 python 클라이언트를 사용할 수도 있습니다.

자신만의 AdGuard Home 서버를 운영하면 공개 DNS 서버를 사용하는 것보다 훨씬 더 많은 일을 할 수 있습니다. 이는 완전히 다른 차원의 경험입니다. 직접 확인해 보세요:

서버가 무엇을 차단하고 허용할지 정확하게 선택할 수 있습니다.

네트워크 활동을 모니터링할 수 있습니다.

자신만의 맞춤형 필터링 규칙 (custom filtering rules)을 추가할 수 있습니다.

가장 중요한 점은, 이것이 당신만의 서버이며, 오직 당신만이 제어권을 갖는다는 것입니다.

이 시점에서 AdGuard Home은 Pi-Hole과 많은 공통점을 가지고 있습니다. 두 서비스 모두 소위 "DNS 싱크홀링 (DNS sinkholing)" 방식을 사용하여 광고와 추적기 (trackers)를 차단하며, 차단 항목을 사용자 정의할 수 있도록 지원합니다.

참고

여기서 멈추지 않겠습니다. DNS 싱크홀링은 나쁜 시작점은 아니지만, 이것은 시작일 뿐입니다.

AdGuard Home은 추가 소프트웨어를 설치하거나 구성할 필요 없이 많은 기능을 기본적으로 (out-of-the-box) 제공합니다. 우리는 일반 사용자들도 최소한의 노력만으로 설정할 수 있을 만큼 단순하기를 원합니다.

참고

나열된 기능 중 일부는 추가 소프트웨어를 설치하거나, SSH 터미널을 수동으로 사용하여 Pi-Hole을 구성하는 유틸리티 중 하나를 재설정함으로써 Pi-Hole에 추가할 수 있습니다. 하지만 저희 의견으로는, 이를 Pi-Hole의 기능이라고 정당하게 간주할 수는 없습니다.

기능	AdGuard Home	Pi-Hole
광고 및 추적기 차단	✅	✅
...

상황에 따라 다릅니다.

DNS 싱크홀링은 상당한 비율의 광고를 차단할 수 있지만, 전통적인 광고 차단기 (ad blockers)의 유연성과 강력함은 부족합니다. AdGuard for Android (전통적인 광고 차단기)와 호스트 수준 광고 차단기 (hosts-level ad blockers, 기능 면에서 DNS 기반 차단기와 거의 동일함)를 비교하는 이 기사를 읽어보면 이러한 방식 간의 차이점에 대해 좋은 인상을 얻을 수 있습니다. 이러한 수준의 보호는 일부 사용자에게는 충분합니다.

또한, DNS 기반 차단기를 사용하면 SmartTV, 스마트 스피커 또는 다른 종류의 IoT 기기(전통적인 광고 차단기를 설치할 수 없는 기기)와 같은 다른 유형의 장치에서 광고, 추적 및 분석 요청을 차단하는 데 도움이 될 수 있습니다.

DNS 레벨 차단기(DNS-level blocker)가 차단할 수 없는 사례는 다음과 같습니다:

YouTube, Twitch 광고;

본질적으로, 콘텐츠와 도메인을 공유하는 모든 광고는 DNS 레벨 차단기로 차단할 수 없습니다.

향후 이를 처리할 가능성이 있을까요? DNS만으로는 이를 수행하기에 결코 충분하지 않을 것입니다. 우리의 유일한 옵션은 독립형 AdGuard 애플리케이션에서 수행하는 것과 같은 콘텐츠 차단 프록시(content blocking proxy)를 사용하는 것입니다. 우리는 향후 AdGuard Home에 이 기능 지원을 도입할 예정입니다. 불행히도, 이 경우에도 여전히 이것만으로는 충분하지 않거나 상당히 복잡한 설정이 필요한 사례가 있을 것입니다.

make init을 실행하여 개발 환경을 준비하세요.

AdGuard Home을 빌드하려면 다음이 필요합니다:

터미널을 열고 다음 명령어를 실행하세요:

git clone https://github.com/AdguardTeam/AdGuardHome
cd AdGuardHome
make

경고

표준이 아닌 -j 플래그는 현재 지원되지 않으므로, make -j 4로 빌드하거나 MAKEFLAGS를 예를 들어 -j 4를 포함하도록 설정하면 빌드가 깨질 가능성이 높습니다. 만약 MAKEFLAGS가 그렇게 설정되어 있고 이를 변경하고 싶지 않다면, make -j 1을 실행하여 이를 재정의할 수 있습니다.

다른 명령어를 알아보려면 Makefile을 확인하세요.

Go가 지원하는 모든 OS/ARCH(운영 체제/아키텍처)용으로 AdGuard Home을 빌드할 수 있습니다. 이를 위해 make를 실행할 때 GOOS 및 GOARCH 환경 변수를 매크로로 지정하십시오.

예시:

env GOOS='linux' GOARCH='arm64' make

또는:

make GOOS='linux' GOARCH='arm64'

릴리스 빌드(release build)를 준비하려면 snapcraft가 필요합니다. 설치가 완료되면 다음 명령어를 실행하세요:

make build-release CHANNEL='...' VERSION='...'

build-release 타겟 문서를 참조하세요.

로컬에서 Docker 이미지(우리가 DockerHub에 게시하는 이미지)를 빌드하려면 make build-docker를 실행하세요. 참고로, 우리는 공식 이미지를 빌드하기 위해 Docker Buildx를 사용하고 있습니다.

이 빌드들을 사용하기 전에 준비가 필요할 수 있습니다:

(Linux 전용) Qemu 설치:

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes --credential yes

빌더 (builder) 준비:

docker buildx create --name buildx-builder --driver docker-container --use

build-docker 타겟 문서를 참조하세요.

매번 프로덕션 (production) 버전을 다시 컴파일하지 않고 프론트엔드 (frontend)를 디버깅해야 할 때(예: 폼 (form)에서 라벨이 어떻게 보이는지 확인하려는 경우) 개발 환경에서 프론트엔드 빌드를 실행할 수 있습니다.

별도의 터미널에서 다음을 실행하세요:

( cd ./client/ && env NODE_ENV='development' npm run watch )

--local-frontend 플래그와 함께 AdGuardHome 바이너리를 실행하세요. 이 플래그는 AdGuard Home이 내장된 프론트엔드 파일을 무시하고 ./build/ 디렉토리의 파일을 사용하도록 지시합니다. -
이제 ./client/ 디렉토리에서 수행하는 모든 변경 사항은 다시 컴파일되어 웹 UI (web UI)에서 사용할 수 있게 됩니다. 실제로 재컴파일된 버전을 적용하려면 브라우저 캐시 (browser cache)를 비활성화해야 합니다.

AdGuard Home은 E2E (End-to-End) 테스트를 위해 Playwright를 사용합니다. 테스트는 tests/e2e에 위치합니다.

테스트 실행 (Running Tests):

npm run test:e2e
– 모든 테스트 실행 (headless).
npm run test:e2e:interactive
– 대화형 (interactively)으로 테스트 실행.
npm run test:e2e:debug
– 디버그 모드 (debug mode)에서 테스트 실행.
npm run test:e2e:codegen
– 새로운 테스트 코드 생성.

설정 (Setup):

• 의존성 (dependencies)을 설치하려면 npm install을 실행하세요.
• 필요한 브라우저를 설정하려면 npx playwright install을 실행하세요.

경고: Playwright는 테스트를 위해 자체 브라우저 바이너리 (browser binaries)를 다운로드하고 설치하며, 이는 시스템에 설치된 브라우저와 다를 수 있습니다.

이 리포지토리 (repository)를 포크 (fork)하여 변경 사항을 만들고 풀 리퀘스트 (pull request)를 제출하는 것을 환영합니다. 다만, 저희의 코드 가이드라인 (code guidelines)을 반드시 준수해 주세요.

참고로, 저희는 사람들이 프로그램의 UI와 백엔드 (backend) 부분을 동시에 기여할 것을 기대하지 않습니다. 이상적으로는 백엔드 부분, 즉 설정 (configuration), API, 그리고 기능 자체를 먼저 구현하는 것이 좋습니다. UI 부분은 나중에 다른 사람이 다른 풀 리퀘스트를 통해 구현할 수 있습니다.

사용할 수 있는 두 가지 업데이트 채널(update channels)이 있습니다:

beta
: AdGuard Home의 베타(beta) 버전입니다. 어느 정도 안정적인 버전이며, 보통 2주 또는 그보다 더 자주 출시됩니다. -
edge
: 개발 브랜치(development branch)에서 제공되는 가장 최신 버전의 AdGuard Home입니다. 새로운 업데이트가 매일 이 채널로 푸시됩니다.

불안정 버전(unstable version)을 설치하는 세 가지 방법이 있습니다:

• Snap Store: beta 및 edge 채널을 확인하세요. -
• Docker Hub: beta 및 edge 태그를 확인하세요. -
• 독립 실행형 빌드(Standalone builds): 자동 설치 스크립트를 사용하거나 Wiki에서 사용 가능한 빌드를 확인하세요.

베타 버전을 설치하는 스크립트:

curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -c beta

edge 버전을 설치하는 스크립트:

curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -c edge

문제가 발생하거나 제안 사항이 있다면, 이 페이지로 이동하여 “New issue” 버튼을 클릭하세요. 이슈 양식(issue form)의 지침을 주의 깊게 따라 주시고, 시작하기 전에 중복된 이슈가 있는지 검색하는 것을 잊지 마세요.

AdGuard Home 번역을 돕고 싶다면, 저희 지식 베이스(Knowledge Base)에서 AdGuard 제품 번역에 대해 더 자세히 알아보세요. CrowdIn에서 AdGuardHome 프로젝트에 기여할 수 있습니다.

기여할 수 있는 또 다른 방법은 help wanted로 표시된 이슈를 찾아, 해당 이슈를 맡아도 되는지 문의한 후, 버그를 수정하거나 기능을 구현하는 PR(Pull Request)을 보내는 것입니다.

이 프로젝트들은 AdGuard와 관련이 없으며, 제3자 개발자 및 팬들에 의해 만들어졌음을 유의해 주세요.

• AdGuard Home Remote: Joost가 만든 iOS 앱.
• OpenWrt LUCI 앱: @kongfl888 제작 (@rufengsuixing이 원작).
• @Lissy93이 만든 AdGuard Home 인스턴스용 터미널 기반 실시간 트래픽 모니터링 및 통계 도구.
• @jumpsmm7 (일명 @SomeWhereOverTheRainBow)의 Asuswrt-Merlin-AdGuardHome-Installer.

이 소프트웨어는 다음이 없었다면 불가능했을 것입니다:

• Go 및 관련 라이브러리:
• Node.js 및 관련 라이브러리:
• whotracks.me 데이터

이전에 CoreDNS가 여기서 언급된 것을 보셨을 수도 있지만, AdGuard Home에서는 더 이상 사용하지 않습니다.

사용 중인 모든 Node.js 패키지의 전체 목록은 client/package.json 파일을 확인해 주세요.

우리의 핵심 아이디어는 여러분이 자신의 데이터를 직접 제어해야 한다는 것입니다. 따라서 AdGuard Home이 사용 통계를 수집하지 않고, 여러분이 직접 설정하지 않는 한 어떠한 웹 서비스도 사용하지 않는 것은 당연한 결과입니다. AdGuard Home에 의해 이론적으로 전송될 수 있는 모든 부분이 명시된 전체 개인정보 처리방침(Privacy Policy)도 참조하시기 바랍니다.