项目	当前值
产品	PGU5 开放平台
应用版本	`v2.1.1`
发布标签	`v2.1.1`
设备序列号	`PGU5A-` + 大写以太网 MAC
现场目录	`/root/PGU5-Core`
Web	`http://192.168.101.172:8080/`
Gitea	`http://107.173.157.41:3000/clear/PGU5-Core`

版本字符串在应用常量、API、Git 标签和 Gitea Release 中必须保留前导 v。

功能范围

当前 Core 功能：

MS602 六通道采集、预览、保存，以及开流自检阶段的小幅反向抖动、大幅/极大位移、低相关度撕裂帧检测和持续低成本帧率监控；异常时只恢复对应通道。
M3Lite 热成像采集、温度数据保存和 PyUSB 控制。
DCL 严格按 ClearDCLXXXXX 序列号名称自动发现；DCL 与 UVC-RGB/IMX766 均支持采集、预览和保存。
单次保存、在线定时保存、保存队列和自动休眠。
文件浏览、预览、ZIP 下载、后台永久删除和空间自动清理。
AP、STA、以太网、HS/Headscale 和 Syncthing 管理。
Web SSH、配置编辑、服务重启、安全关机和 OTA。
管理中心提供多光谱控制页，可开关并调节小抖动、大幅/极大位移、撕裂和帧率检测，保存后即时生效并持久化，同时查看六通道实时恢复诊断。
独立 OLED、DS3231 和 NVMe 服务。

不属于 Core 的功能：

PLC/Modbus、运动控制、水肥控制。
业务自动化、计划任务和业务路径配置。
Hikrobot/MVS/GenICam。
任何应用专属产品身份、业务页面或部署路径。

v2.1.1

同步 v2.0.5..v2.1.1 通用平台能力，不包含 PLC、运动、水肥、业务自动化、计划任务或 MVS/GenICam。
MS602 新增启动期大幅/极大垂直位移检测，解决短时高幅跳动画面可能越过小抖动上限而漏检的问题。
MS602 新增持续低成本单通道帧率监控；连续低于阈值时只重连对应波段，不持续执行灰度缩放、相位相关或撕裂分析。
开流后先显示 CHECKING，通过启动检测窗口后再转为 CONNECTED，避免画面尚未完成自检时过早显示正常。
DCL 支持严格 ClearDCLXXXXX 名称自动发现，现场 camera_name 仅作为优先提示，不再是换机必须修改的绑定项。
DCL 预览宽度同步为 720，刷新间隔调整为 350ms，在提升预览细节的同时控制浏览器和网络刷新负载。

v2.0.5

多光谱六通道诊断表的“设备”列仅显示视频节点编号，例如 /dev/video12 显示为 12，减少现场界面的实现细节。
后端 device_index、设备路径、运行日志和通道打开逻辑保持不变，不影响设备识别、恢复和 API 诊断。

v2.0.4

新增管理中心“多光谱控制”页面，可持久化调整 MS602 开流检测时长、小抖动和撕裂检测参数，并查看六通道诊断。
MS602 昂贵图像分析只在首次启动、休眠唤醒或错误重连后的短暂窗口内运行；通过后停止检测，读帧失败仍保持独立通道恢复。
增强持续撕裂和 720 通道轻微上下抖动识别，使用通道代次、独立锁和诊断证据避免旧线程影响新实例。
管理中心所有页面统一可滚动高度链；多光谱诊断表完整显示通道、设备节点和检测指标，移动端改为无横向溢出的分组布局。
修复暗色主题移动端导航按钮、系统设置菜单、根页面白边和多处文字/组件样式，统一非业务管理界面。
清理空响应式规则、Python 缓存和历史部署临时备份，保留现场配置、配置备份、运行日志和 OTA 状态。

v2.0.3

全面升级桌面与移动端 Web UI，统一浅色/深色主题、弹窗、导航、文件管理和管理工具布局。
增加中英文界面切换、商业化产品文案、现代化品牌区和紧凑设备状态展示。
文件管理支持分页、图像预览、原始文件访问、ZIP 下载、后台永久删除和空间统计。
Web SSH 静态资源改为按需加载，并随仓库保留许可证文件。
自动清理在用户编辑期间不覆盖表单，日志增加结构化时间信息和轻量提示反馈。
保留多相机独立恢复、异步传感器上电、M3/L640 PyUSB 控制、OTA、Syncthing、OLED、RTC 和 NVMe 能力。
清除旧工程标识、业务接口说明和不属于 Core 的历史残余。

完整接口、参数和副作用见 API.md。

运行结构

