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