Raspberry Pi OS Lite（Debian 13 Trixie）全新安装

English | 简体中文

兼容性结论

PIGWay Raspberry Pi Agent v3.7.1 兼容 Raspberry Pi OS Lite 64-bit、Debian 13 Trixie 与 Python 3.13。Agent 只读取 Linux 的 /proc、/sys、systemd、网络状态和 journal，不依赖 GPIO、I²C、Pillow 或第三方 Python 包，也不需要 venv。

Yahboom RGB Cooling HAT 已拆分为独立插件。插件使用 Debian 系统包 python3-smbus2 与 python3-pil，不会通过 pip 修改受 PEP 668 管理的系统 Python。硬件接口保持原实现：

I²C 总线：/dev/i2c-1，需要启用 I²C；不需要 SPI。
控制 MCU：0x0D；OLED：0x3C，SSD1306 兼容 128×32。
风扇通过 MCU 寄存器 0x08 的六档控制，不使用 Raspberry Pi GPIO PWM 引脚，也没有可验证的 RPM 反馈。
RGB 由 MCU 寄存器控制；插件是 MCU、OLED、RGB 与风扇的唯一进程所有者。

因此不能把这块散热板当作直连 GPIO 风扇，也不应猜测或修改 GPIO 引脚。其他 GPIO/PWM 风扇需要独立驱动。

安装前检查

cat /etc/os-release
python3 --version
raspi-config nonint get_i2c
ls -l /dev/i2c-1
ss -ltnp

raspi-config nonint get_i2c 返回 0 才表示 I²C 已启用。启用 I²C 会修改启动配置，并且通常需要重启；远程操作前应确认 SSH 公钥登录与供电稳定。

sudo raspi-config nonint do_i2c 0
sudo reboot

重连后确认 /dev/i2c-1 存在。散热板插件安装器会安装诊断工具并检查 0x0D、0x3C，不会改 SSH、网络或 Wi-Fi。

安装顺序

先安装通用监控 Agent：

git clone https://tea.pigway.com/way/pigway-raspberry-pi-agent.git
cd pigway-raspberry-pi-agent
sudo ./install.sh --disable-api

默认只监控 ssh.service，不会假定已安装向日葵或 Tailscale。需要 NAS 上的 Device Console 时，先确认端口未占用，再显式开启 API：

sudo ./install.sh --enable-api
sudo ss -ltnp | grep ':6001 '
sudo cat /etc/pigway-pi-control-api.token

再安装独立硬件插件：

git clone https://tea.pigway.com/way/pigway-yahboom-cooling-hat.git
cd pigway-yahboom-cooling-hat
sudo ./install.sh --enable-integration

最后在 /etc/pigway-pi-control.conf 的 [plugins] 中登记：

yahboom-cooling-hat = /run/pigway-plugins/yahboom-cooling-hat/api.sock

然后仅重启 Agent：

sudo systemctl restart pigway-pi-control.service

验收

systemctl --no-pager --full status pigway-pi-control.service
systemctl --no-pager --full status pigway-cooling-hat.service
sudo /usr/local/sbin/pigway-pi-control --diagnose
sudo journalctl -u pigway-pi-control.service -b --no-pager
sudo journalctl -u pigway-cooling-hat.service -b --no-pager
curl --unix-socket /run/pigway-plugins/yahboom-cooling-hat/api.sock http://localhost/v1/status

实机还需肉眼确认 OLED 四行主页与10秒轮播、RGB 告警颜色/效果，并通过温度变化确认风扇档位。停止插件时会请求风扇全速，驱动关闭时不会写风扇 OFF；硬件无转速反馈，因此只能确认请求档位，不能声称测得真实 RPM。

API 默认关闭，不占用 TCP 端口。插件只使用本机 Unix socket，不会与 Tailscale 或 API 网关争用端口。两个服务都由 systemd 独立管理，异常退出自动重启，任一项目停止不会停止另一个项目。

3.4 KiB Raw Blame History Unescape Escape

Raspberry Pi OS Lite（Debian 13 Trixie）全新安装

兼容性结论

安装前检查

安装顺序

验收

3.4 KiB

Raw Blame History