11分鐘閱讀

服務監控指南

在單一管理員介面中即時監視 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-TW.md