路径	用途
`pgu5a_base.py`	Web、API、相机、保存、网络、OTA 和管理逻辑
`pgu5a_config.json`	现场运行配置
`assets/`	Logo、按需加载的 xterm.js/xterm.css 及许可证
`ota/ota_update.py`	独立 OTA 更新器
`oled/`	SSD1306 OLED 独立服务
`ds3231/`	RTC/NTP 同步
`nvme/`	NVMe 自动挂载
`backups/config/`	配置编辑器备份，不提交
`backups/ota_state.json`	OTA 运行状态，不提交

现场 pgu5a_config.json 是配置事实来源，不应当作普通本地差异丢弃。每次提交、推送或发布前必须重新读取 192.168.101.172:/root/PGU5-Core/pgu5a_config.json，以当前调试机运行参数更新仓库配置。密码、AuthKey、令牌等设备私有认证值只保留在现场，部署时不得使用公开配置覆盖。

服务

服务	用途	正常状态
`pgu5a_base.service`	Web、API 和相机	`active`
`pgu5a_oled.service`	OLED	`active`
`ds3231-sync.service`	RTC/NTP 一次性同步	完成后可为 `inactive`
`nvme-data-auto.service`	NVMe 挂载	`active (exited)`
`syncthing@root.service`	文件同步	`active`

主服务和 OLED 互相独立，OLED 失败不得影响 Web、API 或相机。

相机与电源

MS602 和 DCL 唤醒时立即启动。
MS602 六通道按 ms602.open_stagger_sec 间隔启动，当前现场值 0.3 秒。
MS602 每个通道仅在首次启动、休眠唤醒或错误重连后执行昂贵的开流图像自检，默认持续 5.0 秒；通过后停止灰度、缩放、相位相关和帧差分析。
开流自检期间判断小幅反向垂直抖动、大幅/极大位移、跨帧低相关度大帧差和单帧横向断层；达到阈值时只重启受影响通道，并在重新打开后开始新一轮独立自检。
轻量帧率监控在通道运行期间持续工作，默认最低 2.0 FPS、连续 2 次低帧率后恢复对应通道；正常间隔会清空连续异常计数。
保存 MS602 六通道数据前校验缺失、恢复中、过期和跨通道时间偏差，默认最大帧龄 2.0 秒、最大时间偏差 1.0 秒。
管理中心的“多光谱控制”页面可调整全部检测参数；保存写入 pgu5a_config.json，无需重启服务或整机。
M3Lite 使用 GPIO 8 延时上电，当前唤醒延迟 2.0 秒。
UVC-RGB 使用 GPIO 9 延时上电，当前唤醒延迟 1.0 秒。
休眠会递增唤醒令牌，取消尚未完成的延时启动。
定时保存和保存队列工作期间暂停自动休眠。

OTA

界面当前版本来自：

APP_VERSION = "v2.1.1"
APP_RELEASE_TAG = "v2.1.1"

Git 信息只用于诊断。在线升级先检查 Gitea Release，只有发现更新后才启用升级按钮。OTA 状态包括：

IDLE CHECKED FETCHING CHECKOUT VERIFYING RESTARTING SUCCESS ERROR

更新目标标签使用强制刷新，以支持明确要求的同名标签修订发布：

git fetch --force origin refs/tags/<tag>:refs/tags/<tag>

项目没有手动回滚接口，也不创建项目外 OTA 备份目录。

验证

cd /root/PGU5-Core
git status --short
/opt/miniconda3/envs/py310/bin/python3 -m py_compile \
  pgu5a_base.py ota/ota_update.py oled/oled_status.py ds3231/sync_ds3231.py
/opt/miniconda3/envs/py310/bin/python3 -m json.tool pgu5a_config.json >/dev/null
systemctl restart pgu5a_base.service
systemctl is-active pgu5a_base.service
curl -fsS http://127.0.0.1:8080/api/system/version
curl -fsS http://127.0.0.1:8080/api/status
curl -fsS http://127.0.0.1:8080/api/network
curl -fsS http://127.0.0.1:8080/api/ota/status
curl -fsS http://127.0.0.1:8080/api/m3/control
curl -fsS http://127.0.0.1:8080/api/syncthing/identity-init/status

常规验证不得调用系统重启、关机、Syncthing 身份初始化、文件删除或 M3 参数修改接口。

安全

Git 远端不得包含用户名或密码。
不在源码、配置、文档和提交中保存 SSH 密码、AuthKey、令牌或 Cookie。
管理 API 没有独立登录层，只应在可信管理网络中开放。
不提交日志、采集数据、backups/ 或 __pycache__/。