hertz_django/docs/API接口文档/系统监控模块接口文档.md

# Hertz Studio Django 系统监控模块接口文档

- 基础路径: `/api/system/`
- 统一响应: 使用 `HertzResponse`，结构如下（参考 `hertz_studio_django_utils/responses/HertzResponse.py`）
  ```json
  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {}
  }
  ```
- 路由挂载: 项目主路由中已通过 `path('api/system/', include('hertz_studio_django_system_monitor.urls'))` 挂载（`hertz_server_django/urls.py:23`）。
- 认证说明: 所有接口均需要登录，需在请求头携带 `Authorization: Bearer <token>`（`hertz_studio_django_auth/utils/decorators/auth_decorators.py:1`）。


## 一、系统信息

### 获取系统信息
- 方法: `GET`
- 路径: `/api/system/system/`
- 认证: 需要登录
- 实现: `SystemInfoView.get`（`hertz_studio_django_system_monitor/views.py:63`）
- 请求示例:
  ```bash
  curl "http://localhost:8000/api/system/system/" \
    -H "Authorization: Bearer <token>"
  ```
- 返回示例:
  ```json
  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
      "hostname": "DESKTOP-ABC123",
      "platform": "Windows-10-10.0.19041-SP0",
      "architecture": "AMD64",
      "boot_time": "2025-11-16T08:30:00Z",
      "uptime": "2 days, 14:30:00"
    }
  }
  ```


## 二、CPU 信息

### 获取CPU信息
- 方法: `GET`
- 路径: `/api/system/cpu/`
- 认证: 需要登录
- 实现: `CPUInfoView.get`（`hertz_studio_django_system_monitor/views.py:63`）
- 请求示例:
  ```bash
  curl "http://localhost:8000/api/system/cpu/" \
    -H "Authorization: Bearer <token>"
  ```
- 返回示例:
  ```json
  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
      "cpu_count": 8,
      "cpu_percent": 25.6,
      "cpu_freq": {"current": 2400.0, "min": 800.0, "max": 3600.0},
      "load_avg": [1.2, 1.5, 1.8]
    }
  }
  ```


## 三、内存信息

### 获取内存信息
- 方法: `GET`
- 路径: `/api/system/memory/`
- 认证: 需要登录
- 实现: `MemoryInfoView.get`（`hertz_studio_django_system_monitor/views.py:94`）
- 请求示例:
  ```bash
  curl "http://localhost:8000/api/system/memory/" \
    -H "Authorization: Bearer <token>"
  ```
- 返回示例:
  ```json
  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
      "total": 17179869184,
      "available": 8589934592,
      "used": 8589934592,
      "percent": 50.0,
      "free": 8589934592
    }
  }
  ```


## 四、磁盘信息

### 获取磁盘信息
- 方法: `GET`
- 路径: `/api/system/disks/`
- 认证: 需要登录
- 实现: `DiskInfoView.get`（`hertz_studio_django_system_monitor/views.py:127`）
- 请求示例:
  ```bash
  curl "http://localhost:8000/api/system/disks/" \
    -H "Authorization: Bearer <token>"
  ```
- 返回示例:
  ```json
  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": [
      {
        "device": "C:\\",
        "mountpoint": "C:\\",
        "fstype": "NTFS",
        "total": 1073741824000,
        "used": 536870912000,
        "free": 536870912000,
        "percent": 50.0
      }
    ]
  }
  ```


## 五、网络信息

### 获取网络信息
- 方法: `GET`
- 路径: `/api/system/network/`
- 认证: 需要登录
- 实现: `NetworkInfoView.get`（`hertz_studio_django_system_monitor/views.py:170`）
- 请求示例:
  ```bash
  curl "http://localhost:8000/api/system/network/" \
    -H "Authorization: Bearer <token>"
  ```
- 返回示例:
  ```json
  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": [
      {
        "interface": "以太网",
        "bytes_sent": 1048576000,
        "bytes_recv": 2097152000,
        "packets_sent": 1000000,
        "packets_recv": 1500000
      }
    ]
  }
  ```


## 六、进程信息

### 获取进程信息
- 方法: `GET`
- 路径: `/api/system/processes/`
- 认证: 需要登录
- 查询参数:
  - `limit`: 返回条数，默认 `20`
  - `sort_by`: 排序字段，默认 `cpu_percent`（可选 `cpu_percent|memory_percent|create_time`）
