服务监控指南
在一个管理员界面中实时监视 GIIP 生态系统中运行的服务与 cron 脚本的状态、健康度和执行历史。用汇总仪表盘纵览整体态势，再通过列表、流程、触发器视图深入查看单个服务。
📋 概述
服务监控页面是用于观察 GIIP 生态系统中运行的 cron 脚本、代理工作进程和 Azure Function 实时状态的管理员控制台。它以表格形式列出每个服务最后上报的状态（运行中/正常/错误/未上报）、执行时间和遥测数据（成功、失败、跳过等），顶部的汇总卡片让你一眼掌握整体健康度。数据来自代理推送到时序存储（tKVS）的状态报告；此界面是运维人员判断“什么在运行、什么已停止”的管制界面。
⚠️ 此界面仅限管理员。 访问需要管理员级别
uLevel >= 70。低于该级别的用户将被重定向到首页。
🔍 界面构成
1. 顶部页头
- 页面标题/说明: “服务监控”（已本地化）及汇总说明。
- 视图切换按钮: 在 列表 / 流程 / 触发器 三种视图之间切换。
- 添加脚本 按钮（仅列表视图，giip #1307）: 打开注册新受监控脚本的弹窗。
- 刷新按钮: 立即重新加载服务状态（加载时图标旋转）。列表视图每 30 秒、流程与触发器视图每 60 秒自动刷新。
2. 汇总仪表盘
顶部 4 张卡片显示所有服务的汇总统计。
| 卡片 | 含义 |
|---|---|
| 总数（Total） | 受监控的服务/脚本总数 |
| 运行中（Running） | 当前处于 RUNNING 状态的服务数 |
| 正常（Healthy） | 以 IDLE（正常待机）上报的服务数 |
| 错误（Error） | 以 ERROR（失败/异常）上报的服务数 |
3. 列表视图（服务表）
每一行代表一个服务/脚本，点击可展开查看详情（子任务、指标）。
| 列 | 说明 |
|---|---|
| Script Name | 脚本/服务名称 |
| Migration | Azure Function 迁移状态（已完成/待迁移/无） |
| Hostname | 上报状态的主机 |
| Status | 状态徽章（RUNNING / IDLE / ERROR / UNKNOWN） |
| Last Execution | 最后执行时间 |
| Telemetry | 成功、失败、跳过、强制终止等执行指标 |
| Details | 展开（查看子任务与原始报告） |
每行右侧最多有两个操作图标（giip #1307 起明确区分）：
| 图标 | 文案 | 动作 | 适用对象 |
|---|---|---|---|
| 🚫（圆圈+X，琥珀色） | “从监控中移除” | 关闭 tServiceMonitorScript.enabled（软删除）。不会触碰 tKVS 遥测数据。 | 所有来自受监控脚本列表的行（包括没有 raw/ksn 的 UNKNOWN 行） |
| 🗑️（垃圾桶，红色） | “删除”（giip #1214） | 按 ksn 删除一条 tKVS 遥测记录。 | 仅限有 raw.ksn 的行（即确实收到过上报的行） |
⚠️ 这两个按钮是完全不同的功能。红色垃圾桶只删除一条遥测历史记录；要让脚本行本身从 界面消失（尤其是从未上报过的
UNKNOWN行），必须使用琥珀色的“从监控中移除”图标。这正是 giip #1214 时缺失的能力（当时无法移除UNKNOWN行），由本次改动（giip #1307）补齐。
4. 流程视图
可视化服务之间的依赖关系与数据流（ServiceMonitorFlow）——以流程图查看哪个服务连接到哪个服务。
5. 触发器视图
以表格显示已注册告警触发器(tKVSTrigger)的实时评估状态。批处理 SP dbo.pKVSCheckSchd 每5分钟(Azure Function KVSCheckSchdTimer,giip #2098)重新评估这些条件并刷新 ktChkDt,超出阈值且启用了 Mail 渠道的触发器会实际发送邮件。
列含义
| 列 | 含义 |
|---|---|
| 键(Key) | 监控对象标识符。ktype='lssn' 时为服务器(lssn)编号。 |
| 因子(Factor) | 监控指标名称(例如 DISKUSAGE、CPUUSAGE),与 tKVS 实际上报时使用的键相同。若此值为空,则永远无法与 tKVS 匹配,状态将永久显示为"未激活"(见下方状态徽章表)。 |
| 条件 | 格式为 kAttrib kLogic kVal(例如 Capacity gt 90 = "Capacity 值超过 90")。kAttrib='giipLogDate' 是特殊情况,比较"距最后一次上报经过的秒数"(例如 giipLogDate gt 600 = "10分钟以上无上报")。 |
| 最后上报 | 该键+因子组合最后一次在 tKVS 中收到真实数值的时间。- 表示最近2天内完全没有上报。 |
| 最后检查 | 批处理(pKVSCheckSchd)最后一次评估此触发器的时间(每5分钟刷新)。若此值过旧,说明批处理本身已停止,请先确认 KVSCheckSchdTimer(Azure Function)是否在运行。 |
| 通知渠道 | 该触发器启用的 Mail / SMS / Slack。Mail 会实际发送(giip #2098,复用 tEmailServerConfig 中的活动 SMTP 配置 + giipApiSendEmail)。SMS 仅显示,尚未接入发送网关,不会实际发送。Slack 仅在触发器自身配置了 Webhook(kSlackWebhook)时才会发送,截至 2026-09-07 尚无任何触发器配置了 Webhook。 Mail收件人决定规则(giip #2412): (1)若kMail非空且不为'-',则用该地址;(2)否则若该usn在tKVSTriggerDefaultMail中有注册默认地址,则用该默认地址;(3)两者均无则不发送,仅记录[WARN] no recipient for ktSn=...日志。kMailAct=0时无论上述条件如何均不发送。 |
| 状态 | 以下四种徽章之一。 |
状态徽章
| 徽章 | 条件 | 含义 |
|---|---|---|
| 正常(绿) | 有因子 + 有最近上报 + 条件未超出 | 运行正常,无需处理。 |
| 超期(红,闪烁) | 有因子 + 条件超出 | 真实异常信号,参见下方"处理示例"。 |
| 无数据(灰) | 有因子 + 最近2天无上报 | 监控对象本身未上报(可能是代理已停止)。 |
| 未激活(灰,变淡,默认隐藏) | 因子值为空 | 与 tKVS 的匹配条件本身不成立,是永远无法匹配的失效触发器定义。并非真实异常,默认从列表中隐藏,点击表格上方的"显示未激活触发器"即可查看(giip #2098)。如需清理,请在数据库中为该 tKVSTrigger 行填写 kfactor,或直接删除该行。 |
处理示例(条件组合 → 含义 → 处理)
| 键 | 因子 | 条件 | 状态 | 含义 | 处理 |
|---|---|---|---|---|---|
| 584 | DISKUSAGE | Capacity gt 90 | 超期(红) | lssn=584 服务器磁盘使用率超过90% | 登录该服务器(lssn 584)清理磁盘(日志/临时文件)或扩容。若 Mail 渠道已启用,邮件应已发送至 kMail。 |
| 2622 | CPUUSAGE | giipLogDate gt 600 | 超期(红) | lssn=2622 服务器的 CPUUSAGE 上报中断超过600秒(10分钟) | 检查该服务器上的代理(giipAgent)进程/调度器是否存活。 |
| (任意) | (任意) | (任意条件) | 无数据(灰) | 最近2天内该键+因子完全没有上报 | 先排查代理安装、网络、密钥问题。触发器定义本身也可能是过时的拼写错误(因子名不匹配)。 |
| (任意) | (空) | 条件看起来不完整 | 未激活(灰,变淡,默认隐藏) | 因子缺失导致永远无法匹配的失效定义 | 若确实需要监控,请补齐 kfactor 后重新配置;若不需要,直接从数据库中删除。 |
🛠️ 状态检查方法
- 进入页面后，先在顶部 汇总卡片 查看错误（Error）数量。
- 在 列表 视图中，查找状态徽章为
ERROR或UNKNOWN（无上报）的行。 - 点击该行展开，查看 Last Execution / Telemetry / 子任务 —— 最后执行时间过旧或失败指标偏高即为停机候选。
- 用 刷新 按钮重新加载最新报告，确认是否只是短暂延迟。
- 切换到 触发器 视图，交叉核对是否有超过预定周期（超时）的触发器。
💡 备注
- 状态值含义:
RUNNING=执行中，IDLE=正常待机（计入汇总的“正常”），ERROR=失败，UNKNOWN=近期无上报（代理未向 tKVS 推送状态）。 - 出现大量 UNKNOWN 通常意味着代理/脚本未上报遥测，而非服务已死亡——请先确认代理本身是否在运行。
- 自动刷新: 列表每 30 秒、流程/触发器每 60 秒自动刷新，因此数值可能周期性变化。
- 访问权限为 prop 模式，页面中硬编码
minLevel={70}，因此始终需要uLevel >= 70（与菜单配置无关）。
API 参考
本页面通过调度命令（经由 fetchAzureCommand）与后端通信。由于没有单独的 API 指南，此处记录要点。
状态轮询（tKVS）
| 命令 | 用途 | 后端 SP |
|---|---|---|
ApiServiceMonitorGetStatus | 获取受监控脚本的 tKVS 状态（RUNNING/IDLE/ERROR，30秒轮询） | pApiApiServiceMonitorGetStatusbyAK |
ApiServiceMonitorGetFlow | 获取流程视图的节点/边 | （流程用 SP） |
ApiServiceMonitorGetTriggerStatus | 获取触发器视图的各触发器执行情况 | pApiApiServiceMonitorGetTriggerStatusbyAK |
ApiServiceMonitorDelete | 按 ksn 删除列表视图中的一条服务状态记录（垃圾桶按钮，必须弹出确认框）。安全限制：仅当该行的 kFactor 属于服务监控 factor 时才删除，否则返回 403。载荷 { ksn }。(giip #1214) | pApiApiServiceMonitorDeletebyAK |
受监控脚本 CRUD（giip #1307，tServiceMonitorScript）
这份列表决定“某一行是否会显示在界面上”。此前硬编码在 useServiceStatus.ts 的 CRON_SCRIPTS
数组中，现已迁移到该表 + API，无需部署即可在界面中完成 CRUD。
| 命令 | 用途 | 后端 SP |
|---|---|---|
ApiServiceMonitorScriptList | 获取受监控脚本列表（enabled=1，按 sortOrder 排序）。载荷可为空（{}）。 | pApiApiServiceMonitorScriptListbyAK |
ApiServiceMonitorScriptAdd | 注册新脚本（“添加脚本”弹窗）。载荷 { scriptName(必填), category?, azureFunction?, migrationStatus? }。若存在同名的已移除脚本则重新启用（200），否则新建（201），若同名已处于启用状态则返回 409。 | pApiApiServiceMonitorScriptAddbyAK |
ApiServiceMonitorScriptDelete | 从监控中移除（琥珀色图标）。不触碰 tKVS，仅关闭 tServiceMonitorScript.enabled，因此 UNKNOWN（从未上报）的行也可以移除。载荷 { scriptId } 或 { scriptName }。 | pApiApiServiceMonitorScriptDeletebyAK |
- 响应为结果集数组形式（例如
[数据, 状态]），客户端读取第一个（数据）数组。 - 状态字段
RstVal = 200（List/Delete/重新启用）或201（Add 新建）表示成功；409表示已在监控中；401表示会话过期/未认证（需重新登录）。 - 未修改禁区（giipfaw
run.ps1）：giipApi 按命令名到 SP 名进行通用路由，因此只需在 giipdb 中新增 SP 即可生效，无需改动 giipfaw 代码（与 giip-1214 相同模式）。
故障排查
| 症状 | 原因 | 解决 |
|---|---|---|
| 打开即被弹回首页 | uLevel 低于 70 | 请使用管理员账户（级别 70+）登录。 |
| “会话过期”/401 错误 | 认证令牌过期或缺失 | 重新登录后点击刷新。 |
表格大部分显示 UNKNOWN | 代理/脚本未向 tKVS 上报状态 | 检查该代理是否运行及遥测上报路径。 |
| 大量灰色变淡的"未激活"行 | kfactor 为空,是永远无法匹配 tKVS 的失效触发器定义(正常现象,并非真实异常) | 默认隐藏。如需查看请点击上方"显示未激活触发器",然后在数据库中补齐 kfactor 或删除该行(giip #2098)。 |
| 存在"超期(红色)"触发器但没收到邮件 | kMailAct 未启用、kMail 和 usn 默认地址(tKVSTriggerDefaultMail)均为空,或批处理(KVSCheckSchdTimer)尚未评估到此触发器 | 先确认"最后检查"时间是否为最近(批处理是否在运行),确认"通知渠道"中显示 Mail。若 Mail 已显示但仍没收到邮件,请在数据库中同时核实 kMail 地址(触发器行)和 tKVSTriggerDefaultMail(对应 usn)。即使 kMail 为空,若 usn 默认地址存在,也会被用于兜底发送(giip #2412)。 |
| "通知渠道"显示 SMS/Slack 但没收到通知 | SMS 尚未接入发送网关;Slack 仅在触发器自身配置了 webhook 时才生效(截至 2026-09-07 尚无任何触发器配置) | 目前只有 Mail 渠道会实际发送。如需 SMS/Slack,请提交 giip issue 请求接入网关/webhook。 |
| 数值持续变化 | 30 秒/60 秒自动刷新正在运行 | 属正常现象。如需固定某一时刻，请自行截取数值。 |
| 顶部指南按钮（📖）不显示 | 指南映射未部署（旧版本） | 本指南部署并建立索引后即会显示。 |
UNKNOWN 行无法消失 | 点击了红色垃圾桶，但那只是删除 tKVS 记录，UNKNOWN 行（没有 ksn）原本就不会显示该按钮 | 请改用琥珀色“从监控中移除”图标（giip #1307）。 |
| “添加脚本”后仍不显示 | 同名脚本已处于启用状态，因此添加返回了 409 | 请检查列表中是否已存在同名脚本。 |
版本: 1.2
最后更新: 2026-09-07（giip #2098：触发器视图 UI 改进(隐藏失效触发器/明确告警渠道状态) + 告警批处理恢复）
源文件: giipv3/public/help/service-monitor.zh-CN.md