iven/csm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
60ee38a3c218af1d00df83fa5fa1136fbb231b5a
csm/wiki/protocol.md
iven 60ee38a3c2 feat: 新增补丁管理和异常检测插件及相关功能 
feat(protocol): 添加补丁管理和行为指标协议类型
feat(client): 实现补丁管理插件采集功能
feat(server): 添加补丁管理和异常检测API
feat(database): 新增补丁状态和异常检测相关表
feat(web): 添加补丁管理和异常检测前端页面
fix(security): 增强输入验证和防注入保护
refactor(auth): 重构认证检查逻辑
perf(service): 优化Windows服务恢复策略
style: 统一健康评分显示样式
docs: 更新知识库文档
2026-04-11 15:59:53 +08:00

2.6 KiB
Raw Blame History

Protocol（二进制协议层）

设计思想

csm-protocol 是 Server 和 Client 共享的协议定义 crate。核心设计决策：

  1. 零拷贝编解码 — Frame::encode() / Frame::decode() 直接操作字节切片，无中间分配
  2. 类型安全 — MessageType 枚举确保所有消息类型在编译期可见，TryFrom<u8> 处理未知类型
  3. JSON payload — 网络传输用 JSON（serde），兼顾可调试性和跨语言兼容性
  4. payload 上限 4MB — MAX_PAYLOAD_SIZE 防止恶意帧耗尽内存

二进制帧格式：MAGIC(4B "CSM\0") + VERSION(1B) + TYPE(1B) + LENGTH(4B big-endian) + PAYLOAD(变长 JSON)

代码逻辑

帧生命周期

发送方: T → Frame::new_json(mt, &data) → Frame::encode() → Vec<u8> → TCP stream
接收方: TCP bytes → Frame::decode(&buf) → Option<Frame> → Frame::decode_payload::<T>()

MessageType 分块规划

范围 插件 方向
0x01-0x0F Core（心跳/注册/状态/资产） 双向
0x10-0x1F Core Server→Client（策略/配置/任务） S→C
0x20-0x2F Web Filter C→S 日志, S→C 规则
0x30-0x3F Usage Timer C→S 报告
0x40-0x4F Software Blocker C→S 违规, S→C 黑名单
0x50-0x5F Popup Blocker C→S 统计, S→C 规则
0x60-0x6F USB File Audit C→S 操作记录
0x70-0x7F Watermark + USB Policy S→C 配置
0x80-0x8F Plugin Control S→C 启停命令
0x90-0x9F Disk Encryption / Print / Clipboard 混合
0xA0-0xAF Patch Management C→S 状态, S→C 配置
0xB0-0xBF Behavior Metrics C→S 指标

关键类型

  • Frame — 帧结构（version + msg_type + payload bytes）
  • FrameError — 解码错误枚举（InvalidMagic / UnknownMessageType / PayloadTooLarge / Io）
  • 每个 MessageType 对应一个 payload struct（如 WebAccessLogEntry, HeartbeatPayload）

关联模块

  • server — TCP 接入层调用 Frame::decode() 解析客户端帧，调用 push_to_targets() 推送配置帧
  • client — 通过 Frame::new_json() 构造上报帧，通过 Frame::decode() 解析服务器下发的帧
  • plugins — 每个插件定义自己的 payload struct 在此 crate 中

关键文件

文件 职责
crates/protocol/src/message.rs MessageType 枚举、Frame 编解码、所有 payload struct
crates/protocol/src/device.rs DeviceStatus、ProcessInfo、HardwareAsset、UsbEvent 等设备相关类型
crates/protocol/src/lib.rs Re-export 所有公开类型