AdGuard Home 0.107.79 配置参数详解

AdGuard Home v0.107.79 配置参数详解：以实测 AdGuardHome.yaml（schema 34）逐段详解 http/dns/tls/querylog/statistics/filters/filtering/clients 核心参数，含 API 即时改参与生效验证、限流与缓存实测、生产配置模板

AdGuard HomeAdGuard HomeDNS 服务2026/10/18

AdGuard Home 0.107.79 配置参数详解

目标：本文面向已完成 AdGuard Home v0.107.79 部署、需要精细调整其行为的读者，以 Ubuntu 22.04 实测环境生成的 /opt/AdGuardHome/AdGuardHome.yaml（schema_version 34）为基准，逐段逐项详解 http、dns、tls、querylog、statistics、filters、filtering、clients 等核心配置段的参数含义、默认值与修改方式，并给出参数生效验证方法与生产配置模板，全部命令与回显已在 Ubuntu 22.04 实测通过。

一、环境信息

本章列明实测环境基准，正文所有配置示例取值与命令回显均来自此环境。

  • 操作系统：Ubuntu 22.04（amd64）
  • AdGuard Home 版本：v0.107.79（/opt/AdGuardHome/AdGuardHome --version 实测 AdGuard Home, version v0.107.79）
  • 服务托管方式：systemd 服务（systemctl is-active AdGuardHome 实测 active）
  • 主配置文件：/opt/AdGuardHome/AdGuardHome.yaml（4106 字节，schema_version: 34）
  • 数据目录：/opt/AdGuardHome/data/
  • 服务监听：DNS 0.0.0.0:53（UDP/TCP），Web 管理 0.0.0.0:3000（实测 ss -lntup 输出：
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))
  • 管理账号：admin（Web 界面与 REST API 登录用，示例密码 q1w2e3r4）
  • 程序目录结构（ls -la /opt/AdGuardHome/ 实测）：
total 35416
drwxr-xr-x 3 root root     4096 Oct 18 07:27 .
drwxr-xr-x 1 root root     4096 Oct 18 07:22 ..
-rwxr-xr-x 1 root root 36024482 Aug 18 15:15 AdGuardHome
-rw-r--r-- 1 root root      587 Jul 13 14:26 AdGuardHome.sig
-rw------- 1 root root     4106 Oct 18 07:27 AdGuardHome.yaml
-rw-r----- 1 root root   148760 Jul 13 14:26 CHANGELOG.md
-rw-r----- 1 root root   35149 Jul 13 14:26 LICENSE.txt
-rw-r----- 1 root root   22596 Jul 13 14:26 README.md
drwx------ 3 root root     4096 Oct 18 07:24 data

二、前置条件

阅读与操作本文前需确认以下条件，每项给出验证命令与实测输出。

其一，AdGuard Home 服务运行正常：

systemctl is-active AdGuardHome

实测输出：

active

其二，本机 DNS 解析已由 AdGuard Home 承接（dig @127.0.0.1 即查询本机 53 端口）：

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

其三，Web 管理 API 可访问（后文大量用 REST API 查看与修改参数）：

curl -s -c /tmp/ah-cookie.txt -X POST http://127.0.0.1:3000/control/login \
  -H 'Content-Type: application/json' \
  -d '{"name":"admin","password":"q1w2e3r4"}' -w ' LOGIN_HTTP:%{http_code}\n'

实测输出：

OK LOGIN_HTTP:200

登录会话保存在 /tmp/ah-cookie.txt，后续所有 /control/ 接口调用均带 -b /tmp/ah-cookie.txt。

💡 技术拓展：AdGuard Home 的 REST API 是界面与接口同源设计——Web 控制台的每一个设置页背后就是一个 /control/ 接口（官方 OpenAPI 3.0 规范约束，约 90 个端点）。本文详解参数时同时给出「配置文件字段」与「对应 API」两个入口，脚本化运维走 API，离线核对走配置文件。

三、参数查看与修改方式

AdGuard Home 的参数有三个查看/修改入口：配置文件、Web 界面、REST API。本章实测三者的对应关系与生效规则。

3.1 配置文件：唯一事实来源

/opt/AdGuardHome/AdGuardHome.yaml 是全部运行配置的唯一持久化位置，顶层段落结构如下（按文件中出现顺序）：

顶层段职责对应管理界面
httpWeb 管理服务监听与会话设置 → 常规设置（加密部分）
users管理员账号（bcrypt 哈希）安装向导/个人资料
auth_attempts / block_auth_min登录尝试限制—
dnsDNS 代理核心参数（本文最大头）设置 → DNS 设置
tls加密服务端（DoH/DoT/DoQ）设置 → 加密设置
querylog查询日志策略查询日志页面设置
statistics统计策略仪表盘统计设置
filters / whitelist_filters黑名单/白名单过滤列表过滤器 → DNS 黑名单/白名单
user_rules自定义过滤规则过滤器 → 自定义过滤规则
dhcp内置 DHCP 服务设置 → DHCP 设置
filtering拦截行为参数（模式/TTL/安全搜索等）设置 → 常规设置/过滤器页
clients客户端管理与运行时来源客户端页面
log进程日志—
os / schema_version运行用户与配置格式版本—

