# 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`,由服务器端解析 + 判定(见下文) ## 服务器端部署(公网) ```bash # 服务器上,反向代理或直接端口 ./dhcp-mon -mode server -web :8080 -data /srv/dhcp-data -stoken '你的令牌' -retain 7 # 浏览器访问(需token) # http://<服务器IP>:8080/?token=你的令牌 ``` 看板功能: - 站点切换栏(每个上报的 site 一个按钮,显示在线/总数) - 统计卡片:在线/离线/总数/事件数 - 设备表:状态、MAC、IP、首次/最近上线/下线、在线次数、累计在线 - **点击设备行 → 展开该设备 7 日上下线历史**(上线/下线次数、累计在线、完整事件流) - 事件流:上下线事件,最新在前 - 每 5 秒自动刷新 ## 采端端部署(树莓派/本地) ```bash # 树莓派上(能访问到路由器 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): ```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 分钟)。 ```bash # 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//`),同样 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**: ```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//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` 并做上下线判定