Logan.Li
e0d652d211
- 支持 Windows Agent 构建、安装脚本和统一上报协议 - 增强 RDP 剪贴板、虚拟盘和文件传输能力 - 新增 AIOps 上下文工具、告警 RCA trace 落库和回放接口 - 重构 docs 模块文档并补充终端、堡垒机、监控、AI Agent 设计
663 lines
14 KiB
Markdown
663 lines
14 KiB
Markdown
# 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`)。
|