README.zh-CN.md

# PIGWay Raspberry Pi Agent v3.11.3

简体中文 | [English](README.md)

新增磁盘由 Console → 系统配置 → 选择设备 → 磁盘设置 → 扫描磁盘手动发现；已保存清单跨重启保留，已知磁盘容量每周刷新。支持在 Agent 保存名称和隐藏设置。见 [部署与验证](docs/STORAGE.md)。


极轻的树莓派本地监控服务：CPU、内存、温度、磁盘、网络、服务/进程、系统健康告警与 journal 日志。有线网络会读取真实协商速率，并可在持续低于配置阈值时告警。无 Web 界面；无需硬件插件，也无需管理中心。

## 安装

Raspberry Pi OS Lite 64-bit（Debian 13 Trixie）的全新安装与兼容性说明见 [Trixie 全新安装指南](docs/RASPBERRY_PI_OS_TRIXIE_FRESH_INSTALL.zh-CN.md)。监控 Agent 本身不访问 GPIO/I²C；OLED、RGB 和风扇由独立硬件插件负责。

```bash
sudo ./install.sh
# 显式启用 API：
sudo ./install.sh --enable-api
# 不启用 API：
sudo ./install.sh --disable-api
```

交互安装询问是否启用远程 API，默认否；非交互安装未指定时也关闭。`--no-start` 仅更新文件和配置，不改变现有服务运行状态，接口开关在下次启动生效。

配置文件：`/etc/pigway-pi-control.conf`。修改监控配置后执行：

```bash
sudo systemctl restart pigway-pi-control.service
```

## 可选 API

默认 `[api] enabled = false`，没有网络监听。需要集中管理时改为 `true`，设置 bind/port，然后：

```bash
sudo systemctl enable --now pigway-pi-control-api.service
sudo cat /etc/pigway-pi-control-api.token
```

默认端口6001。读取及写入都需要 `Authorization: Bearer <token>`。令牌只用于该设备；安装器显示查询方法，不直接显示令牌内容。关闭 API：配置改为 false，执行 `sudo systemctl disable --now pigway-pi-control-api.service`。

API 提供 `/api/v1/health`、`/status`、`/logs`、`/config`、`/services`、`/plugins` 和 `/plugin/config`（均以 `/api/v1` 开头）。不提供网页、多机登记或远程转发。

## 独立管理中心与插件

