AdGuard Home 日常运维手册

目标：本文面向已按标准流程部署 AdGuard Home v0.107.79 并投入日常使用的运维人员，覆盖服务巡检、配置与数据备份恢复、健康监控告警、容量调整、版本升级回滚与典型故障排查六类运维场景，全部命令与回显已在 Ubuntu 22.04 + systemd 托管的 v0.107.79 环境实测通过。

一、环境信息

本章列明本手册实测环境基准，所有命令与回显均基于此环境。

操作系统：Ubuntu 22.04（amd64）
AdGuard Home 版本：v0.107.79（/opt/AdGuardHome/AdGuardHome --version 实测输出 AdGuard Home, version v0.107.79）
服务托管：systemd 服务（服务单元 /etc/systemd/system/AdGuardHome.service，开机自启 enabled）
程序目录：/opt/AdGuardHome/（二进制 AdGuardHome 约 36MB，主配置 AdGuardHome.yaml，数据目录 data/）
服务监听：DNS *:53（UDP/TCP）、Web 管理 *:3000（实测 ss -lntup 确认三种监听全部 LISTEN/UNCONN）
管理账号：admin（示例密码 q1w2e3r4，REST API 登录后以 Cookie 调用 /control/ 接口）
数据现状（实测 du -sh /opt/AdGuardHome/data/）：4.4M（含过滤器缓存 filters/、查询日志 querylog.json、统计库 stats.db、会话库 sessions.db）

二、日常巡检

日常巡检的目标是「在用户投诉之前发现故障」。建议每日执行一轮以下命令组，全部命令本机即可完成。

2.1 服务与端口巡检

确认服务运行中且开机自启、监听端口完整：

systemctl is-active AdGuardHome && systemctl is-enabled AdGuardHome

实测输出：

active
enabled

systemctl status AdGuardHome --no-pager -l | head -7

实测输出（输出节选，CGroup 详情行略）：

