# AIOps 客户端 Agent 实现规格

> 更新：2026-07-05
> 目标：让另一个项目仅阅读本文档，也能实现一个轻量主机采集 Agent 和后端接收链路。
> 范围：Linux 主机指标采集、HTTP 上报、后端入库、任务轮询、安装升级、验收标准。

---

## 1. 最小可用闭环

```text
Agent
  ├── collect CPU / memory / disk
  ├── build report JSON
  └── POST /api/v1/agent/report

Backend
  ├── validate token
  ├── insert agent_reports
  ├── update asset_servers latest metrics
  └── return { code: 200 }

Frontend
  └── query latest metrics and render host monitor
```

第一版必须完成：

| 能力 | 验收 |
|------|------|
| Agent 能启动 | `version` 和 `output` 正常 |
| 指标能上报 | 后端收到并入库 |
| 资产能关联 | hostname/IP 匹配到资产，未匹配时可自动注册 |
| 前端能展示 | 主机监控页面看到实时指标 |
| 离线能识别 | 超过阈值无上报后标记 offline |

---

## 2. Agent 命令行契约

```bash
aiops-agent version
aiops-agent output -top-n 5
aiops-agent -server http://aiops.example.com -token <TOKEN> -hostname <HOST> -interval 30
```

参数：

| 参数 | 默认 | 说明 |
|------|------|------|
| `-server` | 空 | 后端地址，run 模式必填 |
| `-token` | 空 | Agent 鉴权 token |
| `-hostname` | `os.Hostname()` | 主机标识，建议与资产 hostname 一致 |
| `-interval` | `10` | 采集间隔，生产建议 30-60 秒 |
| `-top-n` | `3` | 进程 TOP 数量 |

要求：

- `interval < 5` 应拒绝启动，避免高频上报压垮后端。
- 启动时加入随机 jitter，防止大量 Agent 同时上报。
- `output` 模式不需要 `server/token`，用于安装排障。

---

## 3. 上报协议

### 3.1 请求

```http
POST /api/v1/agent/report
Authorization: Bearer <token>
Content-Type: application/json
```

核心 JSON：

```json
{
  "hostname": "app-01",
  "ip": "10.0.0.11",
  "timestamp": "2026-07-05T10:00:00Z",
  "agent_version": "v2.1.0",
  "cpu": {
    "usage_percent": 12.3,
    "iowait": 0.4,
    "core_count": 8,
    "load1": 0.8,
    "load5": 0.7,
    "load15": 0.6
  },
  "memory": {
    "total_gb": 31.4,
    "used_gb": 12.0,
    "available_gb": 18.2,
    "cached_gb": 4.1,
    "swap_used_gb": 0.0,
    "usage_percent": 38.2
  },
  "disks": [
    {
      "mount": "/",
      "device": "/dev/vda1",
      "total_gb": 100,
      "used_gb": 42,
      "usage_percent": 42,
      "inode_usage_pct": 11
    }
  ],
  "ports": [
    { "port": 8080, "protocol": "tcp", "process": "aiops", "pid": 1234 }
  ],
  "network": {},
  "disk_io": {},
  "process_top": [],
  "fd": {},
  "context_switches": {},
  "heartbeat": {
    "version": "v2.1.0",
    "uptime_sec": 3600,
    "self_rss_mb": 18.5,
    "report_seq": 100
  }
}
```

### 3.2 响应

```json
{ "code": 200, "message": "ok" }
```

错误：

| HTTP | 场景 |
|------|------|
| 400 | JSON 格式错误或必填字段缺失 |
| 401 | token 无效 |
| 500 | 入库失败 |

---

## 4. 采集器规格

| 采集器 | Linux 来源 | 输出 |
|--------|------------|------|
| CPU | `/proc/stat`, `/proc/loadavg` | 使用率、IOWait、核心数、Load |
| Memory | `/proc/meminfo` | total/used/available/cached/swap |
| Disk | `statfs`, mount table | 挂载点容量、inode |
| Disk IO | `/proc/diskstats` | read/write bps、IOPS |
| Network | `/proc/net/dev`, `/proc/net/tcp*` | rx/tx、TCP 状态 |
| Port | `/proc/net/tcp*` + `/proc/<pid>/fd` | 监听端口和进程 |
| ProcessTop | `/proc/<pid>/stat`, `status`, `cmdline` | top N 进程 |
| FD | `/proc/sys/fs/file-nr` | allocated/max/usage |
| Context | `/proc/stat` | ctxt / intr 速率 |
| System | `/etc/os-release`, `uname`, `/proc/uptime` | OS/Kernel/Uptime |
| HealthProbe | 后端配置 | HTTP/TCP/CMD 探测结果 |

实现原则：

- 单个采集器失败不能影响整次上报。
- 采集错误写本地日志，不把错误堆进上报报文。
- 网络/磁盘速率类指标需要保存上一轮样本计算差值。
- 不要依赖 shell 命令做核心采集，优先读 `/proc` 和 Go 标准库。

