pigway-device-agent/README.md

# PIGWay Device Agent v3.7.0

## 中文

极轻的 Raspberry Pi / Linux 本地监控服务：CPU、内存、温度、磁盘、网络、服务/进程、系统健康告警与 journal 日志。无 Web 界面；无需硬件插件，也无需管理中心。

## 安装

```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)。

## English

PIGWay Device Agent is a lightweight local monitoring service for Raspberry Pi and Linux. It monitors CPU, memory, temperature, disk, networking, services, processes, system health alerts, and journal events. It has no embedded Web UI and does not require a hardware plugin or Device Console.

### Installation

```bash
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:

```bash
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:

```bash
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](https://tea.pigway.com/way/pigway-device-console) can run on a NAS or remote server for dashboards, configuration, and batch synchronization.
- [PIGWay Yahboom Cooling HAT](https://tea.pigway.com/way/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

```bash
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](docs/HARDWARE_PLUGIN_API.md).