- 实现: `ProcessInfoView.get`（`hertz_studio_django_system_monitor/views.py:204`）
- 请求示例:
  ```bash
  curl "http://localhost:8000/api/system/processes/?limit=10&sort_by=cpu_percent" \
    -H "Authorization: Bearer <token>"
  ```
- 返回示例:
  ```json
  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": [
      {
        "pid": 1234,
        "name": "python.exe",
        "status": "running",
        "cpu_percent": 15.6,
        "memory_percent": 8.2,
        "memory_info": {"rss": 134217728, "vms": 268435456},
        "create_time": "2025-11-16T10:30:00Z",
        "cmdline": ["python", "manage.py", "runserver"]
      }
    ]
  }
  ```


## 七、GPU 信息

### 获取GPU信息
- 方法: `GET`
- 路径: `/api/system/gpu/`
- 认证: 需要登录
- 实现: `GPUInfoView.get`（`hertz_studio_django_system_monitor/views.py:259`）
- 请求示例:
  ```bash
  curl "http://localhost:8000/api/system/gpu/" \
    -H "Authorization: Bearer <token>"
  ```
- 返回示例（有GPU设备）:
  ```json
  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
      "gpu_available": true,
      "gpu_info": [
        {
          "id": 0,
          "name": "NVIDIA GeForce RTX 3080",
          "load": 45.6,
          "memory_total": 10240,
          "memory_used": 4096,
          "memory_util": 40.0,
          "temperature": 65
        }
      ],
      "timestamp": "2025-11-16 18:30:00"
    }
  }
  ```
- 返回示例（无GPU设备）:
  ```json
  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
      "gpu_available": false,
      "message": "未检测到GPU设备",
      "timestamp": "2025-11-16 18:30:00"
    }
  }
  ```
- 返回示例（GPU库不可用）:
  ```json
  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
      "gpu_available": false,
      "message": "GPU监控不可用，请安装GPUtil库",
      "timestamp": "2025-11-16 18:30:00"
    }
  }
  ```


## 八、综合监控

### 获取系统监测综合信息
- 方法: `GET`
- 路径: `/api/system/monitor/`
- 认证: 需要登录
- 实现: `SystemMonitorView.get`（`hertz_studio_django_system_monitor/views.py:325`）
- 请求示例:
  ```bash
  curl "http://localhost:8000/api/system/monitor/" \
    -H "Authorization: Bearer <token>"
  ```
- 返回示例（节选）:
  ```json
  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
      "system": {"hostname": "DESKTOP-ABC123", "platform": "Windows-10-10.0.19041-SP0", "architecture": "AMD64", "boot_time": "2025-11-16T08:30:00Z", "uptime": "2 days, 14:30:00"},
      "cpu": {"cpu_count": 8, "cpu_percent": 25.6, "cpu_freq": {"current": 2400.0, "min": 800.0, "max": 3600.0}, "load_avg": [1.2, 1.5, 1.8]},
      "memory": {"total": 17179869184, "available": 8589934592, "used": 8589934592, "percent": 50.0, "free": 8589934592},
      "disks": [{"device": "C:\\", "mountpoint": "C:\\", "fstype": "NTFS", "total": 1073741824000, "used": 536870912000, "free": 536870912000, "percent": 50.0}],
      "network": [{"interface": "以太网", "bytes_sent": 1048576000, "bytes_recv": 2097152000, "packets_sent": 1000000, "packets_recv": 1500000}],
      "processes": [{"pid": 1234, "name": "python.exe", "status": "running", "cpu_percent": 15.6, "memory_percent": 8.2, "memory_info": {"rss": 134217728, "vms": 268435456}, "create_time": "2025-11-16T10:30:00Z", "cmdline": ["python", "manage.py", "runserver"]}],
      "gpus": [{"id": 0, "name": "NVIDIA GeForce RTX 3080", "load": 45.6, "memory_total": 10240, "memory_used": 4096, "memory_util": 40.0, "temperature": 65}]
    }
  }
  ```


## 九、错误响应示例
- 通用错误格式:
  ```json
  {"success": false, "code": 401, "message": "未授权访问"}
  ```