2026-10-17 22:51:01 +08:00
|
|
|
# PIGWay Console Adapter — Frame Flow
|
|
|
|
|
|
|
|
|
|
独立 ZIP 插件 `pigway-frame-flow` v1.0.0，采用现有 Console adapter protocol v1，仅依赖 Python 标准库。源码在独立仓库 `pigway-console-adapter-frame-flow` 维护，无需修改 Console 核心或部署额外服务。
|
|
|
|
|
|
|
|
|
|
## 安装
|
|
|
|
|
|
|
|
|
|
1. 在 Console「机器管理」上传 `dist/pigway-frame-flow-1.0.0.zip`，启用插件。
|
|
|
|
|
2. 添加设备，选择 PIGWay Frame Flow，填写 Console 能访问的 Frame Flow HTTP(S) 根地址（不含 `/api/v1`）和 **Frame Flow API 令牌**，不是 KoKonna Key 或网页登录密码。
|
|
|
|
|
3. 若使用受限 API 客户端，授予 `devices:read`、`jobs:read`；默认 `FRAME_FLOW_TOKEN` 也可使用。令牌保存于 Console 敏感字段。跨不可信网络使用 HTTPS。
|
|
|
|
|
4. 查看通用资源看板、告警与历史；默认每 60 秒采集一次。无需自定义前端。
|
|
|
|
|
|
|
|
|
|
采集 `/health`、`/ready`、`/api/v1/devices`、`/api/v1/jobs`，不发送写请求、不刷新画框、不执行任务。设备接口可能按 Frame Flow 现有缓存规则查询厂商只读状态。
|
|
|
|
|
|
|
|
|
|
服务：就绪状态、设备数、任务数。画框：在线状态、可用时的电量。任务：启用状态和最近终态结果。`FAILED` 与 `UNKNOWN` 分别告警；未运行或执行中不当作成功。停用任务仍显示其最近失败，成功后恢复。设备离线、服务未就绪分别告警。
|
|
|
|
|
|
|
|
|
|
`/ready` 的 HTTP 503 作为未就绪状态采集；认证、超时、格式错误或其他采集失败交给 Console 保留旧快照并标记未更新，不伪造离线和零值。完整成功快照才确认告警恢复。历史从安装后的采样开始；设备指标是读取时观察到的 API 状态，不证明物理屏幕已刷新。Mock 服务返回的也是 Mock 设备状态。
|
|
|
|
|
|
|
|
|
|
## 本地验证与打包
|
|
|
|
|
|
|
|
|
|
在本仓库根目录执行（运行插件无需安装第三方依赖）：
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
python3 -m venv .venv
|
|
|
|
|
.venv/bin/python -m pip install pytest ruff
|
|
|
|
|
.venv/bin/python -m pytest -q
|
|
|
|
|
mkdir -p dist
|
|
|
|
|
.venv/bin/python package.py plugin dist/pigway-frame-flow-1.0.0.zip
|
|
|
|
|
```
|
|
|
|
|
|
2026-10-17 23:01:52 +08:00
|
|
|
开发时可将 `PIGWAY_ADAPTER_PATH` 指向本目录 `plugin` 的绝对路径。ZIP 安装默认停用；生产安装与设备登记需在 Console 中执行。本地验证覆盖模拟接口、RPC 和隔离安装；生产部署记录见 [DEPLOYMENT.md](DEPLOYMENT.md)。
|
2026-10-17 22:51:01 +08:00
|
|
|
|
|
|
|
|
Frame Flow API 契约测试为可选集成验证，需要另行安装 Frame Flow 及其依赖。例如相邻项目保留现有虚拟环境时，执行 `PYTHONPATH=../pigway-frame-flow ../pigway-frame-flow/.venv/bin/python -m pytest -q`。独立环境未安装 Frame Flow 时跳过该项，其余测试正常运行。
|
