TermControlAgent/docs/system_api.md

系统API文档

概述

系统API提供了获取机器码和系统信息的功能，支持Windows和Linux系统，遵循项目的分层架构设计。

API端点

1. 获取机器码

端点： GET /api/v1/system/machine-code

描述： 获取当前系统的机器码

响应示例：

{
  "success": true,
  "message": "机器码获取成功",
  "data": {
    "machine_code": "03000200-0400-0500-0006-000700080009",
    "system_type": "windows",
    "method": "wmic csproduct get uuid"
  }
}

2. 获取系统信息

端点： GET /api/v1/system/info

描述： 获取当前系统的详细信息

响应示例：

{
  "success": true,
  "message": "系统信息获取成功",
  "data": {
    "system_type": "windows",
    "platform": "Windows-10-10.0.17763-SP0",
    "architecture": "64bit",
    "processor": "AMD64 Family 23 Model 24 Stepping 1, AuthenticAMD",
    "machine_code": "03000200-0400-0500-0006-000700080009",
    "python_version": "3.10.5"
  }
}

3. 获取详细机器码信息

端点： GET /api/v1/system/machine-code/detailed

描述： 获取包含系统信息的详细机器码信息

响应示例：

{
  "success": true,
  "message": "详细机器码信息获取成功",
  "data": {
    "machine_code": "03000200-0400-0500-0006-000700080009",
    "system_type": "windows",
    "method": "wmic csproduct get uuid",
    "system_info": {
      "system_type": "windows",
      "platform": "Windows-10-10.0.17763-SP0",
      "architecture": "64bit",
      "processor": "AMD64 Family 23 Model 24 Stepping 1, AuthenticAMD",
      "machine_code": "03000200-0400-0500-0006-000700080009",
      "python_version": "3.10.5"
    },
    "timestamp": "2025-08-15T15:21:54.205977"
  }
}

4. 系统健康检查

端点： GET /api/v1/system/health

描述： 检查系统基本功能是否正常

响应示例：

{
  "success": true,
  "message": "系统健康检查通过",
  "data": {
    "system_type": "windows",
    "machine_code_available": true,
    "status": "healthy"
  }
}

技术实现

Windows系统

• 主要方法：wmic csproduct get uuid
• 备用方法：PowerShell Get-WmiObject -Class Win32_ComputerSystemProduct

Linux系统

• 主要方法：dmidecode -s system-serial-number
• 备用方法1：读取 /sys/class/dmi/id/product_serial
• 备用方法2：hostid 命令

错误处理

• 命令执行超时处理
• 多种备用方案确保兼容性
• 详细的错误日志记录

架构设计

API端点层 (app/api/v1/endpoints/system.py)
    ↓
服务层 (app/services/system_service.py)
    ↓
工具层 (app/utils/system_utils.py)
    ↓
系统命令执行

使用示例

Python客户端

import requests

# 获取机器码
response = requests.get("http://localhost:8000/api/v1/system/machine-code")
machine_code = response.json()["data"]["machine_code"]

# 获取系统信息
response = requests.get("http://localhost:8000/api/v1/system/info")
system_info = response.json()["data"]

curl命令

# 获取机器码
curl -X GET "http://localhost:8000/api/v1/system/machine-code"

# 获取系统信息
curl -X GET "http://localhost:8000/api/v1/system/info"

# 系统健康检查
curl -X GET "http://localhost:8000/api/v1/system/health"

注意事项

1. 权限要求：某些系统命令可能需要管理员权限
2. 兼容性：不同系统版本可能有差异，已提供多种备用方案
3. 性能：命令执行有超时限制，避免长时间阻塞
4. 安全性：仅获取系统标识信息，不涉及敏感数据