MosDNS 实时统计面板从零搭建：SSE 秒级推送 + 五区间统计 + 设备级流量

在旁路由上装完 MosDNS，最常见的遗憾是：它跑得很稳，但你不知道它到底干了什么——今天拦了多少广告、缓存命中率有多高、哪个设备在疯狂发查询。MosDNS 自带的 stats_collector 插件其实已经把这些数据算好了，只是缺一个好看的界面。

这篇教程带你在另一台机器上从零搭一个 MosDNS 实时统计面板：不动 MosDNS 本体、不改主路由任何配置，通过 SSH 只读取数，用 Python 标准库起一个 HTTPS 站点，前端用 SSE 秒级推送，带登录认证、五个时间区间统计、设备级流量排行和域名溯源查询。如果你还没搭过 MosDNS 本身，建议先看 OpenWrt + MosDNS + AdGuard Home 全网去广告搭建教程。

github 开源项目地址：https://github.com/996kuku/mosdns-dashboard

一 · 先看效果

面板分为八个区块，全部实装、全部实时。下面按实际界面顺序过一遍。

二 · 取数原理：为什么不直接读 MosDNS

MosDNS 的 stats_collector 插件会把自己的统计数据算好，通过 HTTP 暴露出来。但它在主路由上，而且默认只监听回环地址。面板要拿数据，有三条路：

• 改 MosDNS 配置把 9091 暴露到局域网 —— 动了主网关，不推荐；
• 在 MosDNS 同一台机器上装面板 —— 会往主路由塞 Python 运行环境，也不推荐；
• SSH 只读调用 —— 面板装在另一台机器上，通过 SSH 在 MosDNS 本机执行 curl 拿 JSON。

本教程采用第三条。整条数据链路是这样的：

stats_collector 提供哪些接口

MosDNS 的 stats_collector 暴露了一组 REST 接口，面板主要用其中四个：（想换上游 DNS 的话，这份 DoH/DoT 服务汇总可以直接抄）

其中 /stats 的返回长这样，字段名后面会原样透传到前端：

{
  "total_queries": 1167722,
  "cached_queries": 1117240,
  "cached_percentage": 95.68,
  "blocked_queries": 86,
  "blocked_percentage": 0.01,
  "avg_latency_ms": 1.1,
  "qps": 0,
  "hosts_queries": 0,
  "arbitrary_queries": 0
}

三 · 环境准备

1. 机器选型

面板本身很轻（单进程、标准库、无第三方依赖），一台 1 核 512M 的小机器绰绰有余。可以放在家里的 NAS、另一台软路由、树莓派，或者云服务器。唯一要求是能 SSH 到 MosDNS 所在的主机。

2. 配置免密 SSH

面板要频繁（默认 5 秒一次）去 MosDNS 主机取数，必须用密钥免密登录。没配过免密登录的话可以先看 SSH 密钥登录新手教程：从生成密钥到启用。在面板机器上生成密钥并推送到MosDNS 主机：

ssh-keygen -t ed25519 -f /root/.ssh/id_ed25519_mosdns -N "" -C "dashboard@local"
ssh-copy-id -i /root/.ssh/id_ed25519_mosdns.pub root@192.168.11.253

推送完先手动验证一次，确认不需要输密码：

ssh -i /root/.ssh/id_ed25519_mosdns root@192.168.11.253 "echo OK"

3. 先手工验证一次取数

登录 MosDNS 主机，确认接口能通、字段符合预期：

curl -s --noproxy "*" http://127.0.0.1:9091/plugins/stats_collector/api/v1/stats
curl -s --noproxy "*" http://127.0.0.1:9091/plugins/stats_collector/api/v1/top | head -c 400

四 · 部署面板

1. 目录结构

mkdir -p /opt/mosdns-dashboard
cd /opt/mosdns-dashboard
# 放置以下文件：
#   server.py     后端（Python 标准库，单文件）
#   index.html    前端页面（单文件）
#   login.html    登录页
#   agh.conf      AdGuard Home 只读凭据（可选，600）
#   auth.conf     面板自身的登录凭据（600）
#   ssl/          TLS 证书（可选）

2. 后端启动参数

后端全部参数都可以用环境变量覆盖，方便不改代码调整：

3. systemd 单元

[Unit]
Description=MosDNS Dashboard
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/mosdns-dashboard
ExecStart=/usr/bin/python3 -u /opt/mosdns-dashboard/server.py
Restart=on-failure
RestartSec=3
StandardOutput=journal
StandardError=journal
SyslogIdentifier=mosdns-dashboard

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable --now mosdns-dashboard
systemctl status mosdns-dashboard --no-pager
journalctl -u mosdns-dashboard -f

五 · 把「实时」做真：SSE 推送

大多数仪表盘的「实时」其实是前端每 N 秒轮询一次 HTTP 接口，数据没变也照样请求，白白浪费带宽和服务端算力。这套面板用的是 SSE（Server-Sent Events）：

1. 服务端怎么推

后端起一个后台线程，固定间隔去取一次数据，算一个指纹（总量、缓存命中、拦截数、榜首域名、历史点数、缓存条数等拼成的哈希）。只有指纹变了，才向所有订阅者广播一帧。没有订阅者时自动降频，避免白白去 SSH 打扰 MosDNS。

Content-Type: text/event-stream; charset=utf-8
Cache-Control: no-cache
X-Accel-Buffering: no      # 关键：禁止反代缓冲，否则数据被攒住不吐出来
Connection: keep-alive

