# 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`)。