YunStack-IoT 文档

Appearance

倍肯智控 v0.4.0 — 首次内部版本基线 ​

发布日期：2026-10-26。产品英文名及仓库名继续使用 YunStack-IoT。

这是从总仓库创建的第一次统一发布。此前 v0.1–v0.3 的功能通过各组件提交逐步交付，未单独创建产品 Release；本说明将这些已完成能力与 v0.4 OTA 一并汇总，作为后续开发的 Git 历史基线，不补造旧版本标签。

本次发布用于个人开发与内部在线测试，记录源码组合、验证结果和已知边界；不是正式生产或量产交付。不制作独立安装包、压缩包或包含设备密钥的固件下载包。

本次收口 ​

  • v0.2 真实设备闭环、v0.3 安全接入与实时状态已完成，v0.4 固件升级与 OTA 闭环本次收口。
  • 四路继电器和 EnvSense 两款实际维护的产品固件均基于 ESP-IDF 6.1，具备双分区 OTA。
  • 四路继电器正常 OTA 已获用户实测确认；EnvSense 已真实完成 1.3.0 → 1.3.2 在线升级，云端任务为 success / 100%。
  • 用户已确认最近的小程序升级页面修复无问题。
  • OTA 状态保持、主动断电和故障恢复的专项测试作为后续加固项保留，不宣称全部故障场景已验证。

v0.1–v0.2 累计完成：平台与真实设备基础 ​

后端与数据 ​

  • NestJS / TypeScript 模块化服务，Prisma 访问 PostgreSQL，Redis 承担在线状态与热点数据，InfluxDB 保存时序数据。
  • JWT 登录与刷新、用户和角色管理、RBAC 权限、个人资料、统一响应、异常处理、参数校验、日志和接口文档。
  • 产品 CRUD、物模型与属性定义校验；设备采用逻辑 ID 与 physicalId 的双 ID 体系。
  • 设备注册、管理、影子、在线/离线状态、命令下发和回复确认、设备事件日志。
  • Redis 热缓存与 PostgreSQL 影子持久化；设备属性写入 InfluxDB，支持按时间和属性查询历史。
  • MQTT 标准主题 sys/{pid}/{did}/thing/...，支持属性上报、控制与回复、认领及 OTA 消息。
  • 组织与房间基础 CRUD 已有实现；这不等同于后续完整家庭共享能力。
  • 文件上传与 OSS 存储、签名下载和基础邮件能力。

Web 管理后台与微信小程序 ​

  • Web 提供产品、物模型、设备、遥测、固件、组织及概览页面，配套账号和权限管理。
  • 微信小程序支持登录、设备列表、详情、控制、设置、解绑和数值遥测历史。
  • 小程序首页与个人页完成首轮精简：白色主体、蓝色点缀，减少冗余信息；产品图标改为简约设备插图。
  • 移除过早引入的场景入口与本地模拟场景，将主线聚焦设备接入、设备管理与家庭分享。
  • 中文显示名统一为“倍肯智控”；英文项目名、仓库名和主要目录名保持不变。

四路继电器真实闭环 ​

  • 支持 CH423 IO 扩展、四路继电器控制、本地按键、NVS 状态记忆和真实硬件错误反馈。
  • 已验证 Web / 微信小程序控制与板上按键回传，三端状态同步。
  • 已验证断电后平台离线判定、重新通电自动联网、四路状态恢复，以及约 30 分钟持续运行。
  • 修复控制执行失败仍回报成功的问题：硬件操作失败不更新虚假状态，设备回复失败，后端及时结束命令等待。
  • 完成真实设备注册、凭证展示与复制、属性历史查询及在线判定链路中的首轮问题修复。

v0.3 累计完成：安全接入、真实配网与实时状态 ​

MQTT 认证与权限 ​

  • 当前在线验证使用 EMQX，认证与 Topic 授权由后端 HTTP 回调处理，后端通过 Prisma 查询设备身份。
  • 设备凭证为 ClientId = physicalId、Username = ProductKey、Password = DeviceSecret。
  • 后端服务采用独立身份；认证/授权回调要求独立密钥，异常默认拒绝。
  • 设备仅可访问自身允许的主题，拒绝跨设备、全局通配和未授权操作。
  • 已完成自动验证、临时设备真实 Broker 验证，以及真实继电器重新认证、上线和控制回归。
  • 增加本地 MQTT_ENABLED 开关，普通本地 API 开发可关闭 MQTT，避免与远程实例争抢共享订阅消息；这不提供数据库写入隔离。

