这个项目能做什么

CloudPath（云径）是一个既可在本机运行、也可部署到公网的自托管物联网控制平台，目标是把「接入设备、查看状态、远程控制」做成通用控制面，而不是某块开发板的专用上位机。项目以 MIT 许可开源，主要由三部分组成：单二进制的中心服务 cloudpath-server、运行在每台电脑或站点上的网关 cloudpath-edge，以及负责插件 Registry 控制面的命令行工具 cloudpath。技术上后端使用 Go、前端为 React，WebUI 构建产物内嵌进服务端，数据库使用 SQLite 的 WAL 模式，无需 CGO 即可交叉编译到 Linux 或 arm64。 权威划分 中心服务是期望态、租户与审计的唯一权威，负责 RBAC、令牌、限流、保留期、插件目录与运行实例的期望态，以及操作下发和回执结算。网关是观测态的唯一权威，保存最后一次成功 applied 的快照，负责设备监督、退避重开与离线事件缓冲；断网后继续运行，重连时只应用最终快照、不回放中间副作用。设备身份由租户、网关、设备三元组确定，线上传输键为 edge_id 与 device_id 的组合。账号会话下，网关到服务端再到浏览器的实时链路走 WebSocket，REST 承担历史查询与管理操作。 插件体系 项目区分三类插件：Driver 默认运行在网关侧，负责设备发现、连接、协议解析、能力映射与设备动作；Application 运行在中心服务侧，负责业务对象、绑定、规则、任务与领域 API；Connector 计划运行在网关或中心服务，用于 MQTT、Webhook 等通知与数据出口，目前属于目标态。核心不为任何具体硬件写代码，新设备等于一个 Driver 插件；参考驱动 stcb 与若干应用插件以独立仓库发布，仓库内提供 Go 插件模板、示例应用以及从二进制到宿主的 E2E 测试脚手架。安装插件前会校验 Manifest、兼容范围、Release 资产与摘要，并把版本、digest 与来源记入锁文件。 快速开始 安装 Go、Node、pnpm 以及可选的 task 后，用 task setup 拉取依赖、task build 生成两个二进制。启动 server 默认监听 127.0.0.1:8080，并提供 /healthz 健康检查。没有硬件时可直接用内置 demo 适配器验证设备上线、操作执行与断线重连；接真实串口设备时先安装并启用对应 Driver 插件，再在本地 edge.yaml 中开启 plugin_host 并填写串口与适配器。首次安装管理员账号后，服务立即进入账号模式，除健康检查、静态资源与鉴权接口外均需凭据。 管理台 登录后可访问概览、设备列表与设备详情、运行记录（事件）、应用与插件及实例详情、网关列表与详情、设置；管理员另有成员、权限与访问令牌页面。设备详情页的操作面板按适配器声明的白名单生成按钮；也能直接用 API 下发命令并查询事件流与网关在线状态。操作状态为 pending、sent、ok、failed、timeout，长时间未回执会由后台清理任务标为超时，事件与终态操作默认保留 30 天。 安全设计 README 把暴露面分为 L0 单机、L1 内网或反代、L2 公网三级，并提醒不要把 L0 配置直接放到公网。凭据有两种模式：共享服务令牌属于兼容路径，账号模式则提供会话 cookie 登录、admin 与 operator 和 viewer 三级角色，以及以 cp_ 为前缀的租户令牌，scope 取 read、write、admin、edge 的子集，明文只在创建响应返回一次，库中仅存 SHA-256 与短前缀。Secret 以 secret://name 的 handle 形式出现在服务端配置与审计中，明文只在目标网关本地由 provider 解析，插件必须在 manifest 中显式声明权限，服务端不保存也不转发明文。此外还有操作白名单、参数长度与字符限制、请求体上限、WebSocket 读上限、SPA 路径穿越防护、操作与登录限流以及一组安全响应头。 部署与多网关接入 官方给出不依赖容器的公网部署步骤：先对构建产物做架构断言（发布矩阵包含 Linux arm64），再用 systemd 单元以专用非 root 账号运行服务，机密放在 0600 的环境文件里，最后用 nginx 反代提供 HTTPS 与 WSS，并为 WebSocket 单独配置升级头与较长读超时；同时说明鉴权由本产品自己负责，反代层保持公开。容器与 Compose 形态也可用，但宿主架构必须与镜像一致。多台电脑接同一个服务端是常规用法：管理员为每台电脑创建 edge scope 的租户令牌，把 WSS 端点、令牌与约定好的 edge_id 交给使用者；使用者从 Release 下载对应平台二进制、按 checksums 校验、填写本地配置文件后运行，网关自带指数退避重连，离线事件进入有界缓冲并在重连后回放。跨租户的设备、事件、操作与实例互相不可见，一台网关掉线不会影响另一台。 测试与发布 测试覆盖 Go 单元测试、竞态检测、前端冻结安装与类型检查、插件模板流程，以及聚合门禁命令；发布由版本 tag 触发六平台矩阵构建并生成统一的 checksums 文件。仓库还提供公开边界审计、Markdown 链接检查与 workflow 结构检查等脚本门禁。 当前边界 README 明确区分了现状与目标态：Connector 与通知运行时、MQTT 与 Modbus 接入、远程 OTA、时序聚合、中心密钥管理、分布式配额与多 Server 均尚未实现；租户令牌会话只有 REST，没有浏览器实时通道；同一外部驱动驱动多块真实板卡、覆盖拔插与操作回执的现场 E2E 也尚未完成，因此多板链路在协议与真板证据补齐前不算已验证。项目自述的原则是「未实现的能力不写成现状」。