docs: update README, API reference, dev-log, project structure with Agent monitoring + quick-alarm + latest fixes

- README.md: React 19, default pwd 123456, Docker Compose deploy, correct module list - api-reference.md: add Agent monitoring section (report/latest/rules/quick-setup/alerts/tasks/kline) - dev-log.md: new entry documenting hostname/IP fix, system collector, offline detection, quick alarm - project-structure.md: add agent/ directory, dev-log.md link, React 19
2026-06-18 16:11:13 +00:00
1 parent c51d0b8b8b
commit 4e3f8cb306
@@ -12,6 +12,7 @@
 | [数据库设计](./database-schema.md) | 数据模型和表结构 |
 | [开发规范](./development-guide.md) | 代码规范、Git 工作流 |
 | [部署指南](./deployment.md) | 生产环境部署 |
+| [开发日志](./dev-log.md) | 详细开发日志（按日期记录） |

 ## 设计文档

@@ -259,3 +259,404 @@
  "git_commit": "unknown"
 }
 ```
+
+## Agent 监控
+
+### POST /agent/report — Agent 上报指标 (无需 JWT)
+
+Agent 向服务端上报主机性能指标数据。
+
+**请求体：**
+```json
+{
+  "hostname": "web-server-01",
+  "cpu": {
+    "usage_percent": 45.2,
+    "cores": 8
+  },
+  "memory": {
+    "total_gb": 16,
+    "used_gb": 8.5,
+    "usage_percent": 53.1
+  },
+  "disk": [
+    {
+      "mount": "/",
+      "total_gb": 100,
+      "used_gb": 60,
+      "usage_percent": 60.0
+    }
+  ],
+  "network": {
+    "rx_bytes": 1024000,
+    "tx_bytes": 512000
+  },
+  "uptime_seconds": 864000
+}
+```
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "上报成功",
+  "data": null
+}
+```
+
+### GET /agent/latest — 各主机最新指标 (需 JWT)
+
+获取所有在线主机的最近一次上报指标。仅返回 3 分钟内活跃且匹配 servers 表的主机。
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "hostname": "web-server-01",
+      "cpu": { "usage_percent": 45.2 },
+      "memory": { "usage_percent": 53.1 },
+      "disk": [{"usage_percent": 60.0}],
+      "network": { "rx_bytes": 1024000, "tx_bytes": 512000 },
+      "uptime_seconds": 864000,
+      "reported_at": "2025-06-18T10:30:00Z"
+    }
+  ]
+}
+```
+
+### GET /agent/history/:hostname — 历史趋势 (?hours=N)
+
+查询指定主机在最近 N 小时内的指标历史数据。
+
+**查询参数：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `hours` | int | 24 | 查询最近多少小时的数据 |
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "hostname": "web-server-01",
+      "cpu": { "usage_percent": 45.2 },
+      "memory": { "usage_percent": 53.1 },
+      "reported_at": "2025-06-18T10:30:00Z"
+    }
+  ]
+}
+```
+
+---
+
+### Agent 告警规则
+
+#### GET /agent/rules — 规则列表
+
+获取所有 Agent 告警规则。
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "id": 1,
+      "name": "CPU 使用率过高",
+      "metric": "cpu.usage_percent",
+      "condition": ">",
+      "threshold": 80,
+      "hostname": "*",
+      "enabled": true,
+      "created_at": "2025-06-18T10:00:00Z"
+    }
+  ]
+}
+```
+
+#### POST /agent/rules — 创建规则
+
+创建一条 Agent 告警规则。
+
+**请求体：**
+```json
+{
+  "name": "CPU 使用率过高",
+  "metric": "cpu.usage_percent",
+  "condition": ">",
+  "threshold": 80,
+  "hostname": "*"
+}
+```
+
+#### POST /agent/rules/quick-setup — 一键创建默认规则
+
+一键创建默认告警规则（CPU / 内存 / 磁盘 / 网络，阈值 80%），作用于所有在线主机。
+
+**请求体：** 无（可选传空 JSON `{}`）
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "默认规则创建成功",
+  "data": {
+    "created": 4
+  }
+}
+```
+
+默认创建的规则包括：
+
+| 规则名称 | 指标 | 条件 | 阈值 |
+|----------|------|------|------|
+| CPU 使用率过高 | `cpu.usage_percent` | `>` | 80 |
+| 内存使用率过高 | `memory.usage_percent` | `>` | 80 |
+| 磁盘使用率过高 | `disk.usage_percent` | `>` | 80 |
+| 网络带宽过高 | `network.total_bytes` | `>` | 80 |
+
+#### PUT /agent/rules/:id — 更新规则
+
+更新指定告警规则。
+
+#### DELETE /agent/rules/:id — 删除规则
+
+删除指定告警规则。
+
+---
+
+### Agent 告警事件
+
+#### GET /agent/alerts — 告警事件列表
+
+获取 Agent 触发的告警事件列表。
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "list": [
+      {
+        "id": 1,
+        "rule_id": 1,
+        "rule_name": "CPU 使用率过高",
+        "hostname": "web-server-01",
+        "metric": "cpu.usage_percent",
+        "value": 92.5,
+        "threshold": 80,
+        "status": "firing",
+        "fired_at": "2025-06-18T10:30:00Z",
+        "resolved_at": null
+      }
+    ],
+    "total": 1
+  }
+}
+```
+
+#### POST /agent/alerts/:id/resolve — 恢复告警
+
+手动将指定告警事件标记为已恢复。
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "告警已恢复",
+  "data": null
+}
+```
+
+---
+
+### Agent 远程任务
+
+#### POST /agent/tasks — 下发远程任务
+
+向指定主机下发远程任务（如执行脚本、重启服务等）。
+
+**请求体：**
+```json
+{
+  "hostname": "web-server-01",
+  "command": "systemctl restart nginx",
+  "description": "重启 Nginx 服务",
+  "timeout_seconds": 30
+}
+```
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "任务已下发",
+  "data": {
+    "task_id": "550e8400-e29b-41d4-a716-446655440000",
+    "status": "pending"
+  }
+}
+```
+
+#### GET /agent/tasks — 任务列表
+
+获取所有远程任务的列表（支持分页和筛选）。
+
+**查询参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `hostname` | string | 按主机名筛选 |
+| `status` | string | 按状态筛选：`pending`、`running`、`success`、`failed` |
+| `page` | int | 页码 (默认 1) |
+| `page_size` | int | 每页数量 (默认 20) |
+
+#### GET /agent/tasks/:id — 任务详情
+
+获取指定远程任务的详细信息及执行结果。
+
+#### GET /agent/tasks/poll?hostname=xx — Agent 拉取任务 (无需 JWT)
+
+Agent 主动轮询拉取分配给自己的待执行任务。
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "task_id": "550e8400-e29b-41d4-a716-446655440000",
+      "command": "systemctl restart nginx",
+      "timeout_seconds": 30
+    }
+  ]
+}
+```
+
+#### POST /agent/tasks/:task_id/result — Agent 回传结果 (无需 JWT)
+
+Agent 执行完任务后，回传执行结果。
+
+**请求体：**
+```json
+{
+  "status": "success",
+  "stdout": "nginx restarted successfully\n",
+  "stderr": "",
+  "exit_code": 0,
+  "duration_ms": 2500
+}
+```
+
+---
+
+### Agent K线聚合
+
+#### POST /agent/aggregate — 触发聚合
+
+手动触发 K 线数据聚合任务（通常由定时任务自动执行）。
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "聚合任务已触发",
+  "data": null
+}
+```
+
+#### GET /agent/kline — 查询 K 线
+
+查询主机性能指标的 K 线（聚合）数据。
+
+**查询参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `hostname` | string | 否 | 主机名，不传则返回所有主机 |
+| `metric` | string | 否 | 指标名，如 `cpu.usage_percent` |
+| `interval` | string | 否 | 聚合间隔：`1m`、`5m`、`15m`、`1h`、`1d` |
+| `from` | string | 否 | 起始时间 (ISO 8601) |
+| `to` | string | 否 | 结束时间 (ISO 8601) |
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "hostname": "web-server-01",
+      "metric": "cpu.usage_percent",
+      "timestamp": "2025-06-18T10:00:00Z",
+      "open": 45.0,
+      "high": 92.5,
+      "low": 40.0,
+      "close": 55.0,
+      "avg": 53.2,
+      "count": 60
+    }
+  ]
+}
+```
+
+---
+
+### Agent 二进制分发 (无需 JWT)
+
+提供 Agent 二进制文件及安装脚本的下载。
+
+#### GET /agent/arch — 版本信息 + 下载链接
+
+获取当前 Agent 版本信息及各架构对应的下载链接。
+
+**响应：**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "version": "v1.2.3",
+    "released_at": "2025-06-18",
+    "downloads": {
+      "linux_amd64": "/api/v1/agent/aiops-agent-linux-amd64",
+      "linux_arm64": "/api/v1/agent/aiops-agent-linux-arm64",
+      "darwin_arm64": "/api/v1/agent/aiops-agent-darwin-arm64"
+    },
+    "install_script": "/api/v1/agent/install.sh"
+  }
+}
+```
+
+#### GET /agent/aiops-agent-linux-amd64 — x86_64 二进制
+
+下载 Linux x86_64 架构的 Agent 二进制文件。
+
+响应为二进制流 (`Content-Type: application/octet-stream`)。
+
+#### GET /agent/aiops-agent-linux-arm64 — ARM64 二进制
+
+下载 Linux ARM64 架构的 Agent 二进制文件。
+
+响应为二进制流 (`Content-Type: application/octet-stream`)。
+
+#### GET /agent/aiops-agent-darwin-arm64 — macOS 二进制
+
+下载 macOS Apple Silicon (ARM64) 架构的 Agent 二进制文件。
+
+响应为二进制流 (`Content-Type: application/octet-stream`)。
+
+#### GET /agent/install.sh — 一键安装脚本
+
+下载 Agent 一键安装脚本。
+
+响应为 Shell 脚本文本 (`Content-Type: text/plain`)。
@@ -1807,3 +1807,28 @@ cd ~/devops/aiops
  - 后端 `scripts/mock.go` 644 行（已废弃种子脚本），可考虑直接删除（mocks 已迁移到真实 API）
  - 前端 `services/api.ts` 752 行超 700 行硬上限，可按模块拆分（userApi/dashboardApi/serverApi... 各拆独立文件 barrel re-export），风险较高需谨慎
  - 回到 dev-log 早期建议：用户消息气泡中【平台实时数据】块可折叠展示
+
+
+## 2026-06-18 Agent 监控指标上报修复 + 一键报警 + 品牌统一
+
+### 诊断与修复
+- **Agent hostname 与 servers 表不匹配导致指标更新静默失败**: ReceiveReport 原 WHERE 两参数都填 agent hostname，hostname 不匹配任何 server → RowsAffected=0 → 静默失败（agent_reports 有数据但 servers 不更新）
+  - 修复: Agent 启动时探测本机 IP（net.Dial("udp")）在 JSON 中含 ip 字段；后端用 req.IP 作 OR ip 匹配
+  - 修复: 改用 h.db.Exec() 原始 SQL 避免 GORM soft-delete 自动条件干扰
+- **Agent 未采集系统信息导致 servers.os 为空**: 新建 agent/collector/system.go（读 /etc/os-release PRETTY_NAME + /proc/version kernel），启动采集并前 3 次上报携带
+- **告警引擎离线检测以 agent_reports hostname 为中心而非 servers IP**: 同一服务器可能有多个 hostname 交替上报，旧 hostname 超 3 分钟触发离线告警但服务器实际在线
+  - 修复: checkOfflineAlerts 改为以 servers IP 为中心 — 遍历服务器 IP，检查 3 分钟内是否有任何 agent 对应该 IP → 有则在线
+- **Agent latest API 过滤过期 hostname**: GetLatestReports SQL 添加 WHERE report_time >= NOW() - 3 MINUTE + AND s.id IS NOT NULL 双重过滤，监控大屏不再显示离线/过期主机
+- **主机名自动同步**: ReceiveReport 发现 hostname 不匹配但 IP 匹配时，CASE WHEN 自动更新 servers 表 hostname 字段
+
+### 一键报警
+- 后端新增 POST /api/v1/agent/rules/quick-setup 接口
+- 自动检测所有 agent_status=online 的主机
+- 为每台主机创建 CPU使用率（Warn）/内存使用率（Warn）/磁盘使用率（Warn）/网络带宽使用率（Warn）4 条默认规则（阈值 80%）
+- 前端 AlertCenter 规则列表从 agentApi.listRules() 拉取（之前调 alertCenterApi.getRules() 走的空路由）
+- 规则切换/删除/编辑 全部对接 agentApi
+
+### 品牌统一
+- EZOps → AIOps 全局替换: frontend/backend/agent/scripts 全量扫描替换
+- 小写 ezops（Go module path/launchd plist/JWT secret）保留不改避免破坏编译/运行时
+- WebShell 欢迎语/Login 标题/LLM system prompt 全部统一为 AIOps
@@ -116,10 +116,22 @@ aiops/
 │   │   └── mock.go              # Mock 数据生成
 │   ├── config.yaml              # 配置文件（SQLite 默认）
 │   ├── go.mod                   # Go 模块定义
-│   └── Dockerfile               # Docker 构建
+│   ├── Dockerfile               # Docker 构建
+│
+├── agent/                       # 监控 Agent (Go, 独立 module ezops/agent)
+│   ├── main.go                  # CLI 入口 (-server/-interval/-token/-hostname)
+│   ├── collector/               # CPU/mem/disk/port/system 采集器 (/proc)
+│   ├── model/model.go           # 上报数据结构 (Report/CPUStat/MemStat/...)
+│   ├── model/model_ext.go       # 扩展类型 (NetworkStat/DiskIOStat/SystemStat)
+│   ├── reporter/http.go         # HTTP POST 上报
+│   ├── task/                    # 远程任务执行 (云助手模式)
+│   ├── deploy/                  # systemd service + install.sh 一键安装
+│   ├── Makefile                 # 交叉编译 amd64+arm64+darwin-arm64
+│   └── bin/                     # 编译产物 (gitignore)
 │
 ├── docs/                        # 开发文档
 │   ├── README.md                # 文档索引
+│   ├── dev-log.md               # 开发日志
 │   ├── project-structure.md     # 本文件
 │   ├── quick-start.md           # 快速开始
 │   ├── api-reference.md         # API 接口
@@ -144,7 +156,7 @@ aiops/

 | 技术 | 版本 | 用途 |
 |------|------|------|
-| React | 18+ | 前端框架 |
+| React | 19+ | 前端框架 |
 | TypeScript | 5+ | 类型安全 |
 | Vite | 7+ | 构建工具 |
 | Tailwind CSS | 3+ | 样式框架 |