WatchYourLAN局域网 IP 扫描器部署与监控配置一步到位的实战指南【免费下载链接】WatchYourLANLightweight network IP scanner written in Go. With notifications, history, export to Grafana项目地址: https://gitcode.com/GitHub_Trending/wa/WatchYourLAN谁在你家或办公室的网段里此刻又有几台设备在线WatchYourLAN 是一款用 Go 写的轻量级网络 IP 扫描器它用 ARP 持续扫描网段发现新主机就发通知并维护一份带在线/离线历史的全网主机清单。读完本文你会从 Docker 部署讲到三类配置入口、VLAN 进阶扫描、通知渠道再到 HTTP API最终拥有一套属于自己的局域网监控服务。功能全景WatchYourLAN 扫描器能做什么新主机发现通知未知设备一出现立刻推送到你的消息渠道。在线/离线历史记录每台主机的状态变化可用热力图回看。全网主机清单IP、MAC、厂商、接口、主机名一张表看全。Grafana 数据出口数据写入 InfluxDB2 或暴露给 Prometheus。从入口文件 backend/cmd/WatchYourLAN/main.go 的启动顺序看架构非常精简conf.Start读配置 →gdb.Start连数据库 →routines起扫描与历史清理两个后台协程 →web.Gui启动 Web GUI。技术栈是 Go Gin GORM中间件为零运行时只依赖一个系统命令arp-scan真正的扫描全由它完成。扫描协程循环检查距上次扫描达到TIMEOUT秒就执行一轮arp-scan。结果按 MAC 建映射与now表逐台比对仍在线则更新 IP 和接口消失则标记离线出现新 MAC 先做 DNS 解析拿主机名再触发通知。每次比对都把状态快照写进history表过期记录由另一个协程按TRIM_HIST定期清理。环境准备与部署Docker 一键拉起 WatchYourLAN最短路径就是一条命令docker run --name wyl \ -e IFACES$YOURIFACE \ -e TZ$YOURTIMEZONE \ --networkhost \ -v $DOCKERDATAPATH/wyl:/data/WatchYourLAN \ aceberg/watchyourlan参数是否必填说明IFACES必填要扫描的接口空格分隔多个TZ必填时区保证历史时间正确--networkhost必填arp-scan 需在宿主网络栈收发 ARP-v …:/data/WatchYourLAN必填存配置文件与 SQLite 数据库启动后访问http://localhost:8840即可进入 Web GUI。偏好 docker-compose 的话仓库自带 docker-compose.yml里面还注释了一段本地资源服务后文离线资源模式会用到。不想用 Docker 时去 latest release 取预编译包.deb、.rpm、.apk、.tar.gz都有覆盖amd64、i386、arm_v5、arm_v6、arm_v7、arm64。运行时依赖只有arp-scan和tzdata两个amd64还可用作者维护的 apt 软件源直接安装并跟随更新。命令行另有两个参数-d指定配置目录默认/data/WatchYourLAN-n指定离线资源地址。配置与定制三种入口快速配置配置有三种入口配置文件、Web GUI、环境变量三者等价。底层统一走 Viperbackend/internal/conf/read.go 先设默认值再读config_v2.yaml最后AutomaticEnv()让环境变量覆盖配置文件。配置文件里的键名就是环境变量名转小写TIMEOUT对应timeout。基础项变量作用默认值何时改TZ时区必填一定要设HOSTWeb 监听地址0.0.0.0绑定特定 IP 时PORTWeb GUI 端口8840端口冲突时THEME主题名取 bootswatch 小写名sand换外观时COLOR背景 light 或 darkdark要浅色背景时NODEPATH本地资源路径空离线网络时扫描与数据库项变量作用默认值何时改IFACES要扫描的接口必填首次部署必设TIMEOUT两次扫描间隔秒120想更快发现时ARP_ARGS追加给 arp-scan 的参数空见进阶玩法LOG_LEVEL日志级别 debug 到 errorinfo排错时开 debugTRIM_HIST历史保留时长小时48控制数据库体积时USE_DBsqlite 或 postgressqlite要用 Postgres 时PG_CONNECTPostgres 连接串空要用 Postgres 时数据库层基于 GORMUSE_DBpostgres时按PG_CONNECT连接连不上会自动回退到 SQLite不会中断服务。SQLite 下额外开启PRAGMA journal_mode wal与PRAGMA busy_timeout 5000提升并发表现。表固定两张now存当前在线清单history存历史AutoMigrate自动建表。HIST_IN_DB自 2.1.3 起已弃用历史永远入库体积靠TRIM_HIST控制。InfluxDB2 对接变量作用默认值何时改INFLUX_ENABLE启用导出false接 Grafana 时INFLUX_ADDR服务器地址:端口—启用后填写INFLUX_ORGorg 名—启用后填写INflux_BUCKETbucket 名—启用后填写INFLUX_TOKEN密钥 token—启用后填写INFLUX_SKIP_TLS跳过 TLS 校验false自签证书时每次扫描比对都会向 InfluxDB 写一行行协议数据WatchYourLAN,IPip,ifaceiface,namename,macmac,known0/1 state0/1。state1表示在线、0离线known标记是否已知主机。这组字段与 Grafana 里 InfluxDB 数据源配置一一对应。Prometheus 对接变量作用默认值何时改PROMETHEUS_ENABLE启用 /metrics 端点false用 Prometheus 抓取时启用后核心指标是一个 gauge 向量watch_your_lan_up{ip,iface,name,mac,known}值为 1 在线、0 离线未启用时该端点直接返回 404。最小可用配置如下放在数据目录的config_v2.yaml里ifaces: enp4s0 port: 8840 theme: sand color: dark timeout: 60 trim_hist: 48 use_db: sqlite shoutrrr_url: 其中只有ifaces一行必须填成你真实的接口名其余保持默认即可运行。timeout: 60表示 60 秒扫一次全局默认是 120 秒按需调整。进阶玩法VLAN 与 docker0 扫描配置ARP_STRS 独立扫描当网段藏在 VLAN 里或你想扫 docker0 这类桥接网段单个接口不够用了。原理一句话ARP_STRS把每条字符串原样当作一条arp-scan命令执行与 IFACES 完全独立。扫 VLAN 107 的命令长这样arp-scan -gNx 10.0.107.0/24 -Q 107 -I eth0-Q 107指定 VLAN ID-I eth0指定从哪个接口发包。配置文件里用列表逐条写arp_strs: - -gNx 172.17.0.1/24 -I docker0 - -glNx -I virbr0GUI 里则在 Arp Strings 输入框填一条、点 Save会自动再出现一个空输入框逐条添加即可。⚠️注意字符串的最后一个元素会被写成发现主机的接口名所以接口一定要放在字符串末尾否则主机列表里的接口列会错。用环境变量传多条扫描串ARP_STRS只能通过 GUI 或配置文件设置docker-compose 里要改用ARP_STRS_JOINED逗号分隔的字符串列表逗号前后不能有空格。非空时它会直接覆盖ARP_STRSARP_STRS_JOINED: -gNx 172.17.0.1/24 -I docker0,-gNx 10.0.107.0/24 -Q 107 -I eth0顺手说清ARP_ARGS的区别它不是独立命令而是追加到每一个IFACES 的扫描命令里。设ARP_ARGS: -r 1后实际执行的就是arp-scan -glNx -r 1 -I iface。排错时把LOG_LEVEL调到debug日志会打印每条完整命令backend/internal/arp/arpscan.go 里能对照源码。通知、认证与外部集成把 WatchYourLAN 接入你的基础设施新主机通知只填一个SHOUTRRR_URL格式决定渠道Discord、Email、Gotify、Matrix、Ntfy、Pushover、Slack、Telegram、通用 Webhook 等都能用。Gotify 示例gotify://192.168.0.1:8083/token/?titleUnknown host detectedDisableTLSyes。新 MAC 出现时推送的消息固定包含名称、IP、MAC、硬件厂商与接口URL 为空则只写日志不推送。配好后调用GET /api/notify_test或在 Config 页面点测试按钮发一条test notification验证渠道是否通。认证与访问控制WatchYourLAN没有内置认证。两个通行方案用 Authelia 这类 SSO 工具做前置或用作者写的轻量认证应用 ForAuth仓库里有配套示例 docker-compose-auth.yml。⚠️警告WYL 必须以 host 网络模式运行Web 端口会直接暴露在宿主网络上务必用防火墙或其他方式限制对该端口的访问否则管理界面任何人都能打开。离线资源模式默认情况下主题、图标、字体都从互联网拉取。完全隔离的内网可以改用内置全部静态资源的镜像docker run --name node-bootstrap -p 8850:8850 aceberg/node-bootstrap随后启动 WYL 时追加-n http://$YOUR_IP:8850等价于NODEPATH变量GUI 就会从这台资源服务器取全部模块与字体不再依赖外网。API 与二次开发用 HTTP 接口查询主机主要端点一览方法路径说明GET/api/all返回全部主机 JSONGET/api/host/:id按 ID 取单台主机GET/api/history/:mac/:date按 MAC 与日期过滤历史GET/api/port/:addr/:port检测某地址某端口是否开放GET/api/edit/:id/:name/*known改名known 传 toggle 切换GET/api/host/del/:id删除指定主机GET/api/rescan触发立即重扫GET/api/wol/:mac发送 Wake-on-LAN 魔法包date粒度很灵活2、2025-07、2025-07-26都能传。端口检测长这样curl http://0.0.0.0:8840/api/port/192.168.2.2/8844自 2.1.4 起内置 Swagger 文档启动后访问/swagger/即可在线浏览全部接口。社区还有 AUR 包、Python 客户端、Umbrel、YunoHost 应用等集成都基于这套 API 实现。收尾回顾部署要点回顾与延伸阅读Docker 一条命令起步三种配置入口等价VLAN 靠 ARP_STRS 覆盖通知与监控一步打通延伸阅读建议看这三处完整接口细节docs/API.md复杂扫描参数全解docs/VLAN_ARP_SCAN.md各模块源码backend/internal/适合家庭与小型机房管理员下一步把它接上 Grafana 面板即可。【免费下载链接】WatchYourLANLightweight network IP scanner written in Go. With notifications, history, export to Grafana项目地址: https://gitcode.com/GitHub_Trending/wa/WatchYourLAN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考