5.0 KiB
PIGWay Raspberry Pi Agent v3.11.2
简体中文 | English
Disk discovery is manual: Device Console → System configuration → select the device → Storage settings → Scan disks. The inventory persists across restarts; known filesystem capacity updates weekly. Names and visibility belong to the Agent. See deployment and validation.
PIGWay Raspberry Pi Agent is a lightweight local monitoring service for Raspberry Pi. It monitors CPU, memory, temperature, disk, networking, services, processes, system health alerts, and journal events. Ethernet monitoring reads the negotiated link speed and can alert when it remains below the configured minimum. It has no embedded Web UI and does not require a hardware plugin or Device Console.
Installation
See the Trixie fresh-install guide for Raspberry Pi OS Lite 64-bit based on Debian 13. The Agent itself does not access GPIO or I2C; OLED, RGB, and fan control belong to the independent hardware plugin.
sudo ./install.sh
# Explicitly enable the API:
sudo ./install.sh --enable-api
# Keep the API disabled:
sudo ./install.sh --disable-api
Interactive installation asks whether to enable the remote API and defaults to no. Non-interactive installation also keeps it disabled unless explicitly enabled. --no-start only updates files and configuration; it does not change the current service state.
The configuration file is /etc/pigway-pi-control.conf. Restart the Agent after changing monitoring settings:
sudo systemctl restart pigway-pi-control.service
Optional API
The default is [api] enabled = false, with no network listener. To use centralized management, enable it and configure the bind address and port, then run:
sudo systemctl enable --now pigway-pi-control-api.service
sudo cat /etc/pigway-pi-control-api.token
The default port is 6001. Every read and write request requires Authorization: Bearer <token>. The token belongs only to this device and is not printed directly by the installer. The API exposes health, status, logs, configuration, services, plugins, and plugin configuration under /api/v1. It does not serve a Web UI, register multiple machines, or proxy remote requests.
Console and hardware plugins
- PIGWay Device Console can run on a NAS or remote server for dashboards, configuration, and batch synchronization.
- PIGWay Yahboom Cooling HAT independently provides local telemetry, OLED, fan control, and RGB effects.
The remote API and local plugin integration are independent. After enabling plugin integration, register yahboom-cooling-hat = /run/pigway-plugins/yahboom-cooling-hat/api.sock under [plugins] and restart the Agent, or attach it through the Console. Discovery never binds a plugin automatically. Pausing or disconnecting integration does not stop the plugin's local functions.
Operations
sudo /usr/local/sbin/pigway-pi-control --diagnose
sudo journalctl -u pigway-pi-control.service -f
Logs follow the system journal retention policy; no additional database is created. Uninstalling one project never uninstalls either of the others. See Plugin API v1.
Naming and compatibility
This project targets Raspberry Pi. Other Linux platforms are not covered by its support claim and may have separately maintained adapters. Repository naming does not change the existing pigway-agent adapter ID or pigway-pi-control service, configuration and API identifiers.
v3.8.0 网络流量
主接口每个网络采集周期读取 sysfs 的 rx_bytes/tx_bytes，以单调时间差计算字节/秒，API 新增 rx_bytes_per_second 和 tx_bytes_per_second。首次采样、接口切换、计数器重置或读取失败返回空值；不修改监控告警、硬件插件控制或 API 可选安装行为。2026-10-14 已在 Gateway 部署，实机上下行速率与 Console 标准历史指标验证通过。
v3.9.0 采样时间
API 状态新增 system.observed_at、network.observed_at 和 collection.interval_seconds。Console 可每秒读取缓存，网络等低频指标保留实际采样时间，供历史去重。数据来源与原网络采样周期保持。
生产 v3.9.0 与按设备周期采集的核验见 部署记录。
v3.10.0 独立采集周期
实时状态提供分组采样时间与下一次更新计划。容量每天读取一次，RAM 缓存跨服务重启恢复；读取失败延后一小时重试，避免反复查询存储。网络周期可独立配置，生产计划调整为 1 秒。
v3.11.2 容量周期
当前已知磁盘容量及根盘兼容指标每周更新；新增磁盘只手动发现。容量缓存保留在/run并支持服务重启复用，整机重启后首次初始化容量缓存属于启动检查；不自动调用lsblk发现新设备。当前策略覆盖历史版本的30秒/每日容量刷新描述。