feat: add P0 system health monitoring
This commit is contained in:
@@ -1,127 +1,147 @@
|
||||
# Pigway Pi Control v3.2.0 — Release
|
||||
# Pigway Pi Control v3.3.0 P0 System Health
|
||||
|
||||
适用于本套 Raspberry Pi 4B 散热扩展板的正式发布版。
|
||||
Raspberry Pi 4B + 配套 128×32 OLED / 风扇 / RGB 散热扩展板的本机硬件监控 Agent。
|
||||
|
||||
本包遵循一个原则：
|
||||
v3.3.0 的目标不是增加 Web/API，而是先把 **P0 本地检测、事件状态、日志、诊断和关机收尾**补完整，为后续多机 NAS 监控 API 打基础。
|
||||
|
||||
> **一个程序 + 一个用户配置文件 + 一个说明文档。**
|
||||
## 已有核心功能
|
||||
|
||||
正常使用时，不需要修改源码。
|
||||
- SSD1306 128×32 OLED，四行固定主页
|
||||
- CPU / 内存 / 温度 / 磁盘监控
|
||||
- Wi-Fi RSSI / Ethernet 链路速率
|
||||
- 当前默认路由与 IP 同步切换
|
||||
- 风扇自动温控、回差防抖
|
||||
- RGB：颜色表示故障对象，闪烁速度表示严重程度
|
||||
- systemd 服务与普通进程监控
|
||||
- Raspberry Pi PWR / ACT 运行时 Dark Mode
|
||||
|
||||
---
|
||||
|
||||
## 1. 功能
|
||||
|
||||
### OLED
|
||||
|
||||
配套 OLED 按卖家原生参数锁定为：
|
||||
|
||||
- SSD1306
|
||||
- 128×32
|
||||
- I²C `0x3C`
|
||||
- MUX `0x1F`
|
||||
- COM Pins `0x02`
|
||||
- Page `0..3`
|
||||
- 卖家同源 5×7 点阵字体
|
||||
- 4行：`0 / 8 / 16 / 24`
|
||||
|
||||
主页：
|
||||
主页示例：
|
||||
|
||||
```text
|
||||
CPU 18.6% MEM 16.2%
|
||||
TMP 46.3C FAN OFF
|
||||
DSK 22.4% NET OK
|
||||
DSK 22.4% WIF -32
|
||||
IP4 192.168.89.130
|
||||
```
|
||||
|
||||
IPv6 地址时自动显示 `IP6`。
|
||||
## v3.3.0 P0 新增
|
||||
|
||||
主页左右两栏都是固定位置、左对齐。数据默认每秒刷新。
|
||||
### 1. 供电与降频健康
|
||||
|
||||
有告警时，OLED 会在 HOME 与所有当前告警之间轮播；默认每页停留10秒。
|
||||
|
||||
### 风扇
|
||||
|
||||
默认：
|
||||
|
||||
```text
|
||||
< 50°C OFF
|
||||
50~53°C L1
|
||||
53~56°C L2
|
||||
56~59°C L3
|
||||
59~62°C L4
|
||||
>= 62°C MAX
|
||||
```
|
||||
|
||||
带降档回差，避免临界温度反复升降档。
|
||||
|
||||
### RGB 告警
|
||||
|
||||
正常状态 RGB 完全熄灭。
|
||||
|
||||
颜色表示“什么对象出问题”：
|
||||
|
||||
```text
|
||||
CPU 黄
|
||||
温度 红
|
||||
内存 紫
|
||||
磁盘 橙
|
||||
网络 蓝
|
||||
服务/进程 青
|
||||
```
|
||||
|
||||
所有告警都使用闪烁；闪烁速度表示严重程度：
|
||||
|
||||
```text
|
||||
Warning 慢
|
||||
Critical 中
|
||||
Emergency 快
|
||||
```
|
||||
|
||||
亮度可配置，默认10%，适合暗环境。
|
||||
|
||||
### Dark Mode
|
||||
|
||||
默认关闭 Raspberry Pi 自身：
|
||||
|
||||
- PWR LED
|
||||
- ACT LED
|
||||
|
||||
散热板 D1/D8 黄色硬件状态灯和独立电源模块绿色灯不属于已确认的软件控制接口，本程序不操作。
|
||||
|
||||
---
|
||||
|
||||
## 2. 全新 Raspberry Pi OS 安装
|
||||
|
||||
### 第一步：启用 I²C
|
||||
周期读取：
|
||||
|
||||
```bash
|
||||
sudo raspi-config
|
||||
vcgencmd get_throttled
|
||||
```
|
||||
|
||||
进入：
|
||||
区分：
|
||||
|
||||
- 当前欠压：立即 `POWER LOW / UNDERVOLT` 告警
|
||||
- 当前 CPU throttled / frequency capped：立即告警
|
||||
- 本次启动历史上曾欠压/降频：只写一次历史事件日志，不持续 RGB 告警
|
||||
- 状态恢复：写 `RECOVERED` 类事件
|
||||
|
||||
注意：这里检测的是 **Pi 的供电质量**，不是 UPS 电池百分比。
|
||||
|
||||
### 2. 文件系统健康
|
||||
|
||||
检测根文件系统 `/` 是否被内核切成只读。如果出现只读状态，产生严重告警：
|
||||
|
||||
```text
|
||||
Interface Options
|
||||
→ I2C
|
||||
→ Enable
|
||||
FILESYSTEM RO
|
||||
ROOT READ ONLY
|
||||
CHECK STORAGE
|
||||
```
|
||||
|
||||
然后：
|
||||
### 3. 本机诊断信息
|
||||
|
||||
内部维护：
|
||||
|
||||
- uptime
|
||||
- load average
|
||||
- CPU 当前频率
|
||||
- 当前/历史 throttled flags
|
||||
- 当前主网络接口 / IP
|
||||
- 根文件系统只读状态
|
||||
- sensor / network / service / health 最近成功时间
|
||||
- 主循环异常计数
|
||||
- I²C相关异常计数基础字段
|
||||
|
||||
### 4. 结构化事件日志
|
||||
|
||||
日志继续交给 systemd journal，不额外制造长期 `.log` 文件。
|
||||
|
||||
只在 **状态发生变化** 时记录关键事件，避免每秒刷屏。例如：
|
||||
|
||||
```text
|
||||
level=INFO event=START version=3.3.0
|
||||
level=INFO event=NET_SWITCH old_if=eth0 new_if=wlan0 ...
|
||||
level=WARN event=NETWORK_DOWN ...
|
||||
level=INFO event=NETWORK_RECOVERED ...
|
||||
level=WARN event=WATCH_DOWN name=AWESUN ...
|
||||
level=INFO event=WATCH_RECOVERED name=AWESUN ...
|
||||
level=WARN event=POWER_LOW raw=0x1
|
||||
level=INFO event=POWER_RECOVERED raw=0x0
|
||||
level=WARN event=ALERT_ACTIVE alert=TEMP_HIGH ...
|
||||
level=INFO event=ALERT_RECOVERED ...
|
||||
```
|
||||
|
||||
实时查看：
|
||||
|
||||
```bash
|
||||
sudo reboot
|
||||
journalctl -u pigway-pi-control -f
|
||||
```
|
||||
|
||||
### 第二步：解压本安装包
|
||||
|
||||
进入解压后的目录：
|
||||
只看本次启动：
|
||||
|
||||
```bash
|
||||
cd pigway-pi-control-v3.2.0
|
||||
journalctl -u pigway-pi-control -b --no-pager
|
||||
```
|
||||
|
||||
### 第三步：安装
|
||||
搜索某类事件：
|
||||
|
||||
```bash
|
||||
journalctl -u pigway-pi-control --no-pager | grep 'event=POWER'
|
||||
```
|
||||
|
||||
### 5. 诊断命令
|
||||
|
||||
```bash
|
||||
sudo /usr/local/sbin/pigway-pi-control --diagnose
|
||||
```
|
||||
|
||||
用于快速查看 uptime、load、CPU频率、throttled、根文件系统、当前网络和 Internet 状态。后续排障优先使用该命令，不再反复手工拼大量 grep。
|
||||
|
||||
### 6. 关机收尾
|
||||
|
||||
收到 systemd SIGTERM / 系统关机时：
|
||||
|
||||
1. 写 STOP 日志
|
||||
2. RGB OFF
|
||||
3. 风扇 OFF
|
||||
4. OLED 清屏并 Display OFF
|
||||
5. 关闭 I²C handle
|
||||
|
||||
Pi 红色 PWR 灯关机后恢复硬件默认亮起的行为不强行修改，可作为“系统已关机但 UPS 仍供电”的直观提示。
|
||||
|
||||
## 用户配置
|
||||
|
||||
正式配置只有一个：
|
||||
|
||||
```text
|
||||
/etc/pigway-pi-control.conf
|
||||
```
|
||||
|
||||
编辑：
|
||||
|
||||
```bash
|
||||
sudo nano /etc/pigway-pi-control.conf
|
||||
sudo systemctl restart pigway-pi-control
|
||||
```
|
||||
|
||||
配置文件内已经写明每项用途、单位和修改方式。
|
||||
|
||||
## 安装 / 升级测试分支
|
||||
|
||||
```bash
|
||||
sudo ./install.sh
|
||||
@@ -129,257 +149,25 @@ sudo ./install.sh
|
||||
|
||||
安装器会：
|
||||
|
||||
1. 检查 `/dev/i2c-1`
|
||||
2. 等待 APT/DPKG 锁
|
||||
3. 安装必要的小型系统依赖
|
||||
4. 检查 I²C 总线
|
||||
5. 自动停止并禁用卖家旧 `temp-control.service`
|
||||
6. 安装正式程序
|
||||
7. 安装用户配置
|
||||
8. 安装 systemd 服务并开机自启
|
||||
9. 执行安装后自检
|
||||
- 安装必要依赖
|
||||
- 检查 I²C
|
||||
- 禁用旧 `temp-control.service`
|
||||
- 安装字体、程序、配置和 systemd unit
|
||||
- 保留用户已有 `[services]` / `[processes]`
|
||||
- 启动服务
|
||||
- 执行版本、OLED、UI、P0健康监控和诊断入口自检
|
||||
|
||||
安装成功后查看：
|
||||
## 常用命令
|
||||
|
||||
```bash
|
||||
systemctl status pigway-pi-control --no-pager -l
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 安装后的文件在哪里
|
||||
|
||||
### 用户应该修改
|
||||
|
||||
只有：
|
||||
|
||||
```text
|
||||
/etc/pigway-pi-control.conf
|
||||
```
|
||||
|
||||
编辑：
|
||||
|
||||
```bash
|
||||
sudo nano /etc/pigway-pi-control.conf
|
||||
```
|
||||
|
||||
保存后：
|
||||
|
||||
```bash
|
||||
sudo systemctl restart pigway-pi-control
|
||||
```
|
||||
|
||||
### 用户通常不要修改
|
||||
|
||||
程序：
|
||||
|
||||
```text
|
||||
/usr/local/sbin/pigway-pi-control
|
||||
```
|
||||
|
||||
systemd：
|
||||
|
||||
```text
|
||||
/etc/systemd/system/pigway-pi-control.service
|
||||
```
|
||||
|
||||
这些由安装包维护。
|
||||
|
||||
因此安装成功后，解压出来的 `pigway-pi-control-v3.2.0/` 文件夹可以删除。
|
||||
|
||||
建议把 ZIP 保存到 Mac / NAS，供以后重装。
|
||||
|
||||
---
|
||||
|
||||
## 4. 用户可以自定义什么
|
||||
|
||||
全部集中在：
|
||||
|
||||
```text
|
||||
/etc/pigway-pi-control.conf
|
||||
```
|
||||
|
||||
其中包括：
|
||||
|
||||
- 数据采样周期
|
||||
- OLED刷新周期
|
||||
- 告警页面停留时间
|
||||
- 网络检查周期
|
||||
- 服务检查周期
|
||||
- 风扇温度曲线
|
||||
- 风扇降档回差
|
||||
- CPU告警阈值和持续时间
|
||||
- 内存告警阈值和持续时间
|
||||
- 温度普通/严重告警
|
||||
- 磁盘普通/严重告警
|
||||
- RGB亮度
|
||||
- Warning/Critical/Emergency 闪烁周期
|
||||
- Pi PWR/ACT灯
|
||||
- 要监控的systemd服务
|
||||
- 要监控的普通进程
|
||||
|
||||
**每个参数在配置文件中都已经写有详细中文注释。**
|
||||
|
||||
---
|
||||
|
||||
## 5. 增加一个服务监控
|
||||
|
||||
编辑：
|
||||
|
||||
```bash
|
||||
sudo nano /etc/pigway-pi-control.conf
|
||||
```
|
||||
|
||||
找到：
|
||||
|
||||
```ini
|
||||
[services]
|
||||
SSH = ssh.service
|
||||
AWESUN = runawesun.service
|
||||
```
|
||||
|
||||
例如安装了 Tailscale：
|
||||
|
||||
```ini
|
||||
TAILSCALE = tailscaled.service
|
||||
```
|
||||
|
||||
保存后：
|
||||
|
||||
```bash
|
||||
sudo systemctl restart pigway-pi-control
|
||||
```
|
||||
|
||||
先确认服务真实名称：
|
||||
|
||||
```bash
|
||||
systemctl status tailscaled.service
|
||||
```
|
||||
|
||||
暂时不想监控，行首加 `#`：
|
||||
|
||||
```ini
|
||||
# TAILSCALE = tailscaled.service
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 监控没有 systemd service 的程序
|
||||
|
||||
配置：
|
||||
|
||||
```ini
|
||||
[processes]
|
||||
MYAPP = /opt/myapp/server
|
||||
```
|
||||
|
||||
先测试：
|
||||
|
||||
```bash
|
||||
pgrep -af '/opt/myapp/server'
|
||||
```
|
||||
|
||||
能找到进程再加入监控。
|
||||
|
||||
---
|
||||
|
||||
## 7. 常用维护
|
||||
|
||||
状态：
|
||||
|
||||
```bash
|
||||
systemctl status pigway-pi-control --no-pager -l
|
||||
```
|
||||
|
||||
日志：
|
||||
|
||||
```bash
|
||||
journalctl -u pigway-pi-control -f
|
||||
```
|
||||
|
||||
重启：
|
||||
|
||||
```bash
|
||||
sudo systemctl restart pigway-pi-control
|
||||
sudo /usr/local/sbin/pigway-pi-control --diagnose
|
||||
```
|
||||
|
||||
停止：
|
||||
## 版本路线
|
||||
|
||||
```bash
|
||||
sudo systemctl stop pigway-pi-control
|
||||
```
|
||||
|
||||
启动：
|
||||
|
||||
```bash
|
||||
sudo systemctl start pigway-pi-control
|
||||
```
|
||||
|
||||
查看配置：
|
||||
|
||||
```bash
|
||||
cat /etc/pigway-pi-control.conf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 升级
|
||||
|
||||
新版安装包直接：
|
||||
|
||||
```bash
|
||||
sudo ./install.sh
|
||||
```
|
||||
|
||||
安装器会保留用户已有的 `[services]` 和 `[processes]` 监控列表，并备份旧配置。
|
||||
|
||||
升级后检查：
|
||||
|
||||
```bash
|
||||
systemctl status pigway-pi-control --no-pager -l
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 卸载
|
||||
|
||||
在安装包目录执行：
|
||||
|
||||
```bash
|
||||
sudo ./uninstall.sh
|
||||
```
|
||||
|
||||
卸载程序默认保留：
|
||||
|
||||
```text
|
||||
/etc/pigway-pi-control.conf
|
||||
```
|
||||
|
||||
避免误删用户自定义配置。
|
||||
|
||||
确认以后不再使用时可手工删除：
|
||||
|
||||
```bash
|
||||
sudo rm /etc/pigway-pi-control.conf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 重装树莓派时最短流程
|
||||
|
||||
以后即使完全忘记之前怎么安装，只需要：
|
||||
|
||||
```text
|
||||
1. 安装 Raspberry Pi OS
|
||||
2. raspi-config 开启 I²C
|
||||
3. 重启
|
||||
4. 解压本 ZIP
|
||||
5. cd pigway-pi-control-v3.2.0
|
||||
6. sudo ./install.sh
|
||||
```
|
||||
|
||||
完成。
|
||||
|
||||
## v3.2.0 网络状态增强
|
||||
|
||||
主页显示当前 Linux 默认路由接口：Wi-Fi 为 `WIF -52`（RSSI），有线为 `ETH 1G`（链路速率）。双网同时连接时跟随内核默认路由，IP 与该接口保持一致。新增 Wi-Fi 弱信号持续告警。
|
||||
- v3.2.0：主网络接口 / Wi-Fi RSSI / ETH速率 / 双网切换
|
||||
- **v3.3.0：P0 System Health，本地检测与日志完善**
|
||||
- 后续：只读 `/api/v1/...` Agent API，再由 NAS 统一汇总多台设备
|
||||
|
||||
Reference in New Issue
Block a user