aceberg/watchyourlan

WatchYourLAN 中文技术文档

镜像概述与主要用途

WatchYourLAN 是一款轻量级网络 IP 扫描器，提供 Web 图形界面（GUI），旨在帮助用户监控局域网内设备状态。其核心用途包括实时发现新设备、追踪主机在线/离线历史、维护网络设备清单，以及将数据导出至时序数据库（如 InfluxDB2、Prometheus），进而通过 Grafana 构建可视化监控仪表盘。

核心功能与特性

• 新主机发现通知：当网络中出现未知设备时，通过 Shoutrrr 发送通知（支持 、Email、Gotify、 等多种渠道）。
• 主机状态历史监控：记录所有设备的在线/离线时间，支持历史数据查询与展示。
• 网络设备清单管理：自动维护局域网内所有设备的 IP、MAC 地址、主机名等信息。
• 数据集成能力：支持将扫描数据导出至 InfluxDB2 或 Prometheus，便于与 Grafana 集成构建监控仪表盘。
• 轻量级设计：基于 Go 语言开发，资源占用低，部署简单。

界面预览

!https://raw.githubusercontent.com/aceberg/WatchYourLAN/main/assets/Screenshot_1.png

更多截图

展开查看

!https://raw.githubusercontent.com/aceberg/WatchYourLAN/main/assets/Screenshot_5.png
!https://raw.githubusercontent.com/aceberg/WatchYourLAN/main/assets/Screenshot_2.png
!https://raw.githubusercontent.com/aceberg/WatchYourLAN/main/assets/Screenshot_3.png
!https://raw.githubusercontent.com/aceberg/WatchYourLAN/main/assets/Screenshot_4.png

使用场景与适用范围

• 家庭网络监控：追踪家庭网络中接入的设备（如手机、智能家居设备），及时发现未知设备。
• 小型办公网络管理：监控员工设备在线状态，维护网络设备清单。
• 监控系统集成：作为网络层数据采集工具，与 InfluxDB2 + Grafana 或 Prometheus 集成，构建完整的网络监控体系。
• 无外部网络依赖场景：支持本地部署模式，可通过独立节点模块提供主题、图标等资源，无需访问互联网。

快速开始

Docker 快速部署

WatchYourLAN 需使用 host 网络模式以确保扫描功能正常。部署前需准备：

• 替换 $YOURTIMEZONE 为本地时区（如 Asia/Shanghai）；
• 替换 $YOURIFACE 为需扫描的网络接口（如 eth0，可通过 ip addr 命令查看）；
• 设置 $DOCKERDATAPATH 为数据持久化路径（如 /opt/docker/data）。

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

部署完成后，Web GUI 可通过 http://localhost:8840 访问。

详细配置说明

环境变量配置

配置可通过环境变量、配置文件或 GUI 完成，环境变量名称与配置文件参数一致（小写）。

基础配置

扫描设置

InfluxDB2 配置

用于将数据导出至 InfluxDB2，支持 Grafana 可视化。

Prometheus 配置

用于启用 Prometheus metrics 端点，支持 Prometheus 采集数据。

配置文件说明

配置文件名称为 config_v2.yaml，默认路径为 /data/WatchYourLAN/config_v2.yaml（通过 -d 参数可指定配置目录）。示例配置：

yaml
arp_args: ""                  # arp-scan 参数  
color: dark                   # 背景颜色  
host: 0.0.0.0                 # 监听地址  
ifaces: enp4s0                # 扫描接口  
influx_addr: ""               # InfluxDB2 地址  
influx_bucket: ""             # InfluxDB2 存储桶  
influx_enable: false          # 是否启用 InfluxDB2 导出  
influx_org: ""                # InfluxDB2 组织  
influx_skip_tls: false        # 是否跳过 TLS 验证  
influx_token: ""              # InfluxDB2 令牌  
log_level: info               # 日志级别  
nodepath: ""                  # 本地节点模块路径  
pg_connect: ""                # PostgreSQL 连接地址  
port: "8840"                  # Web 端口  
prometheus_enable: false      # 是否启用 Prometheus 端点  
shoutrrr_url: "gotify://192.168.0.1:8083/AwQqpAae.rrl5Ob/?title=Unknown host detected&DisableTLS=yes"  # 通知 URL  
theme: sand                   # 主题  
timeout: 60                   # 扫描间隔（秒）  
trim_hist: 48                 # 历史数据保留时间（小时）  
use_db: sqlite                # 数据库类型  

命令行选项

身份验证

WatchYourLAN 无内置身份验证功能，建议通过以下方式增强安全性：

• 使用 SSO 工具（如 Authelia）；
• 部署轻量认证应用 https://github.com/aceberg/ForAuth%E3%80%82

示例配置：参考 https://github.com/aceberg/WatchYourLAN/blob/main/docker-compose-auth.yml%E3%80%82

⚠️ 警告：WatchYourLAN 需使用 host 网络模式，因此 Web 端口会直接暴露。请通过防火墙或其他措施限制访问。

本地网络独立部署

默认情况下，Web 界面依赖外部网络获取主题、图标和字体。如需完全脱离外部网络，可部署独立节点模块镜像 aceberg/node-bootstrap 提供本地资源：

1. 启动 node-bootstrap 容器：

sh
docker run --name node-bootstrap \
    -p 8850:8850 \
    aceberg/node-bootstrap

2. 启动 WatchYourLAN 并指定本地节点路径：

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

（$YOUR_IP 为 node-bootstrap 容器所在主机的 IP 地址）

API 与集成

• API 文档：详见 https://github.com/aceberg/WatchYourLAN/blob/main/docs/API.md%E3%80%82
• 第三方集成：
  • ArchLinux (AUR): watch-your-lan
  • Python API 客户端: https://github.com/drwahl/py-watchyourlanclient
  • Umbrel 应用: Watch Your LAN
  • YunoHost 应用: watchyourlan

注意事项

1. 网络模式：必须使用 host 网络模式，否则无法正常扫描局域网设备。
2. 数据持久化：通过 -v 参数挂载数据卷，确保配置文件、数据库和历史记录不丢失。
3. 权限：容器需具备访问网络接口的权限（host 模式下默认具备）。
4. 依赖：若通过二进制包安装（非 Docker），需手动安装依赖 arp-scan 和 tzdata。