2. 前端怎么接

前端用浏览器原生的 EventSource 接长连接，收到一帧就重绘一次。同时做三重降级：连续 3 次 onerror 就主动 close() 并退回 20 秒轮询；页面切到后台时跳过重绘，切回来补一帧。

const ES = new EventSource('/api/stream');
ES.onmessage = (ev) => { applyPush(JSON.parse(ev.data)); };
ES.onerror = () => { if (++errCount >= 3) { ES.close(); fallbackPoll(); } };
document.addEventListener('visibilitychange', () => {
  if (!document.hidden) refreshRangeSilent();   // 回到前台补一帧
});

3. 五个时间区间

面板支持 实时 / 今天 / 近 7 天 / 近 30 天 / 自建库以来五个区间。实时档直接显示 MosDNS 自身的累计值，其余四档来自面板本地建的时序库。本地库分三层，避免全量扫表：

六 · 登录认证：别裸奔

面板一旦通过内网穿透（frp）暴露到公网，就必须有登录。这里没有引入任何 web 框架，用标准库实现了完整的一套：

• 凭据不落明文：auth.conf 里存 PBKDF2-SHA256 哈希 + 随机 salt，权限 600；
• 会话用 HMAC 签名：用户名|过期时间戳|签名，改一个字符就失效；
• Cookie 加固：HttpOnly + SameSite=Lax，HTTPS 下自动加 Secure；
• 防爆破：按来源 IP 记连续失败次数，超阈值直接拦。

/usr/local/bin/dashboard-setpass        # 交互式改密码
/usr/local/bin/dashboard-setpass -d     # 临时关闭认证（仅调试用）

七 · HTTPS 与部署自愈

完整链路可以做成：

面板自身也可以直接跑 HTTPS —— 把证书路径填进环境变量即可，支持标准的自签 CA 或 ACME 证书。几个实践要点：

• 证书链顺序：证书文件必须叶子证书在前、CA 在后，反了会直接握手失败；
• 接入层别校验证书：如果后端用自签证书，前面 nginx 的 upstream 要写 proxy_ssl_verify off;；
• 把 TLS 逻辑做成启动前自愈：与其把 TLS 代码写死在业务文件里（重新部署就被覆盖），不如放一个幂等脚本到 ExecStartPre，每次启动前检查、缺失就补上。

八 · 两个进阶细节

1. 局域网设备表的客户端 IP 从哪来

一个反直觉的现象：在 MosDNS 那层看到的客户端 IP 永远是 127.0.0.1。原因是转发的 dnsmasq 会把源地址改写掉。想要真实的设备级统计，就得换一个能看到真实客户端的地方取数。

所以设备表的数据取自 AdGuard Home 的查询日志（它能看到真实客户端），MAC 地址则来自 MosDNS 主机的邻居表（ip neigh），两者按 IP 关联。设备名优先取爱快 DHCP 租约里的备注名，没有就退回主机名。

# /opt/mosdns-dashboard/agh.conf  （权限 600）
AGH_URL=https://127.0.0.1:3443
AGH_USER=
AGH_PASS=
# 说明：该账号仅用于拉 querylog / stats，请单独建一个，不要用管理员账号

2. 表头三态排序

局域网设备表的五列（IP / MAC / 设备名 / 查询量 / 被拦截）都支持升序 → 降序 → 恢复默认三态循环。IP 列按数值排序而不是字符串，否则 192.168.11.9 会排到 192.168.11.10 后面。

function ipNum(s){
  const m = String(s).match(/^(d+).(d+).(d+).(d+)$/);
  if(!m) return null;                       // 非 IPv4 恒沉底
  return ((+m[1])<<24 | (+m[2])<<16 | (+m[3])<>> 0;
}

九 · 双主题配色规范

面板同时提供暗色与浅色两套主题，用 html[data-theme] 切根节点的 CSS 变量。这里有一条很容易翻车的经验：

十 · 上线验收清单

部署完照这份清单过一遍，基本不会漏：

十一 · 小结

整套方案的思路可以概括成三句话：

• 取数解耦：不去改 DNS 服务本身，用 SSH 只读调用它的官方统计接口；
• 推优于拉：SSE 长连接 + 指纹比对，有变化才推，没变化只发心跳；
• 可自愈：TLS、认证这类容易被覆盖的东西做成启动前幂等补丁，重新部署也不怕。

面板代码是纯 Python 标准库单文件，前端也是单文件，部署就是拷两个文件 + 一个 systemd 单元，没有 Node、没有 npm、没有容器。想改哪个区块，直接改就行。

延伸阅读

• OpenWrt + MosDNS + AdGuard Home 全网去广告搭建教程 —— 先把 MosDNS 本身跑起来，面板才有数据可看。
• PVE 系统 img 格式转换教程：qm importdisk 安装 OpenWrt —— 没有独立机器跑面板时，可以在 PVE 里开一个轻量 LXC/虚拟机。
• SSH 密钥登录新手教程：从生成密钥到启用 —— 免密 SSH 是本方案的前置条件，没配过的先从这篇开始。
• 局域网 HTTPS 绿锁教程：用 PVE 内部 CA 给内网 IP 签证书 —— 想让面板直接跑 HTTPS 又要浏览器不报警，看这篇。
• 国内外常用 DoH/DoT 服务汇总（含 IPv4/IPv6 与接入地址） —— 给 MosDNS 换上游时可以直接抄这份清单。