csm/wiki/client.md

Client（客户端代理）

设计思想

csm-client 是部署在医院终端设备上的 Windows 代理程序，设计为：

1. 无人值守运行 — 支持控制台模式（开发调试）和 Windows 服务模式（生产部署）
2. 自动重连 — 指数退避策略（1s → 60s），断线后 drain stale frames
3. 插件化采集 — 每个插件独立 task，通过 watch channel 接收配置，通过 mpsc channel 上报数据
4. 单入口 data channel — 所有插件共享一个 mpsc::channel::<Frame>(1024)，network 模块统一发送

关键设计决策：

• watch + mpsc 双通道 — watch 用于服务器推送配置到插件（多消费者最新值），mpsc 用于插件上报数据到网络层（多生产者有序队列）
• device_uid 持久化 — UUID 首次生成后写入 device_uid.txt，与可执行文件同目录
• device_secret 持久化 — 注册成功后写入 device_secret.txt，重启后自动认证

代码逻辑

启动流程

main() → load device_uid → load device_secret → create ClientState
       → create data channel (mpsc 1024)
       → create watch channels for each plugin config
       → spawn core tasks (monitor, asset, usb)
       → spawn plugin tasks (11 plugins)
       → reconnect loop: connect_and_run() with exponential backoff

网络层 (network/mod.rs)

• connect_and_run() — TCP 连接、注册/认证、双工读写循环
• handle_server_message() — 根据 MessageType 分发服务器下发的帧到对应 watch channel
• PluginChannels — 持有所有插件的 watch::Sender，用于接收服务器推送的配置
• 注册流程：发送 Register → 收到 RegisterResponse（含 device_secret）→ 持久化 secret
• 认证流程：已有 device_secret 时，心跳帧携带 HMAC-SHA256 签名

插件统一模板

每个插件遵循相同模式：

pub async fn start(
    mut config_rx: watch::Receiver<PluginConfig>,
    data_tx: mpsc::Sender<Frame>,
    device_uid: String,
) {
    loop {
        tokio::select! {
            result = config_rx.changed() => { /* 更新 config */ }
            _ = interval.tick() => {
                if !config.enabled { continue; }
                // 采集数据 → Frame::new_json() → data_tx.send()
            }
        }
    }
}

双模式运行

• 控制台模式: 直接 cargo run -p csm-client，Ctrl+C 优雅退出
• 服务模式: --install 注册 Windows 服务、--service 以服务方式运行、--uninstall 卸载

关联模块

• protocol — 使用 Frame 构造上报帧，解析服务器下发帧
• server — TCP 连接的对端，接收帧并处理
• plugins — 每个插件的具体实现逻辑

关键文件

文件	职责
crates/client/src/main.rs	启动入口、插件 channel 创建、task spawn、重连循环
crates/client/src/network/mod.rs	TCP 连接、注册认证、双工读写、服务器消息分发
crates/client/src/service.rs	Windows 服务安装/卸载/运行（#[cfg(target_os = "windows")]）
crates/client/src/monitor/mod.rs	核心设备状态采集（CPU/内存/进程）
crates/client/src/asset/mod.rs	硬件/软件资产采集
crates/client/src/usb/mod.rs	USB 设备插拔监控
crates/client/src/web_filter/mod.rs	上网拦截插件
crates/client/src/usage_timer/mod.rs	使用时长记录插件
crates/client/src/software_blocker/mod.rs	软件禁止安装插件
crates/client/src/popup_blocker/mod.rs	弹窗拦截插件
crates/client/src/usb_audit/mod.rs	U盘文件操作审计插件
crates/client/src/watermark/mod.rs	屏幕水印插件
crates/client/src/disk_encryption/mod.rs	磁盘加密检测插件
crates/client/src/print_audit/mod.rs	打印审计插件
crates/client/src/clipboard_control/mod.rs	剪贴板管控插件
crates/client/src/patch/mod.rs	补丁管理插件