Pi.Alert 详细部署教程

Pi.Alert 是一款网络入侵检测系统，能持续扫描你的 Wi-Fi/LAN 网络，发现未知设备连接时发出警报，并能监控“始终在线”设备的掉线情况。它最初为树莓派设计，也支持多数 Debian 系 Linux 发行版。

1. 项目现状与版本选择

在开始前，需要了解 Pi.Alert 的几个主要版本：

版本/分支	维护状态	部署方式	主要特点
leiweibau/Pi.Alert (github.com/leiweibau/Pi.Alert)	活跃维护 (推荐)	传统安装 (Bare-metal)	功能最新，持续更新，支持更多扫描源（如 UniFi, OPNsense）和通知方式。
pucherot/Pi.Alert (github.com/pucherot/Pi.Alert)	已停止维护 (原版)	传统安装	原始项目，功能较旧，适合参考，但不推荐新部署。
jokob-sk/NetAlertX (github.com/jokob-sk/NetAlertX)	活跃维护 (Docker版)	Docker	从 Pi.Alert 分支发展而来，已更名并转为 Docker 优先，不再依赖树莓派。

教程选择：下文将基于最活跃的 leiweibau/Pi.Alert 分支，介绍传统的 (Bare-metal) 安装方式，这也是最接近原版且社区支持度高的路径。

2. 准备工作

2.1 硬件与操作系统

硬件：几乎任何树莓派（或类似 SBC）均可。
操作系统：推荐安装 Raspberry Pi OS Lite (无桌面版) 或 Ubuntu Server，并要求是 Debian 系。
网络：设备需通过网线或稳定的 Wi-Fi 连接到你的主网络。
SMTP 邮件服务（可选但推荐）：Pi.Alert 可通过邮件发送通知。建议提前准备一个邮箱账户（如 Gmail）并配置好 SMTP 信息。如果暂不配置，安装过程可以跳过邮件设置。

2.2 连接并更新系统

将系统安装到 SD 卡并启动树莓派。
通过 SSH 连接到你的树莓派：ssh pi@<树莓派的IP地址> (默认密码为 raspberry)。
更新包列表和软件（这可能需要几分钟）：
1
sudo apt update && sudo apt upgrade -y

3. 安装 Pi.Alert

leiweibau 分支提供了一个自动化安装脚本，会处理绝大部分依赖和配置工作。

以 root 身份执行安装脚本：
在终端中复制并粘贴以下命令，然后按回车。此命令会下载并执行官方安装脚本。
1
sudo bash -c "$(wget -qLO - https://github.com/leiweibau/Pi.Alert/raw/main/install/pialert_install.sh)"
注意：较新的版本会将程序安装到 /opt/pialert 目录，而非旧版的 /home/pi，这是为了更好的安全性和系统兼容性。
交互式安装向导：
脚本运行后会启动一个文本界面的安装向导，按提示进行选择：
- 确认开始安装：选择 Yes。
- 选择 Python 版本：如果系统较新（安装了 Python 3），通常选择 Python 3 或 Default 。
- 扫描方法选择：
  - Pi-hole import：如果你在网络上运行了 Pi-hole，选择 Yes，Pi.Alert 会从 Pi-hole 的数据库和 DHCP 租约中读取设备信息。
  - arp-scan：这是核心的主动扫描方法，一般默认启用。
- 标记首次扫描设备：建议选择 No。安装完成后，你可以通过网页界面手动将设备标记为“已知”或“未知”，更不容易误报。
- 设置邮件通知：如果你想配置邮件警报，选择 Yes，然后依次输入 SMTP 服务器地址、用户名、密码 等信息。如果暂不设置，选 No 。
- 配置动态 DNS (DDNS)：如果你有 DDNS 服务并希望 Pi.Alert 监控公网 IP 变化，按提示输入域名和更新 URL。否则选 No。
完成安装：
向导结束后，脚本会完成最后的文件复制和 Web 服务器配置。记下终端最后显示的随机生成的管理员密码，首次登录网页界面时需要用到。

4. 首次启动与配置

4.1 访问 Web 界面

在浏览器地址栏输入 http://<树莓派的IP地址>/pialert (例如 http://192.168.1.128/pialert) 。
在登录界面，用户名通常为 admin，密码则是安装结束时生成的那个随机密码。

4.2 初始设置

登录后，你会看到设备列表和控制面板。

了解界面：
- 侧边栏：包含“设备”、“事件”、“设置”等核心导航。
- 仪表盘/设备列表：会显示 Pi.Alert 扫描到的所有设备。状态图标含义为：绿色表示在线，黄色表示新设备（待确认），红色表示触发了“离线”警报的设备。
配置扫描：
1. 进入 “设置” (Settings) 页面。
2. 检查 SCAN_SUBNETS 是否包含了你的网络子网（例如 192.168.1.0/24）。如果需要修改，可以直接编辑 pialert.conf 配置文件（位于 /opt/pialert/config/ 目录）。
3. 等待约 15 分钟，让 Pi.Alert 完成首次完整扫描。

4.3 设备管理

在 “设备” 列表中，找到你确认属于自己网络的设备。
点击设备条目，在详情页面或通过批量编辑功能，将它的状态标记为 “已知” (Known)。这样，Pi.Alert 就不会再对这些设备发出“未知设备”警报。
你还可以为设备设置 “始终在线” (Always Connected) 标志。这样，如果该设备离线，Pi.Alert 会发出“离线”警报。

至此，核心部署完成。之后你可以根据需求，在“设置”中配置 Telegram、Pushsafer 等更多通知渠道，或添加 Web 服务监控等功能。

5. 故障排除

问题	可能原因与解决方案
无法访问 Web 界面	1. 检查防火墙是否开放 `80` 或 `20211` (Docker版) 端口。 2. 确认 Lighttpd/Nginx Web 服务是否运行：`sudo systemctl status lighttpd`。 3. 尝试用 `http://<树莓派IP>:20211` (Docker版) 访问。
扫描不到任何设备	1. 检查 `SCAN_SUBNETS` 配置是否正确。 2. 确保树莓派与目标设备在同一二层网络（VLAN 或子网可能无法直接 arp-scan）。 3. 查看后端日志：`tail -f /opt/pialert/log/pialert.log`。
邮件通知无法发送	1. 确认 SMTP 服务器地址、用户名、密码（特别是使用 Gmail 等需要“应用专用密码”的服务）无误。 2. 检查 `REPORT_FROM` 配置是否为静态字符串（非 Python 表达式），新版本对安全性有要求。
如何更新？	使用以下命令更新到最新版：`sudo bash -c "$(wget -qLO - https://github.com/leiweibau/Pi.Alert/raw/main/install/pialert_update.sh)"` 。更新前建议备份数据库和配置文件。