NetAlertX（PiAlert）核心干货整理指南

📋 一、平台介绍

NetAlertX 是一款开源、免费且自主托管的 网络资产发现与入侵检测系统。它被誉为局域网内的 “数字哨兵”，利用各种底层扫描协议持续监控网络环境。其核心价值在于帮助用户第一时间发现未知设备（如蹭网者或潜在入侵硬件）。

✨ 核心定义

• 架构类型：自托管开源软件 (Self-Hosted)
• 主要用途：资产管理、安全检测、异常报警
• 工作模式：持续监控局域网设备的在线状态、IP 变动及端口暴露情况。

🛠️ 二、核心功能详解

1. 持续扫描与资产发现

系统支持定期或实时对局域网进行深度扫描，自动构建并维护设备清单。支持的底层协议包括：

• ARP 扫描
• ICMP / PING
• DHCP 租约监测
• Nmap 端口探测

2. 变更与异常警报机制

当网络环境出现以下变动时触发即时警报：

• ⚠️ 新设备接入（未知硬件上线）
• 📴 设备离线（关键服务中断）
• 🔄 IP/MAC 漂移（地址冲突或 MAC 伪造）

3. 80+ 种通知通道集成

通过内置的 Apprise 代理，支持向以下主流渠道推送警报消息：

Telegram、Slack、Pushover、Discord、电子邮件、Webhooks 及其他自定义服务。

4. 多网络与 VLAN 监控

利用 Sync 插件（同步节点）功能，可实现跨子网管理：

• 支持多个子网 / VLAN 联动
• 适合远程分支机构资产汇总

5. 智能家居集成原生支持

通过 MQTT 协议完美对接 Home Assistant：

可将设备在线状态直接转化为自动化触发条件（如“检测到新设备 -> 记录日志”）。

🎯 三、适用人群与场景

角色典型需求NetAlertX 价值点Homelab 玩家掌控家中 NAS、软路由状态7x24 小时监控设备健康度，防止智能家居离线IT/中小企业 (SOHO)办公室局域网安全监测低成本防御非法接入（影子 IT），无需购买商业 IDS网络安全爱好者漏洞管理与资产测绘扫描暴露端口，快速发现潜在的网络攻击面变化

💰 四、开源与授权说明

📜 许可协议

• 完全免费且开源：遵循 GPL-3.0 协议。
• 商业性：无官方付费计划。所有核心功能、插件及通知通道均本地化运行，无需云端账户或订阅费。

🔗 相关资源链接

🌐 官方网站/文档https://netalertx.com

💾 GitHub 开源仓库https://github.com/netalertx/NetAlertX

🚀 五、快速部署指南 (Docker Compose)

官方推荐通过 docker-compose.yml 配置一键拉起。请严格按照以下步骤操作：

✅ 第一步：准备配置文件

1. 创建目录：在宿主机上新建一个文件夹（例如 /opt/netalertx/）。
2. 写入文件：在该目录下创建名为 docker-compose.yml 的文件，并填入以下核心配置内容：

yaml

services:
  netalertx:
    image: netalertx/netalertx:latest
    container_name: netalertx
    network_mode: "host" # 【关键】必须使用 host 模式以获取网络底层权限
    restart: unless-stopped
    volumes:
      - ./config:/app/config   # 配置文件映射 (Web UI、扫描设置)
      - ./db:/app/db           # 数据库文件映射 (SQLite/SQL)
    environment:
      - TZ=Asia/Shanghai       # 【建议】根据您的时区修改此选项
services:
  netalertx:
    image: netalertx/netalertx:latest
    container_name: netalertx
    network_mode: "host" # 【关键】必须使用 host 模式以获取网络底层权限
    restart: unless-stopped
    volumes:
      - ./config:/app/config   # 配置文件映射 (Web UI、扫描设置)
      - ./db:/app/db           # 数据库文件映射 (SQLite/SQL)
    environment:
      - TZ=Asia/Shanghai       # 【建议】根据您的时区修改此选项

✅ 第二步：启动容器服务

1. 进入目录：通过终端切换至配置文件所在目录。
2. 执行命令：输入以下指令后台运行服务：
3. bash

docker compose up -d
docker compose up -d

✅ 第三步：登录与初始化设置

1. 访问控制台：在浏览器地址栏输入 http://<您的设备 IP>:20211。
2. 配置扫描范围：进入后台后点击左侧菜单的 Settings (设置)，务必添加您要监控的子网（例如 192.168.1.0/24）。

⚠️ 六、部署注意事项与避坑指南

在初次使用或配置时，请务必关注以下风险点：

🌐 网络模式限制

• 强制 Host 模式：建议始终部署为 network_mode: "host"。
• ❌ Bridge 模式的后果：容器无法直接抓取局域网 ARP 广播包，导致 Nmap/ARP 扫描器失效，仅能发现映射在 Docker 网段内的设备。

🔒 安全防护与隐私

• 严禁公网裸奔：默认 Web UI 未开启密码保护。请勿将端口（20211）直接暴露在 WAN 口。
• ✅ 正确做法：配置反向代理（如 Nginx Proxy Manager）并启用 Basic Auth 或 Let's Encrypt HTTPS 证书。

📢 通知免打扰机制

• “新设备”洪水问题：首次启动时，系统会将现有已知设备识别为“新接入”，导致触发海量骚扰通知。
• ✅ 正确做法：先关闭所有通知通道。待扫描运行完毕、将所有正常设备在后台标记为 "Trusted (已信任)" 后，再重新开启通知功能。