WatchYourLAN 部署指南：Docker 一条命令跑起局域网 IP 扫描，附配置清单与 VLAN 扫描实操

WatchYourLAN 部署指南Docker 一条命令跑起局域网 IP 扫描附配置清单与 VLAN 扫描实操【免费下载链接】WatchYourLANLightweight network IP scanner written in Go. With notifications, history, export to Grafana项目地址: https://gitcode.com/GitHub_Trending/wa/WatchYourLANWatchYourLAN 是一个用 Go 编写的轻量级局域网 IP 扫描器靠arp-scan持续发现主机、记录在线/离线历史、发现未知主机时推送通知并支持将数据导出到 InfluxDB2 / Prometheus 供 Grafana 消费。本文覆盖 Docker 与 Linux 二进制安装、三类配置方式、VLAN/多网段扫描、认证方案与 HTTP API 集成并给出避坑清单。项目速览它替你盯什么新主机通知扫描到未知 MAC 时经 Shoutrrr 推送Discord、Email、Gotify、Matrix、Ntfy、Pushover、Slack、Telegram、Generic Webhook 等在线/离线历史每次扫描对每台主机落一条历史快照按TRIM_HIST自动清理全网主机清单维护 IP、MAC、厂商、接口、名称含 DNS 解析名、Known 状态Grafana 数据出口写 InfluxDB2 行协议或暴露 Prometheuswatch_your_lan_up指标轻量部署单 Go 二进制 一个arp-scan依赖无其他运行时依赖启动链路见 backend/cmd/WatchYourLAN/main.goconf.Start读配置 →gdb.Start连库建表 → 两个协程ScanRestart周期扫描与HistoryTrim历史裁剪→web.Gui起 Web 界面默认:8840。数据库默认 SQLitescan.db表now当前清单history历史GORMAutoMigrate自动建表。最快上手Docker 一条命令docker run --name wyl \ -e IFACES$YOURIFACE \ -e TZ$YOURTIMEZONE \ --networkhost \ -v $DOCKERDATAPATH/wyl:/data/WatchYourLAN \ aceberg/watchyourlan参数作用默认值备注IFACES要扫描的网口空格分隔多个空必填用ip link show查看漏配则一轮扫描都不执行TZ时区空必填否则历史记录时间不准--networkhost使用宿主机网络bridge必须arp-scan要在宿主网络栈收发 ARP 包-v ...:/data/WatchYourLAN数据卷无配置config_v2.yaml与scan.db都落在这里镜像官方镜像latestaceberg/watchyourlan验证访问http://localhost:8840容器默认HOST0.0.0.0、PORT8840。等一个扫描周期默认 120 秒后Home 页面出现主机列表即为成功也可用 API 快速确认curl -s http://localhost:8840/api/all curl -s http://localhost:8840/api/status/偏好 compose 的话仓库自带 docker-compose.yml写法与上面等价并预留了注释掉的node-bootstrap服务离线资源见后文。不装 Docker 时从 release 下载二进制包支持.deb、.rpm、.apkAlpine与.tar.gz架构覆盖amd64、i386、arm_v5、arm_v6、arm_v7、arm64。运行时依赖两个系统包arp-scan和tzdataamd64另有.debapt 源可跟随更新。配置全景哪些项必须改配置三选一环境变量、config_v2.yaml数据目录内、Web GUI。底层统一走 Viper先设默认值再读 YAML最后AutomaticEnv()让环境变量覆盖backend/internal/conf/read.go。配置文件键名与环境变量同名但全小写TIMEOUT↔timeout。基础配置变量说明默认值备注TZ时区空必填HOST/PORTWeb 监听地址/端口0.0.0.0/8840改端口记得同步防火墙THEME/COLOR主题bootswatch 主题小写名/ 背景色sand/darkLOG_LEVEL日志级别info排错时开debug可看到实际arp-scan命令NODEPATH本地 node modules 地址空离线模式用见进阶场景SHOUTRRR_URL通知渠道 URL空空则只记日志不推送扫描配置变量说明默认值备注IFACES扫描接口空格分隔空必填TIMEOUT两次扫描间隔秒120协程每秒检查一次超时即扫ARP_ARGS追加给每个接口的arp-scan参数空如-r 1重试 1 次ARP_STRS/ARP_STRS_JOINED独立于 IFACES 的完整扫描串空VLAN/docker0 用见进阶场景TRIM_HIST历史保留时长小时48超期自动删USE_DB/PG_CONNECT数据库类型 / PostgreSQL 连接串sqlite/ 空PG 连接失败静默回退 SQLiteHIST_IN_DB自 2.1.3 起弃用空历史始终在库里用TRIM_HIST控体积集成配置变量说明默认值备注INFLUX_ENABLE启用 InfluxDB2 导出false每次比对后写一条行协议INFLUX_ADDR/INFLUX_BUCKET/INFLUX_ORG/INFLUX_TOKENInfluxDB2 连接信息空与 Grafana 数据源配置一致INFLUX_SKIP_TLS跳过 TLS 校验false内网自签证书时置truePROMETHEUS_ENABLE暴露/metricsfalse未启用时该端点返回 404命令行参数backend/cmd/WatchYourLAN/main.go 定义参数说明默认值-d配置目录配置与数据库都在这里/data/WatchYourLAN-nnode modules 路径替代互联网拉取主题/图标/字体空完整配置文件示例config_v2.yamlarp_args: color: dark host: 0.0.0.0 ifaces: enp4s0 influx_addr: influx_bucket: influx_enable: false influx_org: influx_skip_tls: false influx_token: log_level: info nodepath: pg_connect: port: 8840 prometheus_enable: false shoutrrr_url: gotify://192.168.0.1:8083/AwQqpAae.rrl5Ob/?titleUnknown host detectedDisableTLSyes theme: sand timeout: 60 trim_hist: 48 use_db: sqlitetimeout: 60表示 60 秒一轮扫描默认 120扫描越频繁历史数据量越大TRIM_HIST要相应调小。port在 YAML 里建议加引号避免被解析为整数引发类型错误。进阶场景多网段、离线环境与通知对接场景一VLAN / docker0 等多网段扫描IFACES只能覆盖接口直接所在的网段。跨网段、VLAN 或容器网桥docker0、virbr0时用ARP_STRS每条字符串原样拼成一条命令arp-scan $ONE_STRING与 IFACES 扫描完全独立实现见 backend/internal/arp/arpscan.go。# 扫 VLAN 107-Q 指定 VLAN ID arp-scan -gNx 10.0.107.0/24 -Q 107 -I eth0 # 扫 docker0 网段 arp-scan -gNx 172.17.0.1/24 -I docker0docker-compose / 环境变量场景用ARP_STRS_JOINED逗号分隔逗号前后不能有空格ARP_STRS_JOINED: -gNx 172.17.0.1/24 -I docker0,-gNx 10.0.107.0/24 -Q 107 -I eth0配置文件写法arp_strs是字符串列表arp_strs: - -gNx 172.17.0.1/24 -I docker0 - -glNx -I virbr0⚠️ 坑字符串的最后一个元素会被当作发现主机的接口名写入记录所以接口名如eth0务必放在每条字符串末尾。另注意ARP_STRS只能经配置文件/GUI 设置docker-compose 里写ARP_STRS无效必须用ARP_STRS_JOINED。场景二完全隔离的离线内网默认 Web 界面会从互联网拉主题、图标和字体。隔离网络用辅助镜像aceberg/node-bootstrap本地化docker run --name node-bootstrap -p 8850:8850 aceberg/node-bootstrapdocker run --name wyl \ -e IFACES$YOURIFACE \ -e TZ$YOURTIMEZONE \ --networkhost \ -v $DOCKERDATAPATH/wyl:/data/WatchYourLAN \ aceberg/watchyourlan -n http://$YOUR_IP:8850compose 里则取消node-bootstrap服务及command: -n http://YOUR_IP:8850的注释。⚠️ 坑-n指向的地址必须用服务器可达的 IP/域名容器自身localhost:8850不通资源服务没起来时页面样式会缺失但不影响扫描功能。场景三未知主机通知Shoutrrr配置只需一个 URL协议头决定渠道Discord、Email、Gotify、Matrix、Ntfy、Pushover、Slack、Telegram、Webhook 等配好后用 API 发测试消息验证curl http://0.0.0.0:8840/api/notify_test新主机出现时的推送格式固定为Unknown host found. Name: %s, IP: %s, MAC: %s, Hw: %s, Iface: %s⚠️ 坑SHOUTRRR_URL为空时程序不报错只把事件写日志不推送——没收到通知先查这个变量是否真的落进了配置GUI 保存与环境变量覆盖容易漏掉一侧。场景四PostgreSQL 替换 SQLiteUSE_DBpostgres PG_CONNECTpostgres://username:password192.168.0.1:5432/dbname?sslmodedisablebackend/internal/gdb/start.go 中 PG 连接失败只会打 warn 日志并自动回退 SQLite服务不中断。⚠️ 坑回退后数据写在本地scan.db而非 PostgreSQL表面看一切正常。启用后先看启动日志是否出现Connected to DB: PostgreSQL否则核对连接串。生态与集成认证、监控导出与 API认证项目本身不带认证官方推荐 Authelia 或作者的 ForAuth示例见 docker-compose-auth.ymlforauth: image: aceberg/forauth restart: unless-stopped ports: - 8800:8800 # 代理端口 - 8801:8801 # 配置端口 volumes: - ~/.dockerdata/forauth:/data/ForAuth environment: FA_TARGET: YOUR_IP:8840 # 指向 WYL 的 host:port FA_AUTH: true FA_AUTH_EXPIRE: 7d FA_AUTH_PASSWORD: $$2a$$10$$wGLUHXh2cRN1257uGg1s5eZvYgnjw8wB9vAcfcHqqqrxm5hvBqAzK FA_AUTH_USER: user⚠️ 关键前提WYL 必须host网络模式Web 端口直接暴露在宿主网络上。接入 ForAuth/SSO 只挡浏览器路径务必再用防火墙限制8840端口的来源 IP。compose 环境变量里的$必须写成$$bcrypt 哈希含$。监控导出两个出口都是每轮扫描比对后逐主机更新Grafana 任选其一接出口数据形态说明InfluxDB2WatchYourLAN,IP...,iface...,name...,mac...,known... state0/1行协议state1在线、0离线连接前会先 Ping 服务器Prometheuswatch_your_lan_up{ip..., iface..., name..., mac..., known...} 0/1/metrics端点gauge 向量未启用返回 404HTTP API完整文档 docs/API.mdv2.1.4 起启动后访问/swagger/可在线浏览方法路径用途GET/api/all全部主机 JSONGET/api/history全部历史量大不推荐GET/api/history/:mac/:date按 MAC 日期过滤date可取2、2025-07、2025-07-26任意粒度GET/api/history/:mac?num20某设备最近 20 条历史GET/api/host/:id按 ID 取主机GET/api/port/:addr/:port端口开放检测返回true/falseGET/api/edit/:id/:name/*known改主机名known传toggle切换已知状态GET/api/host/del/:id删除主机GET/api/host/add/:mac从 API 添加主机GET/api/wol/:mac发送 Wake-on-LAN 魔法包GET/api/notify_test发送测试通知GET/api/status/*iface总数/在线离线/已知未知统计可只查某接口GET/api/rescan立即触发一轮重扫GET/api/version版本号嵌入现有工作流定时任务里curl /api/status/即可把在线数喂给任何告警脚本/api/port/:addr/:port可做资产端口巡检/api/host/del/:id、/api/edit/...支持自动化纳管。社区亦有 Python API 客户端、Umbrel / YunoHost 应用、AUR 包均基于以上端点。避坑清单现象 → 原因 → 解法现象Home 页面始终无主机。原因arp-scan未安装或IFACES为空/接口名错误。解法which arp-scan确认后手动执行arp-scan -glNx -I $IFACE验证有输出把LOG_LEVEL设为debug看每轮实际执行的命令。现象历史记录时间差 6~18 小时。原因TZ未设置或二进制包环境缺tzdata。解法补TZ$YOURTIMEZONE非容器环境apt install tzdata。现象docker-compose 里配了ARP_STRS但 VLAN 网段从未出现。原因ARP_STRS只能来自配置文件/GUI环境变量形态是ARP_STRS_JOINED且逗号前后带空格会拆出错误命令。解法改用ARP_STRS_JOINED逗号紧贴字符串接口名放每条末尾。现象配了 PostgreSQL但数据仍在本地scan.db。原因PG 连接失败自动回退 SQLite仅一条 warn 日志。解法查启动日志确认Connected to DB: PostgreSQL否则核对PG_CONNECT连接串与网络连通性。现象隔离内网里页面样式/图标加载失败。原因界面默认从互联网拉主题资源。解法部署aceberg/node-bootstrap并加-n http://$YOUR_IP:8850或设NODEPATH。决策清单下一步做什么确认IFACES与TZ两个必填项用 Docker 一条命令或 release 二进制装arp-scan把服务跑起来访问:8840验证。有 VLAN/docker0 网段就配ARP_STRS文件/GUI或ARP_STRS_JOINED环境变量接口名放字符串末尾。需要告警时填SHOUTRRR_URL先打GET /api/notify_test确认渠道通再依赖它。接 Grafana 时二选一PROMETHEUS_ENABLEtrue走/metrics配置最少或配齐 InfluxDB2 五件套。服务要暴露到局域网外先接 ForAuth/Authelia同时用防火墙限制8840端口来源。隔离内网补node-bootstrap-n资源地址把最后一条外网依赖也掐掉。【免费下载链接】WatchYourLANLightweight network IP scanner written in Go. With notifications, history, export to Grafana项目地址: https://gitcode.com/GitHub_Trending/wa/WatchYourLAN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考