document-management/docs/plans/系统管理功能.md

系统管理功能

状态：已定版（2026-09-07 实施，契约 1.23.0）

实施摘要：

• 权限：sys_role 新增 manage_system / manage_audit_log 两管理位（Alembic 0029 + Flyway V14 + 达梦适配 db/migration-dm/V14，三迁移幂等）；AllowedModule 新增 SYSTEM_MANAGEMENT（manage_system 推导，admin 恒真）、AUDIT_LOG 改由 manage_audit_log 推导；备份 6 接口鉴权由 ADMIN 硬判定改为系统管理权位，审计接口改为日志审计权位。
• 后端（Python dms/services/system_management_service.py / Java com.dms.service.SystemManagementService 双版对齐，12 接口 + POST backup/test-target）：资源快照、指标采样历史、进程监控、存储用量、转换器状态、健康体检、系统信息、运行参数总览、运行日志尾部/下载、清空预览缓存、强制下线、备份目标连通测试。
• 采样：sys_metric_sample 表 + 后台线程（30 秒间隔、保留 7 天自动清理，DMS_METRIC_INTERVAL_SECONDS / DMS_METRIC_RETENTION_DAYS 可调）；CPU/内存采样入库，磁盘实时查询不采样。
• 日志：新增 DMS_LOG_FILE 配置（缺省 logs/dms-server.log），Python logging FileHandler / Java logback RollingFileAppender 双端落盘，级别统一为 DEBUG/INFO/WARNING/ERROR/CRITICAL（Java WARN 规范化为 WARNING 落盘）。
• 审计动作：新增 PREVIEW_CACHE_CLEAR / FORCE_OFFLINE / BACKUP_TEST_TARGET（迁移同步扩 CHECK 白名单，含达梦大小写不敏感探测重建）。
• 前端：新页签「系统管理」（features/system/：systemTypes 守卫、systemApi、SystemDashboard）；备份管理页签整体迁入 SystemDashboard；日志审计页签新增「运行日志」大尺寸模态窗口（尾部行数/级别过滤/刷新/全文下载）；角色维护面板管理位区新增「系统管理」「日志审计」复选框；审计页可见性由 ADMIN 硬判定改为 allowedModules 驱动。
• 验证：Python pytest 全量通过（含 test_system_management.py 引擎级 + 接口级）；Java mvn compile/test 通过；前端 tsc 通过、vitest 424 项全绿。

1. 需求

• 新建「系统管理」页签统一收纳系统级管理功能，备份管理页签整体迁入；拥有「系统管理」权限位的角色可见（admin 恒有）；
• 角色配置处新增「系统管理」「日志审计」管理位（与分类/机构/用户编辑并列）；日志审计页签由 ADMIN 硬判定改为「日志审计」权位控制；
• 首期功能：服务器资源监控、应用进程监控、存储用量统计、转换服务状态、健康检查面板、备份管理迁入、备份目标连通测试、运行日志在线查看（并入日志审计页签，单开窗口）、系统信息卡片、运行参数总览（只读）、预览缓存清理、强制下线；
• 二期（本期不做）：在线会话统计、阈值告警、孤儿文件清理。

2. 权限设计