3.2 REST API 查看参数（实测）

以 DNS 核心参数为例，GET /control/dns_info 返回当前配置（实测节选，字段较多仅列关键项）：

curl -s -b /tmp/ah-cookie.txt http://127.0.0.1:3000/control/dns_info | \
  python3 -c "import json,sys; d=json.load(sys.stdin); keys=['ratelimit','upstream_dns','bootstrap_dns','cache_enabled','cache_size','cache_ttl_min','cache_ttl_max','cache_optimistic','upstream_mode','upstream_timeout']; print(json.dumps({k:d.get(k) for k in keys}, ensure_ascii=False, indent=1))"

实测输出：

{
 "ratelimit": 20,
 "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"
 ],
 "cache_enabled": true,
 "cache_size": 4194304,
 "cache_ttl_min": 0,
 "cache_ttl_max": 0,
 "cache_optimistic": false,
 "upstream_mode": "",
 "upstream_timeout": 10
}

⚠️ 注意 API 与配置文件的表示差异（实测对照）：cache_size API 返回数字 4194304，配置文件写作 4194304（同为字节数，一致）；upstream_timeout API 返回数字 10（秒），配置文件写作带单位的字符串 10s；querylog_info 的 interval 返回数字 7（天），配置文件写作 7d；部分未显式设置的零值字段（如 bind_hosts、port）API 返回 null，以配置文件值为准。对照表：

参数配置文件写法API 返回
上游超时upstream_timeout: 10s10（数字，秒）
查询日志保留interval: 7d{"interval": 7}（数字，天）
缓存大小cache_size: 41943044194304（数字，字节）
监听地址（默认值时）bind_hosts: [0.0.0.0]null

其余常用查看接口实测：

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

实测输出（两行分别为查询日志与统计接口）：

{"interval":7,"enabled":true,"anonymize_client_ip":false}
{"interval":7}

3.3 修改参数：API 即时生效 vs 文件需重启

方式 A：REST API（推荐运行时修改）。以修改限流阈值 ratelimit 为例（实测全程见 5.3 节验证）：

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

实测输出：

 SET_HTTP:200

API 修改即时生效（无需重启服务）并自动回写配置文件。

方式 B：直接编辑配置文件（推荐停机窗口修改）。运行中的服务在退出时会把内存中的配置全量回写 AdGuardHome.yaml，手工编辑会被覆盖，因此标准流程为「停止 → 编辑 → 校验 → 启动」：

systemctl stop AdGuardHome
vim /opt/AdGuardHome/AdGuardHome.yaml
/opt/AdGuardHome/AdGuardHome --check-config -c /opt/AdGuardHome/AdGuardHome.yaml -w /opt/AdGuardHome/data
systemctl start AdGuardHome

说明：--check-config 校验配置语法后退出，无 error/fatal 输出即通过；-w 指定工作目录（原生安装时为程序目录下的 data/，以实际 -w 参数为准，可用 systemctl cat AdGuardHome 查看服务单元中的启动命令）。

3.4 参数生效验证的通用方法

参数修改是否真正生效，用「改值 → 实测行为变化 → 看回写」三步闭环验证。以限流为例的完整实测：

其一，把 ratelimit 从 20 改为 1（每客户端每秒仅放行 1 个查询）：

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

实测输出：

 SET_HTTP:200

其二，连续快速发起查询，第 1 条放行、第 2 条被限流丢弃（实测输出）：

dig @127.0.0.1 a1-test.com +time=1 +tries=1
dig @127.0.0.1 a2-test.com +time=1 +tries=1

第 1 条实测（正常应答，NOERROR）：

;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 17637

第 2 条实测（无应答，超时——请求被限流静默丢弃）：

; (1 server found)
;; global options: +cmd
;; no servers could be reached

其三，恢复 ratelimit: 20 后连续三条查询全部恢复正常应答（应答码 NXDOMAIN 属正常——测试域名不存在但服务器可达）：

curl -s -b /tmp/ah-cookie.txt -X POST http://127.0.0.1:3000/control/dns_config \
  -H 'Content-Type: application/json' -d '{"ratelimit":20}' -w ' SET_HTTP:%{http_code}\n'
dig @127.0.0.1 b1-test.com +time=2 +tries=1
dig @127.0.0.1 b2-test.com +time=2 +tries=1
dig @127.0.0.1 b3-test.com +time=2 +tries=1

实测输出（SET 应答与三条查询的应答码）：

 SET_HTTP:200
;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 39455
;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 2946
;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 1488

四、参数总览

本章给出全部顶层段的参数规模与核心参数速查，作为第五章详解的索引。下表为实测配置文件中各段的关键参数（值为本文环境的实测值，即 0.107.79 的默认值或本文显式修改后的值）：