---

## 5. 后端处理规格

```text
ReceiveReport(req)
  ├── parse timestamp
  ├── marshal complex fields to JSON string
  ├── insert AgentReport
  ├── match asset by hostname or IP
  ├── update latest metrics on asset_servers
  ├── if no match, auto register server
  ├── cache latest metrics in Redis if available
  ├── broadcast MetricsHub
  └── return success
```

资产匹配优先级：

1. Agent 上报 `hostname`。
2. Agent 上报 `ip`。
3. 请求来源 IP。
4. 必要时自动注册新资产。

离线判断：

```text
latest_report_time < now - offline_threshold
  → agent_status = offline
```

建议阈值：

| interval | offline threshold |
|----------|-------------------|
| 10s | 60s |
| 30s | 180s |
| 60s | 300s |

---

## 6. 任务轮询

### 6.1 Agent 拉取任务

```http
GET /api/v1/agent/tasks/poll?hostname=app-01
Authorization: Bearer <token>
```

响应：

```json
{
  "code": 200,
  "data": [
    {
      "task_id": "uuid",
      "hostname": "app-01",
      "type": "command",
      "command": "df -h",
      "timeout": 60
    }
  ]
}
```

后端规则：

- 只返回 `pending` 任务。
- 按创建时间升序。
- 拉取后原子更新为 `running`。
- 单次最多返回 5 个。

### 6.2 Agent 回传结果

```http
POST /api/v1/agent/tasks/:task_id/result
```

```json
{
  "exit_code": 0,
  "result": "Filesystem ...",
  "status": "success"
}
```

任务安全要求：

- 命令必须有超时。
- 输出必须截断，避免后端大字段膨胀。
- 任务执行应记录操作者、创建时间、开始时间、结束时间。
- 生产环境应接入命令策略或审批，尤其是 `script` 类型。

---

## 7. 安装和升级

安装链路：

```text
Frontend AgentWizard
  → backend AgentInstallHandler
  → SSH to target server
  → download aiops-agent binary / install.sh
  → write systemd unit
  → systemctl enable --now aiops-agent
  → detect version
  → write audit log
```

systemd 服务要求：

```ini
[Service]
ExecStart=/usr/local/bin/aiops-agent -server <SERVER> -token <TOKEN> -interval 30
Restart=always
RestartSec=5
```

安装验收：

1. `/usr/local/bin/aiops-agent version` 正常。
2. `systemctl status aiops-agent` active。
3. 后端 1 分钟内收到上报。
4. 资产 `agent_version` 更新。
5. 安装审计记录成功或失败原因。

---

## 8. 安全要求

| 风险 | 要求 |
|------|------|
| token 泄漏 | token 不写命令审计、不在前端明文展示 |
| 伪造上报 | token 必须校验，建议绑定 hostname/server_id |
| 命令任务滥用 | command/script 任务接入策略、审计、超时、输出截断 |
| 自动注册污染资产 | 自动注册要有去重策略和可信来源限制 |
| 高并发上报 | Agent jitter + 后端批量/缓存/限流 |
| 采集权限过大 | Agent 默认不需要 root；端口进程归属等能力可降级 |

---

## 9. 与 Redis/MySQL 主动采集的边界

客户端 Agent 第一职责是主机 OS 层采集，Redis/MySQL 第一职责是服务内部指标采集。即使两者部署在同一台机器，也应保持两条链路独立。// Logan.Li

| 能力 | 客户端 Agent | 后端中间件监控 |
|------|--------------|----------------|
| 发现 3306/6379 端口 | 可以，通过端口采集器 | 不负责端口发现 |
| 判断 TCP 是否可连 | 可以，通过健康探针 | 可以，连接失败则目标 offline |
| Redis INFO / DBSIZE | 不做 | 必须做 |
| MySQL SHOW GLOBAL STATUS | 不做 | 必须做 |
| 主机 CPU/内存/磁盘 | 必须做 | 不做 |
| 服务级 QPS/连接数/命中率 | 不做 | 必须做 |

如果要把 Redis/MySQL 指标下沉到 Agent，需要新增独立的 `middleware` 采集器和权限配置；当前设计不建议这么做，因为后端主动采集更便于集中管理凭据、采集间隔和告警策略。

---

## 10. 验收矩阵

| 场景 | 预期 |
|------|------|
| `output` 调试 | 打印完整指标，不访问后端 |
| 正常上报 | 后端写入 `agent_reports` |
| 资产匹配 | `asset_servers` 实时指标更新 |
| 自动注册 | 新 hostname 创建资产 |
| 网络断开 | Agent 记录失败并下轮重试 |
| 后端重启 | Agent 自动恢复上报 |
| 任务执行成功 | 状态 `success`，保存输出 |
| 任务超时 | 状态 `timeout`，进程被终止 |
| Agent 停止 | 超过阈值后标记 offline |
| 一键安装 | systemd 服务 active，审计可查 |