csm/wiki/server.md

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	审计日志