PRJ-07 WIP
CoBotrix 协熵云枢
cloud platform framework for robotics & smart devices
面向机器人与智能设备的 Rust 云平台框架
- Rust
- 云原生
- 分布式
8 个
Cargo workspace 成员（cobotsrv / cobotusr / cobotlet / cobotnet / cobotmap 等）
3 种
部署形态：嵌入式单二进制 / 前后端分离 / 开发热重载
7 项
OIDC / OAuth 标准合规（Core 1.0、RFC 6749 / 7636 / 7517 / 7009 / 7662 / 6750）
// 01
问题背景
管理一群分布在各地的机器人 / 智能设备，痛点出奇一致：设备在 NAT 后面没有公网地址、每台设备网络环境不同、认证授权要同时服务人和机器。通用 IoT 平台要么太重，要么不解决 P2P 大流量传输。
CoBotrix 的思路是提供「框架」而非「全家桶」：核心通信用 MQTT 反向代理保证可达且可水平扩容，大流量走 EasyTier 组的 P2P VPN mesh，身份与权限做成标准 OIDC IdP + PDP，各业务应用按「声明权限 → 启动同步」接入。
// 02
系统架构
云端服务层
Server 侧核心组件
边缘与设备层
运行在各 Device 上的代理与工具
网络通信层
可达性与大流量分通道解决
前端与工具链层
管理界面与开发集群
// 03
关键技术决策
每一条都包含「为什么这样选」与「代价是什么」——这是我理解这个项目的方式。
Net4mqtt 反向代理保核心通信，P2P VPN 扛大流量
设备在 NAT 后无法直连，常规做法是全部流量过云端中转——成本高且云端带宽成瓶颈。拆成两条路：控制面走 Net4mqtt（MQTT 上的 HTTP 反向代理），无状态可水平扩容；数据面（音视频、地图、大文件）走 EasyTier 组的 P2P mesh，虚拟 IP 直连。代价是两套网络模型并存、运维心智成本上升——README 也明确标注 Net4mqtt 不适合大规模数据传输和高性能网络。
内置标准 OIDC IdP，而非外挂 Keycloak
嵌入式 / 边缘场景要求单二进制、低依赖，外挂 Keycloak 太重。自己在 cobotusr 里实现 Authorization Code + PKCE、Client Credentials、Refresh Token 轮换，2048-bit RSA 密钥首次启动自动生成落盘，JWKS 端点对外发布。SPA 是 public client、权限同步是 confidential client——按 OAuth 规范拆成两个 client，bootstrap 时对「public 却带 client_credentials」的非法组合直接拒绝启动。代价是要自己守住 7 项 RFC 的合规细节，测试与文档成本不低。
权限平台：粗粒度走 JWT claims，细粒度走 PDP
路由级权限检查如果每次都远程调用，延迟与可用性都不可接受。用户登录时把 permission 数组解析进 JWT claims，应用侧用 require_perm! 宏本地 O(1) 判断；只有「用户只能操作自己的设备」这类需要匹配 resource_id 的细粒度场景才调 /enforce（glob 匹配 resource_pattern，建议调用方缓存 5s）。代价是 claims 有过期窗口内的权限滞后，用短 token + 刷新轮换缓解。
rust-embed 单二进制发行作为推荐生产形态
边缘网关与离线发行场景没有 Nginx、没有 CDN。前端产物编译期内嵌进 cobotsrv，一个进程同时供 SPA 与 API，交付物就是二进制。代价是前端改动要重编后端、二进制变大；三种部署形态（嵌入 / 分离 / 开发）共用一套配置模板派生流程（*.example 模板 → 本地派生、.gitignore 排除）来降低切换成本。
// 04
我的职责与产出
RESPONSIBILITIES
- 参与 workspace 整体分层（云端 / 边缘 / 设备）与组件命名规范设计
- 实现 OIDC 认证中心：授权流程、JWKS、Refresh Token 轮换
- 实现权限平台：application / permission 数据模型、require_perm! 宏、/enforce PDP 端点
- 实现 cobotnet 的 EasyTier 配置分发与 IP 池管理（分配 / 静态绑定 / 租约回收）
- 搭建三种部署形态的配置模板派生与嵌入式单二进制构建链路
OUTCOMES
- 设备在 NAT 后无需公网 IP 即可被云端管理与反向调用
- OIDC 中心同时服务 SPA（PKCE）与机器间调用（Client Credentials）
- 权限体系实现应用间隔离，新业务按「声明权限 → 启动同步」即可接入
- cobotnil 一键起本地虚拟集群，开发联调不依赖真实设备
// 05
踩坑与复盘
最深的体会是「框架的克制」：cobotsrv 作为 IdP + PDP 坚决不碰业务权限规则，所有应用自己在配置里声明、启动时幂等同步——这条边界让平台没被任何一个业务拖进泥潭。不足是文档与代码的命名经历过一次迭代（cobotsrv / cobotusr 权责拆分），部分章节仍沿用旧命名；KVM 扩展等模块仍在 TODO。
// 06
技术栈
- Rust
- MQTT · Net4mqtt
- EasyTier
- OIDC
- SeaORM
- PostgreSQL
- Vue 3