AdGuard Home是一款全网广告拦截和追踪软件

您和您的设备的隐私保护中心

您和您的设备的隐私保护中心

AdGuard Home 是一款全网广告拦截和追踪软件。设置完成后，它将覆盖您所有的家用设备，无需任何客户端软件。

它作为 DNS 服务器运行，将追踪域名重新路由到“黑洞”，从而阻止您的设备连接到这些服务器。它基于我们用于公共 [AdGuard DNS] 服务器的软件，两者共享大量代码。

• 入门
  • 自动安装 (Linux/Unix/MacOS/FreeBSD/OpenBSD)
  • 替代方法
  • 指南
  • API
• AdGuard Home 与其他解决方案的比较
  • 这与公共 AdGuard DNS 服务器有何不同？
  • AdGuard Home 与 Pi-Hole 的比较
  • AdGuard Home 与传统广告拦截器的比较
  • 已知限制
• 如何从源代码构建
  • 先决条件
  • 构建
• 贡献
  • 测试不稳定版本
  • 报告问题
  • 翻译帮助
  • 其他
• 隐私

入门

自动安装 (Linux/Unix/MacOS/FreeBSD/OpenBSD)

使用 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 <channel> 使用指定渠道；
• -r 重新安装 AdGuard Home；
• -u 卸载 AdGuard Home；
• -v 显示详细输出。

请注意，选项 -r 和 -u 互斥。

其他方法

手动安装

请阅读我们 Wiki 上的 入门 文章，了解如何手动安装 AdGuard Home，以及如何配置您的设备以使用它。

Docker

您可以在 Docker Hub 上使用我们官方的 Docker 镜像。

Snap Store

如果您运行的是 Linux 系统，有一种安全便捷的安装 AdGuard Home 的方法：从 Snap Store 获取。

指南

查看我们的Wiki。

API

如果您想与 AdGuard Home 集成，可以使用我们的 REST API。或者，您可以使用这个 python 客户端，它用于构建 AdGuard Home Hass.io 插件。

AdGuard Home 与其他解决方案的比较

这与公共 AdGuard DNS 服务器有何不同？

运行您自己的 AdGuard Home 服务器比使用公共 DNS 服务器功能更强大。这是一个完全不同的级别。您可以亲自体验：

• 选择服务器阻止和允许的具体内容。

• 监控您的网络活动。

• 添加您自己的自定义过滤规则。

• 最重要的是，这是您自己的服务器，只有您才能控制它。

AdGuard Home 与 Pi-Hole 相比如何

目前，AdGuard Home 与 Pi-Hole 有很多共同之处。两者都使用所谓的“DNS sinkholing”方法拦截广告和跟踪器，并且都允许自定义拦截内容。

我们不会就此止步。DNS sinkholing 是一个不错的起点，但这仅仅是个开始。

AdGuard Home 提供了许多开箱即用的功能，无需安装和配置其他软件。我们希望它简单易用，即使是普通用户也能轻松完成设置。

可以通过安装其他软件或手动使用 SSH 终端并重新配置 Pi-Hole 包含的某个实用程序，将列出的部分功能添加到 Pi-Hole。然而，我们认为，这不能合法地算作 Pi-Hole 的功能。

AdGuard Home 与传统广告拦截器相比如何

视情况而定。

DNS sinkholing 能够拦截大量广告，但它缺乏传统广告拦截器的灵活性和强大功能。您可以通过阅读本文来了解这些方法之间的区别，本文将 Android 版 AdGuard（一款传统广告拦截器）与主机级广告拦截器（其功能与基于 DNS 的拦截器几乎相同）进行了比较。这种级别的保护对某些用户来说已经足够了。

此外，使用基于 DNS 的拦截器可以帮助拦截其他类型设备上的广告、跟踪和分析请求，例如智能电视、智能音箱或其他类型的物联网设备（您无法在这些设备上安装传统广告拦截器）。

已知限制

以下是一些 DNS 级拦截器无法拦截的内容示例：

• YouTube、Twitch 广告；

• Facebook、Twitter、Instagram 赞助帖子。

本质上，任何与内容共享域名的广告都无法被 DNS 级拦截器拦截。

