签入版本

2026-10-20 21:53:26 +08:00
parent 5cc3da657c
commit b33799aa63
427 changed files with 32547 additions and 1 deletions
@@ -0,0 +1,76 @@
+# 6.17 服务器监控
+
+:::tip 概述
+服务器监控是无表模块：单接口聚合返回运行时、内存、磁盘、数据库连通、缓存模式与调度器健康。磁盘读取按平台分文件实现（windows/other build tags）。路由 GET /api/server/info（登录即可）。
+:::
+
+## 接口
+
+```text
+GET /api/server/info   登录即可，log "服务器监控-查询信息"
+权限：无 permission 节点（登录即可）
+```
+
+## 返回结构（ServerInfoRes）
+
+```text
+Server      hostname / goVersion / arch / numCPU / goroutines / uptime
+            （procStart 为包加载时刻）
+Mem         allocMB / totalAllocMB / sysMB / heapAllocMB / heapSysMB /
+            heapObjects / gccycles（runtime.ReadMemStats，MB 保留两位小数）
+Disk        平台分支实现：
+            windows（//go:build windows）：GetDiskFreeSpaceEx 读工作目录所在盘符
+                      （wd[:3] 如 "E:\"），返回 totalGB/freeGB/usedPercent
+            other（!windows）：syscall.Statfs
+Db          SELECT VERSION() 计时（pingMs）+ 版本号；
+            数据库不通不视为整体失败（版本留空，err 置 nil 返回）
+Cache       cache.UsingMemory() → {mode:"memory", connected:false}
+            否则 Redis PING → {mode:"redis", connected:true/false}
+Scheduler   调度器健康：统计 gcron 中 "job:" 前缀条目数（mounted）与
+            goframe_job status=1 计数（expected）；enabled=DaemonInit 已执行；
+            healthy = mounted >= expected（挂载失败或数据被外部改动会出现差值）
+```
+
+## 平台分支实现（文件组织示例）
+
+```text
+internal/logic/server_monitor.go            公共组装
+internal/logic/server_monitor_windows.go    //go:build windows —— GetDiskFreeSpaceEx
+internal/logic/server_monitor_other.go      //go:build !windows —— syscall.Statfs
+
+Go build tags 实现"同函数名、按平台选实现"——编译期裁剪，零运行时分支
+```
+
+## 调度器健康判定（运维关键）
+
+```text
+mounted  = gcron 中 "job:" 前缀条目数（实际挂载）
+expected = goframe_job status=1 计数（应该挂载）
+healthy  = mounted >= expected
+
+差值排查：
+  mounted < expected   部分任务挂载失败（cron 表达式无效？）
+                       或任务数据被外部改动（直接改库没走 API）
+  mounted > expected   摘除遗漏（API 路径应先摘除再处理）
+注意口径：daemonStatus.running 是 gcron 全部条目数（含 CleanTemp 等非任务条目），
+         Scheduler.mounted 只统计 "job:" 前缀——两处口径不同
+```
+
+## 运维用法
+
+```text
+日常巡检：GET /api/server/info 一眼看全（CPU 核数/内存/磁盘余量/DB/缓存/调度）
+磁盘告警阈值：usedPercent > 85% 关注
+内存观察：heapObjects 持续增长 + gccycles 低 → 疑似泄漏
+调度异常：healthy=false → 逐条核对任务 cron 与 status
+```
+
+## 排障
+
+| 症状 | 原因 |
+|------|------|
+| Disk 数据异常 | windows 读的是工作目录所在盘符（wd[:3]）——服务在哪个盘就读哪个盘 |
+| Db 版本为空 | 数据库不通（不视为整体失败的设计）；查 database 配置 |
+| Cache mode=memory | Redis 不可用已降级（限流/锁/黑名单退化单机语义） |
+| Scheduler healthy=false | 见上方差值排查；对照 /api/job/daemonStatus |
+| uptime 很长但内存高 | procStart 是包加载时刻——优雅重启才会重置 |