win_monitor/api-docs.md

Windows 监控管理系统接口说明

基础信息

• 后端默认地址：http://127.0.0.1:8000
• 返回格式：JSON
• 确认状态枚举：PENDING、TRUSTED、SUSPICIOUS、IGNORED、NEED_MORE_INFO
• AI 风险等级枚举：LOW、MEDIUM、HIGH

仪表盘

获取仪表盘概览

GET /api/dashboard

返回最近扫描记录、服务总数、进程总数、待确认数量、本次未出现数量。

标签

系统内置两个默认标签：

标签	默认是否可以被控制	说明
windows系统	否	用于标记 Windows 系统原生服务或进程
本系统相关	否	用于标记本项目自身相关服务或进程

如果服务或进程存在任一 is_controllable = false 的标签，前端不会显示启动、停止、重启等控制操作，后端控制接口也会拒绝执行。

查询标签

GET /api/tags

新增标签

POST /api/tags

{
  "name": "业务软件",
  "description": "业务系统相关组件",
  "is_controllable": true
}

更新标签

PATCH /api/tags/{tag_id}

{
  "name": "windows系统",
  "description": "Windows 系统原生服务或进程",
  "is_controllable": false
}

删除标签

DELETE /api/tags/{tag_id}

内置标签不可删除。

扫描

执行完整扫描

POST /api/scans/run

执行 Windows 服务和进程采集，写入扫描记录，并按业务规则更新 is_present_now、last_seen_at、运行状态等字段。

查询扫描历史

GET /api/scans?page=1&page_size=20

查询扫描详情

GET /api/scans/{scan_id}

传感器

获取实时传感器信息

GET /api/sensors

说明：

• 数据不写入数据库。
• CPU、内存负载来自 psutil。
• 显卡优先使用 nvidia-smi；如果不可用，尝试 Windows GPU 性能计数器。
• 温度优先读取 LibreHardwareMonitor/OpenHardwareMonitor WMI，其次尝试 psutil 和 ACPI 热区。
• Windows 原生接口不一定能提供 CPU/GPU 真实温度，实际可见字段取决于硬件、驱动和监控组件。

返回主要字段：

字段	说明
collected_at	采集时间
cpu	CPU 总负载、每核心负载、核心数、频率
memory	物理内存和交换区使用情况
gpu	显卡负载、温度、显存、功耗等
temperatures	psutil/ACPI 温度
hardware_sensors	LibreHardwareMonitor/OpenHardwareMonitor 传感器

硬盘 SMART

扫描 smartctl 设备列表

GET /api/smart/scan

等价于执行：

smartctl --scan

获取全部硬盘 SMART 信息

GET /api/smart/devices?include_jmb39x=true&jmb39x_slots=8

查询参数：

参数	类型	说明
include_jmb39x	boolean	是否对 SAT/ATA 类设备额外探测 JMB39x 阵列槽位
jmb39x_slots	integer	探测槽位数量，范围 0-16，默认 8

普通设备会按 smartctl --scan 返回的设备和类型执行：

smartctl -a -d sat /dev/sdb

JMB39x 阵列会按槽位执行：

smartctl -a -d jmb39x,0 /dev/sdb
smartctl -a -d jmb39x,1 /dev/sdb

返回每块盘的解析摘要、ATA SMART 属性表、警告信息和原始 smartctl 输出。

获取单个设备 SMART 信息

GET /api/smart/device?device=/dev/sda&device_type=nvme

查询参数：

参数	类型	说明
device	string	设备路径，例如 /dev/sda
device_type	string	可选，smartctl 的 -d 类型，例如 nvme、sat、jmb39x,0

Windows 服务

查询服务列表

GET /api/services

查询参数：

参数	类型	说明
keyword	string	按名称、显示名称、路径、描述搜索
confirm_status	string	确认状态
present	boolean	true 本次出现，false 本次未出现
page	integer	页码，默认 1
page_size	integer	每页数量，默认 20，最大 200

获取服务详情

GET /api/services/{service_id}

更新服务说明和状态

PATCH /api/services/{service_id}