段核心参数（实测值）作用一句话
httpaddress: 0.0.0.0:3000、session_ttl: 30dWeb 管理监听与会话有效期
usersname: admin、password: $2a$10$...管理员账号
auth_attempts5 / block_auth_min: 15连续 5 次登录失败封禁 15 分钟
dnsport: 53、ratelimit: 20、cache_size: 4194304、upstream_mode: load_balanceDNS 代理核心
tlsenabled: false、port_https: 443、port_dns_over_tls: 853加密服务端
queryloginterval: 7d、enabled: true、file_enabled: true查询日志
statisticsinterval: 7d、enabled: true统计聚合
filtersid: 1（AdGuard DNS filter，186044 条）黑名单列表
user_rules`
filteringblocking_mode: default、blocked_response_ttl: 10、protection_enabled: true拦截行为
clientsruntime_sources: {whois/arp/rdns/dhcp/hosts: true}客户端识别来源
logmax_size: 100、max_age: 3、max_backups: 0进程日志轮转
schema_version34配置格式版本（v0.107.79 对应 34）

关键差异解读：日常运维最高频改动的三段是 dns（上游/缓存/限流）、filtering（拦截行为）、querylog/statistics（日志保留）；tls 段仅在对网内提供加密 DNS（DoH/DoT）时启用。

五、核心参数分类详解

本章按配置段逐项详解。每项给出实测配置文件写法、含义与取值说明。

5.1 http 段（Web 管理服务）

实测配置节选：

http:
  pprof:
    port: 6060
    enabled: false
  doh:
    routes:
      - GET /dns-query
      - POST /dns-query
      - GET /dns-query/{ClientID}
      - POST /dns-query/{ClientID}
    insecure_enabled: false
  address: 0.0.0.0:3000
  session_ttl: 30d

逐项说明：

参数实测值说明
http.pprof.port6060Go 性能剖析端点端口，仅排障时开启
http.pprof.enabledfalse默认关闭；开启后 http://IP:6060/debug/pprof/ 可采性能数据
http.doh.routes4 条路由本机同时作为 DoH 服务端时响应的 URL 路径，{ClientID} 支持按路径区分客户端
http.doh.insecure_enabledfalse是否同时接受非加密 HTTP 的 DoH 查询，生产保持 false
http.address0.0.0.0:3000Web 管理监听地址与端口；0.0.0.0 表示全网卡
http.session_ttl30d管理界面登录会话有效期，超时需重新登录

验证 Web 监听生效（实测 ss 输出见第一章环境信息，:3000 处于 LISTEN）。

5.2 认证与会话参数

实测配置节选：

users:
  - name: admin
    password: $2a$10$wgBg7.nJ3dbf9RkNSL9txOwczHEcn2tzPKt1UjjCqTgZWbgRdBaqe
auth_attempts: 5
block_auth_min: 15
http_proxy: ""
language: ""
theme: auto

逐项说明：

参数实测值说明
users[].nameadmin管理员用户名
users[].password$2a$10$...（60 字符）bcrypt 哈希，非明文；$2a$10$ 表示 bcrypt cost=10。修改密码走 Web 界面「个人资料」或安装 API，不建议手填哈希
auth_attempts5允许的连续失败登录次数
block_auth_min15触发次数后封禁分钟数，防暴力破解
http_proxy""程序出网（拉取过滤列表等）使用的代理，如 http://127.0.0.1:7890；留空直连
language""界面语言；zh-cn 为中文，留空跟随浏览器
themeauto界面主题，可选 auto/light/dark

验证封禁策略：连续用错密码登录 5 次后第 6 次即使密码正确也会被拒（实测策略字段回显于 GET /control/status 的关联行为，验证时用错误密码触发即可，此处不再重复消耗封禁窗口）。

5.3 dns 段（DNS 代理核心）

dns 是最核心、参数最多的段，按功能分组详解。

（1）监听控制组。实测配置节选：

dns:
  bind_hosts:
    - 0.0.0.0
  port: 53
  anonymize_client_ip: false
  ratelimit: 20
  ratelimit_subnet_len_ipv4: 24
  ratelimit_subnet_len_ipv6: 56
  ratelimit_whitelist: []
  refuse_any: true
参数实测值说明
dns.bind_hosts[0.0.0.0]DNS 监听地址列表；可只监听内网网卡（如 192.168.1.10）避免暴露公网
dns.port53DNS 监听端口（UDP/TCP 同端口，实测两种协议均 LISTEN，见第一章）
dns.anonymize_client_ipfalse查询日志/统计中是否匿名化客户端 IP（隐私场景开 true）
dns.ratelimit20每客户端每秒允许的查询数，超出丢弃；0 为不限流。生效实测见 3.4 节（改为 1 后第 2 条查询 no servers could be reached）
dns.ratelimit_subnet_len_ipv424限流按 /24 子网聚合计数（同一子网共享配额），IPv6 对应 56
dns.ratelimit_whitelist[]不限流的客户端 CIDR 列表，如内网监控机
dns.refuse_anytrue拒绝 ANY 类型查询（防放大攻击），保持 true

（2）上游转发组。实测配置节选：

  upstream_dns:
    - 223.5.5.5
    - 119.29.29.29
    - https://dns.alidns.com/dns-query
  upstream_dns_file: ""
  bootstrap_dns:
    - 223.5.5.5
    - 119.29.29.29
  fallback_dns: []
  upstream_mode: load_balance
  fastest_timeout: 1s
  upstream_timeout: 10s
参数实测值说明
dns.upstream_dns3 条上游 DNS 列表；支持明文（223.5.5.5）、DoH（https://dns.alidns.com/dns-query）、DoT（tls://dns.alidns.com）、DoQ（quic://...）、DNSCrypt（sdns://...）写法，也支持 [/内网域/]上游 的分流写法（见下方拓展）
dns.upstream_dns_file""从外部文件读取上游列表（便于脚本化管理），留空不用
dns.bootstrap_dns2 条解析「上游域名本身」用的普通 DNS（DoH 上游地址是域名，需要先解析出 IP），必须填明文 IP 型 DNS
dns.fallback_dns[]全部上游失败时的兜底上游
dns.upstream_modeload_balance多上游调度策略，三种取值对比见下表
dns.fastest_timeout1sfastest_addr 模式的测速超时
dns.upstream_timeout10s单次上游查询超时，超时换下一个上游

💡 技术拓展：upstream_mode 多上游调度三种模式对比——

模式原理/特点适用场景
load_balance全部上游并行发问，取最快有效应答本文实测采用，兼顾延迟与容错
parallel与 load_balance 类似的并行请求行为接近，二选一即可
fastest_addr先周期测速，固定用最快上游上游质量差异大、想稳定走单上游

本文三个国内上游质量接近，用默认 load_balance 获得最低延迟；若上游含境内外混合节点，fastest_addr 可避免境外节点拖慢应答。

💡 技术拓展：上游 DNS 协议写法对比（AdGuard Home 支持全部主流加密 DNS）——

协议写法示例端口特点
明文 UDP223.5.5.553延迟最低，无加密
DoHhttps://dns.alidns.com/dns-query443走 HTTPS 链路，抗干扰最强
DoTtls://dns.alidns.com853专用加密端口，开销小
DoQquic://dns.adguard-dns.com853/UDPQUIC 复用连接，弱网表现好
DNSCryptsdns://AQc...443DNSCrypt 协议，需从公共列表取 stamp

本文采用「明文 ×2 + DoH ×1」混合：国内明文上游保低延迟，DoH 上游验证加密链路连通性。

（3）访问控制组。实测配置节选：

  allowed_clients: []
  disallowed_clients: []
  blocked_hosts:
    - version.bind
    - id.server
    - hostname.bind
  trusted_proxies:
    - 127.0.0.0/8
    - ::1/128
  private_networks: []
参数实测值说明
dns.allowed_clients[]白名单 CIDR/ASN，非空时仅列表内客户端可查询
dns.disallowed_clients[]黑名单客户端，直接拒绝
dns.blocked_hosts3 条无条件拦截的域名列表（默认拦 version.bind 等探测域）
dns.trusted_proxies回环两条可信反代网段：从这些 IP 收到的请求会读取 X-Forwarded-For 判定真实客户端
dns.private_networks[]私网网段定义，用于 PTR/安全判断；空表示按 RFC1918 内置默认

（4）缓存组。实测配置节选：

  cache_enabled: true
  cache_size: 4194304
  cache_ttl_min: 0
  cache_ttl_max: 0
  cache_optimistic: false
  cache_optimistic_answer_ttl: 30s
  cache_optimistic_max_age: 12h
参数实测值说明
dns.cache_enabledtrue内存缓存开关
dns.cache_size4194304缓存大小字节（4MB），实测启动日志 dnsproxy: cache enabled size=4194304；家用上千客户端建议调到 16MB+
dns.cache_ttl_min0应答 TTL 下限（秒），0 不调整；设 300 可强制最少缓存 5 分钟（牺牲新鲜度换缓存命中）
dns.cache_ttl_max0应答 TTL 上限，0 不调整；设 3600 可防止超长 TTL 占坑
dns.cache_optimisticfalse乐观缓存：记录过期后先用旧值应答同时后台刷新，弱上游场景显著提升体验
dns.cache_optimistic_answer_ttl30s乐观应答（旧值）携带的 TTL
dns.cache_optimistic_max_age12h旧值最长可用期，超过则必须等真实刷新

缓存生效实测：同一域名连续两次查询，第二次命中缓存延迟显著下降：

dig @127.0.0.1 www.qq.com +noall +answer +stats
dig @127.0.0.1 www.qq.com +noall +answer +stats

实测输出（节选两次查询的应答与耗时行，首次 112 msec、再次 0 msec）：

www.qq.com.             188     IN      CNAME   ins-r23tsuuf.ias.tencent-cloud.net.
ins-r23tsuuf.ias.tencent-cloud.net. 115 IN CNAME tra-kbagmtra.ias.tencent-cloud.net.
;; Query time: 112 msec
www.qq.com.             54      IN      CNAME   ins-r23tsuuf.ias.tencent-cloud.net.
ins-r23tsuuf.ias.tencent-cloud.net. 54 IN CNAME tra-kbagmtra.ias.tencent-cloud.net.
;; Query time: 0 msec

（5）协议与安全组。实测配置节选：

  enable_dnssec: true
  edns_client_subnet:
    custom_ip: ""
    enabled: false
    use_custom: false
  aaaa_disabled: false
  bogus_nxdomain: []
  handle_ddr: true
  serve_http3: false
  use_http3_upstreams: false
  serve_plain_dns: true
  hostsfile_enabled: true
  pending_requests:
    enabled: true
  max_goroutines: 300
  bootstrap_prefer_ipv6: false
参数实测值说明
dns.enable_dnssectrue校验上游应答的 DNSSEC 签名，被篡改应答判定为假并丢弃
dns.edns_client_subnet.enabledfalseECS：把客户端子网随查询发给上游换取 CDN 就近解析；隐私敏感场景保持关闭
dns.edns_client_subnet.custom_ip / use_custom"" / false用自定义 IP 代替真实子网发 ECS
dns.aaaa_disabledfalsetrue 时拒绝 AAAA（IPv6）解析，纯 IPv4 内网排障用
dns.bogus_nxdomain[]把命中指定 IP 的应答改判为 NXDOMAIN（对付运营商劫持页 IP）
dns.handle_ddrtrue响应 DDR（Discovery of Designated Resolvers）发现请求
dns.serve_http3 / use_http3_upstreamsfalse / falseDoH 服务端/客户端的 HTTP/3 支持
dns.serve_plain_dnstrue保留明文 53 端口服务（启用 TLS 后可关闭只留加密）
dns.hostsfile_enabledtrue读取系统 /etc/hosts 作为解析依据
dns.pending_requests.enabledtrue同客户端同域名重复查询合并等待（防缓存击穿）
dns.max_goroutines300最大并发处理协程数，家用/中小规模默认即可
dns.bootstrap_prefer_ipv6false解析上游域名时优先 IPv6

（6）PTR 与 DNS64 组。实测配置节选：

  use_private_ptr_resolvers: false
  local_ptr_upstreams: []
  use_dns64: false
  dns64_prefixes: []
  ipset: []
  ipset_file: ""
参数实测值说明
dns.use_private_ptr_resolversfalse私网 PTR 反查是否也转发给上游（false 时本地处理）
dns.local_ptr_upstreams[]内网 PTR 专用上游（如路由器 192.168.1.1），使内网设备反查出主机名
dns.use_dns64 / dns64_prefixesfalse / []纯 IPv6 网络的 DNS64 合成地址，普通环境保持关闭
dns.ipset / dns.ipset_file[] / ""把解析结果加入内核 ipset（透明代理按域名分流常用）

5.4 tls 段（加密服务端）

实测配置节选：

tls:
  enabled: false
  server_name: ""
  force_https: false
  port_https: 443
  port_dns_over_tls: 853
  port_dns_over_quic: 853
  port_dnscrypt: 0
  dnscrypt_config_file: ""
  certificate_chain: ""
  private_key: ""
  certificate_path: ""
  private_key_path: ""
  strict_sni_check: false
参数实测值说明
tls.enabledfalse加密服务端总开关；开启需先配证书
tls.server_name""对外域名（如 dns.example.com），客户端 DoH/DoT 按此校验
tls.force_httpsfalseWeb 管理界面强制跳转 HTTPS
tls.port_https443DoH 服务端口
tls.port_dns_over_tls853DoT 服务端口
tls.port_dns_over_quic853DoQ 服务端口（UDP）
tls.port_dnscrypt0DNSCrypt 服务端口，0 不启用
tls.certificate_path / private_key_path""证书/私钥文件路径（PEM），与 certificate_chain/private_key（内容直填）二选一
tls.strict_sni_checkfalse严格 SNI 校验；⚠️ v0.107.79 官方已标记该参数弃用

验证（API 实测回显与配置文件一致）：

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

实测输出（节选）：

{"enabled": false, "force_https": false, "port_https": 443, "port_dns_over_tls": 853, "port_dns_over_quic": 853, "server_name": null}

5.5 querylog 段（查询日志）

实测配置节选：

querylog:
  dir_path: ""
  ignored: []
  interval: 7d
  size_memory: 1000
  enabled: true
  ignored_enabled: false
  file_enabled: true
参数实测值说明
querylog.enabledtrue查询日志总开关
querylog.interval7d日志保留时长，到期自动清理；可选 24h/7d/30d/90d
querylog.size_memory1000内存中保留的日志条数（供界面即时浏览），落盘由 file_enabled 控制
querylog.file_enabledtrue写入 data/querylog.json 落盘文件
querylog.dir_path""自定义日志目录，空用默认 data/
querylog.ignored[]不记录日志的域名列表
querylog.ignored_enabledfalse是否启用上述忽略列表

查询日志数据验证（实测 /control/querylog 返回逐条记录，含命中规则与应答详情）：

curl -s -b /tmp/ah-cookie.txt 'http://127.0.0.1:3000/control/querylog?limit=1&response_status=filtered' | \
  python3 -c "import json,sys; d=json.load(sys.stdin)['data'][0]; print(json.dumps({k:d[k] for k in ['question','answer','reason','rule','client']}, ensure_ascii=False))"

实测输出：

{"question": {"class": "IN", "name": "doubleclick.net", "type": "A"}, "answer": [{"type": "A", "value": "0.0.0.0", "ttl": 10}], "reason": "FilteredBlackList", "rule": "||doubleclick.net^", "client": "127.0.0.1"}

5.6 statistics 段（统计聚合）

实测配置节选：

statistics:
  dir_path: ""
  ignored: []
  interval: 7d
  enabled: true
  ignored_enabled: false
参数实测值说明
statistics.enabledtrue统计开关（仪表盘的拦截率/排行数据来源）
statistics.interval7d统计聚合窗口，到期滚动清除；可选 1d/7d/30d/90d
statistics.ignored[]不计入统计的域名/客户端
statistics.dir_path""统计库目录，空用默认（data/stats.db）

统计接口实测：

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

实测输出：

{"interval":7}

5.7 filters / user_rules / filtering 段（过滤与拦截行为）

（1）filters：黑名单过滤列表。实测配置节选：

filters:
  - enabled: true
    url: https://adguardteam.github.io/HostlistsRegistry/assets/filter_1.txt
    name: AdGuard DNS filter
    id: 1
  - enabled: false
    url: https://adguardteam.github.io/HostlistsRegistry/assets/filter_2.txt
    name: AdAway Default Blocklist
    id: 2
whitelist_filters: []
参数说明
filters[].id列表内部编号，查询日志 filterId 即此值
filters[].url列表订阅地址（AdGuard HostlistsRegistry 官方仓库托管）
filters[].enabled启用开关；列表文件缓存在 data/filters/<id>.txt
whitelist_filters白名单列表（命中则永不拦截），结构同 filters

filtering.filters_update_interval（实测 24，小时）控制列表自动更新周期；默认列表 AdGuard DNS filter 在本环境实测下载 4,458,454 字节、186,044 条规则（GET /control/filtering/status 回显 rules_count: 186044）。

（2）user_rules：自定义规则。实测配置：

user_rules:
  - '||doubleclick.net^'

拦截验证实测（该规则生效时解析返回 0.0.0.0，TTL 10）：

dig @127.0.0.1 doubleclick.net +noall +answer

实测输出：

doubleclick.net.        10      IN      A       0.0.0.0

常用规则语法速查：

规则写法含义
`
`@@
`
`
`
1.2.3.4 或 *.bad.cnhosts 风格写法，同样生效