● AdGuardHome.service - AdGuard Home: Network-level blocker
     Loaded: loaded (/etc/systemd/system/AdGuardHome.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-18 07:27:06 UTC; 3h 7min ago
   Main PID: 3234 (AdGuardHome)
     Tasks: 17 (limit: 5753)
     Memory: 49.1M
        CPU: 2.887s

要点解读：Memory: 49.1M 为长时间运行的典型占用（DNS 代理属轻量服务）；Active: active (running) 且运行时长连续无重启记录说明服务稳定。端口监听核对：

ss -lntup | grep AdGuardHome

实测输出：

udp   UNCONN 0      0                  *:53              *:*    users:(("AdGuardHome",pid=3234,fd=6))
tcp   LISTEN 0      4096               *:53              *:*    users:(("AdGuardHome",pid=3234,fd=12))
tcp   LISTEN 0      4096               *:3000            *:*    users:(("AdGuardHome",pid=3234,fd=10))

三条监听缺一不可：UDP 53（普通解析）、TCP 53（大响应/区域传输）、TCP 3000（管理界面）。

2.2 解析与拦截功能巡检

解析功能巡检（正常域名应返回 IP，且第二次查询应命中缓存明显变快）：

dig @127.0.0.1 www.baidu.com +noall +answer

实测输出：

www.baidu.com.          1132    IN      CNAME   www.a.shifen.com.
www.a.shifen.com.       52      IN      A       110.242.69.21
www.a.shifen.com.       52      IN      A       110.242.70.57

拦截功能巡检（用已列入黑名单规则的域名验证拦截引擎在工作）：

dig @127.0.0.1 doubleclick.net +noall +answer

实测输出（0.0.0.0 且 TTL 10 为正常拦截）：

doubleclick.net.        10      IN      A       0.0.0.0

⚠️ 若该域名返回真实 IP，说明拦截规则或保护开关被变更，按「七、故障排查手册」7.3 节处理。

2.3 日志与资源巡检

进程日志巡检（确认无持续 error 刷屏）：

journalctl -u AdGuardHome --since "-1 hour" --no-pager -o cat | grep -i error | tail -3

实测输出（健康状态下无 error 行，命令无输出）：

数据目录占用巡检：

du -sh /opt/AdGuardHome/data/ /opt/AdGuardHome/data/filters/

实测输出：

4.4M    /opt/AdGuardHome/data/
4.2M    /opt/AdGuardHome/data/filters/

要点解读：过滤器缓存约 4.2MB（AdGuard DNS filter 单列表实测 186,044 条规则）属正常水位；data/ 总量随查询日志保留期（querylog.interval）线性增长，磁盘紧张时按 7.4 节清理。

三、备份与恢复

DNS 是全网关键服务，配置与数据必须可快速恢复。本章给出实测过的备份与恢复全流程。

3.1 备份范围

对象	路径	说明
主配置	`/opt/AdGuardHome/AdGuardHome.yaml`	全部运行配置（含账号哈希、上游、规则开关）
运行数据	`/opt/AdGuardHome/data/`	过滤器缓存、查询日志、统计库、会话库
二进制	`/opt/AdGuardHome/AdGuardHome`	可选；随时可从官方发布包重取，一般不备份

最小备份集合是 AdGuardHome.yaml + data/，一条 tar 完成。

3.2 手工备份（实测）

mkdir -p /opt/backup
tar czf /opt/backup/adguardhome-2026-10-18.tar.gz -C /opt/AdGuardHome AdGuardHome.yaml data
ls -lh /opt/backup/

实测输出：

total 1.5M
-rw-r--r-- 1 root root 1.5M Oct 18 10:35 adguardhome-2026-10-18.tar.gz

说明：运行中备份可用（tar 读取顺序一致），但查询日志可能缺最后几秒写入；严格一致性场景先 systemctl stop AdGuardHome 再备份。建议每日 cron 打包并异地转存。

3.3 恢复演练（实测）

本节完整演练「备份 → 配置漂移 → 从备份恢复 → 验证回滚」闭环。第一步确认备份时点规则基线：

grep -A2 "^user_rules:" /opt/AdGuardHome/AdGuardHome.yaml

实测输出：

user_rules:
  - '||doubleclick.net^'

第二步制造配置漂移（模拟误操作，通过 API 追加一条规则）：

curl -s -b /tmp/ah-cookie.txt -X POST http://127.0.0.1:3000/control/filtering/set_rules \
  -H 'Content-Type: application/json' \
  -d '{"rules":["||doubleclick.net^","||backup-test.example^"]}' -w ' HTTP:%{http_code}\n'

实测输出（规则已漂移为两条）：

 HTTP:200
user_rules:
  - '||doubleclick.net^'
  - '||backup-test.example^'

第三步停服、用备份覆盖、启动：

systemctl stop AdGuardHome && echo "stop: ok"
tar xzf /opt/backup/adguardhome-2026-10-18.tar.gz -C /opt/AdGuardHome
systemctl start AdGuardHome && systemctl is-active AdGuardHome

实测输出：

stop: ok
active

第四步验证恢复效果——配置精确回到备份时点（漂移的规则消失、原拦截功能正常）：

grep -A2 "^user_rules:" /opt/AdGuardHome/AdGuardHome.yaml | head -2
dig @127.0.0.1 doubleclick.net +noall +answer

实测输出：

user_rules:
  - '||doubleclick.net^'
doubleclick.net.        10      IN      A       0.0.0.0

3.4 跨机迁移说明

把上述 tar 包解到新机器的 /opt/AdGuardHome/、安装同版本程序并接管服务单元即可，AdGuardHome.yaml 中的监听地址（dns.bind_hosts、http.address）需按新机网卡调整。迁移后 dig 与 Web 登录双验证。

四、监控告警

4.1 健康探测脚本（实测可用）

以下脚本检查「服务运行 → DNS 可解析 → Web 可达」三层，任一层失败输出告警并以非零退出码结束，可直接接入 cron 或告警通道。落地为 /opt/adguard-monitor.sh：

#!/bin/bash
# AdGuard Home 健康探测：异常时输出告警并返回非零退出码（可接入 cron）
SERVICE=AdGuardHome
TEST_DOMAIN=www.baidu.com

systemctl is-active --quiet "$SERVICE" || { echo "ALERT: $SERVICE 服务未运行"; exit 1; }
dig @127.0.0.1 "$TEST_DOMAIN" +time=2 +tries=1 +short | grep -qE "^[0-9a-f.:]+$" || { echo "ALERT: DNS 解析异常"; exit 2; }
curl -sf -o /dev/null http://127.0.0.1:3000/login.html || { echo "ALERT: Web 管理不可达"; exit 3; }
echo "OK: 服务、DNS 解析、Web 管理均正常"

实测运行：

/opt/adguard-monitor.sh

实测输出：

OK: 服务、DNS 解析、Web 管理均正常

接入 cron 示例（每 5 分钟探测一次，grep -q ALERT 时触发外部告警通道）：

*/5 * * * * /opt/adguard-monitor.sh | grep -q ALERT && /usr/local/bin/send-alert.sh "AdGuard Home 异常"

4.2 状态与统计 API 监控

管理 API 提供机器可读的运行状态（需先登录取 Cookie，见《AdGuard Home 0.107.79 配置参数详解》第二章）：

curl -s -b /tmp/ah-cookie.txt http://127.0.0.1:3000/control/status

实测输出（节选）：

{
    "version": "v0.107.79",
    "dns_port": 53,
    "http_port": 3000,
    "protection_enabled": true,
    "running": true
}

running: true、protection_enabled: true 双真为健康态；统计接口 GET /control/stats 返回当日查询量、被拦域名 Top 等聚合数据（GET /control/stats_info 实测返回 {"interval":7} 即统计窗口 7 天），可用于绘制趋势看板。

4.3 日志级异常监控

对进程日志做关键词监控，以下两类日志行出现即代表上游故障（实测样例见 7.2 节）：

journalctl -u AdGuardHome --since "-10 min" --no-pager -o cat | grep -c "exchange failed"

实测输出（健康状态下为 0）：

五、扩容缩容

5.1 缓存扩容（实测）

客户端增多、解析延迟敏感时，把内存缓存从默认 4MB 扩到 16MB。通过 API 修改即时生效：

curl -s -b /tmp/ah-cookie.txt -X POST http://127.0.0.1:3000/control/dns_config \
  -H 'Content-Type: application/json' -d '{"cache_size":16777216}' -w ' HTTP:%{http_code}\n'

实测输出：

 HTTP:200

生效验证（进程日志即时打印新缓存大小）：

journalctl -u AdGuardHome --since "-30 sec" --no-pager -o cat | grep "cache enabled"

实测输出：

2026/10/18 10:37:34.105915 [info] dnsproxy: cache enabled size=16777216

缩容同理改回 4194304 即可；16MB 缓存对 4GB 内存的机器无压力，占用增长主要来自查询日志而非缓存。

5.2 日志与统计保留期调整

查询日志与统计的保留期决定磁盘占用与可追溯范围，API 调整即时生效：

curl -s -b /tmp/ah-cookie.txt -X POST http://127.0.0.1:3000/control/querylog_config \
  -H 'Content-Type: application/json' -d '{"enabled":true,"interval":168,"anonymize_client_ip":false}' -w ' HTTP:%{http_code}\n'

说明：interval 单位为小时（168 即 7 天，720 即 30 天）；统计窗口对应 POST /control/stats_config（interval 单位天，实测 GET /control/stats_info 返回 {"interval":7}）。调整后 GET /control/querylog_info 复核。

5.3 并发与文件描述符参数

客户端规模上千或遭遇解析高峰时调整两个参数：dns.max_goroutines（并发处理协程数，默认 300）经 POST /control/dns_config 调整；os.rlimit_nofile（文件描述符上限，默认跟随系统）在 AdGuardHome.yaml 中设置后重启服务生效。反向缩容（资源受限小机器）可把 max_goroutines 降到 100 并将 querylog.size_memory 从 1000 降到 200。

六、升级与回滚

6.1 查询最新稳定版本

不硬编码版本号，用官方发布页重定向实测获取（不消耗 API 配额）：

curl -sI https://github.com/AdguardTeam/AdGuardHome/releases/latest | grep -i "^location"

实测输出：

location: https://github.com/AdguardTeam/AdGuardHome/releases/tag/v0.107.79

URL 末尾 v0.107.79 即当前最新稳定版。生产环境跟随 0.107.x 稳定通道，勿使用 beta/edge。

6.2 升级步骤（实测）

以升级（重装）到 v0.107.79 为例演示完整流程，升级到未来版本只需替换下载 URL 与 tag。

第一步，下载官方包并用官方 checksums.txt 校验完整性：

export https_proxy=http://192.168.1.62:7897
mkdir -p /opt/upgrade && cd /opt/upgrade
wget -q https://github.com/AdguardTeam/AdGuardHome/releases/download/v0.107.79/AdGuardHome_linux_amd64.tar.gz
wget -q https://github.com/AdguardTeam/AdGuardHome/releases/download/v0.107.79/checksums.txt
grep linux_amd64.tar.gz checksums.txt && sha256sum AdGuardHome_linux_amd64.tar.gz

实测输出（两行哈希一致即通过校验）：

c48f4a43000665484c5ec28177de11a004759b620dae8f77b2aabefc9ef3687f  ./AdGuardHome_linux_amd64.tar.gz
c48f4a43000665484c5ec28177de11a004759b620dae8f77b2aabefc9ef3687f  AdGuardHome_linux_amd64.tar.gz

⚠️ 内网无代理出口时，先在能联网的机器下载上述两个文件再内网传输，校验步骤不变。

第二步，停服、备份旧二进制、覆盖：

systemctl stop AdGuardHome
cd /opt/upgrade && tar xzf AdGuardHome_linux_amd64.tar.gz
cp /opt/AdGuardHome/AdGuardHome /opt/AdGuardHome/AdGuardHome.v0.107.79.bak
cp AdGuardHome/AdGuardHome /opt/AdGuardHome/AdGuardHome

第三步，启动并验证版本与功能：

systemctl start AdGuardHome && systemctl is-active AdGuardHome
/opt/AdGuardHome/AdGuardHome --version
dig @127.0.0.1 doubleclick.net +noall +answer

实测输出：

active
AdGuard Home, version v0.107.79
doubleclick.net.        10      IN      A       0.0.0.0

AdGuardHome.yaml 与 data/ 在升级中不动，规则、日志、统计全部保留（实测拦截行为升级后一致）。

6.3 回滚

升级后异常时回滚到旧版：停服 → 用 AdGuardHome.v0.107.79.bak 覆盖回 /opt/AdGuardHome/AdGuardHome → 启动 → 版本复核。若新版本启动时自动迁移过配置格式（schema_version 升级），旧版程序可能拒绝读取新格式配置——所以升级前的 AdGuardHome.yaml 备份（3.2 节）是回滚的必要前提，回滚时一并恢复旧配置文件。

七、故障排查手册

7.1 启动失败：53 端口被占用

现象：服务无法启动，或手工测试运行时报错（实测复现：另起一个实例抢 53 端口时）：

[error] failed to bind to port 53; binding to port 53 is required for a dns server err="listen tcp 127.0.0.1:53: bind: address already in use"

定位：查占用者：

ss -lntup | grep ":53 "

Ubuntu 22.04 最常见占用者是系统自带的 systemd-resolved（stub 监听 127.0.0.53:53）。处理分两种情况：

stub 仅绑 127.0.0.53 时不阻塞 AdGuard Home 绑定 0.0.0.0:53，无需处理（本手册实测环境即如此，服务正常监听 *:53）；
若系统改为通配监听 0.0.0.0:53（如某些自定义 resolv 配置），编辑 /etc/systemd/resolved.conf 设置 DNSStubListener=no，systemctl restart systemd-resolved 后再启动 AdGuard Home。⚠️ 改动前先确认 /etc/resolv.conf 的 nameserver 指向，避免远程服务器解析失联。

7.2 全部解析超时：上游故障

现象：dig @127.0.0.1 任意域名 超时（实测复现：把上游改为不可达地址 10.255.255.1）：

;; communications error to 127.0.0.1#53: timed out
;; no servers could be reached

进程日志出现明确的交换失败记录（实测 journalctl 节选）：

[error] dnsproxy: response received upstream_type=main addr=10.255.255.1:53 proto=udp status="exchanging with 10.255.255.1:53 over udp: read udp 10.0.0.4:48652->10.255.255.1:53: i/o timeout"
[error] dnsproxy: exchange failed upstream=10.255.255.1:53 question=";www.baidu.com.	 IN	 A" duration=20.000904235s err="exchanging with 10.255.255.1:53 over udp: read udp 10.0.0.4:48652->10.255.255.1:53: i/o timeout"

定位三步：其一 GET /control/dns_info 查看当前上游列表是否被改坏（本例 10.255.255.1）；其二用 dig @223.5.5.5 www.baidu.com 直接测上游连通性；其三检查服务器自身出网（ping 223.5.5.5）。修复即恢复可达上游（实测恢复后查询立刻正常，应答 NOERROR）：

curl -s -b /tmp/ah-cookie.txt -X POST http://127.0.0.1:3000/control/dns_config \
  -H 'Content-Type: application/json' \
  -d '{"upstream_dns":["223.5.5.5","119.29.29.29","https://dns.alidns.com/dns-query"],"bootstrap_dns":["223.5.5.5","119.29.29.29"]}' -w ' HTTP:%{http_code}\n'

实测输出：

 HTTP:200

⚠️ 新初始化实例默认上游为国外 DoH（Quad9），国内网络不可达，症状与本次故障完全一致——首次部署后请立即按此方法切换国内上游。

7.3 拦截规则不生效

现象：已设置拦截规则的域名仍返回真实 IP。

排查三步（每步实测可行）：

查保护总开关：GET /control/status 中 "protection_enabled": true；
查过滤引擎开关与规则列表：GET /control/filtering/status 的 user_rules 应包含目标规则；
本机复测：dig @127.0.0.1 doubleclick.net +short 应为 0.0.0.0。

若第 2 步发现过滤被整体关闭（filtering_enabled: false），恢复开关后拦截立即生效（实测对比：关闭时 doubleclick.net 返回真实 IP 142.251.45.142，开启后恢复 0.0.0.0）：

curl -s -b /tmp/ah-cookie.txt -X POST http://127.0.0.1:3000/control/filtering/config \
  -H 'Content-Type: application/json' -d '{"enabled":true}' -w ' HTTP:%{http_code}\n'

实测输出：

 HTTP:200

若本机拦截正常而终端设备不拦，是终端 DNS 未指向本机或终端系统缓存未刷（Windows 用 ipconfig /flushdns）。

7.4 查询日志与统计的磁盘回收

现象：data/ 目录持续增长（查询日志 querylog.json 随时间线性膨胀）。

在线清理（立即回收，实测接口返回 200 且日志文件被删除、统计库重置）：

curl -s -b /tmp/ah-cookie.txt -X POST http://127.0.0.1:3000/control/querylog_clear -w ' QUERYLOG_CLEAR:%{http_code}\n'
curl -s -b /tmp/ah-cookie.txt -X POST http://127.0.0.1:3000/control/stats_reset -w ' STATS_RESET:%{http_code}\n'
ls -la /opt/AdGuardHome/data/querylog.json /opt/AdGuardHome/data/stats.db

实测输出：

 QUERYLOG_CLEAR:200
 STATS_RESET:200
ls: cannot access '/opt/AdGuardHome/data/querylog.json': No such file or directory
-rw------- 1 root root 16384 Oct 18 10:37 /opt/AdGuardHome/data/stats.db

长效治理：调小 querylog.interval（5.2 节）从保留期上控制增长；清空查询日志不影响过滤规则与统计配置。

八、常见问题

Q1：巡检发现 Memory 占用持续上涨正常吗？ 轻量增长（几十 MB 级）来自缓存与日志内存区（querylog.size_memory 条目），属正常；数百 MB 级异常增长时检查 querylog.size_memory 是否被调得过大，以及 journalctl 是否有错误刷屏。

Q2：systemctl restart 后规则、统计会丢吗？ 不会。规则与全部运行配置在 AdGuardHome.yaml，统计在 data/stats.db，查询日志在 data/querylog.json，均独立于进程生命周期（本文 3.3 节恢复演练实测重启后规则与拦截行为完整）。

Q3：升级前必须备份什么？ 最低限度备份 /opt/AdGuardHome/AdGuardHome.yaml（3.2 节 tar 包已含）。原因：新版可能自动升级配置格式（schema_version），旧版程序读不了新格式，回滚时需连配置一起还原（6.3 节）。

Q4：如何确认升级包没有被篡改？ 同时下载官方 checksums.txt，grep 目标文件名比对本地 sha256sum 输出，两行哈希一致方可使用（6.2 节实测一致通过）。

Q5：暂停过滤做对比测试，之后怎么恢复？ Web 界面「暂停保护」或 POST /control/filtering/config {"enabled":false} 临时关闭；对比结束后再传 {"enabled":true} 恢复（7.3 节实测开关瞬时生效）。计划性暂停可用 filtering.protection_disabled_until 定时自动恢复。

九、参考链接

官方仓库与文档首页：https://github.com/AdguardTeam/AdGuardHome
官方 Getting Started：https://adguard-dns.io/kb/adguard-home/getting-started/
官方发布页（版本与校验文件）：https://github.com/AdguardTeam/AdGuardHome/releases
REST API 规范（/control/ 接口定义）：https://github.com/AdguardTeam/AdGuardHome/tree/master/openapi
本专栏配套文档：《AdGuard Home 0.107.79 介绍与选型指南》、《AdGuard Home Docker Compose 部署指南》、《AdGuard Home 0.107.79 配置参数详解》