From c82d9ab3c275caeba5225ac967355f08a11867c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=B8=A1=E5=8F=A3=E6=B5=AA=E4=BA=BA?= Date: Sun, 18 Oct 2026 17:59:18 +0800 Subject: [PATCH] docs: organize project guides and consolidate historical records --- README.md | 4 +++- README.zh-CN.md | 4 +++- SHA256SUMS | 6 +++-- STORAGE-DISCOVERY.md | 52 -------------------------------------------- docs/README.md | 8 +++++++ docs/STORAGE.md | 21 ++++++++++++++++++ 6 files changed, 39 insertions(+), 56 deletions(-) delete mode 100644 STORAGE-DISCOVERY.md create mode 100644 docs/README.md create mode 100644 docs/STORAGE.md diff --git a/README.md b/README.md index 88e1c7a..fdde8e1 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [简体中文](README.zh-CN.md) | 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](STORAGE-DISCOVERY.md). +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](docs/STORAGE.md). 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. @@ -57,3 +57,5 @@ Logs follow the system journal retention policy; no additional database is creat ## 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. + +[Documentation](docs/README.md) diff --git a/README.zh-CN.md b/README.zh-CN.md index 58ef500..f1a68ca 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -2,7 +2,7 @@ 简体中文 | [English](README.md) -新增磁盘由 Console → 系统配置 → 选择设备 → 磁盘设置 → 扫描磁盘手动发现；已保存清单跨重启保留，已知磁盘容量每周刷新。支持在 Agent 保存名称和隐藏设置。见 [部署与验证](STORAGE-DISCOVERY.md)。 +新增磁盘由 Console → 系统配置 → 选择设备 → 磁盘设置 → 扫描磁盘手动发现；已保存清单跨重启保留，已知磁盘容量每周刷新。支持在 Agent 保存名称和隐藏设置。见 [部署与验证](docs/STORAGE.md)。 极轻的树莓派本地监控服务：CPU、内存、温度、磁盘、网络、服务/进程、系统健康告警与 journal 日志。有线网络会读取真实协商速率，并可在持续低于配置阈值时告警。无 Web 界面；无需硬件插件，也无需管理中心。 @@ -59,3 +59,5 @@ sudo journalctl -u pigway-pi-control.service -f ## 名称与兼容性 本项目支持范围明确为树莓派；其他 Linux 平台以后独立维护项目。仓库改名不改变现有 `pigway-pi-control` 服务名、配置路径和 API。远程 API 仍可选择启用，默认关闭。 + +[文档目录](docs/README.md) diff --git a/SHA256SUMS b/SHA256SUMS index 46d3e64..6ec3c29 100644 --- a/SHA256SUMS +++ b/SHA256SUMS @@ -1,6 +1,6 @@ ecf1884bb89b86ed4573d4d922a971abde43772bf7b2ffa6a999a12fbfb72caf .gitignore -f9aff4abd70490d0d70669d41c603ff63df5df63ea854a138055eccfb9bf5eb9 README.md -64a9708701f8c8d872a587e8a2845afff463797b06a2791319daadd705933d31 README.zh-CN.md +a16429e43b2876ac4587479c3c3b5c7e3b5c666d7e889c2178a34a4ae9de8deb README.md +5a81a035871415f88fee6f12e20a42c8ff606f90e13fd383b8dd9407fe8aa909 README.zh-CN.md c5853f283c0951b43f2bacbc49e66c26d3a605a184d427828e042eb9236d2740 app/network_rates.py 69877b4ad2b8307db69495d629988ff4bca838dea9e36d839165029fdb6ed4a8 app/pigway_pi_control.py 757eb6a83ca07740a2389af9b51c6fd5d940b4eb86abbc603f231409416d45db app/pigway_pi_control_api.py @@ -16,3 +16,5 @@ b54ec1f3e9fb15473910686c54142a85d387e44ea5df427a4cf1b06052e789b3 docs/RASPBERRY 8b97229abfb31c68464eb5754bc3a8fec7a6a78e216d74a86b7cc89486700740 tests/test_network_rates.py f78e31e0eeee4e02532885ace5c8f6f7011d084e4c7440b704408bc88495e40e tests/test_storage_cache.py 9f59e7313ee58e687ae6dd29d175c67082674254ac5c5f54168b2735b64c20a4 uninstall.sh +67f56bdb128d64f434ca52e45245fd2f3548da3852b3e06cc8def8c804502bf0 docs/README.md +6552741bb5639520c331a8c38d5d99c90f0ab3d9b1f11e571cb789c386bd0577 docs/STORAGE.md diff --git a/STORAGE-DISCOVERY.md b/STORAGE-DISCOVERY.md deleted file mode 100644 index aae367c..0000000 --- a/STORAGE-DISCOVERY.md +++ /dev/null @@ -1,52 +0,0 @@ -# 磁盘手动扫描（2026-10-15） - -后续显示层已升级为 Console v2.7.0 / Ubuntu 插件 v1.5.0 / Raspberry Pi 插件 v1.6.0 / Synology 插件 v1.9.0：默认原样使用设备返回顺序，取消 NAS 特殊倒序和优先级。显示名称、同组排序、隐藏统一保存到 Console，首页与配置共用，支持恢复默认顺序。设备已有名称/隐藏定义保留为默认上报值；本篇后文“名称保存在 Agent”等描述为当时的设备定义行为，不代表最新 Console 显示偏好的存储位置。最新验收见相邻 pigway-web-manager/docs/STORAGE-PRESENTATION-v2.7.0-2026-10-15.md；所有实际扫描行为保持手动。 - -## 已上线状态 - -Ubuntu Agent v1.3.1 / Console 插件 v1.4.1，Raspberry Pi Agent v3.11.1 / 插件 v1.5.1，Synology 插件 v1.8.1 已上线。两台 Agent 各识别两个实际分区，监控/API 服务 active，循环错误 0。 - -三种设备在线；中英文及 1440/820/390 三种屏宽的生产界面通过。设备名称、顺序和隐藏设置保留。Console 重启、页面加载及浏览器验收前后，NAS storage_observed_at 未改变，本次没有额外扫描 NAS 硬盘。尚未插入新物理磁盘，也未进行休眠/唤醒实测。 - -用户最终确认“三种设备都手动发现新增磁盘”。此前自动发现与 NAS 每 5 分钟扫描的候选方案已替换。 - -## 使用 - -Ubuntu、树莓派：Console → 系统配置 → 选择设备 → 磁盘设置 → 扫描磁盘。扫描后重新打开该页查看新磁盘，概览随正常轮询更新。名称和隐藏设置保存到 Agent，隐藏不停止历史采集。 - -NAS：与其他设备一样在配置 → 磁盘设置中点击“扫描磁盘”，首页只展示数据。磁盘清单、容量、温度、健康状态仅在手动扫描时更新；页面保留采集时间。CPU、内存和网络等快速采集继续工作。已有卷别名仍由 Console 保存。 - -v1.4.1 / v1.5.1 / v1.8.1 统一配置页扫描入口，保存按钮上方保留 20px 间距，扫描与保存反馈分别显示。按用户最终要求，NAS 每个机箱内硬盘采用 DSM 返回顺序反转；存储空间同样反转，主空间和 SSD 空间优先。生产三种屏宽、中英文已验证入口、间距、倒序及优先级；NAS 存储采集时间未改变。前两次发布因验收脚本固定计入网络卡片位置而自动回退，修正为直接验证存储卡片后通过。 - -扫描有 60 秒冷却，NAS 在途请求合并。页面加载、普通刷新、定时轮询和重启不会重新枚举磁盘。部署时执行过一次明确的初始扫描以保存现有 Agent 磁盘清单。 - -## 实现与边界 - -认证 PUT /api/v1/storage/scan 调用 lsblk，读取宿主机挂载点，将块设备清单保存到对应配置旁的 .storage.json（0600）。监控服务只读取清单；已知磁盘挂载和容量每 30 秒更新，新增磁盘必须手动扫描。根分区原有指标和告警保留兼容。 - -UUID 优先作为标识，其次为设备序列号和分区编号，再退回路径并标记 stable_identity=false。展示可用叶设备，去除重复挂载及 loop/swap 等伪设备。未挂载设备不伪造使用率。配置过的条目在后续扫描未发现时保留为断开；扫描失败保留原清单。 - -不执行挂载、格式化、分区或 SMART 指令。本次没有增加每磁盘断开/容量告警。 - -Agent 手工配置使用 status.system.storage_inventory[].id 的 32 位十六进制 key： - -```ini -[storage_names] -0123456789abcdef0123456789abcdef = 媒体盘 -[storage_visible] -0123456789abcdef0123456789abcdef = true -``` - -NAS 普通 collect 不再调度存储任务，只有 device.refresh(group=storage) 触发慢查询。重启复用上次摘要；过旧健康数据标为未确认，不确认旧告警恢复。只展示 DSM hdd_info / vol_info 上报的硬盘、扩展柜和卷，未验证任意 USB 外接盘是否均由接口提供。 - -## 验证和备份 - -两种 Agent 覆盖挂载点转义、bind 去重、伪设备、未挂载状态、UUID 稳定性、百分号名称、隐藏设置、手动发现和重启后禁止自动枚举。两种插件的中英文/三屏宽测试覆盖 0% 使用率、名称转义、隐藏恢复和显式扫描；打开设置不会扫描。NAS 15 项 Python 回归及六种浏览器布局通过。 - -生产备份： - -- Ubuntu：/var/backups/pigway-ubuntu-agent-storage-1792043168 -- Raspberry Pi：/var/backups/pigway-pi-control-storage-1792043209 -- Console 容器：/data/storage-release-backups/1792043974（旧插件与 SQLite 备份） - -ops/deploy-storage.py 检查 SHA-256 清单、备份三个程序文件与配置，仅重启两个项目服务；验证失败恢复原文件。Console 更新验证三个插件版本、全部设备在线、显示设置保留、NAS 未额外扫描，并执行生产浏览器检查。 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..ac11561 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,8 @@ +# 文档目录 + +安装、连接及日常使用从[中文首页](../README.zh-CN.md)或[英文首页](../README.md)开始。本目录收录仍适用的功能、配置与开发说明；版本变化见[版本记录](../RELEASE_NOTES.md)。 + +- [本地硬件插件协议](HARDWARE_PLUGIN_API.md) +- [Raspberry Pi OS Lite (Debian 13 Trixie) fresh installation](RASPBERRY_PI_OS_TRIXIE_FRESH_INSTALL.md) +- [Raspberry Pi OS Lite（Debian 13 Trixie）全新安装](RASPBERRY_PI_OS_TRIXIE_FRESH_INSTALL.zh-CN.md) +- [磁盘发现、刷新与显示](STORAGE.md) diff --git a/docs/STORAGE.md b/docs/STORAGE.md new file mode 100644 index 0000000..8f78ae8 --- /dev/null +++ b/docs/STORAGE.md @@ -0,0 +1,21 @@ +# 磁盘发现与显示 + +## 使用 + +在 Console → 系统配置 → 选择设备 → 磁盘设置中点击“扫描磁盘”，显式发现新增磁盘。打开页面、普通刷新和重启不执行新增磁盘发现。扫描失败保留已有清单；不执行挂载、格式化或分区操作。 + +已知磁盘容量每周刷新，CPU、内存与网络按自身周期采集。摘要显示实际采集时间；缺失指标不补零，采集失败不据此确认告警恢复。 + +显示名称、同组顺序与隐藏偏好统一保存到 Console，首页与配置页共用；Agent 已有名称和隐藏定义作为默认值。隐藏只影响显示，不停止采集或删除历史。 + +## Agent 行为 + +认证接口 `PUT /api/v1/storage/scan` 读取块设备和挂载点，持久化清单到对应配置旁的 `.storage.json`。监控服务读取清单；新增磁盘须再次手动扫描。根分区指标保留兼容，服务重启可复用容量缓存，整机重启后的容量初始化不自动发现新磁盘。 + +UUID 优先作为标识，其次为设备序列号和分区编号，再退回路径并标记 `stable_identity=false`。重复挂载及 loop/swap 等伪设备不展示；未挂载设备不伪造使用率。配置过的磁盘在扫描未发现时保留为断开状态。 + +磁盘扫描不执行 SMART 或自检；SMART 能力以本项目的独立说明为准。 + +## 相关说明 + +[中文首页](../README.zh-CN.md) · [文档目录](README.md)