- [PIGWay Device Console](https://tea.pigway.com/way/pigway-device-console)：可部署在 NAS 或远端，登记设备地址与令牌，统一看板、配置和批量同步。
- [PIGWay Yahboom Cooling HAT](https://tea.pigway.com/way/pigway-yahboom-cooling-hat)：独立本地采集、OLED、风扇与 RGB。

远程 API 与本地插件联动相互独立。插件启用接入后，可在 `[plugins]` 显式登记 `yahboom-cooling-hat = /run/pigway-plugins/yahboom-cooling-hat/api.sock` 并重启监控，或通过管理中心接入。发现不会自动绑定；暂停/断开联动不停止插件本地功能。

## 运维

```bash
sudo /usr/local/sbin/pigway-pi-control --diagnose
sudo journalctl -u pigway-pi-control.service -f
```

日志依照系统 journal 的保留策略，不额外建库。卸载任何一个项目不会卸载另外两个项目。插件协议见 [API v1](docs/HARDWARE_PLUGIN_API.md)。

## 名称与兼容性

本项目支持范围明确为树莓派；其他 Linux 平台以后独立维护项目。仓库改名不改变现有 `pigway-pi-control` 服务名、配置路径和 API。远程 API 仍可选择启用，默认关闭。

[文档目录](docs/README.md)
-											fix: validate atomic configuration updates and expire stale monitoring snapshots
										
										
											2026-10-18 18:15:22 +08:00
+								# PIGWay Raspberry Pi Agent v3.11.3
-											docs: split English and Chinese readmes
										
										
											2026-09-28 20:03:13 +08:00
-											docs: refine language switch links
										
										
											2026-09-28 21:28:27 +08:00
+								简体中文 | [English](README.md)
-											docs: split English and Chinese readmes
										
										
											2026-09-28 20:03:13 +08:00
-											docs: organize project guides and consolidate historical records
										
										
											2026-10-18 17:59:18 +08:00
+								新增磁盘由 Console → 系统配置 → 选择设备 → 磁盘设置 → 扫描磁盘手动发现；已保存清单跨重启保留，已知磁盘容量每周刷新。支持在 Agent 保存名称和隐藏设置。见 [部署与验证](docs/STORAGE.md)。
-											feat: add manual disk discovery and weekly capacity cache
										
										
											2026-10-15 23:30:06 +08:00
-											docs: split English and Chinese readmes
										
										
											2026-09-28 20:03:13 +08:00
-											docs: clarify Raspberry Pi project names and integration scope
										
										
											2026-10-11 16:29:26 +08:00
+								极轻的树莓派本地监控服务：CPU、内存、温度、磁盘、网络、服务/进程、系统健康告警与 journal 日志。有线网络会读取真实协商速率，并可在持续低于配置阈值时告警。无 Web 界面；无需硬件插件，也无需管理中心。
-											docs: split English and Chinese readmes
										
										
											2026-09-28 20:03:13 +08:00
 								## 安装
-											release: support Raspberry Pi OS Trixie
										
										
											2026-10-11 00:06:22 +08:00
+								Raspberry Pi OS Lite 64-bit（Debian 13 Trixie）的全新安装与兼容性说明见 [Trixie 全新安装指南](docs/RASPBERRY_PI_OS_TRIXIE_FRESH_INSTALL.zh-CN.md)。监控 Agent 本身不访问 GPIO/I²C；OLED、RGB 和风扇由独立硬件插件负责。
-											docs: split English and Chinese readmes
										
										
											2026-09-28 20:03:13 +08:00
+								```bash
 								sudo ./install.sh
 								# 显式启用 API：
 								sudo ./install.sh --enable-api
 								# 不启用 API：
 								sudo ./install.sh --disable-api
 								```
 								交互安装询问是否启用远程 API，默认否；非交互安装未指定时也关闭。`--no-start` 仅更新文件和配置，不改变现有服务运行状态，接口开关在下次启动生效。
 								配置文件：`/etc/pigway-pi-control.conf`。修改监控配置后执行：
 								```bash
 								sudo systemctl restart pigway-pi-control.service
 								```
 								## 可选 API
 								默认 `[api] enabled = false`，没有网络监听。需要集中管理时改为 `true`，设置 bind/port，然后：
 								```bash
 								sudo systemctl enable --now pigway-pi-control-api.service
 								sudo cat /etc/pigway-pi-control-api.token
 								```
 								默认端口6001。读取及写入都需要 `Authorization: Bearer <token>`。令牌只用于该设备；安装器显示查询方法，不直接显示令牌内容。关闭 API：配置改为 false，执行 `sudo systemctl disable --now pigway-pi-control-api.service`。
 								API 提供 `/api/v1/health`、`/status`、`/logs`、`/config`、`/services`、`/plugins` 和 `/plugin/config`（均以 `/api/v1` 开头）。不提供网页、多机登记或远程转发。
 								## 独立管理中心与插件
 								- [PIGWay Device Console](https://tea.pigway.com/way/pigway-device-console)：可部署在 NAS 或远端，登记设备地址与令牌，统一看板、配置和批量同步。
 								- [PIGWay Yahboom Cooling HAT](https://tea.pigway.com/way/pigway-yahboom-cooling-hat)：独立本地采集、OLED、风扇与 RGB。
 								远程 API 与本地插件联动相互独立。插件启用接入后，可在 `[plugins]` 显式登记 `yahboom-cooling-hat = /run/pigway-plugins/yahboom-cooling-hat/api.sock` 并重启监控，或通过管理中心接入。发现不会自动绑定；暂停/断开联动不停止插件本地功能。
 								## 运维
 								```bash
 								sudo /usr/local/sbin/pigway-pi-control --diagnose
 								sudo journalctl -u pigway-pi-control.service -f
 								```
 								日志依照系统 journal 的保留策略，不额外建库。卸载任何一个项目不会卸载另外两个项目。插件协议见 [API v1](docs/HARDWARE_PLUGIN_API.md)。
-											docs: clarify Raspberry Pi project names and integration scope
										
										
											2026-10-11 16:29:26 +08:00
 								## 名称与兼容性
 								本项目支持范围明确为树莓派；其他 Linux 平台以后独立维护项目。仓库改名不改变现有 `pigway-pi-control` 服务名、配置路径和 API。远程 API 仍可选择启用，默认关闭。
-											docs: organize project guides and consolidate historical records
										
										
											2026-10-18 17:59:18 +08:00
 								[文档目录](docs/README.md)