60ee38a3c2
feat(protocol): 添加补丁管理和行为指标协议类型 feat(client): 实现补丁管理插件采集功能 feat(server): 添加补丁管理和异常检测API feat(database): 新增补丁状态和异常检测相关表 feat(web): 添加补丁管理和异常检测前端页面 fix(security): 增强输入验证和防注入保护 refactor(auth): 重构认证检查逻辑 perf(service): 优化Windows服务恢复策略 style: 统一健康评分显示样式 docs: 更新知识库文档
59 lines
2.6 KiB
Markdown
59 lines
2.6 KiB
Markdown
# 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 所有公开类型 |
|