# AIOps 客户端 Agent 设计说明

> 更新：2026-07-05
> 范围：`agent/` 独立 Go 模块、主机指标采集、HTTP 上报、远程任务轮询、安装升级。
> 说明：本文档描述的是部署在被管主机上的 **客户端 Agent**，不要与 [AI Agent / Agent CLI](../ai-agent/00-README.md) 混淆。// Logan.Li

---

## 文档阅读路径

| 文档 | 适合读者 | 内容 |
|------|----------|------|
| [README.md](./README.md) | 产品、运维、架构人员 | 客户端 Agent 的定位、能力、链路和文件清单 |
| [implementation-spec.md](./implementation-spec.md) | 后端、Agent、测试工程师 | 可复刻的采集器、上报协议、任务轮询、安装和验收规格 |

---

## 定位

AIOps 客户端 Agent 是安装在 Linux 主机上的轻量采集代理，负责把主机运行状态周期性上报给 AIOps 后端，并支持后端下发少量远程任务。

一句话：**客户端 Agent 解决“主机实时状态从哪里来”的问题；AI Agent 解决“如何用大模型自动排障和执行任务”的问题。**

| 维度 | 客户端 Agent | AI Agent / Agent CLI |
|------|--------------|----------------------|
| 目录 | `agent/` | `backend/pkg/agentcli/` + `frontend/src/components/aiops/` |
| 运行位置 | 被管主机 | AIOps 后端 |
| 核心职责 | 采集指标、上报心跳、轮询任务 | ReAct 推理、工具调用、AI 排障 |
| 数据来源 | `/proc`、`/sys`、netstat、健康探针 | LLM、SSH、K8s API、历史记忆 |
| 交互方式 | HTTP 定时上报 / 轮询 | WebSocket 对话流 |
| 风险边界 | 本机采集和任务执行 | AI 自动化执行和高危确认 |

---

## 当前能力

| 能力 | 状态 | 说明 |
|------|------|------|
| CPU / Load | 已完成 | 使用率、IOWait、核心数、1/5/15 分钟负载 |
| 内存 / Swap | 已完成 | 总量、已用、可用、缓存、Swap 使用 |
| 磁盘 | 已完成 | 按挂载点上报容量、使用率、inode 使用率 |
| 磁盘 IO | 已完成 | 读写速率、IOPS |
| 网络 | 已完成 | TCP 状态、网卡流量 |
| 端口发现 | 已完成 | 监听端口、协议、进程、PID |
| 进程 TOP | 已完成 | 按 CPU 排序的 TOP N 进程 |
| FD / 上下文切换 | 已完成 | 文件句柄、ctx/irq 速率 |
| 系统信息 | 已完成 | OS、Kernel、Uptime |
| 健康探针 | 已完成 | HTTP/TCP/CMD 探针结果 |
| 心跳 | 已完成 | Agent 版本、运行状态、上报序号、自身 RSS |
| 任务轮询 | 已完成 | 后端 pending 任务拉取、执行、回传结果 |
| 一键安装 | 已完成 | systemd 服务、架构识别、安装/升级/卸载审计 |

---

## 运行链路

```text
agent/main.go
  ├── 解析参数：server / token / hostname / interval / top-n
  ├── 初始化 collectors
  ├── 初始化 HTTP client / reporter
  ├── 启动 startup jitter
  ├── ticker: collectAndReport()
  └── ticker: poll tasks

collectAndReport()
  ├── collector.CPU / Mem / Disk / Network / Port / ...
  ├── 组装 model.Report
  ├── reporter.Send()
  ▼
POST /api/v1/agent/report
  ├── 写入 agent_reports
  ├── 同步 asset_servers 实时指标
  ├── 必要时自动注册资产
  └── WebSocket 广播前端指标更新
```

任务链路：

```text
Agent task client
  ├── GET /api/v1/agent/tasks/poll?hostname=<hostname>
  ├── executor 执行 command/script
  └── POST /api/v1/agent/tasks/:task_id/result
```

---

## 目录职责

| 路径 | 职责 |
|------|------|
| `agent/main.go` | CLI 参数、采集编排、上报循环、任务轮询 |
| `agent/collector/` | CPU、内存、磁盘、网络、端口、进程、FD、探针等采集器 |
| `agent/model/` | Agent 上报报文和各类指标结构 |
| `agent/client/` | 后端 HTTP 客户端，封装 baseURL、token、连接复用 |
| `agent/reporter/` | 上报器，负责序列化 `Report` 并 POST 后端 |
| `agent/task/` | 任务轮询客户端和本地命令执行器 |
| `agent/deploy/` | systemd 服务模板和安装脚本 |
| `backend/controller/agent.go` | 接收 Agent 上报、入库、更新资产、广播指标 |
| `backend/controller/agent_task.go` | Agent 任务创建、轮询、结果回传 |
| `backend/controller/agent_install.go` | 通过 SSH 安装/升级/卸载客户端 Agent |
| `frontend/src/components/agent/` | Agent 监控、告警、安装向导、主机详情 |