未来有机会解决这个问题吗？DNS 永远不足以实现这一点。我们唯一的选择是使用内容拦截代理，就像我们在独立 AdGuard 应用程序中所做的那样。我们将在未来将此功能支持引入 AdGuard Home。遗憾的是，即使在这种情况下，仍然会存在这不够用或需要相当复杂的配置的情况。

如何从源代码构建

先决条件

运行 make init 准备开发环境。

构建 AdGuard Home 需要以下软件：

• Go v1.25 或更高版本；
• Node.js v20.19 或更高版本；
• npm v10.8 或更高版本；

Building

打开终端并执行以下命令：

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'

准备发布

您需要 snapcraft 来准备发布版本。安装后，运行以下命令：

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

请参阅 build-release 目标文档。

Docker 镜像

运行 make build-docker 在本地构建 Docker 镜像（我们将发布到 DockerHub 的镜像）。请注意，我们使用 Docker Buildx 来构建我们的官方镜像。

在使用这些构建版本之前，您可能需要进行以下准备：

-（仅限 Linux）安装 Qemu：

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

• 准备构建器：

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

请参阅 build-docker 目标文档。

调试前端

如果您需要调试前端，但又不想每次都重新编译生产版本，例如检查标签在表单上的显示效果，您可以运行前端构建开发环境。

1. 在单独的终端中运行：

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

2. 使用 --local-frontend 标志运行您的 AdGuardHome 二进制文件，该标志指示 AdGuard Home 忽略内置的前端文件，并使用 ./build/ 目录中的文件。

3. 现在，您在 ./client/ 目录中所做的任何更改都应重新编译并在 Web UI 上可用。请务必禁用浏览器缓存，以确保您确实获取到重新编译的版本。

端到端 (E2E) 前端测试

AdGuard Home 使用 Playwright 进行端到端测试。测试位于 tests/e2e 目录。

运行测试：

• npm run test:e2e – 运行所有测试（无头模式）。
• npm run test:e2e:interactive – 以交互方式运行测试。
• npm run test:e2e:debug – 以调试模式运行测试。
• npm run test:e2e:codegen – 生成新的测试代码。

设置：

1. 运行 npm install 安装依赖项。
2. 运行 npx playwright install 设置所需的浏览器。

警告： Playwright 将下载并安装其自带的浏览器二进制文件进行测试，这些二进制文件可能与您系统上安装的浏览器不同。

贡献

欢迎您 fork 此代码库，进行更改并提交拉取请求。请务必遵循我们的代码指南。

请注意，我们不希望人们同时为程序的 UI 和后端部分做出贡献。理想情况下，应首先实现后端部分，即配置、API 和功能本身。UI 部分可以稍后由其他人通过不同的拉取请求来实现。

测试不稳定版本

您可以使用两个更新渠道：

• beta：AdGuard Home 的 Beta 版本。这些版本或多或少比较稳定，通常每两周或更频繁地发布一次。

• edge：来自开发分支的 AdGuard Home 最新版本。新的更新每天都会推送到此渠道。

您可以通过三种方式安装不稳定版本：

1. Snap Store：查找 beta 和 edge 渠道。

2. Docker Hub：查找 beta 和 edge 标签。

3. 独立构建。使用自动安装脚本或查找 Wiki 上的可用版本。

安装 Beta 版本的脚本：

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

报告问题

如果您遇到任何问题或有任何建议，请前往此页面并点击“新问题”按钮。请仔细按照问题表单中的说明操作，并不要忘记先搜索重复问题。

翻译帮助

如果您想帮助 AdGuard Home 翻译，请在我们的知识库中了解更多关于 AdGuard 产品翻译的信息。您可以为CrowdIn 上的 AdGuardHome 项目做出贡献。

其他

您也可以通过查找标记为“help wanted”的问题来贡献自己的力量，询问该问题是否可提交，并发送 PR 来修复错误或实现相应功能。

隐私

我们的核心理念是，您才是真正掌控自己数据的人。因此，AdGuard Home 不会收集任何使用情况统计信息，也不会使用任何网络服务，除非您进行配置。另请参阅[完整的隐私政策][privacy]，了解 AdGuard Home 理论上可能发送的所有信息。