Domovská stránka Prehľadávať Pomoc
Registrovať Prihlásiť sa
Luxnk
/
win_monitor
1
0
Fork 0
Súbory Issues 0 Pull requesty 0 Wiki
Strom: 398fa25833
Branche Tagy
win_monitor
/
api-docs.md

api-docs.md 16 KB
História Raw

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}

内置标签不可删除。

AI 配置与调用

AI 模块分为项目内部统一 AI 服务层和具体供应商 API 对接层。当前支持：

类型 说明
OPENAI OpenAI Chat Completions API，默认 Base URL 为 https://api.openai.com/v1
OPENAI_COMPATIBLE OpenAI 兼容格式 API，适用于 LM Studio、本地模型服务或其他兼容服务
GOOGLE_GEMINI Google Gemini Generate Content API，默认 Base URL 为 https://generativelanguage.googleapis.com/v1beta

服务商 API Key 可为空，接口返回时只返回 api_key_set，不会返回明文 Key。

查询 AI 服务商

GET /api/ai/providers

新增 AI 服务商

POST /api/ai/providers

{
  "name": "本地 LM Studio",
  "provider_type": "OPENAI_COMPATIBLE",
  "base_url": "http://127.0.0.1:1234/v1",
  "api_key": "",
  "enabled": true
}

更新 AI 服务商

PATCH /api/ai/providers/{provider_id}

{
  "name": "OpenAI",
  "provider_type": "OPENAI",
  "base_url": "https://api.openai.com/v1",
  "api_key": "sk-xxxx",
  "clear_api_key": false,
  "enabled": true
}

说明：编辑时 api_key 留空表示不修改原 Key；clear_api_key = true 表示清空原 Key。

删除 AI 服务商

DELETE /api/ai/providers/{provider_id}

会级联删除该服务商下的模型配置。

查询 AI 模型

GET /api/ai/models?provider_id=1

provider_id 可选；不传时返回全部模型。

新增 AI 模型

POST /api/ai/models

{
  "provider_id": 1,
  "name": "gpt-4o-mini",
  "display_name": "GPT-4o mini",
  "is_default": true
}

更新 AI 模型

PATCH /api/ai/models/{model_id}

{
  "provider_id": 1,
  "name": "gemini-1.5-flash",
  "display_name": "Gemini Flash",
  "is_default": true
}

同一服务商只能有一个默认模型。设置新的默认模型后，同服务商其他模型会自动取消默认。

删除 AI 模型

DELETE /api/ai/models/{model_id}

测试 AI 服务

POST /api/ai/test

{
  "provider_id": 1,
  "model_id": 1,
  "prompt": "请用一句话回答：你已经可以连接了吗？",
  "temperature": 0.2
}

返回：

{
  "provider": {},
  "model": {},
  "content": "AI 输出文本",
  "raw_response": {}
}

扫描

执行完整扫描

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": "保持运行。",
      "tags": ["windows系统"]
    }
  ]
}

说明：

  • tags 为可选字段，格式为标签名称数组；老格式不传 tags 仍可导入。
  • 如果传入 tags，后端会将对应服务的标签替换为该数组。
  • 数据库中不存在的标签会自动创建，默认 is_controllable = true、is_builtin = false。

调用 AI 分析服务并返回待确认结果

POST /api/services/analyze-ai

{
  "provider_id": 1,
  "model_id": 1,
  "temperature": 0.2,
  "scope": "selected",
  "ids": [1, 2]
}

说明：

  • 后端会复用服务 AI 提示词模板，调用配置的 AI 服务商和模型。
  • 接口只返回 AI 输出解析结果和更新预览，不直接写入数据库。
  • 前端确认后继续调用 /api/services/import-ai 入库。

返回主要字段：

字段 说明
items 解析后的 AI JSON 数组
preview 当前数据库值与 AI 建议值的对比
raw_output AI 原始输出文本
provider 本次使用的服务商信息
model 本次使用的模型信息
prompt_text 本次发送给 AI 的提示词
markdown_table 人工核对表

生成服务 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": "建议隔离并检查哈希和网络连接。",
      "tags": ["可疑程序"]
    }
  ]
}

说明：

  • tags 为可选字段，格式为标签名称数组；老格式不传 tags 仍可导入。
  • 如果传入 tags，后端会将对应进程的标签替换为该数组。
  • 数据库中不存在的标签会自动创建，默认 is_controllable = true、is_builtin = false。

调用 AI 分析进程并返回待确认结果

POST /api/processes/analyze-ai

{
  "provider_id": 1,
  "model_id": 1,
  "temperature": 0.2,
  "scope": "pending"
}

说明：

  • 后端会复用进程 AI 提示词模板，调用配置的 AI 服务商和模型。
  • 接口只返回 AI 输出解析结果和更新预览，不直接写入数据库。
  • 前端确认后继续调用 /api/processes/import-ai 入库。

