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