DHCP 客户端监控 + 数据上报看板

抓取水星 MW305R 路由器(192.168.1.1)的 DHCP 客户端列表,记录每个设备的上线/下线时间,支持本地展示和公网多站点看板。数据滚动保留 7 天。

架构

┌─ 本地(树莓派等) ─────────────────────────┐   ┌─ 公网服务器 ────────────────────────┐
│ 路由器(192.168.1.1)                      │   │                                    │
│    │ DHCP列表(每60s抓取)                  │   │  dhcp-mon -mode server              │
│    ▼                                      │   │  ├─ POST /api/report ←─ 接收上报    │
│  dhcp-mon -mode client                    │   │  │     (带 token 认证)               │
│  ├─ 判定上线/下线 → events.csv/devices.json│   │  ├─ 按 site 分组存储(7天保留)       │
│  └─ 上报 (事件增量+设备快照) ─────────────┼──▶│  └─ 多站点看板 :8080(公网访问)      │
└───────────────────────────────────────────┘   └────────────────────────────────────┘
  • 一个二进制 dhcp-mon,两种模式
  • client(采集端):抓路由器 DHCP 列表,判定上下线,本地存数据,按周期上报
  • server(看板端):公网接收上报,按站点分组存储,提供多站点看板页
  • 上报内容:增量事件 + 全量设备快照,服务器据此精确还原当前在线状态
  • 认证:client 用 -token 上报,server 用 -stoken 校验,不匹配拒绝;看板也需 token 访问
  • 低功耗采集端:ESP8266 可只抓原始页面 POST 到 POST /api/raw,由服务器端解析 + 判定(见下文)

服务器端部署(公网)

# 服务器上,反向代理或直接端口
./dhcp-mon -mode server -web :8080 -data /srv/dhcp-data -stoken '你的令牌' -retain 7

# 浏览器访问(需token)
#   http://<服务器IP>:8080/?token=你的令牌

看板功能:

  • 站点切换栏(每个上报的 site 一个按钮,显示在线/总数)
  • 统计卡片:在线/离线/总数/事件数
  • 设备表:状态、MAC、IP、首次/最近上线/下线、在线次数、累计在线
  • 点击设备行 → 展开该设备 7 日上下线历史(上线/下线次数、累计在线、完整事件流)
  • 事件流:上下线事件,最新在前
  • 每 5 秒自动刷新

采端端部署(树莓派/本地)

# 树莓派上(能访问到路由器 192.168.1.1)
./dhcp-mon -mode client \
  -host 192.168.1.1 \
  -password 123456 \
  -site home \
  -report http://<服务器IP>:8080/api/report \
  -token '你的令牌' \
  -data /home/pi/dhcp-data

# 后台常驻(systemd / nohup 均可)
nohup ./dhcp-mon -mode client -host 192.168.1.1 -password 123456 \
  -site home -report http://<服务器IP>:8080/api/report -token '你的令牌' \
  > /home/pi/dhcp-mon.log 2>&1 &

多个采集点:每台树莓派给不同的 -site(如 home/office/shop),看板自动分组展示。

采集端不配 -report 时仅在本地工作(保留原来单机功能)。

低功耗采集:ESP8266 + 服务器端解析

想做到极致低功耗(深度睡眠,一天耗电 <0.1Wh),用 ESP8266 只做「登录 → 抓页面 → 把原始 HTML POST 给服务器」,解析和上下线判定全部放服务器端,不移植 Go 代码,固件极简:

ESP8266 (每15分钟深度睡眠唤醒)
  ├─ HTTP 登录路由器:设 Cookie `Authorization=Basic base64("admin:"+密码)`,带浏览器UA
  ├─ GET /userRpm/AssignedIpAddrListRpm.htm → 拿到原始 HTML
  └─ POST http://服务器:8080/api/raw  (Header X-Token + X-Site, body=原始HTML)
       服务器: 解析 DHCPDynList → 判定上线/下线 → 记录事件 → 持久化

/api/raw 上报协议

  • 方法:POST
  • 认证:Header X-Token: <令牌>(或 query ?token=),与 server 的 -stoken 一致
  • 站点:Header X-Site: home(或 query ?site=home)
  • body:原始路由器页面 HTML(/userRpm/AssignedIpAddrListRpm.htm 的完整响应),可直接上传,无需转码

响应(JSON):

{"ok": true, "site": "home", "clients": 3, "device_count": 4, "time": "2026-10-12T13:15:18+08:00"}

错误响应:

HTTP 含义
401 token 不匹配
400 缺 site / body 为空 / 页面无法解析
502 路由器返回认证失败页(403/密码错误)——ESP8266 应据此重新登录或换密码

判定规则:与 client 模式一致——设备首次出现记上线事件;连续 2 次上报缺席判定下线(防抖,等价 -absent 2);按 X-Site 独立状态机,互不干扰。

注:节点上报的原始页面包含完整 HTTP 头(UTF-8 或 GBK 均可,服务器端自动转码)。

ESP8266 关键注意点

  1. 认证 cookie 必须无引号:Authorization=Basic xxx,不能用标准 cookie 编码(会加引号导致 403)
  2. 必须带浏览器 User-Agent + Referer,否则水星路由器返回 403
  3. 上线判定:首次抓到的当前在线设备会记一条上线事件,服务器端快照以最近一次上报为准
  4. 网络/服务器不可达时 ESP8266 内部应保留原始页面上报失败重试(简单起见可直接丢弃,下轮再抓;上下线判定在服务器端做,不漏事件)

