aiops/docs/reference/api-reference.md

API 接口文档

基础信息

项目	值
Base URL	http://localhost:8080/api/v1
认证方式	JWT Bearer Token
请求格式	JSON
响应格式	JSON

通用响应结构

{
  "code": 200,
  "message": "success",
  "data": {}
}

分页响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "list": [],
    "total": 100
  }
}

认证

POST /auth/login

用户登录，获取 JWT Token。

请求体：

{
  "username": "admin",
  "password": "admin123"
}

响应：

{
  "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

无需认证。

{
  "status": "ok"
}

GET /version

无需认证。

{
  "version": "dev",
  "build_time": "unknown",
  "git_commit": "unknown"
}

Agent 监控

POST /agent/report — Agent 上报指标 (无需 JWT)

Agent 向服务端上报主机性能指标数据。

请求体：

{
  "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
}

响应：

{
  "code": 200,
  "message": "上报成功",
  "data": null
}

GET /agent/latest — 各主机最新指标 (需 JWT)

获取所有在线主机的最近一次上报指标。仅返回 3 分钟内活跃且匹配 servers 表的主机。

响应：

{
  "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	查询最近多少小时的数据

响应：

{
  "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 告警规则。

响应：

{
  "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 告警规则。

请求体：

{
  "name": "CPU 使用率过高",
  "metric": "cpu.usage_percent",
  "condition": ">",
  "threshold": 80,
  "hostname": "*"
}

POST /agent/rules/quick-setup — 一键创建默认规则

一键创建默认告警规则（CPU / 内存 / 磁盘 / 网络，阈值 80%），作用于所有在线主机。

请求体： 无（可选传空 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 触发的告警事件列表。

响应：

{
  "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 — 恢复告警

手动将指定告警事件标记为已恢复。

响应：

{
  "code": 200,
  "message": "告警已恢复",
  "data": null
}

---

Agent 远程任务

POST /agent/tasks — 下发远程任务

向指定主机下发远程任务（如执行脚本、重启服务等）。

请求体：

{
  "hostname": "web-server-01",
  "command": "systemctl restart nginx",
  "description": "重启 Nginx 服务",
  "timeout_seconds": 30
}

响应：

{
  "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 主动轮询拉取分配给自己的待执行任务。

响应：

{
  "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 执行完任务后，回传执行结果。

请求体：

{
  "status": "success",
  "stdout": "nginx restarted successfully\n",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 2500
}

---

Agent K线聚合

POST /agent/aggregate — 触发聚合

手动触发 K 线数据聚合任务（通常由定时任务自动执行）。

响应：

{
  "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)

响应：

{
  "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 版本信息及各架构对应的下载链接。

响应：

{
  "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",
      "windows_amd64": "/api/v1/agent/aiops-agent-windows-amd64.exe"
    },
    "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)。