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

backend/internal/api/handlers/agent.go

@@ -74,7 +74,7 @@ func (h *AgentHandler) ReceiveReport(c *gin.Context) {
 		return
 	}
 
-	// 同步更新 servers 表的实时指标（通过 hostname 匹配）
+	// 同步更新 servers 表的实时指标（三级匹配：hostname → client IP → hostname LIKE）
 	diskAvg := avgDiskUsage(req.Disks)
 
 	// 计算硬件规格
@@ -84,19 +84,48 @@ func (h *AgentHandler) ReceiveReport(c *gin.Context) {
 	}
 	memMB := int64(req.Memory.TotalGB * 1024) // GB → MB
 
-	result := h.db.Model(&models.Server{}).
-		Where("hostname = ? OR ip = ?", req.Hostname, req.Hostname).
-		Updates(map[string]interface{}{
-			"cpu_usage":     req.CPU.UsagePercent,
-			"memory_usage":  req.Memory.UsagePercent,
-			"disk_usage":    diskAvg,
-			"cpu":           req.CPU.CoreCount,
-			"memory":        memMB,
-			"disk":          int64(totalDiskGB),
-			"status":        "running",
-			"agent_status":  "online",
-			"agent_version": req.AgentVersion,
-		})
+	clientIP := c.ClientIP()
+
+	// 三级匹配：优先用 Agent 上报的 IP，其次用请求源 IP，最后用报文的 hostname
+	matchIP := req.IP
+	if matchIP == "" {
+		matchIP = clientIP
+	}
+
+	// 直接 SQL 更新，避免 GORM soft delete 自动添加 deleted_at 条件干扰
+	updateSQL := `UPDATE servers SET 
+		cpu_usage = ?, memory_usage = ?, disk_usage = ?,
+		cpu = ?, memory = ?, disk = ?,
+		status = ?, agent_status = ?, agent_version = ?,
+		hostname = CASE WHEN hostname != ? AND ip = ? THEN ? ELSE hostname END,
+		updated_at = NOW()`
+	args := []interface{}{
+		req.CPU.UsagePercent, req.Memory.UsagePercent, diskAvg,
+		req.CPU.CoreCount, memMB, int64(totalDiskGB),
+		"running", "online", req.AgentVersion,
+		// CASE WHEN hostname != ? AND ip = ? THEN ? ELSE hostname END
+		req.Hostname, matchIP, req.Hostname,
+	}
+	if req.System != nil && req.System.OSVersion != "" {
+		updateSQL += ", os = ?"
+		args = append(args, req.System.OSVersion)
+	}
+	updateSQL += " WHERE hostname = ? OR ip = ?"
+	args = append(args, req.Hostname, matchIP)
+
+	result := h.db.Exec(updateSQL, args...)
+
+	// 如果 hostname 和 IP 都没匹配到，尝试用 hostname 反向匹配 IP 字段
+	if result.RowsAffected == 0 && req.Hostname != matchIP {
+		updateSQL2 := updateSQL + " OR ip = ?"
+		args2 := append(args, req.Hostname)
+		result = h.db.Exec(updateSQL2, args2...)
+	}
+
+	// 如果还是没匹配到，记录日志（Agent 上报了，但服务器列表里没有对应条目）
+	if result.RowsAffected == 0 {
+		fmt.Printf("[agent] 上报主机 %q (IP: %s) 未匹配任何 servers 条目，指标仅写入 agent_reports 表\n", req.Hostname, matchIP)
+	}
 
 	// WebSocket 广播：向所有前端客户端推送该主机的最新指标 // Logan.Li
 	if h.hubMetrics != nil && result.RowsAffected > 0 {
@@ -154,10 +183,11 @@ func (h *AgentHandler) writeHotMetric(c *gin.Context, key string, value float64,
 	_ = h.cache.ZRemRangeByScore(ctx, key, "-inf", fmt.Sprintf("%.0f", cutoff))
 }
 
-// GetLatestReports 获取各主机最新上报
+// GetLatestReports 获取各主机最新上报（仅 3 分钟内活跃的 hostname）
 // GET /api/v1/agent/latest
 func (h *AgentHandler) GetLatestReports(c *gin.Context) {
 	var results []models.AgentLatestResponse
+	threeMinAgo := time.Now().Add(-3 * time.Minute)
 	h.db.Raw(`
 		SELECT
 			a.hostname,
@@ -179,10 +209,13 @@ func (h *AgentHandler) GetLatestReports(c *gin.Context) {
 		LEFT JOIN servers s ON s.hostname = a.hostname
 		LEFT JOIN regions r ON r.id = s.region_id
 		WHERE a.id IN (
-			SELECT MAX(id) FROM agent_reports GROUP BY hostname
+			SELECT MAX(id) FROM agent_reports
+			WHERE report_time >= ?
+			GROUP BY hostname
 		)
+		AND s.id IS NOT NULL  -- 只显示匹配 servers 表的主机（首次上线后自动同步 hostname）
 		ORDER BY a.report_time DESC
-	`).Scan(&results)
+	`, threeMinAgo).Scan(&results)
 
 	if results == nil {
 		results = []models.AgentLatestResponse{}