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