186 lines
6.5 KiB
Markdown
186 lines
6.5 KiB
Markdown
# Pigway Pi Control v3.3.0 P0 System Health
|
||
|
||
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
|
||
|
||
主页示例：
|
||
|
||
```text
|
||
CPU 18.6% MEM 16.2%
|
||
TMP 46.3C FAN OFF
|
||
DSK 22.4% WIF -32
|
||
IP4 192.168.89.130
|
||
```
|
||
|
||
## v3.3.0 P0 新增
|
||
|
||
### 1. 供电与降频健康
|
||
|
||
周期读取：
|
||
|
||
```bash
|
||
vcgencmd get_throttled
|
||
```
|
||
|
||
区分：
|
||
|
||
- 当前欠压：立即 `POWER LOW / UNDERVOLT` 告警
|
||
- 当前 CPU throttled / frequency capped：立即告警
|
||
- 本次启动历史上曾欠压/降频：只写一次历史事件日志，不持续 RGB 告警
|
||
- 状态恢复：写 `RECOVERED` 类事件
|
||
|
||
注意：这里检测的是 **Pi 的供电质量**，不是 UPS 电池百分比。
|
||
|
||
### 2. 文件系统健康
|
||
|
||
检测根文件系统 `/` 是否被内核切成只读。如果出现只读状态，产生严重告警：
|
||
|
||
```text
|
||
FILESYSTEM RO
|
||
ROOT READ ONLY
|
||
CHECK STORAGE
|
||
```
|
||
|
||
### 3. 本机诊断信息
|
||
|
||
内部维护：
|
||
|
||
- uptime
|
||
- load average
|
||
- CPU 当前频率
|
||
- 当前/历史 throttled flags
|
||
- 当前主网络接口 / IP
|
||
- 根文件系统只读状态
|
||
- sensor / network / service / health 最近成功时间
|
||
- 主循环异常计数
|
||
- I²C相关异常计数基础字段
|
||
|
||
### 4. DisplayController、OLED 与 RGB
|
||
|
||
每个当前故障都是 DisplayController 中的一个 active request，包含稳定 ID、priority、severity、OLED 显示数据、首次发现时间、最后变化时间和元数据。监控只提交或清除 request，同一轮采样作为一个原子批次，全部更新后只仲裁一次。DisplayController 始终只选一个最高优先级 owner；同一 ID 更新原请求而不重复入队，恢复时删除请求，同优先级新 request 排队而不抢占，owner 恢复后按 priority、first_seen、ID 重新仲裁。OLED 在主页和全部当前告警页之间轮播，告警页右上角显示 `当前页/告警总数`，新 owner 会立即抢占一次 OLED。告警页显示时 RGB 同步表达该页对象；回到主页时 RGB 保持最高优先级 active owner，全部恢复后才 OFF。历史 power flags 只进入 diagnose 和一次性 Journal 记录。
|
||
|
||
### 5. RGB 告警引擎
|
||
|
||
RGB 模式由当前 OLED 告警页决定；OLED 位于主页时则使用最高优先级 active owner。颜色表示故障对象：CPU/供电/降频为黄色，温度为红色，内存为紫色，磁盘为白色，网络/Wi-Fi 为蓝色，服务/进程为青色。速度表示严重等级：Warning 慢呼吸、Critical 快呼吸、Emergency 纯红快速频闪；没有 active alert 时 OFF。模式变化时按 `speed → color → effect` 写入，呼吸动画完全由 MCU 生成，不使用软件 PWM 或逐帧 R/G/B 写入。相邻页面 RGB mode 相同时不关闭、不重启灯效。动画不写循环日志，owner 变化记录 `DISPLAY_OWNER`，实际模式变化才记录 `RGB_MODE`。
|
||
|
||
### 6. 结构化事件日志
|
||
|
||
日志继续交给 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
|
||
journalctl -u pigway-pi-control -f
|
||
```
|
||
|
||
只看本次启动：
|
||
|
||
```bash
|
||
journalctl -u pigway-pi-control -b --no-pager
|
||
```
|
||
|
||
搜索某类事件：
|
||
|
||
```bash
|
||
journalctl -u pigway-pi-control --no-pager | grep 'event=POWER'
|
||
```
|
||
|
||
### 7. 诊断命令
|
||
|
||
```bash
|
||
sudo /usr/local/sbin/pigway-pi-control --diagnose
|
||
```
|
||
|
||
输出 Agent 版本、系统 uptime、配置路径、load、CPU 频率、根文件系统、全部当前/历史 power 位、主网络接口、完整 IP 和 Internet 状态，以及所有 service/process watch 状态。
|
||
|
||
诊断使用与运行时相同的配置和检查函数；仅以 I²C receive-byte 读取探测 MCU 0x0D / OLED 0x3C，失败显示 MISSING/ERROR，不初始化或写入风扇、RGB、OLED。独立诊断进程无法获取正在运行的服务的内存计数，故 loop_errors / i2c_errors 明确标记 UNAVAILABLE；服务退出的 STOP 事件包含该次运行计数。
|
||
|
||
RGB 保留卖家 MCU 0x0D 寄存器协议。实机校准确认呼吸应使用 MCU 内置效果，模式切换间隔默认 10ms，并由正常 OLED 刷新保持共享总线活动。旧版 `brightness`、软件呼吸周期、更新频率和 R/G/B 配置继续允许保留在用户配置中，但硬件灯效引擎会忽略它们。
|
||
|
||
### 8. 关机收尾
|
||
|
||
收到 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
|
||
```
|
||
|
||
安装器会：
|
||
|
||
- 安装必要依赖
|
||
- 检查 I²C
|
||
- 禁用旧 `temp-control.service`
|
||
- 安装字体、程序、配置和 systemd unit
|
||
- 完整保留用户现有配置（包括所有 section、用户值和注释），新选项使用运行时默认值
|
||
- 启动服务
|
||
- 执行版本、OLED、UI、P0健康监控和诊断入口自检
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
systemctl status pigway-pi-control --no-pager -l
|
||
journalctl -u pigway-pi-control -f
|
||
sudo systemctl restart pigway-pi-control
|
||
sudo /usr/local/sbin/pigway-pi-control --diagnose
|
||
```
|
||
|
||
## 版本路线
|
||
|
||
- v3.2.0：主网络接口 / Wi-Fi RSSI / ETH速率 / 双网切换
|
||
- **v3.3.0：P0 System Health，本地检测与日志完善**
|
||
- 后续：只读 `/api/v1/...` Agent API，再由 NAS 统一汇总多台设备
|