生成进程 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 时不允许控制。
  • 停止进程要求该进程在最近一次扫描中仍然存在。

Windows 自动化

自动化接口用于后续复杂本机操作编排。关机、重启、鼠标和键盘操作会直接影响当前 Windows 桌面环境，调用前应由上层业务明确确认。

关机

POST /api/automation/power/shutdown

{
  "delay_seconds": 60,
  "force": false,
  "reason": "计划关机"
}

重启

POST /api/automation/power/restart

请求体同关机接口。

取消已排程关机或重启

POST /api/automation/power/cancel

启动程序

POST /api/automation/programs/start

{
  "command": "notepad.exe",
  "cwd": null,
  "shell": true
}

关闭程序

POST /api/automation/programs/stop

{
  "pid": 1234,
  "name": null,
  "timeout_seconds": 8,
  "kill_after_timeout": true
}

说明：pid 和 name 至少传一个；按名称关闭时会匹配同名进程。

屏幕截图

POST /api/automation/screenshot

{
  "save_path": "C:/Temp/screen.png",
  "include_base64": true
}

鼠标操作

POST /api/automation/mouse

{
  "action": "click",
  "x": 100,
  "y": 200,
  "button": "left",
  "clicks": 1,
  "duration": 0,
  "amount": 0
}

action 支持：move_to、move_rel、click、double_click、right_click、drag_to、scroll。

键盘操作

POST /api/automation/keyboard

{
  "action": "hotkey",
  "keys": ["ctrl", "s"],
  "interval": 0
}

action 支持：press、hotkey、write、key_down、key_up。

AI 视觉分析当前界面

POST /api/automation/vision/analyze

{
  "provider_id": 1,
  "model_id": 1,
  "temperature": 0.1
}

后端会截取当前 Windows 屏幕，调用支持视觉输入的 AI 模型识别界面名称、描述、是否为 Windows 桌面、是否为浏览器网页，以及可操作元素列表。AI 返回的百分比坐标会按原始截图分辨率换算为像素坐标；截图和识别结果会保存到数据库。

高层自动化动作接口

以下接口会在动作执行前获取一次当前进程列表，执行后再次获取并对比新增进程。若请求携带 screen_id，后端会先截图当前屏幕，并把当前截图和数据库中保存的目标界面截图发送给 AI 做界面对比；不匹配时会写入自动化错误记录并终止动作。

POST /api/automation/actions/mouse

{
  "screen_id": 1,
  "provider_id": 1,
  "model_id": 1,
  "temperature": 0.1,
  "x": 420,
  "y": 260,
  "mouse_action": "click"
}

mouse_action 支持：click、right_click、double_click。

POST /api/automation/actions/keyboard

{
  "screen_id": 1,
  "provider_id": 1,
  "model_id": 1,
  "keys": ["ctrl", "s"]
}

POST /api/automation/actions/text-input

{
  "screen_id": 1,
  "provider_id": 1,
  "model_id": 1,
  "text": "要输入的中文文本"
}

文本输入使用剪贴板粘贴，避免中文直接按键模拟不稳定。

POST /api/automation/actions/start-program

{
  "command": "msedge",
  "cwd": null,
  "shell": true
}

POST /api/automation/actions/close-opened-programs

{
  "pids": [1234, 5678]
}

如果不传 pids，后端会尝试关闭当前后端进程内记录的自动化新增进程。

自动化工作流

GET /api/automation/workflows

POST /api/automation/workflows

{
  "name": "打开浏览器并点击",
  "description": "示例工作流",
  "nodes": [
    {
      "node_type": "start_program",
      "title": "启动 Edge",
      "config": { "command": "msedge" }
    },
    {
      "node_type": "mouse",
      "screen_id": 1,
      "title": "点击按钮",
      "config": { "x": 420, "y": 260, "mouse_action": "click" }
    }
  ]
}

节点类型当前支持：mouse、keyboard、text_input、start_program、close_programs。

GET /api/automation/workflows/{workflow_id}

PUT /api/automation/workflows/{workflow_id}

DELETE /api/automation/workflows/{workflow_id}

已识别界面

GET /api/automation/screens

GET /api/automation/screens/{screen_id}?include_image=true

DELETE /api/automation/screens/{screen_id}

自动化错误记录

GET /api/automation/errors

GET /api/automation/errors/{error_id}?include_images=true

AI 提示词中的标签信息

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

  • 每个待分析对象的 tags 字段。
  • 系统中已有标签列表，包括 name、description、is_controllable。
  • 标签判断要求：AI 需要结合已有标签进行分析，并在输出对象的 tags 字段中返回建议绑定的标签名称数组。
  • AI 可以使用已有标签，也可以在确有必要时返回新的短标签名称；导入时不存在的标签会自动新增。