AdGuard Home Ubuntu 部署指南

环境要求

  • Ubuntu 20.04 / 22.04 / 24.04 LTS
  • 至少 512MB 内存，建议 1GB+
  • 静态 IP 地址（作为局域网 DNS 服务器时）

一、安装 AdGuard Home

1.1 一键安装脚本

1
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v

脚本会自动完成以下操作：

  • 下载最新版 AdGuard Home
  • 创建 adguardhome 系统用户
  • 注册 systemd 服务
  • 启动服务并监听 0.0.0.0:3000（初始 Web 管理界面）

1.2 手动安装（备选）

1
2
3
4
5
6
7
8
# 下载最新版本（替换为实际版本号）
wget https://github.com/AdguardTeam/AdGuardHome/releases/latest/download/AdGuardHome_linux_amd64.tar.gz

# 解压
tar xzf AdGuardHome_linux_amd64.tar.gz

# 安装
sudo ./AdGuardHome -s install

二、初始配置

2.1 访问 Web 管理界面

  1. 浏览器打开 http://<服务器IP>:3000
  2. 点击”开始配置”

2.2 配置向导

步骤 配置项 建议值
1 管理界面监听端口 0.0.0.0:80（或保留 3000，用 Nginx 反代）
2 DNS 监听端口 0.0.0.0:53
3 创建管理员账号 设置用户名和强密码

2.3 DNS 上游服务器建议

1
2
3
4
5
https://dns.quad9.net/dns-query
https://dns.cloudflare.com/dns-query
tls://dns.quad9.net
114.114.114.114
223.5.5.5

2.4 常用过滤器列表

在 过滤器 → DNS封锁清单 中添加：

清单名称 URL
AdGuard DNS Filter https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt
Anti-AD https://anti-ad.net/easylist.txt
Easylist China https://easylist-downloads.adblockplus.org/easylistchina.txt
CJX’s Annoyance List https://raw.githubusercontent.com/cjx82630/cjxlist/master/cjx-annoyance.txt

三、核心配置文件位置

用途 路径
主配置文件 /opt/AdGuardHome/AdGuardHome.yaml
数据目录 /opt/AdGuardHome/data/
查询日志 /opt/AdGuardHome/data/querylog.json
统计数据库 /opt/AdGuardHome/data/stats.db
systemd 服务 /etc/systemd/system/AdGuardHome.service
二进制文件 /opt/AdGuardHome/AdGuardHome

3.1 关键 YAML 配置说明

配置文件结构及常用修改项：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# DNS 绑定地址
dns:
  bind_hosts:
    - 0.0.0.0
  port: 53
  # 上游 DNS
  upstream_dns:
    - https://dns.quad9.net/dns-query
    - https://dns.cloudflare.com/dns-query
  # Bootstrap DNS（用于解析上游 DoH/DoT 域名）
  bootstrap_dns:
    - 9.9.9.10
    - 1.1.1.1
  # 缓存大小（字节），默认 4MB，可调大
  cache_size: 8388608
  # EDNS 客户端子网
  edns_client_subnet:
    enabled: false

# DHCP 服务（如需）
dhcp:
  enabled: false

# 查询日志保留时间（小时），默认 2160h(90天)
querylog:
  enabled: true
  interval: 2160h

# 统计保留时间
statistics:
  enabled: true
  interval: 2160h

注意：修改 AdGuardHome.yaml 后需要重启服务生效。

四、systemd 服务管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 启动
sudo systemctl start AdGuardHome

# 停止
sudo systemctl stop AdGuardHome

# 重启
sudo systemctl restart AdGuardHome

# 设置开机自启
sudo systemctl enable AdGuardHome

# 查看运行状态
sudo systemctl status AdGuardHome

# 查看实时日志
sudo journalctl -u AdGuardHome -f

# 查看最近 100 行日志
sudo journalctl -u AdGuardHome -n 100

五、备份与恢复

5.1 完整备份脚本

创建备份脚本 ~/adguard-backup.sh：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
#!/bin/bash
BACKUP_DIR="/backup/adguard"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/adguard_backup_$DATE.tar.gz"

mkdir -p "$BACKUP_DIR"

# 停止服务
sudo systemctl stop AdGuardHome

# 打包配置和数据
sudo tar czf "$BACKUP_FILE" \
  /opt/AdGuardHome/AdGuardHome.yaml \
  /opt/AdGuardHome/data/

# 启动服务
sudo systemctl start AdGuardHome

echo "备份完成: $BACKUP_FILE"

# 保留最近 30 天的备份，删除旧备份
find "$BACKUP_DIR" -name "adguard_backup_*.tar.gz" -mtime +30 -delete

设置可执行并加入 crontab 每日备份：

1
2
3
4
chmod +x ~/adguard-backup.sh

# 每天凌晨 3 点自动备份
(crontab -l 2>/dev/null; echo "0 3 * * * /home/$USER/adguard-backup.sh >> /var/log/adguard-backup.log 2>&1") | crontab -

5.2 恢复备份

1
2
3
4
5
6
7
# 恢复指定日期的备份
sudo systemctl stop AdGuardHome

# 恢复配置文件
sudo tar xzf /backup/adguard/adguard_backup_20250101_030000.tar.gz -C /

sudo systemctl start AdGuardHome

