60ee38a3c2
feat(protocol): 添加补丁管理和行为指标协议类型 feat(client): 实现补丁管理插件采集功能 feat(server): 添加补丁管理和异常检测API feat(database): 新增补丁状态和异常检测相关表 feat(web): 添加补丁管理和异常检测前端页面 fix(security): 增强输入验证和防注入保护 refactor(auth): 重构认证检查逻辑 perf(service): 优化Windows服务恢复策略 style: 统一健康评分显示样式 docs: 更新知识库文档
85 lines
3.8 KiB
Markdown
85 lines
3.8 KiB
Markdown
# Server（服务端）
|
||
|
||
## 设计思想
|
||
|
||
`csm-server` 是整个系统的核心枢纽，同时承载三个协议：
|
||
1. **TCP 二进制协议** (端口 9999) — 接入 Client 代理
|
||
2. **HTTP REST API** (端口 9998) — 服务 Web 面板
|
||
3. **WebSocket** (`/ws`) — 实时推送设备状态变更到前端
|
||
|
||
关键设计决策：
|
||
- **SQLite + WAL** — 单机部署零依赖，WAL 模式支持并发读写
|
||
- **include_dir 嵌入前端** — 编译时将 `web/dist/` 打包进二进制，部署只需一个文件
|
||
- **三层权限** — public（登录/健康检查）→ authenticated（只读）→ admin（写操作）
|
||
- **ClientRegistry** — `Arc<RwLock<HashMap>>` 管理在线客户端的 TCP 写端，支持 `push_to_targets()` 三级作用域推送
|
||
|
||
## 代码逻辑
|
||
|
||
### 启动流程
|
||
|
||
```
|
||
main() → load config → init SQLite → run migrations → ensure admin
|
||
→ spawn TCP listener (9999)
|
||
→ spawn alert cleanup task
|
||
→ spawn health score task
|
||
→ build HTTP router (9998) with CORS/security headers/SPA fallback
|
||
→ axum::serve()
|
||
```
|
||
|
||
### TCP 接入层 (`tcp.rs`)
|
||
|
||
- `start_tcp_server()` — 监听 TCP，每连接 spawn 一个 task
|
||
- `process_frame()` — 根据 MessageType 分发到对应 handler（需先 verify_device_uid）
|
||
- `ClientRegistry` — 线程安全的在线设备注册表，支持 `list_online()`、`send_frame()`
|
||
- `push_to_targets(db, clients, msg_type, payload, target_type, target_id)` — 三级作用域推送（global/group/device）
|
||
- 帧速率限制：100 帧/5秒/连接
|
||
- HMAC 验证：心跳帧必须携带 HMAC-SHA256 签名，连续 3 次失败断开
|
||
- 空闲超时：180 秒无数据断开
|
||
- 最大并发连接：500
|
||
|
||
### HTTP API (`api/`)
|
||
|
||
路由分三层：
|
||
- **public**: `/api/auth/login`, `/api/auth/refresh`, `/health`
|
||
- **authenticated** (require_auth 中间件): GET 类设备/资产/告警/插件查询
|
||
- **admin** (require_admin + require_auth): 设备删除、策略增删改、插件配置写入
|
||
|
||
统一响应格式 `ApiResponse<T>`：`{ success, data, error }`，分页默认 page=1, page_size=20, 上限 100。
|
||
|
||
### WebSocket (`ws.rs`)
|
||
|
||
- `WsHub` 广播设备上线/离线/状态变更事件给所有连接的前端客户端
|
||
- JWT 认证通过 query parameter `?token=xxx`
|
||
|
||
### 后台任务
|
||
|
||
- `alert::cleanup_task()` — 定期清理过期告警
|
||
- `health::health_score_task()` — 定期计算设备健康评分
|
||
|
||
## 关联模块
|
||
|
||
- [[protocol]] — 使用 Frame 编解码和 MessageType 分发
|
||
- [[client]] — TCP 连接的对端
|
||
- [[web-frontend]] — HTTP API 和 WebSocket 的消费者
|
||
- [[plugins]] — API 层的 plugins/ 子模块处理所有插件相关路由
|
||
- [[database]] — 数据库操作集中在 db.rs
|
||
|
||
## 关键文件
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `crates/server/src/main.rs` | 启动入口、数据库初始化、迁移、路由组装、SPA fallback |
|
||
| `crates/server/src/tcp.rs` | TCP 监听、帧处理、ClientRegistry、push_to_targets |
|
||
| `crates/server/src/ws.rs` | WebSocket hub 广播 |
|
||
| `crates/server/src/api/mod.rs` | 路由定义、ApiResponse 信封、Pagination |
|
||
| `crates/server/src/api/auth.rs` | JWT 登录/刷新/改密、限流、require_auth/require_admin 中间件 |
|
||
| `crates/server/src/api/devices.rs` | 设备列表/详情/状态/历史/健康评分 API |
|
||
| `crates/server/src/api/plugins/mod.rs` | 插件路由注册（read_routes + write_routes） |
|
||
| `crates/server/src/api/plugins/*.rs` | 各插件 API handler（每个插件一个文件） |
|
||
| `crates/server/src/db.rs` | DeviceRepo 数据库操作方法集合 |
|
||
| `crates/server/src/config.rs` | AppConfig TOML 配置加载 |
|
||
| `crates/server/src/health.rs` | 设备健康评分计算 |
|
||
| `crates/server/src/anomaly.rs` | 异常检测逻辑 |
|
||
| `crates/server/src/alert.rs` | 告警处理与清理 |
|
||
| `crates/server/src/audit.rs` | 审计日志 |
|