Initial release: Pigway Pi Control v3.1.0

README.md

@@ -0,0 +1,381 @@
+# Pigway Pi Control v3.1.0 — Release
+
+适用于本套 Raspberry Pi 4B 散热扩展板的正式发布版。
+
+本包遵循一个原则：
+
+> **一个程序 + 一个用户配置文件 + 一个说明文档。**
+
+正常使用时，不需要修改源码。
+
+---
+
+## 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
+IP4 192.168.89.130
+```
+
+IPv6 地址时自动显示 `IP6`。
+
+主页左右两栏都是固定位置、左对齐。数据默认每秒刷新。
+
+有告警时，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
+```
+
+进入：
+
+```text
+Interface Options
+→ I2C
+→ Enable
+```
+
+然后：
+
+```bash
+sudo reboot
+```
+
+### 第二步：解压本安装包
+
+进入解压后的目录：
+
+```bash
+cd pigway-pi-control-v3.1.0
+```
+
+### 第三步：安装
+
+```bash
+sudo ./install.sh
+```
+
+安装器会：
+
+1. 检查 `/dev/i2c-1`
+2. 等待 APT/DPKG 锁
+3. 安装必要的小型系统依赖
+4. 检查 I²C 总线
+5. 自动停止并禁用卖家旧 `temp-control.service`
+6. 安装正式程序
+7. 安装用户配置
+8. 安装 systemd 服务并开机自启
+9. 执行安装后自检
+
+安装成功后查看：
+
+```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.1.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
+```
+
+停止：
+
+```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.1.0
+6. sudo ./install.sh
+```
+
+完成。