feat: 完善堡垒机与 Agent 智能运维能力

- 支持 Windows Agent 构建、安装脚本和统一上报协议 - 增强 RDP 剪贴板、虚拟盘和文件传输能力 - 新增 AIOps 上下文工具、告警 RCA trace 落库和回放接口 - 重构 docs 模块文档并补充终端、堡垒机、监控、AI Agent 设计
2026-07-05 23:49:36 +08:00
1 parent a9513c2056
commit e0d652d211
@@ -0,0 +1,183 @@
+# 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 超过离线阈值后，后端能识别离线。
@@ -0,0 +1,339 @@
+# 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，审计可查 |