aiops/docs/client-agent/README.md

AIOps 客户端 Agent 设计说明

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

---

文档阅读路径

文档	适合读者	内容
README.md	产品、运维、架构人员	客户端 Agent 的定位、能力、链路和文件清单
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 服务、架构识别、安装/升级/卸载审计

---

运行链路

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 广播前端指标更新

任务链路：

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	插件化采集器	中间件、本地进程、业务脚本指标可动态扩展

---

验证清单

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 超过离线阈值后，后端能识别离线。