BLE 配网与账号认领 ​

  • 复用统一的小程序 BLE 连接内核，结合 ESP-IDF provisioning / Security 2 安全会话承载应用协议。
  • 设备通过物理按键进入限时配网窗口，自动发现与读取设备身份，不依赖用户扫描二维码或手填设备凭证。
  • 小程序取得云端认领票据，经安全 BLE 通道下发 WiFi SSID、密码与认领信息，设备联网后与后端确认归属。
  • 支持未预先创建的设备自动注册与绑定，并处理已归属其他账号、解绑和重新添加的边界。
  • WiFi 使用 DHCP；不提供自定义静态 IP、网关或 DNS。
  • 添加设备采用逐步引导：按说明书进入配网、选择/填写 WiFi、发现与连接设备、显示进度和结果。
  • 修复 Android MTU 请求失败后的容量查询、iPhone 特征发现缺失等兼容问题，增加阶段诊断日志并优化往返耗时。
  • Android 与 iPhone 已完成四路继电器的实际添加验证；不将此扩大为全部手机型号均已测试。

实时状态与展示 ​

  • 后端 Socket.IO 通道使用 JWT 认证，按当前账号归属和角色限制可见设备。
  • Web 与小程序接收影子、在线状态及解绑失效事件；重连与前后台恢复后重新同步。
  • 用户已确认三端状态同步、断电离线/重新上线、小程序退后台与手机断网后的恢复。
  • 四路继电器去除无实际需要的芯片温度展示；固件版本保留在设置，减少无意义的属性卡片。

v0.4 新增：固件升级与 OTA 闭环 ​

固件仓库与后端任务 ​

  • 产品通用应用固件存于私有 OSS；下载时生成限时 HTTPS 地址，逐板私密 USB 基础版不作为通用更新。
  • 上传检查 ESP 应用镜像、芯片、内置版本、硬件兼容标识与单槽容量，记录 SHA-256 和版本说明。
  • 升级任务校验设备权限与归属快照，同设备只允许一个活跃任务。
  • 支持待下发、通知、下载、校验、重启、成功、失败与回滚状态；按实际设备报告更新进度。
  • 提供有界通知重试、任务过期、超时和显式重试；重试创建新任务，保留原失败记录。
  • 后端自动部署后 MQTT 首次订阅失败可重试恢复；设备端 OTA 订阅以 SUBACK 确认为准。
  • 已按用户授权应用 OTA 增量数据库迁移，不执行整库重建或 seed，不修改用户、设备身份与遥测历史。

Web 与小程序升级体验 ​

  • Web 支持固件上传、版本详情、该版本的升级记录、产品固件列表、设备升级入口及任务查询。
  • 小程序从设备设置进入升级页，只提供高于当前版本的最新兼容固件；未知版本不误显示“已是最新”。
  • 圆形进度展示真实阶段与百分比，区分下载、校验、重启、成功、失败与回滚；不使用模拟进度。
  • 修复圆环容器误触发全局边框样式、轮询造成按钮闪烁，以及旧查询覆盖重试新任务的问题。
  • 低于 EnvSense OTA 基础版本的设备显示初始化提示，不允许用 OTA 迁移旧分区布局。

四路继电器 OTA ​

  • 维护硬件 V2.1.0，ESP32-C3，实测 Flash 4MB；NVS 保留原位置，双 OTA 槽各 0x1e0000。
  • 完成 USB 基础版迁移后，真实 3.1.3 → 3.1.4 在线升级成功，用户另已确认正常 OTA 可用；3.1.5 通用包保留在私有 OSS。
  • 修复 OSS 交叉签名证书链验证问题，启用 IDF 官方交叉签名支持，保持 HTTPS 证书与主机名验证。
  • 下载校验 SHA-256、镜像版本和槽位大小；新应用通过本地自检后确认启动，失败可由 IDF 回滚。

