WatchYourLAN 网络IP扫描器技术分析

一、概述

1. 项目简介

WatchYourLAN 是一个轻量级网络 IP 扫描器，提供 Web 图形界面。该项目使用 Go 语言开发，旨在帮助用户监控局域网内的主机状态。

2. 核心特性

A. 主要功能

• 发现新主机时发送通知
• 监控主机在线/离线历史记录
• 维护网络中所有主机的列表
• 支持将数据发送到 InfluxDB2 或 Prometheus，用于构建 Grafana 仪表板

B. 技术特点

• 轻量级设计，资源占用少
• 基于 ARP 协议进行主机扫描
• 支持多种部署方式（Docker、Linux 包安装）
• 提供友好的 Web GUI 界面

3. 应用场景

A. 网络管理

• 家庭网络设备监控
• 办公环境资产管理
• 网络安全审计

B. 运维监控

• 设备可用性监控
• 异常设备检测
• 网络拓扑可视化

二、系统架构

1. 整体架构

graph TB
    subgraph "扫描层"
        A[ARP Scanner]
        B[arp-scan 工具]
    end

    subgraph "数据处理层"
        C[数据存储]
        D[SQLite/PostgreSQL]
        E[历史记录管理]
    end

    subgraph "通知层"
        F[Shoutrrr 通知]
        G[多渠道通知]
    end

    subgraph "集成层"
        H[InfluxDB2 导出]
        I[Prometheus 导出]
        J[Grafana 仪表板]
    end

    subgraph "展示层"
        K[Web GUI]
        L[主题系统]
    end

    A --> B
    A --> C
    C --> D
    C --> E
    A --> F
    F --> G
    C --> H
    C --> I
    H --> J
    I --> J
    C --> K
    K --> L

2. 核心组件

A. ARP 扫描模块

使用 arp-scan 工具进行网络扫描，支持：

• 多网卡同时扫描
• 自定义扫描参数
• VLAN 环境支持

B. 数据存储模块

• SQLite：轻量级部署场景
• PostgreSQL：大规模部署场景
• 历史记录可配置存储策略

C. 通知系统

集成 Shoutrrr 通知库，支持：

• Discord
• Email
• Gotify
• Matrix
• Ntfy
• Pushover
• Slack
• Telegram
• Generic Webhook

D. 数据导出

• InfluxDB2：时序数据存储
• Prometheus：监控指标暴露

3. 数据流

sequenceDiagram
    participant S as ARP Scanner
    participant D as Database
    participant N as Notification
    participant E as External Storage
    participant U as Web UI

    S->>D: 存储主机信息
    S->>N: 检测到新主机
    N->>U: 发送通知
    S->>E: 导出历史数据
    U->>D: 读取主机列表
    U->>D: 查询历史记录

三、技术实现

1. 技术栈

A. 后端技术

• 语言：Go
• 数据库：SQLite、PostgreSQL
• 扫描工具：arp-scan
• 通知：Shoutrrr

B. 前端技术

• Web 框架：Bootstrap
• 主题：Bootswatch
• 图标：Flaticon

2. 扫描原理

A. ARP 协议扫描

使用 ARP（Address Resolution Protocol）请求发现局域网内的活动主机：

graph LR
    A[扫描器] -->|发送 ARP 请求| B[广播域]
    B --> C[主机 1]
    B --> D[主机 2]
    B --> E[主机 3]
    C -->|ARP 响应| A
    D -->|ARP 响应| A
    E -->|ARP 响应| A

B. 扫描配置

关键参数：

• IFACES：指定扫描网卡
• TIMEOUT：扫描间隔（默认 120 秒）
• ARP_ARGS：arp-scan 自定义参数
• TRIM_HIST：历史记录保留时间（默认 48 小时）

3. 通知机制

A. 新主机检测

首次发现主机时触发通知，配置示例：

shoutrrr_url: "gotify://192.168.0.1:8083/AwQqpAae.rrl5Ob/?title=Unknown host detected&DisableTLS=yes"

B. 支持的通知渠道

四、部署方案

1. Docker 部署

A. 基础部署

docker run --name wyl \
    -e "IFACES=$YOURIFACE" \
    -e "TZ=$YOURTIMEZONE" \
    --network="host" \
    -v $DOCKERDATAPATH/wyl:/data/WatchYourLAN \
    aceberg/watchyourlan

重要说明：

• 必须使用 host 网络模式
• 需要指定扫描网卡接口
• 配置数据持久化路径

B. Docker Compose 部署

支持通过 docker-compose.yml 进行编排部署，包含认证配置示例。

2. Linux 系统部署

A. 支持的发行版

• Debian/Ubuntu：.deb 包
• RedHat/CentOS：.rpm 包
• Alpine Linux：.apk 包
• 通用：.tar.gz 压缩包

B. 支持的架构

• amd64
• i386
• arm_v5、arm_v6、arm_v7
• arm64

