adguardian

用于监控 AdGuard Home 实例的终端工具。通过x-cmd一键安装，即刻体验高效工作流程。

Language	Rust
Homepage	https://adguardian.as93.net/

容器调用: ^{实验性功能}

1. 使用 docker 模块自动拉取基础镜像，并在首次执行时根据需求重构为一个可直接运行的完整软件镜像。
2. 在后续运行中，命令会基于已构建好的镜像快速启动容器，实现秒级响应。
3. 所有操作均在容器内部完成，与本地系统完全隔离，无需任何本地依赖，安全、干净且不留痕迹。
4. 当因软件版本或依赖发生变化需重构镜像时，会充分利用 Docker 镜像构建的缓存机制，最大限度地复用已下载的依赖与构建成果，大幅缩短重建耗时。

该功能仍在测试中，使用过程中如有问题，欢迎在 X-CMD 社区 留言反馈。

x docker alpine adguardian

xd alp adguardian

---

x install adguardian

/cargo	cargo install adguardian
(win|wsl2)/scoop	x scoop install extras/adguardian
arch/paru	paru -Syu adguardian
arch/yay	yay -Syu adguardian
arch/makepkg	git clone https://aur.archlinux.org/adguardian.git && cd adguardian && makepkg -si
/curl	bash <(curl -sL https://raw.githubusercontent.com/Lissy93/AdGuardian-Term/main/quick-start.sh)
/nix-env	nix-env -iA nixos.adguardian

AdGuardian：在终端实时监控 AdGuard Home 网络流量

如果你在家用 AdGuard Home 做全网广告拦截，可能会遇到这样的需求：想看实时查询日志、统计拦截率、监控热门域名，但又不想每次都打开 AdGuard 的 Web 管理界面。AdGuardian 解决的就是这个痛点——一个直接在终端运行的实时监控仪表盘，让你用键盘就能掌握全网 DNS 活动。

这是一个专为 AdGuard Home 设计的终端监控工具，用 Rust 编写，资源占用极低。它把实时查询流、拦截统计、热门域名、过滤器状态等关键信息，整合在一个 TUI（文本用户界面）仪表盘里。对于习惯命令行的用户来说，这比浏览器页面更轻量、更快捷。

核心功能一览

AdGuardian 的设计思路很直接：把 AdGuard Home 管理界面里最常用的监控功能，搬到终端里实时展示。

功能	说明
实时查询监控	滚动显示所有 DNS 查询记录，包括请求域名、类型、来源客户端、处理结果（放行/拦截/过滤）
拦截统计	实时展示放行、过滤、拦截的查询数量及比例
历史趋势	按时间维度展示查询量变化，帮助发现异常流量
过滤器状态	显示当前启用的过滤列表及其拦截贡献度
热门域名	统计访问量最高的域名（分放行、拦截、全部三类）
轻量部署	单二进制文件，零依赖；或 Docker 一键运行（仅 12MB）

实际使用场景很典型：部署在家庭服务器或软路由上，SSH 登录后 adguardian 一下，就能快速扫一眼全网的 DNS 活动。有没有异常请求、广告拦截是否生效、哪个设备在疯狂查询——一目了然。

安装方式

AdGuardian 提供多种安装途径，适应不同环境：

Docker（推荐）

最简单的方式，适合已有 Docker 环境的用户：

docker run -it lissy93/adguardian

如果需要持久化配置，可传入环境变量：

docker run -it \
  -e "ADGUARD_IP=192.168.1.1" \
  -e "ADGUARD_PORT=3000" \
  -e "ADGUARD_USERNAME=admin" \
  -e "ADGUARD_PASSWORD=yourpassword" \
  lissy93/adguardian

镜像同时托管在 GHCR（GitHub Container Registry）：ghcr.io/lissy93/adguardian

直接下载可执行文件

没有 Docker 时的最佳选择，零依赖：

# Linux 示例（根据实际系统和版本调整 URL）
curl -L -o adguardian https://github.com/Lissy93/AdGuardian-Term/releases/latest/download/adguardian-linux
chmod +x adguardian
./adguardian

Windows 用户可从 Releases 页面下载对应版本的 .exe 文件。

Cargo 安装（Rust 用户）

cargo install adguardian
adguardian

Scoop（Windows）

scoop install extras/adguardian

AUR（Arch Linux）

# 使用 paru
paru -Syu adguardian

# 或使用 yay
yay -Syu adguardian

# 或手动构建
git clone https://aur.archlinux.org/adguardian.git
cd adguardian
makepkg -si

一键脚本

bash <(curl -sL https://raw.githubusercontent.com/Lissy93/AdGuardian-Term/main/quick-start.sh)

建议先阅读脚本内容，确认安全后再执行。

配置连接参数

AdGuardian 需要知道如何连接到你的 AdGuard Home 实例。支持两种配置方式：

命令行参数

adguardian \
  --adguard-ip "192.168.1.1" \
  --adguard-port "3000" \
  --adguard-username "admin" \
  --adguard-password "yourpassword"

环境变量

export ADGUARD_IP="192.168.1.1"
export ADGUARD_PORT="3000"
export ADGUARD_USERNAME="admin"
export ADGUARD_PASSWORD="yourpassword"
adguardian

参数/变量	说明	必填
--adguard-ip / ADGUARD_IP	AdGuard Home 的 IP 地址	是
--adguard-port / ADGUARD_PORT	AdGuard Home 的端口	是
--adguard-username / ADGUARD_USERNAME	登录用户名	是（若启用了认证）
--adguard-password / ADGUARD_PASSWORD	登录密码	是（若启用了认证）
ADGUARD_PROTOCOL	连接协议，默认 http	否
ADGUARD_UPDATE_INTERVAL	UI 刷新间隔（秒），默认 2 秒	否

如果参数不完整，启动时会交互式提示输入。

Web 模式：浏览器访问终端界面

AdGuardian 支持通过浏览器访问终端仪表盘，这在以下场景很有用：

• 不想保持 SSH 连接，但想偶尔查看监控
• 需要在其他设备（如平板）上快速浏览
• 想嵌入到现有的仪表板系统中

实现原理是基于 ttyd 将终端界面转发到浏览器。

使用第三方 Web 镜像（快速体验）

docker run -d \
  -p 7681:7681 \
  -e ADGUARD_IP=your.adguard.ip \
  -e ADGUARD_PORT=80 \
  -e ADGUARD_USERNAME=admin \
  -e ADGUARD_PASSWORD=your_password \
  sdjnmxd/adguardian-web

然后访问 http://localhost:7681。

注意：这是第三方镜像，非官方维护，生产环境请自行评估。

手动组合 ttyd

如果你已安装 ttyd，可以直接包装 AdGuardian：

ttyd docker run -it lissy93/adguardian

或本地二进制：

ttyd adguardian

项目仓库中也提供了 ttyd-Dockerfile，可以将 AdGuardian 和 ttyd 打包成单一镜像。

界面布局与使用

启动后，AdGuardian 会展示一个多面板 TUI 界面：

1. 顶部状态栏：当前连接状态、刷新间隔
2. 统计卡片：总查询数、放行数、过滤数、拦截数及比例
3. 实时查询流：滚动显示的 DNS 查询日志
4. 热门域名：访问量最高的域名排行
5. 过滤器列表：各过滤规则的拦截贡献
6. 历史图表：查询量随时间的变化趋势

操作很简单：

• 按 q 或 Ctrl+C 退出
• 界面自动刷新（默认 2 秒）
• 窗口大小调整时会自动重新布局

适用场景

家庭网络监控

部署在家庭服务器、NAS 或软路由上，随时查看全网的 DNS 活动。快速发现：

• 哪个设备在频繁请求异常域名
• 广告拦截是否正常工作
• 是否有大量被拦截的追踪请求

排查网络问题

当某个应用无法联网时，通过实时查询流可以看到 DNS 请求是否发出、是否被拦截、返回了什么结果。比查看 AdGuard 的 Web 日志更快捷。

轻量级监控方案

对于资源受限的设备（如树莓派），AdGuardian 比完整监控栈（Prometheus + Grafana）轻量得多。单二进制文件，内存占用极低。

嵌入式展示

配合 ttyd 和 Web 模式，可以把监控界面嵌入到 HomeLab 仪表板（如 Dashy、Homer）中，作为 AdGuard 状态的快速预览。

技术特点

特性	说明
Rust 实现	内存安全、性能优异、二进制体积小
异步架构	基于 Tokio 实现高效的并发请求处理
零依赖运行	编译后单文件，不需要额外运行时
单元测试覆盖	核心逻辑有测试保障
开源协议	MIT 协议，可自由使用和修改

与同类工具对比

工具	适用平台	特点
AdGuardian	终端	实时监控、TUI 仪表盘、资源占用极低
PADD	终端	Pi-hole 官方终端仪表盘，功能类似但专为 Pi-hole 设计
AdGuard Home Remote	iOS	移动端 App，适合手机查看
AdGuard Home Manager	Android	安卓端管理工具

如果你用的是 Pi-hole 而非 AdGuard Home，推荐直接使用 PADD；如果是 AdGuard Home 用户，AdGuardian 是目前终端监控的最佳选择。

总结

AdGuardian 的定位很明确：为 AdGuard Home 用户提供一个轻量、实时、终端原生的监控工具。它不是功能最全的管理界面（不支持修改配置、添加规则等），但在实时查看流量、快速了解网络状况这个场景下，体验非常直接。

对于习惯命令行、追求效率的 AdGuard Home 用户来说，这是一个实用的小工具。配合 Docker 或 systemd，可以设置为开机自启，让监控始终在手边。

相关资源

• GitHub 仓库
• 在线演示
• Crates.io 页面
• 技术文档

来源：

https://github.com/Lissy93/AdGuardian-Term