Module Document
基础架构 · 指令协议平台技术选型
基础架构 ·
指令协议平台技术选型
版本: v0.1
日期: 2026-07-06
归属: 基础架构 / 指令协议平台
1. 选型背景与约束
| 约束 |
说明 |
| 协议双轨 |
Protobuf（固件/云端高效通信）+ JSON
Schema（私网控制指令兼容）并存。 |
| SDK 多语言 |
固件端 C，云端 Go，App 端 TypeScript，必须自动生成。 |
| 禁止私改 |
已发布版本技术层面 immutable，不依赖流程约束。 |
| 评审集成 |
评审流程集成飞书审批，减少工具切换。 |
2. 候选方案对比
协议定义格式
| 方案 |
优势 |
劣势 |
场景 |
| Protobuf 3（推荐主协议） |
高效编解码、强类型、多语言生成成熟 |
需 proto 工具链 |
固件↔︎云端核心通信 |
| JSON Schema |
人类可读、调试方便、兼容 REST |
无原生 SDK 生成 |
私网控制指令过渡 |
| FlatBuffers |
零拷贝、极致性能 |
工具链不如 proto 成熟 |
超高性能场景备选 |
SDK 生成工具链
| 方案 |
优势 |
劣势 |
场景 |
| buf CLI（推荐） |
Breaking change 检测、lint、多语言生成、与 GitLab CI 集成 |
学习曲线 |
Proto SDK 生成 |
| protoc 原生 |
标准工具 |
无 lint/breaking change 检测 |
与 buf 配合使用 |
| openapi-generator |
JSON Schema/OpenAPI → SDK |
生成质量参差 |
JSON Schema 端 |
版本不可变存储
| 方案 |
优势 |
劣势 |
场景 |
| PostgreSQL 行级锁定 + API 层 403（推荐） |
简单可靠，技术强制 |
需 API 层配合 |
版本锁定 |
| 对象存储 immutable flag（OSS/S3） |
物理层面不可修改 |
协议变更仍可新建覆盖 |
制品存储配合使用 |
签名方案
| 方案 |
优势 |
劣势 |
场景 |
| Ed25519（推荐） |
轻量、快速、固件 C 库成熟（libsodium） |
需管理私钥 |
SDK 签名校验 |
| RSA-2048 |
广泛支持 |
密钥大、签名慢 |
老系统兼容 |
评审流程集成
| 方案 |
优势 |
劣势 |
场景 |
| 飞书审批 Webhook（推荐） |
团队已在飞书，响应快 |
依赖飞书可用性 |
协议评审通知 |
| GitLab MR Approval |
开发者友好 |
非开发人员（固件方）体验差 |
技术评审补充 |
3. 推荐方案
| 层级 |
推荐 |
| 主协议格式 |
Protobuf 3 |
| 兼容格式 |
JSON Schema（私网指令过渡期） |
| SDK 生成 |
buf CLI + protoc |
| C SDK |
protoc-c 生成 + libsodium 签名校验 |
| Go SDK |
protoc-gen-go |
| TS SDK |
protoc-gen-ts / ts-proto |
| 版本锁定 |
PostgreSQL 行级锁定 + API 403 |
| SDK 签名 |
Ed25519（libsodium） |
| 评审集成 |
飞书审批 Webhook |
4. 迁移 / 切换成本
| 场景 |
成本评估 |
| protoc 原生 → buf CLI |
低：配置 buf.yaml，CI 替换命令，1 周。 |
| JSON Schema 过渡期 → 全面 Proto |
中：固件/App 逐步迁移，需协议兼容窗口，4-8 周。 |
| Ed25519 → RSA |
低：libsodium 支持 RSA，替换签名算法，1 周。 |
5. 决策记录
| 决策 |
结论 |
日期 |
决策人 |
| 主协议格式 |
Protobuf 3 |
2026-07-06 |
架构 Owner |
| SDK 生成工具 |
buf CLI + protoc |
2026-07-06 |
架构 Owner |
| SDK 签名 |
Ed25519 |
2026-07-06 |
架构 Owner |
| 版本锁定机制 |
DB 行级锁 + API 403 |
2026-07-06 |
架构 Owner |
| 评审集成 |
飞书审批 Webhook |
2026-07-06 |
架构 Owner |