C. 依赖要求

• arp-scan
• tzdata

3. 配置管理

A. 配置方式

• 配置文件：config_v2.yaml
• 环境变量：Docker 部署
• Web GUI：可视化配置

B. 基础配置项

C. 扫描配置项

五、集成与扩展

1. InfluxDB2 集成

A. 配置参数

B. 数据用途

• 长期历史数据存储
• Grafana 仪表板展示
• 趋势分析

2. Prometheus 集成

A. 配置参数

B. 使用方式

Prometheus 可通过 /metrics 端点抓取监控数据。

3. 认证集成

A. 第三方认证工具

• Authelia：SSO 单点登录
• ForAuth：简单认证应用

B. 安全建议

由于需要 host 网络模式，端口会直接暴露，建议：

• 使用防火墙限制访问
• 配置反向代理认证
• 部署在隔离网络

六、最佳实践

1. 网络配置

A. 网卡选择

• 选择连接内网的物理网卡
• 避免使用 Docker 虚拟网卡
• 多网卡环境用空格分隔

B. 扫描间隔

• 高频扫描：30-60 秒（实时监控）
• 标准扫描：120 秒（推荐）
• 低频扫描：300 秒以上（节省资源）

2. 数据管理

A. 历史记录策略

• 短期存储：内存存储（HIST_IN_DB=false）
• 长期存储：数据库 + InfluxDB2
• 数据清理：设置合理的 TRIM_HIST

B. 数据库选择

• 小型网络（< 100 设备）：SQLite
• 中大型网络：PostgreSQL
• 高可用需求：PostgreSQL + 主从复制

3. 监控告警

A. 通知配置

• 新主机检测：启用通知
• 通知频率：避免重复告警
• 通知渠道：选择可靠渠道

B. Grafana 仪表板

利用 InfluxDB2 数据构建可视化仪表板，监控：

• 设备在线趋势
• 网络设备总数
• 异常设备检测

七、技术优势与局限

1. 技术优势

A. 轻量高效

• 单一二进制文件，无需复杂依赖
• 资源占用少，适合嵌入式设备
• 快速部署，开箱即用

B. 功能全面

• 支持多种通知渠道
• 集成主流监控工具
• 提供友好的 Web 界面

C. 灵活扩展

• 支持多种部署方式
• 丰富的配置选项
• 良好的集成能力

2. 技术局限

A. 网络模式限制

• 必须使用 host 网络模式
• 安全隔离性较差
• 不适合多租户环境

B. 认证机制缺失

• 无内置认证功能
• 需要依赖第三方工具
• 配置相对复杂

C. 扫描协议限制

• 仅支持 ARP 协议
• 无法跨越网段扫描
• 依赖网络二层互通

八、适用场景分析

1. 家庭网络

A. 需求特点

• 设备数量较少（10-50 台）
• 简单部署需求
• 基本监控功能

B. 推荐配置

• 数据库：SQLite
• 扫描间隔：120 秒
• 通知：Telegram 或 Email
• 数据存储：内存即可

2. 办公网络

A. 需求特点

• 设备数量中等（50-500 台）
• 需要历史数据
• 集成监控系统

B. 推荐配置

• 数据库：PostgreSQL
• 扫描间隔：60 秒
• 通知：Slack 或 Discord
• 数据存储：InfluxDB2 + Grafana

3. 数据中心

A. 需求特点

• 设备数量大（500+ 台）
• 高可用要求
• 安全审计需求

B. 推荐配置

• 数据库：PostgreSQL 主从
• 扫描间隔：30 秒
• 通知：多种渠道冗余
• 数据存储：InfluxDB2 + Prometheus

九、技术对比

1. 与其他网络扫描工具对比

2. 技术选型建议

A. 选择 WatchYourLAN 的场景

• 需要 Web GUI 界面
• 需要通知功能
• 需要集成监控系统
• 轻量级部署需求

B. 选择其他工具的场景

• 需要复杂端口扫描：Nmap
• 需要跨网段扫描：专业资产管理系统
• 需要云端管理：Fing 商业版

十、总结

WatchYourLAN 是一个设计简洁、功能实用的网络 IP 扫描器。它采用 Go 语言开发，基于 ARP 协议进行主机发现，提供了友好的 Web 界面和丰富的集成能力。

该项目特别适合家庭和小型办公网络的设备监控场景，通过集成 InfluxDB2 和 Prometheus，可以构建完整的网络监控解决方案。虽然存在 host 网络模式的安全限制和缺乏内置认证等不足，但通过合理配置和第三方工具集成，可以满足大多数网络监控需求。

对于需要轻量级、易部署的网络设备监控解决方案的用户，WatchYourLAN 是一个值得考虑的选择。

参考资料

1. WatchYourLAN GitHub 仓库
2. arp-scan 官方文档
3. Shoutrrr 通知库
4. InfluxDB2 文档
5. Prometheus 文档