csm/wiki/database.md

Database（数据库层）

设计思想

SQLite 单文件数据库，WAL 模式支持并发读写。设计原则：

1. 只追加迁移 — 永不修改已有 migration 文件
2. 参数绑定 — 所有 SQL 使用 .bind()，绝不拼接
3. upsert 模式 — ON CONFLICT ... DO UPDATE 处理重复上报，必须更新 updated_at
4. 嵌入式迁移 — SQL 文件通过 include_str! 编译进二进制，运行时按序执行
5. 外键启用 — foreign_keys(true) 强制引用完整性

代码逻辑

初始化

main() → init_database() → SQLite WAL + Normal sync + 5s busy timeout + FK on
       → run_migrations() → CREATE _migrations 表 → 按序执行 001-018
       → ensure_default_admin() → 首次启动生成随机 admin 密码

连接池配置

• 最大 8 连接
• cache_size = -64000 (64MB)
• wal_autocheckpoint = 1000

迁移历史

#	文件	内容
001	init.sql	users, devices 表
002	assets.sql	hardware_assets, software_assets, asset_changes 表
003	usb.sql	usb_events, usb_policies, usb_device_patterns 表
004	alerts.sql	alert_rules, alert_records 表
005	web_filter.sql	web_filter_rules, web_access_logs 表
006	usage_timer.sql	usage_daily, app_usage 表
007	software_blocker.sql	software_blacklist, software_violations 表
008	popup_blocker.sql	popup_blocker_rules, popup_block_stats 表
009	usb_file_audit.sql	usb_file_operations 表
010	watermark.sql	watermark_configs 表
011	token_security.sql	token_families 表（JWT token family 轮换）
012	disk_encryption.sql	disk_encryption_status, disk_encryption_alerts 表
013	print_audit.sql	print_events 表
014	clipboard_control.sql	clipboard_rules, clipboard_violations 表
015	plugin_control.sql	plugin_states 表
016	encryption_alerts_unique.sql	唯一约束修复
017	device_health_scores.sql	device_health_scores 表
018	patch_management.sql	patch_status 表

数据操作层 (db.rs)

DeviceRepo 提供：

• 设备注册/查询/删除/分组
• 资产增删改查
• USB 事件记录和策略管理
• 告警规则和记录操作
• 所有插件数据的 CRUD

关联模块

• server — 通过 db.rs 访问数据库
• plugins — 每个插件有对应的数据库表

关键文件

文件	职责
crates/server/src/db.rs	DeviceRepo 数据库操作方法集合
crates/server/src/main.rs	数据库初始化、迁移执行
migrations/001_init.sql ~ 018_*.sql	数据库迁移脚本