EnvSense IDF6.1 与 OTA ​

  • 本次实板 ESP32-D0WD-V3、Flash 16MB；按实测容量准备固件，不根据原理图 N8 标注推定容量。
  • BOOT 长按约 3 秒即进入配网，WS2812 统一显示配网、在线、故障与升级状态。
  • AHT20、BMP280、SC8CO2 正常采集；BH1750 光照可缺省，缺失或读失败时不发布虚假值，真实零值保留。
  • 完成独立身份登记、Security 2 BLE 配网与手机添加，用户已确认传感器回归。
  • 硬件兼容标识 esp32-16mb-v1；最低 OTA 基础版本 1.3.0，两槽各 0x3e0000。
  • 1.3.1 曾实际触发启动校验超时并回滚：采集任务等待 MQTT，而主入口等待本地采集后才启动 MQTT。
  • 1.3.2 修复上述顺序，保持严格传感器启动校验；真实 1.3.0 → 1.3.2 升级 success / 100%，约 1.5 秒完成本地启动校验，身份/WiFi/原绑定保留，传感器继续上报。
  • 此次失败与修复记录保留，不覆盖已发布的同版本固件内容。

工程、部署与版本追溯 ​

  • Web 与后端由 GitHub Actions 构建、验证并推送到在线测试服务器，服务器无需从 GitHub 拉代码。
  • 后端使用版本化目录、current 软链接、PM2 reload、健康检查与部署失败回滚；服务端环境变量独立保留。
  • 文档由 Cloudflare Pages 部署，受组织账号认证保护；小程序仍由微信开发者工具人工编译/发布。
  • 总仓库通过固定 Git 子模块指针组织后端、Web、小程序、文档、模拟器和硬件；硬件仓库统一放在 hardware/。
  • 本次产品标签只锁定这些组件的源码组合，不等同于重新部署全部服务，也不自动升级全部设备。
  • release-manifest.json 记录本标签全部组件提交；它只是文本追溯清单，无需下载安装。固件仍走平台私有 OSS。
  • 真实 .env、逐板密钥、私钥、构建缓存和 local-tools/ 本机工具不进入本次发布文件。
  • 进度统一维护在滴答清单，已完成历史不重建；后续加固与新版本规划分别保留。

验证记录 ​

以下是对应代码阶段的已完成验证，不将发布文档更新描述为重新完成所有硬件专项测试：

  • 后端：41 套件 / 440 项单元测试、11 套件 / 90 项 HTTP 测试，类型检查与构建通过。
  • Web：25 项 OTA 相关回归、类型检查与构建通过。
  • 小程序：13 项 OTA 页回归、类型检查与微信 Build 通过；此前 BLE、解绑、引导与实时状态回归见组件历史。
  • 固件：实际 OTA worker 故障注入、镜像/协议边界、通知分片、身份复用、传感器与按键灯效主机测试通过；IDF6.1 构建通过。
  • 新增启动顺序回归执行真实传感器任务首轮：离线/联网及必需读数成功/失败四场景，旧代码失败、修复后通过。
  • 实物：继电器正常升级与三端控制；EnvSense 配网/传感器与 1.3.2 在线升级；最近升级页修复已获用户确认。

已知边界与后续工作 ​

  • 四路继电器 OTA 后的逐路物理状态保持、受控下载中断电、主动制造启动失败等专项验证转为 v0.9 加固任务；EnvSense 已观察到自然失败回滚，但不据此宣称全部断电恢复组合通过。
  • 未启用 Secure Boot、eFuse 防回退或独立固件数字签名。SHA-256 表示完整性校验，不等同于签名认证。
  • 不提供差分升级、断点续传、批量灰度或强制升级。OTA 页面查询任务状态，不宣称 OTA 专属 WebSocket 推送。
  • 全线 IDF6.x 指当前维护的两款产品固件；历史 demo / 旧实验工程不作为本次交付固件。
  • 当前是在线测试环境，生产高可用、监控告警、备份恢复、硬件量产与全机型测试尚未完成。
  • 下一主线为 v0.5 家庭共享与基础管理；随后是界面精简与产品专属页、继电器定时/延时、初代 BLE 网关与子设备、组合联调及 v1.0。
  • HA 桥接暂缓，其他 MQTT Broker 的兼容验证排在 HA 之后；不宣称 RMQTT 等已验证兼容。

使用这个版本记录 ​

GitHub Release 和总仓库 v0.4.0 标签用于查阅或复现本次源码组合；组件固件版本可以不同，不将产品 v0.4.0 写入所有组件版本号。

恢复源码的方式见总仓库 RELEASING.md。检出旧源码不会自动回滚数据库、服务器配置或设备 NVS。旧单分区设备必须先经维护人员 USB 初始化对应 OTA 基础版，不能直接下发通用包迁移分区。

统一产品发布入口：GitHub v0.4.0。本页是首次内部发版的静态记录，执行任务仍以滴答清单为准。

Copyright © 2026 - YunStack-IoT. All Rights Reserved.