5.3 仅备份配置文件（轻量）

1
sudo cp /opt/AdGuardHome/AdGuardHome.yaml /backup/adguard/AdGuardHome.yaml.$(date +%Y%m%d)

六、更新升级

6.1 自动更新

在 Web 管理界面 设置 → 常规设置 → 自动更新 中开启。

6.2 手动更新

1
2
3
4
5
# 下载新版本并安装
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v

# 或重新安装（不会覆盖配置）
sudo ./AdGuardHome -s install

七、常用维护操作

7.1 释放 53 端口（系统 DNS 冲突）

Ubuntu 默认的 systemd-resolved 占用 53 端口，需要释放：

1
2
3
4
5
6
7
# 停止并禁用 systemd-resolved
sudo systemctl stop systemd-resolved
sudo systemctl disable systemd-resolved

# 删除 /etc/resolv.conf 符号链接并重建
sudo rm /etc/resolv.conf
echo "nameserver 127.0.0.1" | sudo tee /etc/resolv.conf

7.2 配置防火墙

1
2
3
4
5
6
7
8
9
# ufw
sudo ufw allow 53/tcp
sudo ufw allow 53/udp
sudo ufw allow 80/tcp       # 管理界面
sudo ufw allow 3000/tcp     # 如果保留默认端口

# iptables
sudo iptables -A INPUT -p tcp --dport 53 -j ACCEPT
sudo iptables -A INPUT -p udp --dport 53 -j ACCEPT

7.3 Nginx 反向代理（可选）

为管理界面配置 HTTPS 反代：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
server {
    listen 443 ssl http2;
    server_name adguard.example.com;

    ssl_certificate     /etc/nginx/certs/adguard.crt;
    ssl_certificate_key /etc/nginx/certs/adguard.key;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

7.4 查询日志与统计清理

1
2
3
4
5
6
7
8
9
# 清空查询日志
sudo systemctl stop AdGuardHome
sudo rm -f /opt/AdGuardHome/data/querylog.json
sudo systemctl start AdGuardHome

# 清空统计数据
sudo systemctl stop AdGuardHome
sudo rm -f /opt/AdGuardHome/data/stats.db
sudo systemctl start AdGuardHome

7.5 性能优化

在 AdGuardHome.yaml 中调整：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
dns:
  # 缓存从 4MB 提升到 16MB（大网络场景）
  cache_size: 16777216
  # 最大并发查询数
  upstream_dns:
    - https://dns.quad9.net/dns-query
  # Bootstrap DNS 切换到更快的
  bootstrap_dns:
    - 114.114.114.114
    - 223.5.5.5
  # 启用乐观缓存（TTL 过期后仍返回旧值，同时刷新）
  optimistic_cache: true
  # 限制每秒请求数（防滥用）
  ratelimit: 1000

八、客户端配置

8.1 路由器层面（推荐）

将路由器 DHCP 的 DNS 服务器指向 AdGuard Home 所在服务器的 IP。

8.2 单台设备

Windows：

  • 网络适配器 → IPv4 属性 → DNS 192.168.1.x

Linux：

1
2
3
4
# 临时
sudo resolvectl dns eth0 192.168.1.x
# 或编辑 /etc/resolv.conf
nameserver 192.168.1.x

手机：

  • Wi-Fi 详情 → 静态 IP → DNS 1 填写 AdGuard Home IP

九、故障排查

问题 检查命令
服务未运行 sudo systemctl status AdGuardHome
端口占用 sudo ss -tlnp | grep 53
DNS 解析失败 nslookup baidu.com 127.0.0.1
管理界面无法访问 curl -v http://127.0.0.1:3000
查看错误日志 sudo journalctl -u AdGuardHome --since "10 min ago"
配置语法错误 检查 /opt/AdGuardHome/AdGuardHome.yaml YAML 格式

十、卸载

1
2
3
4
5
6
7
8
9
10
11
12
13
# 停止服务
sudo systemctl stop AdGuardHome
sudo systemctl disable AdGuardHome

# 删除服务文件
sudo rm /etc/systemd/system/AdGuardHome.service
sudo systemctl daemon-reload

# 删除程序和数据
sudo rm -rf /opt/AdGuardHome

# 删除用户
sudo userdel adguardhome

附录：一键环境准备脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
#!/bin/bash
# 预安装准备：释放 53 端口 + 防火墙配置

set -e

echo "=== 停止 systemd-resolved ==="
sudo systemctl stop systemd-resolved
sudo systemctl disable systemd-resolved
sudo rm -f /etc/resolv.conf
echo "nameserver 127.0.0.1" | sudo tee /etc/resolv.conf

echo "=== 配置防火墙 ==="
sudo ufw allow 53/tcp
sudo ufw allow 53/udp
sudo ufw allow 80/tcp
sudo ufw allow 3000/tcp

echo "=== 安装 AdGuard Home ==="
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v

echo "=== 完成 ==="
echo "请访问 http://$(hostname -I | awk '{print $1}'):3000 完成初始化配置"
Linux > 工具
#Ubuntu #AdGuardHome #DNS #广告过滤
AdGuard Home Ubuntu 部署指南
https://bote798.top/2026/07/11/AdGuardHome-Ubuntu部署指南/
作者
bote798
发布于
2026年7月11日
更新于
2026年7月11日
许可协议