feat: 完善堡垒机与 Agent 智能运维能力

- 支持 Windows Agent 构建、安装脚本和统一上报协议 - 增强 RDP 剪贴板、虚拟盘和文件传输能力 - 新增 AIOps 上下文工具、告警 RCA trace 落库和回放接口 - 重构 docs 模块文档并补充终端、堡垒机、监控、AI Agent 设计
2026-07-05 23:49:36 +08:00
1 parent a9513c2056
commit e0d652d211
@@ -0,0 +1,662 @@
+# API 接口文档
+
+## 基础信息
+
+| 项目 | 值 |
+|------|---|
+| Base URL | `http://localhost:8080/api/v1` |
+| 认证方式 | JWT Bearer Token |
+| 请求格式 | JSON |
+| 响应格式 | JSON |
+
+## 通用响应结构
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {}
+}
+```
+
+分页响应：
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "list": [],
+    "total": 100
+  }
+}
+```
+
+## 认证
+
+### POST /auth/login
+
+用户登录，获取 JWT Token。
+
+**请求体：**
+```json
+{
+  "username": "admin",
+  "password": "admin123"
+}
+```
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "登录成功",
+  "data": {
+    "token": "eyJhbGciOiJIUzI1NiIs...",
+    "expires_in": 86400,
+    "user": {
+      "id": 1,
+      "username": "admin",
+      "real_name": "管理员"
+    }
+  }
+}
+```
+
+### POST /auth/register
+
+用户注册。
+
+### GET /user/profile
+
+获取当前登录用户信息。（需认证）
+
+### PUT /user/profile
+
+更新当前用户信息。（需认证）
+
+### PUT /user/password
+
+修改密码。（需认证）
+
+## 用户管理（管理员）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/admin/users` | 用户列表 |
+| GET | `/admin/users/:id` | 用户详情 |
+| POST | `/admin/users` | 创建用户 |
+| PUT | `/admin/users/:id` | 更新用户 |
+| DELETE | `/admin/users/:id` | 删除用户 |
+
+## 仪表盘
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/dashboard/stats` | 统计数据 |
+| GET | `/dashboard/recent-alerts` | 最近告警 |
+| GET | `/dashboard/recent-releases` | 最近发布 |
+| GET | `/dashboard/metrics` | 性能指标 |
+
+## 服务器管理
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/servers` | 服务器列表 |
+| GET | `/servers/stats` | 服务器统计 |
+| GET | `/servers/:id` | 服务器详情 |
+| POST | `/servers` | 添加服务器 |
+| PUT | `/servers/:id` | 更新服务器 |
+| DELETE | `/servers/:id` | 删除服务器 |
+| POST | `/servers/batch-delete` | 批量删除 |
+
+## 云平台管理
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/cloud-accounts` | 云账号列表 |
+| POST | `/cloud-accounts` | 添加云账号 |
+| DELETE | `/cloud-accounts/:id` | 删除云账号 |
+| GET | `/domains` | 域名列表 |
+| POST | `/domains` | 添加域名 |
+| DELETE | `/domains/:id` | 删除域名 |
+
+## K8s 集群
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/k8s-clusters` | 集群列表 |
+| GET | `/k8s-clusters/:id` | 集群详情 |
+| POST | `/k8s-clusters` | 添加集群 |
+| PUT | `/k8s-clusters/:id` | 更新集群 |
+| DELETE | `/k8s-clusters/:id` | 删除集群 |
+| GET | `/k8s-clusters/:id/nodes` | 节点列表 |
+| GET | `/k8s-clusters/:id/pods` | Pod 列表 |
+| GET | `/k8s-clusters/:id/deployments` | Deployment 列表 |
+| GET | `/k8s-clusters/:id/services` | Service 列表 |
+| GET | `/k8s-clusters/:id/ingresses` | Ingress 列表 |
+
+## 监控告警
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/alerts` | 告警事件列表 |
+| GET | `/alerts/rules` | 告警规则列表 |
+| POST | `/alerts/rules` | 创建告警规则 |
+| PUT | `/alerts/rules/:id` | 更新规则 |
+| DELETE | `/alerts/rules/:id` | 删除规则 |
+| POST | `/alerts/rules/:id/toggle` | 启用/禁用规则 |
+| POST | `/alerts/:id/ack` | 确认告警 |
+
+## CI/CD 流水线
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/pipelines` | 流水线列表 |
+| POST | `/pipelines` | 创建流水线 |
+| GET | `/pipelines/:id` | 流水线详情 |
+| PUT | `/pipelines/:id` | 更新流水线 |
+| DELETE | `/pipelines/:id` | 删除流水线 |
+| POST | `/pipelines/:id/trigger` | 触发流水线 |
+| GET | `/pipelines/:id/runs` | 执行记录 |
+
+## 应用发布
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/releases` | 发布列表 |
+| POST | `/releases` | 创建发布 |
+| POST | `/releases/:id/approve` | 审批发布 |
+| POST | `/releases/:id/deploy` | 部署发布 |
+| POST | `/releases/:id/rollback` | 回滚发布 |
+
+## 自动化运维
+
+### 定时任务
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/cron-jobs` | 任务列表 |
+| POST | `/cron-jobs` | 创建任务 |
+| GET | `/cron-jobs/:id` | 任务详情 |
+| PUT | `/cron-jobs/:id` | 更新任务 |
+| DELETE | `/cron-jobs/:id` | 删除任务 |
+| POST | `/cron-jobs/:id/toggle` | 启用/禁用 |
+| POST | `/cron-jobs/:id/execute` | 手动执行 |
+
+### 脚本管理
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/scripts` | 脚本列表 |
+| POST | `/scripts` | 创建脚本 |
+| GET | `/scripts/:id` | 脚本详情 |
+| PUT | `/scripts/:id` | 更新脚本 |
+| DELETE | `/scripts/:id` | 删除脚本 |
+| POST | `/scripts/:id/execute` | 执行脚本 |
+
+## 审批流程
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/approvals/templates` | 审批模板列表 |
+| POST | `/approvals/templates` | 创建模板 |
+| GET | `/approvals/templates/:id` | 模板详情 |
+| PUT | `/approvals/templates/:id` | 更新模板 |
+| DELETE | `/approvals/templates/:id` | 删除模板 |
+| GET | `/approvals/processes` | 审批流程列表 |
+| POST | `/approvals/processes` | 发起审批 |
+| GET | `/approvals/processes/:id` | 流程详情 |
+| POST | `/approvals/processes/:id/approve` | 审批通过 |
+| POST | `/approvals/processes/:id/reject` | 审批驳回 |
+
+## 导航管理
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/navigations/groups` | 导航分组列表 |
+| POST | `/navigations/groups` | 创建分组 |
+| PUT | `/navigations/groups/:id` | 更新分组 |
+| DELETE | `/navigations/groups/:id` | 删除分组 |
+| GET | `/navigations/links` | 导航链接列表 |
+| POST | `/navigations/links` | 创建链接 |
+| PUT | `/navigations/links/:id` | 更新链接 |
+| DELETE | `/navigations/links/:id` | 删除链接 |
+| POST | `/navigations/links/:id/favorite` | 收藏/取消收藏 |
+
+## 审计日志
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/audit/logs` | 审计日志列表 |
+| GET | `/audit/logs/:id` | 日志详情 |
+| GET | `/audit/modules` | 审计模块列表 |
+| GET | `/audit/actions` | 审计操作列表 |
+| GET | `/audit/logs/export` | 导出日志 |
+| GET | `/audit/statistics` | 审计统计 |
+| POST | `/audit/logs/clear` | 清空日志 |
+
+## 健康检查
+
+### GET /health
+
+无需认证。
+
+```json
+{
+  "status": "ok"
+}
+```
+
+### GET /version
+
+无需认证。
+
+```json
+{
+  "version": "dev",
+  "build_time": "unknown",
+  "git_commit": "unknown"
+}
+```
+
+## Agent 监控
+
+### POST /agent/report — Agent 上报指标 (无需 JWT)
+
+Agent 向服务端上报主机性能指标数据。
+
+**请求体：**
+```json
+{
+  "hostname": "web-server-01",
+  "cpu": {
+    "usage_percent": 45.2,
+    "cores": 8
+  },
+  "memory": {
+    "total_gb": 16,
+    "used_gb": 8.5,
+    "usage_percent": 53.1
+  },
+  "disk": [
+    {
+      "mount": "/",
+      "total_gb": 100,
+      "used_gb": 60,
+      "usage_percent": 60.0
+    }
+  ],
+  "network": {
+    "rx_bytes": 1024000,
+    "tx_bytes": 512000
+  },
+  "uptime_seconds": 864000
+}
+```
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "上报成功",
+  "data": null
+}
+```
+
+### GET /agent/latest — 各主机最新指标 (需 JWT)
+
+获取所有在线主机的最近一次上报指标。仅返回 3 分钟内活跃且匹配 servers 表的主机。
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "hostname": "web-server-01",
+      "cpu": { "usage_percent": 45.2 },
+      "memory": { "usage_percent": 53.1 },
+      "disk": [{"usage_percent": 60.0}],
+      "network": { "rx_bytes": 1024000, "tx_bytes": 512000 },
+      "uptime_seconds": 864000,
+      "reported_at": "2025-06-18T10:30:00Z"
+    }
+  ]
+}
+```
+
+### GET /agent/history/:hostname — 历史趋势 (?hours=N)
+
+查询指定主机在最近 N 小时内的指标历史数据。
+
+**查询参数：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `hours` | int | 24 | 查询最近多少小时的数据 |
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "hostname": "web-server-01",
+      "cpu": { "usage_percent": 45.2 },
+      "memory": { "usage_percent": 53.1 },
+      "reported_at": "2025-06-18T10:30:00Z"
+    }
+  ]
+}
+```
+
+---
+
+### Agent 告警规则
+
+#### GET /agent/rules — 规则列表
+
+获取所有 Agent 告警规则。
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "id": 1,
+      "name": "CPU 使用率过高",
+      "metric": "cpu.usage_percent",
+      "condition": ">",
+      "threshold": 80,
+      "hostname": "*",
+      "enabled": true,
+      "created_at": "2025-06-18T10:00:00Z"
+    }
+  ]
+}
+```
+
+#### POST /agent/rules — 创建规则
+
+创建一条 Agent 告警规则。
+
+**请求体：**
+```json
+{
+  "name": "CPU 使用率过高",
+  "metric": "cpu.usage_percent",
+  "condition": ">",
+  "threshold": 80,
+  "hostname": "*"
+}
+```
+
+#### POST /agent/rules/quick-setup — 一键创建默认规则
+
+一键创建默认告警规则（CPU / 内存 / 磁盘 / 网络，阈值 80%），作用于所有在线主机。
+
+**请求体：** 无（可选传空 JSON `{}`）
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "默认规则创建成功",
+  "data": {
+    "created": 4
+  }
+}
+```
+
+默认创建的规则包括：
+
+| 规则名称 | 指标 | 条件 | 阈值 |
+|----------|------|------|------|
+| CPU 使用率过高 | `cpu.usage_percent` | `>` | 80 |
+| 内存使用率过高 | `memory.usage_percent` | `>` | 80 |
+| 磁盘使用率过高 | `disk.usage_percent` | `>` | 80 |
+| 网络带宽过高 | `network.total_bytes` | `>` | 80 |
+
+#### PUT /agent/rules/:id — 更新规则
+
+更新指定告警规则。
+
+#### DELETE /agent/rules/:id — 删除规则
+
+删除指定告警规则。
+
+---
+
+### Agent 告警事件
+
+#### GET /agent/alerts — 告警事件列表
+
+获取 Agent 触发的告警事件列表。
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "list": [
+      {
+        "id": 1,
+        "rule_id": 1,
+        "rule_name": "CPU 使用率过高",
+        "hostname": "web-server-01",
+        "metric": "cpu.usage_percent",
+        "value": 92.5,
+        "threshold": 80,
+        "status": "firing",
+        "fired_at": "2025-06-18T10:30:00Z",
+        "resolved_at": null
+      }
+    ],
+    "total": 1
+  }
+}
+```
+
+#### POST /agent/alerts/:id/resolve — 恢复告警
+
+手动将指定告警事件标记为已恢复。
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "告警已恢复",
+  "data": null
+}
+```
+
+---
+
+### Agent 远程任务
+
+#### POST /agent/tasks — 下发远程任务
+
+向指定主机下发远程任务（如执行脚本、重启服务等）。
+
+**请求体：**
+```json
+{
+  "hostname": "web-server-01",
+  "command": "systemctl restart nginx",
+  "description": "重启 Nginx 服务",
+  "timeout_seconds": 30
+}
+```
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "任务已下发",
+  "data": {
+    "task_id": "550e8400-e29b-41d4-a716-446655440000",
+    "status": "pending"
+  }
+}
+```
+
+#### GET /agent/tasks — 任务列表
+
+获取所有远程任务的列表（支持分页和筛选）。
+
+**查询参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `hostname` | string | 按主机名筛选 |
+| `status` | string | 按状态筛选：`pending`、`running`、`success`、`failed` |
+| `page` | int | 页码 (默认 1) |
+| `page_size` | int | 每页数量 (默认 20) |
+
+#### GET /agent/tasks/:id — 任务详情
+
+获取指定远程任务的详细信息及执行结果。
+
+#### GET /agent/tasks/poll?hostname=xx — Agent 拉取任务 (无需 JWT)
+
+Agent 主动轮询拉取分配给自己的待执行任务。
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "task_id": "550e8400-e29b-41d4-a716-446655440000",
+      "command": "systemctl restart nginx",
+      "timeout_seconds": 30
+    }
+  ]
+}
+```
+
+#### POST /agent/tasks/:task_id/result — Agent 回传结果 (无需 JWT)
+
+Agent 执行完任务后，回传执行结果。
+
+**请求体：**
+```json
+{
+  "status": "success",
+  "stdout": "nginx restarted successfully\n",
+  "stderr": "",
+  "exit_code": 0,
+  "duration_ms": 2500
+}
+```
+
+---
+
+### Agent K线聚合
+
+#### POST /agent/aggregate — 触发聚合
+
+手动触发 K 线数据聚合任务（通常由定时任务自动执行）。
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "聚合任务已触发",
+  "data": null
+}
+```
+
+#### GET /agent/kline — 查询 K 线
+
+查询主机性能指标的 K 线（聚合）数据。
+
+**查询参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `hostname` | string | 否 | 主机名，不传则返回所有主机 |
+| `metric` | string | 否 | 指标名，如 `cpu.usage_percent` |
+| `interval` | string | 否 | 聚合间隔：`1m`、`5m`、`15m`、`1h`、`1d` |
+| `from` | string | 否 | 起始时间 (ISO 8601) |
+| `to` | string | 否 | 结束时间 (ISO 8601) |
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "hostname": "web-server-01",
+      "metric": "cpu.usage_percent",
+      "timestamp": "2025-06-18T10:00:00Z",
+      "open": 45.0,
+      "high": 92.5,
+      "low": 40.0,
+      "close": 55.0,
+      "avg": 53.2,
+      "count": 60
+    }
+  ]
+}
+```
+
+---
+
+### Agent 二进制分发 (无需 JWT)
+
+提供 Agent 二进制文件及安装脚本的下载。
+
+#### GET /agent/arch — 版本信息 + 下载链接
+
+获取当前 Agent 版本信息及各架构对应的下载链接。
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "version": "v1.2.3",
+    "released_at": "2025-06-18",
+    "downloads": {
+      "linux_amd64": "/api/v1/agent/aiops-agent-linux-amd64",
+      "linux_arm64": "/api/v1/agent/aiops-agent-linux-arm64",
+      "darwin_arm64": "/api/v1/agent/aiops-agent-darwin-arm64"
+    },
+    "install_script": "/api/v1/agent/install.sh"
+  }
+}
+```
+
+#### GET /agent/aiops-agent-linux-amd64 — x86_64 二进制
+
+下载 Linux x86_64 架构的 Agent 二进制文件。
+
+响应为二进制流 (`Content-Type: application/octet-stream`)。
+
+#### GET /agent/aiops-agent-linux-arm64 — ARM64 二进制
+
+下载 Linux ARM64 架构的 Agent 二进制文件。
+
+响应为二进制流 (`Content-Type: application/octet-stream`)。
+
+#### GET /agent/aiops-agent-darwin-arm64 — macOS 二进制
+
+下载 macOS Apple Silicon (ARM64) 架构的 Agent 二进制文件。
+
+响应为二进制流 (`Content-Type: application/octet-stream`)。
+
+#### GET /agent/install.sh — 一键安装脚本
+
+下载 Agent 一键安装脚本。
+
+响应为 Shell 脚本文本 (`Content-Type: text/plain`)。