WatchYourLAN常见问题FAQ：从部署到功能故障排除

【免费下载链接】WatchYourLAN Lightweight network IP scanner with web GUI 项目地址: https://gitcode.com/GitHub_Trending/wa/WatchYourLAN

引言：解决你的网络扫描痛点

你是否在部署WatchYourLAN时遇到网络模式配置困惑？扫描不到设备时无从下手？通知功能失效不知如何排查？本文系统梳理从部署到高级功能的20+常见问题，通过12个实操案例、8张配置对比表和5个故障排除流程图，帮你一站式解决Lightweight network IP scanner的所有技术难题。读完本文你将掌握：Docker与Linux原生部署的坑点规避、ARP参数调优技巧、MAC厂商自定义方法、通知失败的5层排查法，以及InfluxDB数据持久化方案。

一、部署常见问题与解决方案

1.1 Docker部署网络模式必知

问题现象：容器启动后Web界面可访问，但扫描结果始终为空
根本原因：未正确配置host网络模式导致ARP扫描失败

配置项	错误示例	正确配置	影响
network_mode	bridge	host	必须使用host模式以获取网络接口访问权限
端口映射	-p 8840:8840	无需端口映射	host模式下直接使用主机端口
环境变量	IFACES=eth0	IFACES=正确接口名	使用ip link show确认接口名称

正确部署命令：

docker run --name wyl \
  -e "IFACES=eth0" \
  -e "TZ=Asia/Shanghai" \
  --network="host" \
  -v /opt/wyl:/data/WatchYourLAN \
  aceberg/watchyourlan

⚠️ 警告：Windows和macOS的Docker Desktop不支持host网络模式，需使用Linux原生部署或虚拟机方案

1.2 Linux系统服务部署故障排除

问题现象：systemctl start watchyourlan启动失败，状态显示exited
排查流程：

解决方案：

1. 安装必需依赖：sudo apt install arp-scan tzdata -y（Debian/Ubuntu）
2. 验证配置文件权限：chmod 600 /etc/watchyourlan/config_v2.yaml
3. 服务状态检查命令集：

sudo systemctl enable watchyourlan  # 设置开机自启
sudo systemctl status watchyourlan  # 查看当前状态
sudo journalctl -u watchyourlan -f  # 实时查看日志

二、核心配置参数解析与常见错误

2.1 IFACES与ARP参数配置矩阵

问题现象：指定多接口扫描时部分网段无结果
技术原理：IFACES、ARP_ARGS与ARP_STRS的优先级关系

参数类型	使用场景	优先级	配置示例
IFACES	简单单网段扫描	基础级	IFACES="eth0 wlan0"
ARP_ARGS	全局ARP扫描参数	次级	ARP_ARGS="--timeout=500"
ARP_STRS	复杂多网段/VLAN扫描	最高	ARP_STRS=["--macfile=/data/mac-vendor.txt -I eth0 192.168.1.0/24"]

多VLAN扫描配置示例：

arp_strs:
  - --macfile=/data/mac-vendor.txt -gNx 10.0.107.0/24 -Q 107 -I eth0
  - --macfile=/data/mac-vendor.txt -gNx 10.0.108.0/24 -Q 108 -I eth0

⚠️ 注意：当ARP_STRS存在时，IFACES配置将被忽略，所有扫描参数需在ARP_STRS中显式定义

2.2 MAC厂商自定义覆盖方案

业务需求：网络中存在私有OUI的设备需要正确识别厂商信息
实现步骤：

1. 创建mac-vendor.txt文件：

00:1A:2B:3C:4D:5E  MyCustomVendor
00:AA:BB:CC:DD:EE  AnotherVendor

2. 配置ARP参数（二选一）：

   • 针对IFACES模式：

   arp_args: --macfile=/data/WatchYourLAN/mac-vendor.txt
   

   • 针对ARP_STRS模式：

   arp_strs:
     - --macfile=/data/WatchYourLAN/mac-vendor.txt -gNx 192.168.1.0/24 -I eth0
   

3. 使配置生效：

# Docker环境
docker restart wyl

# Linux服务环境
sudo systemctl restart watchyourlan