---

## 上报数据流向

| 数据 | 后端处理 |
|------|----------|
| `agent_reports` 原始上报 | 保存历史指标，用于查询和趋势 |
| `asset_servers` 实时字段 | 更新 CPU/内存/磁盘/Agent 状态，资产页和监控页使用 |
| Redis 热数据 | 可选缓存最近指标，减少高频查询压力 |
| MetricsHub | WebSocket 广播给前端实时图表 |
| 告警引擎 | 基于最新指标触发 CPU/内存/磁盘/网络/离线告警 |

---

## 与其他模块关系

| 模块 | 关系 |
|------|------|
| 资产管理 | Agent 自动注册主机，并同步实时指标到资产表 |
| 监控中心 | 主机监控大屏和图表主要消费 Agent 指标 |
| 告警中心 | 阈值告警、离线告警、端口/探针告警依赖 Agent 数据 |
| 自动化运维 | Agent 任务能力可承接轻量命令执行，但复杂远程执行仍建议走 SSH/脚本库 |
| 安全审计 | Agent 安装、卸载、升级写入操作审计 |
| AI Agent | AI Agent 可读取 Agent 指标作为排障上下文，但两者不是同一个进程 |

---

## 与中间件监控的边界

Redis / MySQL 当前由 AIOps 后端中间件监控主动直连采集，不通过客户端 Agent。客户端 Agent 不登录 Redis/MySQL，不执行 `INFO`、`DBSIZE`、`SHOW GLOBAL STATUS`、`SHOW GLOBAL VARIABLES`，因此不会与中间件监控重复采集服务内部指标。// Logan.Li

| 数据层级 | 采集方 | 示例指标 | 是否重复 |
|----------|--------|----------|----------|
| 主机资源 | 客户端 Agent | CPU、内存、磁盘、网络、FD、上下文切换 | 不重复 |
| 进程/端口存在性 | 客户端 Agent | `redis-server` 进程、6379 监听、`mysqld` 进程、3306 监听 | 与中间件可用性相邻，但语义不同 |
| 健康探针 | 客户端 Agent | TCP 6379/3306 连通性、HTTP/CMD 探针 | 可能与中间件在线状态有轻微重叠 |
| Redis 内部指标 | 后端中间件监控 | connected_clients、used_memory、qps、hit_rate、db_size、cluster_size | 不重复 |
| MySQL 内部指标 | 后端中间件监控 | Threads_connected、Threads_running、Slow_queries、QPS、buffer_hit_rate、max_connections | 不重复 |

建议展示口径：

- 资产/主机监控页展示 Agent 主机层指标。
- 中间件监控页展示 Redis/MySQL 服务层指标。
- 如果同一台主机既安装 Agent 又配置 Redis/MySQL 监控，前端可通过 IP/端口做关联展示，但不要把两套指标合并成同一类指标。
- 告警规则应按 `host`、`middleware` 两类指标源区分，避免同一个“不可用”事件重复通知。// Logan.Li

---

## 当前优化方向

| 优先级 | 方向 | 说明 |
|--------|------|------|
| P0 | Agent 鉴权增强 | 当前轮询/回传接口需要更严格的 Agent token 校验和主机绑定 |
| P0 | 任务安全边界 | command/script 任务应接入命令审计、超时、白名单或策略 |
| P1 | 指标保留策略 | 原始指标、聚合指标、冷热数据分层保存 |
| P1 | 安装包版本管理 | 前端展示当前版本、可用版本、升级结果和回滚建议 |
| P1 | 探针配置中心 | HTTP/TCP/CMD 探针从后端集中配置，Agent 只执行 |
| P2 | 多平台采集 | Windows/macOS 采集器独立实现，不污染 Linux `/proc` 采集逻辑 |
| P2 | 插件化采集器 | 中间件、本地进程、业务脚本指标可动态扩展 |

---

## 验证清单

```bash
cd agent
go build -o aiops-agent .
./aiops-agent version
./aiops-agent output -top-n 5
```

联调：

1. 后端启动后，使用 `./aiops-agent -server http://localhost:8080 -token <token> -interval 10`。
2. `POST /api/v1/agent/report` 返回成功。
3. `asset_servers` 对应主机 `agent_status=online`。
4. 监控页面能看到 CPU、内存、磁盘、网络指标。
5. 创建 Agent 任务后，Agent 能轮询、执行、回传结果。
6. 停止 Agent 超过离线阈值后，后端能识别离线。