上传规范文档

2025-11-17 16:39:30 +08:00
parent 545335b666
commit 638e152cff
11 changed files with 2757 additions and 0 deletions
--- a/docs/API接口文档/系统监控模块接口文档.md
+++ b/docs/API接口文档/系统监控模块接口文档.md
@@ -0,0 +1,302 @@
+# 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": "未授权访问"}
+  ```