⚠️ 警告：更新厂商信息后需删除对应主机记录才能看到更新效果，历史记录不会自动刷新

三、功能故障排除高级指南

3.1 扫描结果异常排查流程图

关键命令工具包：

# 检查接口是否支持ARP
ip link show eth0

# 手动执行扫描测试
sudo arp-scan -I eth0 192.168.1.0/24

# 查看应用日志
tail -f /data/WatchYourLAN/logs/app.log

3.2 通知功能失效5层排查法

问题现象：新设备接入但未收到通知
排查层级：

1. 配置层：验证Shoutrrr URL格式

# 正确示例：Gotify通知
shoutrrr_url: "gotify://192.168.0.1:8083/AwQqpAae.rrl5Ob/?title=Unknown host detected&DisableTLS=yes"

2. 网络层：测试目标通知服务连通性

curl -X POST http://192.168.0.1:8083/message \
  -H "Content-Type: application/json" \
  -d '{"title":"Test","message":"Hello"}'

3. 应用层：触发测试通知

# 通过API发送测试通知
curl http://localhost:8840/api/notify_test

4. 代码层：检查日志中的通知错误

grep "Notification failed" /data/WatchYourLAN/logs/app.log

5. 依赖层：确认Shoutrrr支持对应服务

// 内部实现逻辑
err := shoutrrr.Send(conf.AppConfig.ShoutURL, wyl+msg)
if err != nil {
    slog.Error("Notification failed (shoutrrr): ", "", err)
}

四、高级功能配置与优化

4.1 InfluxDB数据持久化配置

配置对比表：

参数	描述	默认值	推荐配置
INFLUX_ENABLE	启用数据导出	false	true
INFLUX_ADDR	数据库地址	""	http://influxdb:8086
INFLUX_TOKEN	访问令牌	""	从InfluxDB界面生成
INFLUX_ORG	组织名称	""	my-org
INFLUX_BUCKET	存储桶名称	""	wyl_metrics
INFLUX_SKIP_TLS	跳过TLS验证	false	开发环境true，生产环境false

配置示例：

influx_enable: true
influx_skip_tls: true
influx_addr: http://192.168.2.3:8086/
influx_bucket: test
influx_org: home
influx_token: your_secure_token_here

4.2 Prometheus监控集成

实现步骤：

1. 启用Prometheus端点：

prometheus_enable: true

2. 配置Prometheus抓取：

scrape_configs:
  - job_name: 'watchyourlan'
    static_configs:
      - targets: ['localhost:8840']

3. 关键指标说明：
   • wyl_hosts_total：总主机数
   • wyl_hosts_online：在线主机数
   • wyl_scan_duration_seconds：扫描耗时
   • wyl_scan_errors_total：扫描错误计数

五、总结与最佳实践

5.1 部署方式选择建议

部署方式	适用场景	优势	注意事项
Docker	快速测试、多环境隔离	部署简单、依赖管理方便	需host网络模式，性能略低
Linux原生	生产环境、性能要求高	资源占用少、启动更快	需手动管理依赖和服务

5.2 日常维护 checklist

1. 每日检查：

   • 扫描状态：curl http://localhost:8840/api/status
   • 日志错误：grep "ERROR" /data/WatchYourLAN/logs/app.log

2. 每周维护：

   • 数据库备份：cp /data/WatchYourLAN/scan.db /backup/
   • 版本更新：关注Docker镜像更新或GitHub发布

3. 每月优化：

   • 调整TRIM_HIST参数控制数据库大小
   • 清理旧日志：rm /data/WatchYourLAN/logs/app.log.old

通过本文的指南，你已经掌握了WatchYourLAN从部署到高级功能的全方位解决方案。记住，网络扫描问题通常可以通过"接口检查-手动测试-日志分析"三步法解决。如有其他问题，欢迎在项目GitHub讨论区交流。收藏本文，下次遇到问题时即可快速查阅解决方案！

【免费下载链接】WatchYourLAN Lightweight network IP scanner with web GUI 项目地址: https://gitcode.com/GitHub_Trending/wa/WatchYourLAN