diff --git a/README.md b/README.md index f3d0d12..7ab6f1a 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Build the ZIP below, upload it under Machine management and enable it. Register Install only trusted plugins: frontend code shares the page JavaScript environment, and the backend process is not a security sandbox. The ZIP contains the manifest, worker and UI, not Console internals or Git metadata. -See [storage behavior](STORAGE-DISCOVERY.md), [release notes](RELEASE_NOTES.md), and the [Console UI semantics](https://tea.pigway.com/way/pigway-device-console/src/branch/main/docs/UI_SEMANTICS.md). Dated deployment records describe historical validation, not a fresh online check. +See [storage behavior](docs/STORAGE.md), [release notes](RELEASE_NOTES.md), and the [Console UI semantics](https://tea.pigway.com/way/pigway-device-console/src/branch/main/docs/UI_SEMANTICS.md). Dated deployment records describe historical validation, not a fresh online check. ## Build @@ -28,3 +28,5 @@ Current adapter version: **1.6.10**. mkdir -p dist python3 package.py plugin dist/pigway-agent-1.6.10.zip ``` + +[Documentation](docs/README.md) diff --git a/README.zh-CN.md b/README.zh-CN.md index 46cdb69..1421faa 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -4,7 +4,7 @@ 磁盘呈现统一版本已上线，需要 Console v2.7.0：默认按设备返回顺序，同组支持上移/下移、显示名称及隐藏，所有显示偏好保存到 Console，首页与配置页共用。Agent 的名称和隐藏定义继续作为设备默认值保留。扫描仍只由配置页按钮触发。 -当前 v1.6.10 支持统一磁盘显示设置与手动扫描，需要 Console v2.7.0、Agent v3.11.1；新磁盘仅手动发现，已知磁盘容量继续刷新。见 [磁盘发现说明](STORAGE-DISCOVERY.md)。 +当前 v1.6.10 支持统一磁盘显示设置与手动扫描，需要 Console v2.7.0、Agent v3.11.1；新磁盘仅手动发现，已知磁盘容量继续刷新。见 [磁盘发现说明](docs/STORAGE.md)。 独立维护的树莓派接入插件：连接现有 PIGWay Raspberry Pi Agent，不在树莓派安装新进程。设备 API、状态转换、配置字段、服务/进程监控、硬件界面及其翻译均由本仓库维护。 @@ -26,3 +26,5 @@ python3 package.py plugin dist/pigway-agent-1.6.10.zip ## 命名与兼容性 本项目面向 Raspberry Pi，不承诺支持其他 Linux 平台。仓库名称不改变现有 `pigway-agent` 适配器 ID，以及 `pigway-pi-control` 服务、配置和 API 标识。 + +[文档目录](docs/README.md) diff --git a/SHA256SUMS b/SHA256SUMS index e9591b9..29bd181 100644 --- a/SHA256SUMS +++ b/SHA256SUMS @@ -1,7 +1,6 @@ 3cfd361f7663a9a9c93b507d17bb1c7e98003d61316826f0a4ba4a93594f72d4 .gitignore -610c8e95de327f99e89236ffe6ed33add00dd4ed85344008dceeacf0e6d4af9c README.md +fe269ddd32b6ae068cbff1b9697934933d415162978537769275bdeab661a5c2 README.md 291ec4f06dcf990843d8403a0c431a1346f9ab430ebcdaccef4b4b08a76a3c40 RELEASE_NOTES.md -a669ccb22bf3aafec6fa558fd84108dca013cb8dc2988206b7b5fe58a1eb2035 STORAGE-DISCOVERY.md d081c599d821149853368b1a8637c57a16995344406ff5ec9d7619b66e0479b3 package.py 97cb3cd8119147da93a73c5ad82faedd99daab5093a1aa0fb6b855d1df1c65a4 plugin/manifest.json d6a342605426357da7d2e65daa435e99d7234549cffa52e1a9229ef5bc36f33c plugin/ui/config.js @@ -18,4 +17,6 @@ d5b22366a2c7b375e6f3e35cefb9f95da0ea3b8390b3ec4d1000492f00128f6e plugin/worker. 494c90f6d154edc64aad3169653cc08c7f5fd4a6613341b4c0ff10dd7e0e1cb5 tests/browser_alert_semantics.cjs 40c038aa7689c127c0d90ddf390674f534a2bdee8fd3c344d09f8fb6d4bb3964 tests/test_metrics.py 40d10555aef08f8132f576976b7205b3e1c16d330196a11c6cc1c5cbc167c670 tests/test_storage_metrics.py -5a231d6208b15565361ccdb8fb24480c6eb56a0b7c7095e2e989378e7512ae9d README.zh-CN.md +08042c91cea87e2ee9a55533e307a09741143615c7fcabfa602c7303cc3004da README.zh-CN.md +bd422976fbf034b10413479d483353eb7719fb90357c20f535441c9d60880536 docs/README.md +45b7bfb3d8f414e28d50c1f160aee2af8e4150dcd24b815569d48765b1eb413f 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..a8cd8fc --- /dev/null +++ b/docs/README.md @@ -0,0 +1,5 @@ +# 文档目录 + +安装、连接及日常使用从[中文首页](../README.zh-CN.md)或[英文首页](../README.md)开始。本目录收录仍适用的功能、配置与开发说明；版本变化见[版本记录](../RELEASE_NOTES.md)。 + +- [磁盘发现、刷新与显示](STORAGE.md) diff --git a/docs/STORAGE.md b/docs/STORAGE.md new file mode 100644 index 0000000..beb94c8 --- /dev/null +++ b/docs/STORAGE.md @@ -0,0 +1,19 @@ +# 磁盘发现与显示 + +## 使用 + +在 Console → 系统配置 → 选择设备 → 磁盘设置中点击“扫描磁盘”，显式发现新增磁盘。打开页面、普通刷新和重启不执行新增磁盘发现。扫描失败保留已有清单；不执行挂载、格式化或分区操作。 + +已知磁盘容量每周刷新，CPU、内存与网络按自身周期采集。摘要显示实际采集时间；缺失指标不补零，采集失败不据此确认告警恢复。 + +显示名称、同组顺序与隐藏偏好统一保存到 Console，首页与配置页共用；Agent 已有名称和隐藏定义作为默认值。隐藏只影响显示，不停止采集或删除历史。 + +## 适配器边界 + +适配器连接现有 Agent API，不在设备安装额外进程。扫描请求通过既有认证接口转交 Agent；Console 管理展示偏好和通用历史，不替代 Agent 的磁盘身份和持久化清单。 + +磁盘显示集成需要 Console v2.7.0 或更新的兼容实现；具体 Agent 与适配器版本要求见项目首页。 + +## 相关说明 + +[中文首页](../README.zh-CN.md) · [文档目录](README.md)