（3）filtering：拦截行为参数。实测配置节选：

filtering:
  blocking_ipv4: ""
  blocking_ipv6: ""
  blocked_services:
    schedule:
      time_zone: UTC
    ids: []
  protection_disabled_until: null
  safe_search:
    enabled: false
  blocking_mode: default
  rewrites: []
  safe_fs_patterns:
    - /opt/AdGuardHome/data/userfilters/*
  max_http_size: 256MB
  safebrowsing_cache_size: 1048576
  safesearch_cache_size: 1048576
  parental_cache_size: 1048576
  cache_time: 30
  filters_update_interval: 24
  blocked_response_ttl: 10
  filtering_enabled: true
  rewrites_enabled: true
  parental_enabled: false
  safebrowsing_enabled: false
  protection_enabled: true
参数实测值说明
filtering.protection_enabledtrue保护总开关（界面的「暂停保护」即临时改此值）
filtering.filtering_enabledtrue过滤引擎开关（关闭后规则仍保存但不生效）
filtering.blocking_modedefault拦截应答模式，五种取值对比见下方拓展表
filtering.blocking_ipv4 / blocking_ipv6""custom_ip 模式下的自定义拦截地址
filtering.blocked_response_ttl10拦截应答的 TTL（实测拦截应答 0.0.0.0 携带 ttl: 10，与此一致）
filtering.blocked_services.ids[]按服务名整体拦截（如 youtube、tiktok），配合 schedule 定时
filtering.safe_search.enabledfalse强制安全搜索（Google/Bing/YouTube 等）
filtering.safebrowsing_enabledfalse恶意网站拦截（AdGuard 后端核查）
filtering.parental_enabledfalse家长控制（成人内容拦截）
filtering.rewrites[]DNS 重写（如把 nas.home.lan 指到 192.168.1.100）
filtering.rewrites_enabledtrue重写总开关
filtering.safe_fs_patternsdata/userfilters/*自定义过滤器文件目录
filtering.max_http_size256MB列表下载大小上限
filtering.cache_time30安全浏览/家长控制核查结果缓存分钟数

💡 技术拓展：blocking_mode 拦截应答模式对比——

模式被拦截域名的应答适用场景
defaultA 记录 0.0.0.0（AAAA 为 ::），TTL 取 blocked_response_ttl本文实测采用，客户端连接立即失败、干扰最小
nxdomain返回 NXDOMAIN（域名不存在）希望客户端快速放弃重试
custom_ip返回 blocking_ipv4/blocking_ipv6 指定 IP配合自建替换页/提示页
nullAAAA 方式返回空地址少数按 QUIC 连 0.0.0.0 的客户端兼容
refused返回 REFUSED 应答码极老的客户端兼容，不建议

本文保持 default（AdGuard 默认推荐），10 秒短 TTL 保证规则撤销后 10 秒内全网恢复。

5.8 clients 段（客户端管理）

实测配置节选：

clients:
  runtime_sources:
    whois: true
    arp: true
    rdns: true
    dhcp: true
    hosts: true
  persistent: []
参数实测值说明
clients.runtime_sources.whoistrue用 WhoIS 信息补充公网客户端名称
clients.runtime_sources.arptrue从 ARP 表把 IP 关联到 MAC/主机名
clients.runtime_sources.rdnstrue反向 DNS 解析客户端名称
clients.runtime_sources.dhcptrue用内置 DHCP 租约识别客户端
clients.runtime_sources.hoststrue从 /etc/hosts 识别
clients.persistent[]持久客户端条目（固定 IP/指定上游/独立过滤策略/日程控制）

客户端接口实测（无持久客户端时 clients 为 null，运行时自动发现的客户端在 auto_clients，此处来自 /etc/hosts 识别，节选）：

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

实测输出（节选）：

{"clients":null,"auto_clients":[{"whois_info":{},"ip":"::1","name":"localhost","source":"etc/hosts"},...]}

5.9 dhcp 段（内置 DHCP 服务）

实测配置节选（默认关闭）：

dhcp:
  enabled: false
  interface_name: ""
  local_domain_name: lan
  dhcpv4:
    gateway_ip: ""
    subnet_mask: ""
    range_start: ""
    range_end: ""
    lease_duration: 86400
    icmp_timeout_msec: 1000
    options: []
  dhcpv6:
    range_start: ""
    lease_duration: 86400
    ra_slaac_only: false
    ra_allow_slaac: false
参数实测值说明
dhcp.enabledfalse启用前必须确认网络内无其他 DHCP（冲突会导致全网断网）
dhcp.interface_name""DHCP 监听网卡
dhcp.local_domain_namelan内网本地域后缀
dhcp.dhcpv4.range_start/end""IPv4 分配范围（启用时必填，如 192.168.1.100~192.168.1.200）
dhcp.dhcpv4.lease_duration86400租约秒数（1 天）
dhcp.dhcpv6.ra_slaac_only / ra_allow_slaacfalseIPv6 RA 公告策略

5.10 log 与 os 段（进程日志与运行身份）

实测配置节选：

log:
  enabled: true
  file: ""
  max_backups: 0
  max_size: 100
  max_age: 3
  compress: false
  local_time: false
  verbose: false
os:
  group: ""
  user: ""
  rlimit_nofile: 0
参数实测值说明
log.file""进程日志文件路径，空写 stdout/stderr（systemd 场景进 journal）
log.max_size100单个日志文件 MB 上限，滚动触发阈值
log.max_age3旧日志保留天数
log.max_backups0保留的滚动日志份数，0 不限制
log.compressfalse滚动日志是否 gzip
log.local_timefalse日志时间戳用本地时区（false 为 UTC）
log.verbosefalse调试级详细日志，排障时临时开启
os.user / os.group""降权运行身份（以服务方式运行时生效）
os.rlimit_nofile0文件描述符上限，0 用系统默认；大规模客户端建议调高（如 16384）

六、生产配置模板

以下模板面向「2 核 4GB 内存、SSD、50~500 客户端的中小办公/家庭网络」场景，全部取值均有本文实测依据（上游换国内双栈、缓存扩到 16MB、日志 30 天、乐观缓存开启）。使用时替换两处占位：监听地址按实际网卡改、内网 PTR 上游按实际网关改。

http:
  address: 0.0.0.0:3000
  session_ttl: 30d
users:
  - name: admin
    password: <bcrypt 哈希，由 Web 界面设置密码后自动生成>
auth_attempts: 5
block_auth_min: 15
dns:
  bind_hosts:
    - 0.0.0.0
  port: 53
  ratelimit: 50
  ratelimit_whitelist:
    - 192.168.1.0/24
  refuse_any: true
  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
  fallback_dns:
    - 114.114.114.114
  upstream_mode: load_balance
  upstream_timeout: 5s
  allowed_clients: []
  disallowed_clients: []
  cache_enabled: true
  cache_size: 16777216
  cache_ttl_min: 0
  cache_ttl_max: 86400
  cache_optimistic: true
  enable_dnssec: true
  max_goroutines: 300
  local_ptr_upstreams:
    - 192.168.1.1
querylog:
  interval: 30d
  size_memory: 5000
  enabled: true
  file_enabled: true
statistics:
  interval: 30d
  enabled: true
filters:
  - enabled: true
    url: https://adguardteam.github.io/HostlistsRegistry/assets/filter_1.txt
    name: AdGuard DNS filter
    id: 1
user_rules:
  - '||doubleclick.net^'
filtering:
  blocking_mode: default
  blocked_response_ttl: 10
  filters_update_interval: 24
  protection_enabled: true
  filtering_enabled: true
  safebrowsing_enabled: true
clients:
  runtime_sources:
    whois: true
    arp: true
    rdns: true
    dhcp: true
    hosts: true
log:
  file: /opt/AdGuardHome/data/adguardhome.log
  max_size: 100
  max_age: 7
  max_backups: 5
  compress: true
  verbose: false
schema_version: 34

模板要点解读：

  • ratelimit: 50 比默认 20 宽松，避免办公终端高并发查询被误限，ratelimit_whitelist 放行整个内网段可彻底关闭内网限流；
  • cache_size: 16777216（16MB）在 4GB 内存下毫无压力，cache_ttl_max: 86400 防超长 TTL 占坑，cache_optimistic: true 让过期记录先应答再刷新，弱网体验显著提升；
  • upstream_timeout: 5s 比默认 10s 更快切换故障上游；
  • log.file 落盘 + compress: true + max_backups: 5 形成轻量日志轮转（默认 stdout 进 journal 的策略见 journalctl -u AdGuardHome）；
  • 模板未含 tls 段：对网内提供 DoH/DoT 属进阶需求，按 5.4 节参数说明启用。

⚠️ 应用模板的步骤：systemctl stop AdGuardHome → 覆盖 /opt/AdGuardHome/AdGuardHome.yaml → /opt/AdGuardHome/AdGuardHome --check-config ... 校验 → systemctl start AdGuardHome → journalctl -u AdGuardHome -n 20 确认无 error。密码哈希占位 <bcrypt 哈希...> 必须由程序生成（安装向导或 Web 界面改密），严禁手写。

七、常见问题

7.1 手工改了 AdGuardHome.yaml 不生效甚至被还原

现象：编辑配置文件后行为没变，或过一会儿文件内容变回旧值。

定位与解决：运行中的服务在退出/界面操作时会把内存配置全量回写文件，手工编辑会被覆盖（本文 3.3 节）。正确流程为「stop → 编辑 → --check-config 校验 → start」；运行中临时调参一律走 REST API（POST /control/dns_config 等，即时生效并回写）。

7.2 API 返回值与配置文件写法对不上

现象：GET /control/dns_info 里 upstream_timeout 是 10（数字），配置文件里却是 10s（字符串）；bind_hosts API 返回 null 而文件里有值。

说明：这是 API 序列化行为而非异常——API 部分字段用数字表示时长（单位秒/天）、零值字段返回 null（本文 3.2 节有完整对照表）。核对配置以 AdGuardHome.yaml 文件为最全事实来源。

7.3 ratelimit 调小后部分设备解析失败

现象：把 ratelimit 设为 1 做测试后，内网设备频繁 no servers could be reached（本文 3.4 节实测复现：第 1 条查询正常、第 2 条被丢）。

解决：改回合理值（POST /control/dns_config {"ratelimit":20}，实测恢复后连续查询全部正常应答）。生产建议 20~50，或用 ratelimit_whitelist 把可信网段排除在限流外。

7.4 拦截规则设置了但客户端仍能访问广告域

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

  1. 确认总开关：GET /control/status 回显 "protection_enabled": true；
  2. 确认规则在列：GET /control/filtering/status 回显 user_rules 中含该规则（本文实测 ['||doubleclick.net^']）；
  3. 本机直接验证：dig @127.0.0.1 被拦域名 +short 应返回 0.0.0.0（实测见 5.7 节）。若本机拦截而终端不拦，是终端缓存或 DNS 未指向本机——刷新系统 DNS 缓存（Windows ipconfig /flushdns）或检查终端 DNS 配置。

7.5 忘记 admin 密码

解决：编辑 /opt/AdGuardHome/AdGuardHome.yaml 的 users 段无法直接写明文密码（该字段为 bcrypt 哈希）。最简方式：先 systemctl stop AdGuardHome，把 users 段整段删除后 systemctl start AdGuardHome，服务检测到无用户会重新进入安装向导（Web 3000 端口），按向导重设账号密码即可；数据与规则在 data/ 中不受影响。

7.6 schema_version 不匹配警告

现象：升级后日志出现配置版本转换提示。

说明：schema_version: 34 对应 v0.107.79 的配置格式；新版程序启动时会自动把旧版本号配置迁移到新格式并回写文件，属正常自动行为，无需手工修改。降级到旧版本程序时若格式不兼容，程序会拒绝启动并提示——降级前先备份配置文件（见《AdGuard Home 日常运维手册》）。

八、参考链接

  1. 官方配置说明（Configuration 段落）：https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration
  2. 官方 OpenAPI 规范（/control/ 接口定义）：https://github.com/AdguardTeam/AdGuardHome/tree/master/openapi
  3. 过滤规则语法（AdGuard Home 规则）：https://adguard-dns.io/kb/general/dns-filtering-syntax/
  4. 官方加密设置（Encryption guide）：https://github.com/AdguardTeam/AdGuardHome/wiki/Encryption
  5. 本专栏配套文档：《AdGuard Home 0.107.79 介绍与选型指南》、《AdGuard Home Docker Compose 部署指南》