AdguardTeam/AdGuardHome
GitHub: AdguardTeam/AdGuardHome
一款开源的网络级 DNS 服务器，通过拦截广告与追踪域名来保护全网络设备的隐私与安全。
Stars: 33308 | Forks: 2285
Privacy protection center for you and your devices
Free and open source, powerful network-wide ads & trackers blocking DNS server.
AdGuard.com |
Wiki |
Reddit |
Twitter |
Telegram
AdGuard Home 是一款全网络范围的广告和跟踪拦截软件。设置完成后，它将覆盖您家里的所有设备，且无需安装任何客户端软件。
它作为 DNS 服务器运行，将跟踪域名重新路由到一个“黑洞”，从而阻止您的设备连接到这些服务器。它基于我们用于公共 [AdGuard DNS] 服务器的软件，两者共用大量代码。
- [入门指南](#getting-started)
- [自动安装](#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)
##
入门指南
###
自动安装
使用 `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` 详细输出。
请注意，选项 `-r` 和 `-u` 是互斥的。
### 其他安装方法
#### 手动安装
请阅读我们 Wiki 上的 **[Getting Started][wiki-start]** 文章，了解如何手动安装 AdGuard Home 以及如何配置您的设备使用它。
#### Docker
您可以使用我们在 [Docker Hub] 上的官方 Docker 镜像。
#### Snap Store
如果您正在运行 **Linux**，有一种安全且简便的方法安装 AdGuard Home：从 [Snap Store] 获取。
### 指南
请参阅我们的 [Wiki][wiki]。
### API
如果您想与 AdGuard Home 集成，可以使用我们的 [REST API][openapi]。或者，您也可以使用这个 [python client][pyclient]，它被用于构建 [AdGuard Home Hass.io Add-on][hassio]。
## AdGuard Home 与其他方案的对比
### 这与公共 AdGuard DNS 服务器有何不同？
运行您自己的 AdGuard Home 服务器比使用公共 DNS 服务器能做更多事情。这完全是不同的级别。请亲自看看：
- 选择服务器具体拦截和允许的内容。
- 监控您的网络活动。
- 添加您自己的自定义过滤规则。
- **最重要的是，这是您自己的服务器，您是唯一掌控它的人。**
### AdGuard Home 与 Pi-Hole 对比
目前，AdGuard Home 与 Pi-Hole 有很多共同点。两者都使用所谓的“DNS sinkholing”方法拦截广告和跟踪器，并且都允许自定义拦截内容。
AdGuard Home 开箱即用，提供了许多功能，无需安装和配置额外的软件。我们希望它简单易用，即使是普通用户也能以最小的精力完成设置。
| 功能 | AdGuard Home | Pi-Hole |
|-------------------------------------------------------------------------|-------------------|-----------------------------------------------------------|
| 拦截广告和跟踪器 | ✅ | ✅ |
| 自定义拦截列表 | ✅ | ✅ |
| 内置 DHCP 服务器 | ✅ | ✅ |
| 管理界面的 HTTPS | ✅ | 勉强可以，但您需要手动配置 lighttpd |
| 加密的 DNS 上游服务器 (DNS-over-HTTPS, DNS-over-TLS, DNSCrypt) | ✅ | ❌ (需要额外的软件) |
| 跨平台 | ✅ | ❌ (原生不支持，仅通过 Docker) |
| 作为 DNS-over-HTTPS 或 DNS-over-TLS 服务器运行 | ✅ | ❌ (需要额外的软件) |
| 拦截钓鱼和恶意软件域名 | ✅ | ❌ (需要非默认的拦截列表) |
| 家长控制（拦截成人域名） | ✅ | ❌ (需要非默认的拦截列表) |
| 强制搜索引擎使用安全搜索 | ✅ | ❌ |
| 针对单个客户端（设备）的配置 | ✅ | ✅ |
| 访问设置（选择谁可以使用 AGH DNS） | ✅ | ❌ |
| [无 root 权限运行][wiki-noroot] | ✅ | ❌ |
### AdGuard Home 与传统广告拦截器对比
这取决于具体情况。
DNS sinkholing 能够拦截很大一部分广告，但它缺乏传统广告拦截器的灵活性和功能。通过阅读[这篇文章][blog-adaway]，您可以对这些方法之间的区别有一个很好的了解，该文章比较了 AdGuard for Android（一种传统广告拦截器）与主机级别的广告拦截器（在功能上几乎与基于 DNS 的拦截器相同）。对于某些用户来说，这种级别的保护已经足够了。
此外，使用基于 DNS 的拦截器可以帮助拦截其他类型设备上的广告、跟踪和分析请求，例如智能电视、智能音箱或其他类型的 IoT 设备（在这些设备上您无法安装传统的广告拦截器）。
### 已知的限制
以下是一些 DNS 级别拦截器无法拦截的示例：
- YouTube、Twitch 广告；
- Facebook、Twitter、Instagram 赞助帖子。
本质上，任何与内容共享同一个域名的广告都无法被 DNS 级别的拦截器拦截。
未来有机会处理这个问题吗？ DNS 永远不足以完成这项工作。我们唯一的选择是使用内容拦截代理，就像我们在独立的 AdGuard 应用程序中所做的那样。我们计划在将来[引入][issue-1228]此功能支持到 AdGuard Home。不幸的是，即使在这种情况下，仍然会有不够用或需要相当复杂的配置的情况。
## 如何从源代码构建
### 前置条件
运行 `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 或更高版本；
### 构建
打开您的终端并执行以下命令：
```
git clone https://github.com/AdguardTeam/AdGuardHome
cd AdGuardHome
make
```
查看 [`Makefile`][src-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` 目标文档][targ-release]。
#### Docker 镜像
运行 `make build-docker` 以在本地构建 Docker 镜像（即我们发布到 DockerHub 的那个）。请注意，我们使用 [Docker Buildx][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` 目标文档][targ-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](https://playwright.dev) 进行 E2E 测试。测试位于 `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` 设置所需的浏览器。
## 贡献
欢迎您 Fork 本仓库，进行更改并[提交 Pull Request][pr]。不过，请确保遵循我们的[代码指南][guide]。
请注意，我们不期望人们同时为程序的 UI 和后端部分做出贡献。理想情况下，后端部分首先实现，即配置、API 和功能本身。UI 部分可以稍后由其他人在不同的 Pull Request 中实现。
### 测试不稳定版本
您可以使用两个更新频道：
- `beta`: AdGuard Home 的测试版。相对稳定的版本，通常每两周或更频繁地发布一次。
- `edge`: 来自开发分支的最新版 AdGuard Home。新更新每天推送到此频道。
有三种安装不稳定版本的方法：
1. [Snap Store]: 查找 `beta` 和 `edge` 频道。
2. [Docker Hub]: 查找 `beta` 和 `edge` 标签。
3. 独立构建。使用自动安装脚本或在 [Wiki][wiki-platf] 上查找可用的构建。
安装 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
### 报告问题
如果您遇到任何问题或有建议，请前往[此页面][iss]并点击“New issue”按钮。请仔细遵循问题表单中的说明，不要忘记先搜索是否有重复的问题。
### 帮助翻译
如果您想帮助翻译 AdGuard Home，请在我们[知识库][kb-trans]中了解更多关于翻译 AdGuard 产品的信息。您可以参与 [CrowdIn 上的 AdGuardHome 项目][crowdin]。
### 其他
您可以做出贡献的另一种方式是[查找][iss-help]标记为 `help wanted` 的问题，询问该问题是否可以认领，并发送修复错误或实现功能的 PR。
## 使用 AdGuard Home 的项目
请注意，这些项目不隶属于 AdGuard，而是由第三方开发者和粉丝制作的。
- [AdGuard Home Remote](https://apps.apple.com/app/apple-store/id1543143740): [Joost](https://rocketscience-it.nl/) 开发的 iOS 应用。
- [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) 开发。
- [Terminal-based, real-time traffic monitoring and statistics for your AdGuard Home instance](https://github.com/Lissy93/AdGuardian-Term) 由 [@Lissy93](https://github.com/Lissy93) 开发
- [AdGuard Home on GLInet routers](https://forum.gl-inet.com/t/adguardhome-on-gl-routers/10664) 由 [Gl-Inet](https://gl-inet.com/) 开发。
- [Cloudron app](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 library](https://github.com/Andrea055/AdguardHomeAPI) 由 [@Andrea055](https://github.com/Andrea055/) 开发。
- [Browser Extension](https://github.com/satheshshiva/Adguard-Home-Browser-Ext) 由 [@satheshshiva](https://github.com/satheshshiva/) 开发。
- [Zabbix Template for AdGuard Home](https://github.com/diasdmhub/AdGuard_Home_Zabbix_Template) 由 [@diasdmhub](https://github.com/diasdmhub) 开发。
- [Chocolatey package](https://community.chocolatey.org/packages/adguardhome/) 由 [niks255](https://community.chocolatey.org/profiles/niks255) 开发。
## 致谢
如果没有以下软件，这个软件是不可能实现的：
- [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 data](https://github.com/cliqz-oss/whotracks.me)
您可能之前看到这里提到过 [CoreDNS]，但我们已经停止在 AdGuard Home 中使用它。
有关所有正在使用的 Node.js 包的完整列表，请查看 [`client/package.json`][src-packagejson] 文件。
## 隐私
我们的主要理念是您应该是控制您数据的人。因此，AdGuard Home 不收集任何使用统计数据，也不使用任何 Web 服务，除非您配置它这样做。另请参阅[完整的隐私政策][privacy]，其中包含 AdGuard Home *理论上可能发送*的每一位数据。
标签：AdGuard Home, DNS sinkhole, DNS 服务器, DNS 过滤, DNS 隐私, Docker, DoH, DoT, EVTX分析, Go 语言, MITM代理, tracker, 互联网安全, 去广告, 反跟踪, 安全防御评估, 家庭网络, 家长控制, 广告拦截, 恶意软件拦截, 日志审计, 流量过滤, 网络安全, 网络安全, 网络广告, 网络追踪, 自托管, 请求拦截, 路由器, 防追踪, 隐私保护, 隐私保护