ESP8266 固件(PlatformIO 刷写)

固件在 firmware/esp8266/(源码 + 详细接线/排查见其 README),功能: WiFi 连接 → 登录路由器抓原始 DHCP 页面 → POST /api/raw → 深度睡眠(默认 15 分钟)。

# 1. 配置: 编辑 firmware/esp8266/src/secrets.h
#    (WiFi / SERVER_URL / X_TOKEN=X stoken / X_SITE / ROUTER_PASS / SLEEP_SECONDS)

# 2. 编译
~/.platformio/penv/bin/pio run -d firmware/esp8266

# 3. 上传(串口已接好,如 /dev/cu.usbserial-1430)
~/.platformio/penv/bin/pio run -d firmware/esp8266 -t upload \
  --upload-port /dev/cu.usbserial-1430

# 4. 串口日志确认(115200)
~/.platformio/penv/bin/pio device monitor -p /dev/cu.usbserial-1430 -b 115200

要点:

  • 登录 cookie 必须无引号(固件已按 Authorization=Basic xxx 手动设置),必须带浏览器 UA + Referer
  • 定时深睡唤醒需把 GPIO16(D0) 短接到 RST,否则只靠手动复位触发
  • ESP8266 仅支持 2.4GHz WiFi
  • 上报成功日志示例:{"ok":true,"site":"home","clients":3,...}

参数

参数 默认 说明
-mode client client(采集上报)/ server(接收+看板)
-host 192.168.1.1 路由器管理地址(client)
-password 123456 路由器管理员密码(client)
-https false 使用 https 访问路由器
-timeout 10 HTTP 超时秒数
-interval 60s 抓取间隔(clent)
-data ./data 数据目录
-web :8080 Web 监听地址(server 看板 / client 本地页)
-retain 7 数据保留天数(滚动清理)
-absent 2 连续缺席多少次判定下线(防抖)
-site 空 站点标识(client 上报用)
-report 空 上报地址 http://server:8080/api/report(空=不上报)
-token 空 client 上报令牌(需与 server -stoken 一致)
-stoken 空 server 接收/看板令牌
-once false 仅抓取一次打印列表
-quiet false 安静模式

Web API

server 模式:

端点 说明
GET / 多站点看板页面(需 token)
POST /api/report 采集端上报(事件+快照),带 token
POST /api/raw ESP8266 原始页面上报(Header X-Token/X-Site,body=原始HTML),服务器端解析判定
GET /api/sites 站点列表(在线数/设备数/最近上报)
GET /api/site?site=X 单站点详情(设备+事件)
GET /api/device?site=X&mac=Y 单设备 7 日历史(该设备保留期内全部上下线事件)

client 模式(本地):

端点 说明
GET / 本地展示页面
GET /api/devices 设备 JSON
GET /api/events 事件 JSON

数据保留(滚动清理)

默认 7 天(-retain),每天清理一次:

  • events.csv:删除超期事件
  • devices.json:移除离线超 7 天的设备(在线永远保留)
  • server 端按站点目录存储(data/sites/<site>/),同样 7 天滚动

下线时间误差说明

DHCP 租约默认 10 分钟:设备断开后路由器 DHCP 列表仍保留直到租约到期才移除,因此检测到的下线时间比真实晚 0~10 分钟。这是 DHCP 列表监控的固有限制。-absent 2 的防抖(缺 2 次判定下线)避免误判。

输出文件(client 端)

events.csv:

timestamp,event,mac,ip,name,detail
2026-10-12T13:15:18+08:00,online,40-AC-BF-D2-B0-1E,192.168.1.100,K23879676,00:05:52
2026-10-12T13:23:04+08:00,offline,A2-C5-F2-03-A9-EA,192.168.1.112,PgyBox_X1-2111,在线时长 00h00m; 下线检测误差≤10m(DHCP租约)

devices.json:

{
  "40-AC-BF-D2-B0-1E": {
    "mac": "40-AC-BF-D2-B0-1E", "name": "K23879676",
    "last_ip": "192.168.1.100", "status": "online",
    "first_seen": "2026-10-12T13:15:18+08:00",
    "last_online": "2026-10-12T13:15:18+08:00",
    "last_offline": "2026-10-12T13:23:04+08:00",
    "online_count": 2, "total_online_seconds": 3600
  }
}

server 端存储结构:data/sites/<site>/devices.json + events.csv。

实现要点

  • 路由器认证:设置 Authorization cookie = Basic base64("admin:"+密码),必须带浏览器 User-Agent,否则 403
  • 数据源:/userRpm/AssignedIpAddrListRpm.htm 页面的 DHCPDynList JS 数组,每 4 元素 = 一条记录(名/MAC/IP/租约)
  • 上报协议(树莓派采集端):POST /api/report body = {site, token, events[], snapshot:{devices[]}},失败自动重传
  • 上报协议(ESP8266 采集端):POST /api/raw body = 原始路由器页面 HTML,Header 带 X-Token + X-Site,服务器端解析 DHCPDynList 并做上下线判定
S
Description
No description provided
Readme
114 KiB
0 Stars 1 Watchers 0 Forks
Languages
Go 63.2%
HTML 27.4%
C++ 7.6%
Shell 1.8%