服務模式自動發現指南
這是一個管理員畫面，用於顯示從網路/資料庫連線遙測資料(netstat、資料庫連線)中實際觀察到的應用程式與行程，並可一鍵將其啟用或停用為 Normal Service 模式。
📋 概觀
服務模式自動發現(Auto-Discovery) 頁面彙整了 giipAgent 所收集的網路連線(netstat)與資料庫連線(db_connections)遙測資料中實際觀察到的程式/行程名稱。它會標示每一項是否已在 Normal Service Patterns 頁面中註冊，未註冊的項目可一鍵新增為模式。在此頁面啟用的模式會用於在 Network Topology(sql3d)頁面中，將符合的用戶端顯示為青色(天藍色)。
⚠️ 此頁面僅限管理員使用。 存取需要
uLevel >= 50(程式碼中硬編碼的 prop 模式數值)。低於此層級的使用者會被重新導向至首頁。
🔍 畫面結構
1. 頂部標題列
- 頁面標題: 「✨ Auto-Discovery: Service Patterns」。
- 說明文字: 發現的應用程式來自基礎設施中實際的網路/資料庫連線，點擊 Enable 即可將其新增為 Normal Service 模式。
2. 命令列
| 元素 | 說明 |
|---|---|
| 🔄 Refresh 按鈕 | 從伺服器重新載入發現清單。 |
| 搜尋框 | 依 pattern_value(應用程式/行程名稱)即時篩選清單。 |
| 📋 Manage Patterns 按鈕 | 跳轉到 /admin/service-patterns 頁面直接管理已註冊模式。 |
3. 發現清單表格
| 欄位 | 說明 |
|---|---|
| Application/Process | 觀察到的程式名稱(program)或行程名稱(process) |
| Type | program(來自資料庫連線)或 process(來自 netstat)標籤 |
| Seen Count | 觀察到的次數(occurrence_count) |
| Status | ✅ Pattern(已註冊)或 Not enabled(未註冊) |
| Action | 未註冊顯示 Enable，已註冊顯示 Disable 按鈕 |
表格底部顯示發現總數，以及其中已啟用(已註冊)的數量。
🛠️ 如何啟用/停用模式
- 在清單中找到目標應用程式/行程(可用搜尋框縮小範圍)。
- 若顯示 未註冊(Not enabled)，點擊 Enable — 會立即將其新增為目前專案(csn)範圍內的 Normal Service 模式。
- 若顯示 已註冊(✅ Pattern)，點擊 Disable — 將該模式停用(軟刪除)。
- 請求處理期間，所有 Enable/Disable 按鈕會暫時停用；完成後頂部會顯示成功訊息，清單會自動重新整理。
- 條件: Disable 僅適用於從此頁面註冊的(同一 csn 擁有的)模式。全域模式(csn=0)或其他專案擁有的模式須遵循 Manage Patterns 頁面的權限規則。
💡 補充說明
- 發現資料優先使用最近 30 分鐘內收集的
tKVS(netstat/db_connections)紀錄。若該時段內完全沒有收集到資料(例如新專案、未安裝代理程式、測試環境)，頁面會改為不限時間顯示最近 50 筆紀錄作為備援。 - 清單會排除
unknown、System、Idle等無意義的值。 - 發現清單僅彙整屬於目標 csn 的伺服器(
tLSvr.CSn)的資料。伺服器必須安裝 giipAgent 並傳送 netstat/資料庫連線遙測資料，其行程才會出現在此清單中。 - Enable/Disable 透過 giipfaw(Azure Function)→ SQL Server 立即生效，操作完成後清單會自動重新整理。
API 參考
此頁面透過三個派發命令(經由 fetchAzureCommand)與後端通訊。由於沒有獨立的 API 指南，核心內容記錄如下。
| 命令 | 用途 | 主要參數 |
|---|---|---|
Net3dServicePatternDiscovery | 列出從 tKVS netstat/db_connections 發現的程式/行程(含註冊狀態) | csn |
Net3dServicePatternPut | 將發現的項目註冊為 Normal Service 模式(啟用) | csn、nspId(新建為 0)、pattern_type、pattern_value、display_name |
Net3dServicePatternDelete | 停用已註冊模式(軟刪除) | csn、nspId |
- 三個命令都可能在回應中包含
RstVal狀態欄位。RstVal = 200表示成功，RstVal = 401表示驗證失敗(工作階段過期)，RstVal = 403表示對該專案無權限。 Net3dServicePatternDiscovery成功時回傳包含pattern_value、pattern_type、occurrence_count、is_registered、nspId欄位的列陣列。當結果剛好只有一列時，由於後端(PowerShellConvertTo-Json)的特性，可能回傳單一物件而非陣列——客戶端會對此進行正規化處理。
疑難排解
| 症狀 | 原因 | 解決方法 |
|---|---|---|
| 存取後立即被重新導向至首頁 | uLevel 低於 50 | 請使用管理員帳號(層級 50+)登入。 |
| "Unexpected token '<' ... is not valid JSON" 錯誤 | (2026-08-07 之前)前端呼叫了一個從未存在過的 Next.js API 路由(/api/service-patterns/discovery)——已在 giip-issue #938 中修正為直接呼叫 fetchAzureCommand | 目前部署不應再出現此問題。若仍出現，請確認部署版本是否為最新。 |
| "Unauthorized" 錯誤訊息 | 工作階段權杖過期或缺失 | 請重新登入後點擊 Refresh。 |
| "No applications discovered yet." | 目標專案(csn)所屬伺服器近期沒有 netstat/資料庫連線遙測資料 | 請確認伺服器已安裝並執行 giipAgent，收集到資料後再試一次。 |
| 沒有出現新項目 | 最近 30 分鐘內無資料，正在回退顯示最近 50 筆紀錄 | 屬正常行為。一旦最近 30 分鐘內累積了資料，頁面會切換到該範圍。 |
| 頂部指南按鈕(📖)不顯示 | 指南對應缺失(舊版本部署) | 此指南部署並建立索引後即會顯示。 |
版本: 1.0
最後更新: 2026-08-07
來源檔案: giipv3/public/help/service-patterns-discovery.zh-TW.md