请求体：

{
  "confirm_status": "TRUSTED",
  "user_note": "人工确认说明"
}

批量更新服务状态

PATCH /api/services/batch

请求体：

{
  "ids": [1, 2, 3],
  "confirm_status": "SUSPICIOUS",
  "user_note": "批量标记说明，可为空"
}

根据 AI JSON 批量更新服务

POST /api/services/import-ai

请求体：

{
  "items": [
    {
      "type": "service",
      "name": "WinDefend",
      "description": "Microsoft Defender 防病毒核心服务。",
      "judgement": "TRUSTED",
      "risk_level": "LOW",
      "reason": "Microsoft 官方安全组件。",
      "suggestion": "保持运行。"
    }
  ]
}

生成服务 AI 分析提示词

POST /api/services/ai-prompt

请求体：

{
  "scope": "selected",
  "ids": [1, 2]
}

说明：

• scope = selected 时使用 ids 指定的服务。
• scope = pending 时忽略 ids，生成全部待确认服务的提示词。
• 返回 prompt_text、markdown_table 和 items。

更新服务标签

PUT /api/services/{service_id}/tags

{
  "tag_ids": [1, 2]
}

启动服务

POST /api/services/{service_id}/start

停止服务

POST /api/services/{service_id}/stop

重新启动服务

POST /api/services/{service_id}/restart

控制规则：

• confirm_status 必须是 TRUSTED、SUSPICIOUS 或 IGNORED。
• PENDING 和 NEED_MORE_INFO 不允许控制。
• 任一关联标签 is_controllable = false 时不允许控制。
• 服务必须在最近一次扫描中仍然存在。

Windows 进程

查询进程列表

GET /api/processes

查询参数：

参数	类型	说明
keyword	string	按名称、路径、命令行、用户搜索
confirm_status	string	确认状态
present	boolean	true 本次出现，false 本次未出现
page	integer	页码，默认 1
page_size	integer	每页数量，默认 20，最大 200

获取进程详情

GET /api/processes/{process_id}

更新进程说明和状态

PATCH /api/processes/{process_id}

请求体：

{
  "confirm_status": "SUSPICIOUS",
  "user_note": "人工确认说明"
}

批量更新进程状态

PATCH /api/processes/batch

请求体：

{
  "ids": [10, 11],
  "confirm_status": "IGNORED",
  "user_note": "批量忽略说明，可为空"
}

根据 AI JSON 批量更新进程

POST /api/processes/import-ai

请求体：

{
  "items": [
    {
      "type": "process",
      "name": "unknown.exe",
      "description": "未知用途执行文件。",
      "judgement": "SUSPICIOUS",
      "risk_level": "HIGH",
      "reason": "路径和命令行异常。",
      "suggestion": "建议隔离并检查哈希和网络连接。"
    }
  ]
}

生成进程 AI 分析提示词

POST /api/processes/ai-prompt

请求体：

{
  "scope": "pending"
}

返回 prompt_text、markdown_table 和 items。

更新进程标签

PUT /api/processes/{process_id}/tags

{
  "tag_ids": [2]
}

启动进程

POST /api/processes/{process_id}/start

使用数据库中记录的 cmdline 或 exe_path 重新启动进程。

停止进程

POST /api/processes/{process_id}/stop

使用数据库中记录的 last_pid 停止进程，并校验当前 PID 的进程名与记录一致，避免误杀 PID 复用后的其他进程。

控制规则：

• confirm_status 必须是 TRUSTED、SUSPICIOUS 或 IGNORED。
• PENDING 和 NEED_MORE_INFO 不允许控制。
• 任一关联标签 is_controllable = false 时不允许控制。
• 停止进程要求该进程在最近一次扫描中仍然存在。

AI 提示词中的标签信息

服务和进程的 AI 提示词会包含：

• 每个待分析对象的 tags 字段。
• 系统中已有标签列表，包括 name、description、is_controllable。
• 标签判断要求：AI 需要结合已有标签进行分析，如果适合已有标签，可以在 suggestion 中建议使用对应标签名称，但不能创造不存在的新标签。