• sys_role 两新列：manage_system / manage_audit_log（BOOLEAN NOT NULL DEFAULT 0）；
• 模块推导：SYSTEM_MANAGEMENT ← manage_system；AUDIT_LOG ← manage_audit_log；其余模块推导不变；admin 恒真；
• 鉴权口径：
  • system/** 全部接口（除 logs）：系统管理权位；
  • system/logs 与 system/logs/download（运行日志）：日志审计权位（功能并入日志审计页签）；
  • backup/** 6 接口 + backup/test-target：ADMIN 硬判定 → 系统管理权位；
  • audit/** 既有接口：ADMIN 硬判定 → 日志审计权位；
• 前端：导航项由 allowedModules 下发；角色维护面板管理位区新增两复选框；admin 不受矩阵约束、默认全选。

3. 接口（契约 1.23.0）

均为 /api/v1 前缀，响应 camelCase：

方法	路径	权限	说明
GET	system/metrics/current	系统管理	CPU（占用率/核数/1分钟负载，Windows 负载为 null）/内存/交换/磁盘分区实时快照 + 开机时间（Java 无 API 恒空串）
GET	system/metrics/history?hours=	系统管理	采样历史（hours ∈ 1/6/24/168/720，缺省 24），{hours, entries[]}
GET	system/process	系统管理	进程 PID/CPU/RSS/VMS/线程数/启动时间/运行时长/运行时版本（Python 版 psutil、Java 版 MXBean，pythonVersion 字段名契约定版，Java 填 JDK 版本）
GET	system/storage-usage	系统管理	七目录（original/preview/extracted/temporary/quarantine/recycle/voucher）字节数与文件数
GET	system/converter	系统管理	LibreOffice 可用状态/可执行文件/并发上限/进行中/累计成功/累计失败/预览开关/超时（内存计数，重启清零）
GET	system/health	系统管理	体检 5 项：DATABASE / STORAGE_WRITABLE / LIBREOFFICE / BACKUP_TARGET / STORAGE_ENCRYPTION，逐项 {item, ok, detail}
GET	system/info	系统管理	14 字段：契约版本/后端类型(JAVA|PYTHON)/运行时版本/OS/主机名/架构/数据库类型/启动时间/运行时长/工作目录/存储根/备份配置路径/.env 路径/日志文件路径
GET	system/runtime-config	系统管理	只读配置总览（分类分组），密钥类（JWT 密钥/KEK/rsync 密码等）仅显示配置状态不回显值
GET	system/logs?lines=&level=	日志审计	日志文件尾部（lines ∈ 1..5000 缺省 500，级别过滤），{file, lines[], truncated, error?}；级别过滤为全量扫描后取尾部时 truncated=true
GET	system/logs/download	日志审计	日志全文（text/plain 附件流）
POST	system/maintenance/preview-cache	系统管理	清空 preview/ 目录，{removedFiles, removedBytes}，审计 PREVIEW_CACHE_CLEAR
POST	system/users/{userId}/force-offline	系统管理	目标用户 authVersion+1 全令牌失效，{userId, username, authVersion}，审计 FORCE_OFFLINE；不能对自己执行
POST	backup/test-target	系统管理	按当前备份配置探测目标可写，{ok, target?, error?}，审计 BACKUP_TEST_TARGET

写操作（清缓存/强制下线/目标测试）不需要二次认证（与备份触发一致口径）。

4. 关键设计

4.1 指标采样

• 表 sys_metric_sample（id/sampled_at/cpu_percent/mem_used_bytes/mem_total_bytes），迁移 0029/V14 幂等建表；
• Python 后台守护线程（MetricSampler）按 DMS_METRIC_INTERVAL_SECONDS（缺省 30 秒）采样入库；Java @Scheduled 固定延迟同口径；
• 清理：每次采样顺带删除早于 DMS_METRIC_RETENTION_DAYS（缺省 7 天）的旧样本；
• 磁盘不采样（分区实时查询，量小无历史需求）。

4.2 运行日志

• DMS_LOG_FILE 配置日志文件路径（相对运行目录），缺省 logs/dms-server.log；目录不存在自动创建（Java LogFileInitializer 启动兜底）；
• Python：Root logger 追加 FileHandler；Java：logback RollingFileAppender（按日滚动）+ 控制台；
• 尾部读取：按字节从文件末尾反向回溯定位行边界，取尾部 N 行；级别过滤时全量扫描匹配行后取尾部并置 truncated=true；
• 未配置或文件未生成时 file 为空串，前端提示「未配置运行日志文件（DMS_LOG_FILE），或文件尚未生成」。

4.3 存储用量与体检

• 存储用量遍历七个存储子目录累加大小与文件数（大目录遍历为毫秒级本地 IO，未做缓存）；
• 体检 5 项：DB 连通（SELECT 1）、存储根可写（临时文件写入探测）、LibreOffice 可用（转换器状态）、备份目标可达（仅启用时探测）、信封加密（KEK 配置状态）。

4.4 强制下线

• 复用既有 authVersion 失效机制：目标用户 auth_version+1，其全部 JWT 立即失效需重新登录；
• 拒绝对自己执行（HTTP 400）；目标不存在报 404。

5. 前端

• 导航：AllowedModule 新增 SYSTEM_MANAGEMENT，模块页映射 system；「备份管理」本地页签下线，BackupDashboard 整体嵌入 SystemDashboard 底部；
• SystemDashboard（features/system/）：操作条（刷新/一键体检）、系统信息卡片（14 行）、应用进程卡片、实时资源（CPU/内存/交换 + 分区表，使用率 ≥90% 红色）、资源采样趋势（近 1/6/24 小时与 7/30 天切换，纯 SVG 双折线图：CPU 红/内存蓝，含 25/50/75% 参考线）、存储目录用量表、转换器卡片、运行参数总览表（只读，密钥仅显示状态）、维护操作（清空预览缓存二次确认、测试备份目标、强制下线弹窗）、体检结果弹窗（逐项 ✓/✗ + 详情）；
• 运行日志窗口（AuditDashboard 内 RuntimeLogModal）：日志审计页筛选栏头部「运行日志」按钮打开；全屏模态（max-w-5xl）：尾部行数选择（200~5000）、级别过滤（DEBUG~CRITICAL）、刷新、下载全文（Blob 锚点落盘 dms-runtime.log）、文件路径与截断提示、等宽字体日志正文；
• 角色维护面板：管理位区新增「系统管理」「日志审计」复选框，创建缺省 false、编辑回显；
• 契约守卫：systemTypes.ts 逐字段类型守卫（与双后端响应形状逐字对齐），不符契约抛 contractHttpError。

6. 验证记录

• Python：pytest 全量 298 通过 / 496 跳过（较备份定版基线 289/470 新增 test_system_management.py 引擎级与接口级用例：采样与清理、存储用量七目录、体检形状、参数脱敏、日志尾部与级别过滤、清缓存/强制下线/目标测试；跳过项为 B2 门控的 DB 集成用例，提供 DMS_TEST_* 环境变量时执行）；test_openapi_storage 守卫 1.23.0 版本与 system 路径白名单；
• Java：mvn compile / mvn test 通过（29 项测试无回归）；
• 前端：npx tsc --noEmit 通过；npx vitest run 66 文件 424 项全绿（含 UserSummary/Role 新增权位字段的守卫与 fixture、审计页 allowedModules 驱动的 q3f/f7 断言更新）；
• 双端形状对齐：SystemManagementService（Java）与 system_management_service.py（Python）逐字段核对（coreCount、loadAvgOneMinute、memoryRssBytes、sampledAt 等 camelCase 键双端一致）。

7. 二期备忘

• 在线会话统计：需令牌登记表（JWT 无状态），双后端并行时按当前实例口径；
• 阈值告警：磁盘/内存超阈值页签红点；
• 孤儿文件清理：存储有文件但 DB 无记录扫描（含 .upload 残留）。