aiops/docs/client-agent/implementation-spec.md

AIOps 客户端 Agent 实现规格

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

---

1. 最小可用闭环

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 命令行契约

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 请求

POST /api/v1/agent/report
Authorization: Bearer <token>
Content-Type: application/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 响应

{ "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. 后端处理规格

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. 必要时自动注册新资产。

离线判断：

latest_report_time < now - offline_threshold
  → agent_status = offline

建议阈值：

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

---

6. 任务轮询

6.1 Agent 拉取任务

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

响应：

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

后端规则：

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

6.2 Agent 回传结果

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

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

任务安全要求：

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

---

7. 安装和升级

安装链路：

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 服务要求：

[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，审计可查