 安装教程 —— 把安卓机顶盒变成「去广告 DNS 盒子」（旁路由 / AdGuard Home）

 OpenHW Lab · 智能硬件开放实验室 · 面向普通用户 / 开发者。约 30–50 分钟。
 用一台吃灰的安卓机顶盒，做成一台 局域网 DNS 服务器：全家设备自动去广告、防跟踪，
 一次配置、全屋生效，手机/电视/电脑都干净。进阶可当"旁路由"。
 本项目在 B860AV1.1-T2（中兴微 ZX296715 / Android 7.1 / armv8）实测通过。

---

 0. 你需要

- 一台已 root 的安卓机顶盒（能开 ADB；不刷机）。
- 已搭好的 Linux 子系统（chroot Ubuntu）（参见系列其它教程 / 系统改造手册）。
- 电脑一台（装 adb；用 SSH 也行）。
- 路由器能改 DHCP 的 DNS（把下发的 DNS 指到盒子）。

 总思路：子系统里跑 AdGuard Home（DNS :53 + 管理页 :3000），
 把它的上游 DNS 改成 TCP（老盒子 UDP 常被封）、加广告过滤列表；
 再把家里路由器的 DHCP DNS 指向盒子 → 全家生效。

---

 1. 认清你的盒子（1 分钟）

    getprop ro.product.cpu.abi     # armv7 / arm64（决定下哪个 AdGuard 包）
    getprop ro.build.version.release
    free -m | head -2
 AdGuard Home 是单文件二进制，很轻，1G 内存的盒子跑它无压力。

---

 2. 控制通道（ADB / SSH）

盒子开「ADB 调试」→ 电脑：
    adb connect <盒子IP>:5555 && adb devices
    # 或：ssh root@<盒子IP>   （登录即进子系统）

---

 3. 取 AdGuard Home

AdGuard Home 只有 https 下载，而老盒子子系统常只通 HTTP/80 → 在电脑上下好再传进盒子：

    # 电脑上（有 https）：到 github.com/AdguardTeam/AdGuardHome/releases 下
    #   AdGuardHome_linux_arm64.tar.gz   （armv7 盒子用 ..._linux_armv7.tar.gz）
    # 传进子系统 /root：
    adb push AdGuardHome_linux_arm64.tar.gz /data/linux/root/adg.tgz
    # 或 scp AdGuardHome_linux_arm64.tar.gz root@<盒子IP>:/root/adg.tgz

盒子子系统里解压：
    cd /root && tar xzf adg.tgz && ls AdGuardHome/
    ./AdGuardHome/AdGuardHome --version

---

 4. 首次配置（用 API 免网页向导）

先后台跑起来（首次是"设置模式"，只开 :3000）：
    cd /root/AdGuardHome && nohup ./AdGuardHome >/root/adg.log 2>&1 &

用 安装文件/adg_setup.py 一步配置（web :3000 / dns :53 / 管理员）：
    scp 安装文件/adg_setup.py root@<盒子IP>:/root/
    ssh root@<盒子IP> "python3 /root/adg_setup.py 你的密码"
（脚本等价于向 POST /control/install/configure 提交配置。）

---

 5. ⭐ 把上游 DNS 改成 TCP（关键！）

老盒子子系统里 UDP 常被封（DNS 查询发不出去）→ 必须用 TCP 上游，否则解析超时：

    scp 安装文件/adg_upstream.py root@<盒子IP>:/root/
    ssh root@<盒子IP> "python3 /root/adg_upstream.py 你的密码"
它把上游设为 tcp://223.5.5.5 / tcp://119.29.29.29 / tcp://114.114.114.114。

验证（在电脑上查盒子）：
    nslookup example.com <盒子IP>
能解析出地址就说明 DNS 服务通了。

---

 6. 加广告过滤列表

AdGuard 的默认列表是 https（老盒子下不了）。用 http 列表：
    scp 安装文件/adg_filters.py root@<盒子IP>:/root/
    ssh root@<盒子IP> "python3 /root/adg_filters.py 你的密码"
默认加了两个 http 列表：pgl.yoyo.org（≈3500 条）+ someonewhocares.org（≈1.3 万条）。

验证拦截：
    nslookup doubleclick.net <盒子IP>     # 应返回 0.0.0.0（被拦）
    nslookup example.com   <盒子IP>       # 应正常解析

---

 7. 设为"全家 DNS"

把路由器的 DHCP 设置里，下发的 DNS 改成盒子的 IP（如 192.168.31.161）。
这样家里所有设备（手机/电视/电脑）自动用盒子做 DNS → 全屋去广告。

- 只做 DNS（推荐起步）：改 DHCP DNS 即可。
- 完整旁路由（可选进阶）：再把设备网关也指向盒子（盒子做转发/分流）——需更多网络配置。

 ⚠️ 盒子是 DNS 单点：建议在路由器里设备用 DNS（如 223.5.5.5），以防盒子关机时断解析。
 ⚠️ 部分 App 用硬编码 IP/DoH 绕过 DNS，拦不到；视频前贴片/YouTube 广告也拦不全。

---

 8. 开机自启

把 安装文件/3-开机自启.sh 并入子系统的启动链（拉起 AdGuard Home）：
    # 3-开机自启.sh 内容要点：
    pgrep -f "[A]dGuardHome" >/dev/null || ( cd /root/AdGuardHome && nohup ./AdGuardHome >/root/adg.log 2>&1 & )
4-开机兜底.sh 是盒子侧（Android）挂载+启动脚本模板，按你盒子的启动链放置。

重启一次验证：盒子重启后能继续解析（nslookup 到盒子）。

---

 9. 使用 / 管理

| 用途 | 地址 |
|---|---|
| AdGuard Home 管理页（看拦截统计/规则/设备） | http://<盒子IP:3000/（账号 admin / 你设的密码） |
| DNS 服务 | <盒子IP:53（路由器 DHCP 指向它） |

管理页可看：总查询量、拦截比例、拦截排行、每台设备的查询、被拦域名；也能加/减规则、设家长控制。

---

 10. 恢复 / 卸载

不刷机、不改固件，全部可逆：
- 停服务：pkill -f AdGuardHome
- 路由器 DHCP 的 DNS 改回原样（或自动获取）
- 删 /root/AdGuardHome 与启动脚本里那行即可。

---

 有问题先看 常见问题.md。更多见 开发者资料/（系统改造手册 / 关键坑与经验 / 源码）。
 本项目开源（MIT）——OpenHW Lab · openhwlab.com
