物理/雲端伺服器列表指南
引導您如何查看並過濾 GIIP 平台管理的各種伺服器（包括物理 IDC 伺服器及公有雲虛擬機）庫存。
📋 概述
伺服器列表介面提供了所有計算資產的統一視圖。您可以在此即時確認各伺服器的運行狀態，快速搜索所需資產，並跳轉至詳情頁面。
🔍 核心功能與頁面構成
1. 整合篩選器與搜尋
- 專案篩選器: 僅篩選特定專案名下的伺服器。
- 狀態篩選器: 支援按
Running(運行中)、Stopped(已停止)、Warning(警告)、Unknown(未知) 狀態進行過濾。 - 搜尋欄: 可通過主機名 (Hostname) 或 IP 地址立即搜尋。
2. 代理狀態 (Agent Icon)
通過伺服器列表中的圖標顏色，直觀掌握代理的連接情況。
- 🟢 綠色: 連接正常，正即時收集指標。
- 🟡 黃色: 存在延遲（網絡不穩定）。
- 🔴 紅色: 連接斷開（需重啟代理）。
3. 資產屬性摘要
您可以直接在每行記錄中查看到作業系統版本、CPU 核心數、運行時長 (Uptime) 等核心規格。
🛠️ 操作欄 (Action Bar)
- 批量執行: 勾選多個伺服器後，點擊上方的 [執行指令] 按鈕，可同步進行包更新或重啟服務。
- 匯出 Excel: 將目前過濾後的伺服器列表匯出為 CSV 或 Excel 文件。
💡 技巧
- 利用標籤: 為伺服器分配
Web、DB、Staging等標籤，可以幫助您在列表中更快速地按用途分類。
API 參考
有關此功能的 API 詳細規格，請參閱單獨的指南。
疑難排解
| 症狀 | 原因 | 解決 |
|---|---|---|
| 伺服器圖標顯示為 🔴 紅色 | 代理連接斷開 | 在該伺服器上重啟代理 |
| 伺服器圖標顯示為 🟡 黃色 | 網絡不穩定導致的延遲 | 檢查網絡狀態並稍後重新確認 |
| 列表中找不到所需的伺服器 | 已套用專案/狀態篩選器或搜尋詞 | 重置篩選器或通過主機名/IP 地址搜尋 |
| 批量指令未套用到部分伺服器 | 目標伺服器的代理處於斷開狀態 | 僅勾選代理圖標為 🟢 綠色的伺服器後重新執行 |
🤖 將 AI Agent 註冊為 lsvr 的方法
本節提供一個完整可執行的流程，讓 AI 代理僅憑本文件就能把自己註冊進這個伺服器列表（lsvr）。請直接複製並執行以下指令（無需額外判斷或調查）。
前提條件
- 必須擁有目標 csn（專案）的 SK（Secret Key）。沒有 SK 則無法完成註冊 —— 請先在
/svclist（登入後的專案設定頁面）簽發/確認 SK。SK 的簽發流程本身不在本指南範圍內，詳情請參閱代理註冊與佇列 API 規格。
執行 —— curl
curl -X POST "https://giipfaw.azurewebsites.net/api/giipApiSk2" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "text=AgentAutoRegister hostname jsondata" \
--data-urlencode "jsondata={\"hostname\":\"<伺服器唯一主機名>\",\"os\":\"<OS 描述>\",\"agent_version\":\"<版本>\"}" \
--data-urlencode "token=<SK>"執行 —— PowerShell
$jsonData = '{"hostname": "<伺服器唯一主機名>", "os": "<OS 描述>", "agent_version": "<版本>"}'
$form = New-Object System.Collections.Specialized.NameValueCollection
$form.Add('text', 'AgentAutoRegister hostname jsondata')
$form.Add('token', '<SK>')
$form.Add('jsondata', $jsonData)
$wc = New-Object System.Net.WebClient
$wc.Encoding = [System.Text.Encoding]::UTF8
$resp = $wc.UploadValues('https://giipfaw.azurewebsites.net/api/giipApiSk2', 'POST', $form)
[System.Text.Encoding]::UTF8.GetString($resp)請務必將 <伺服器唯一主機名>、<OS 描述>、<版本>、<SK> 替換為實際值。hostname 為必填項，且在該 csn 內必須唯一。
解讀回應
HTTP 狀態碼始終為 200，因此必須依據回應 JSON 中的 data[0].RstVal 判斷是否成功。
RstVal | 意義 | 回應範例 |
|---|---|---|
200（新建） | 成功註冊為新伺服器，action: "new" | {"data":[{"Proc_MSG":"200|Server auto-registered successfully","lssn":71290,"action":"new","RstVal":200,"RstMsg":"Server auto-registered successfully"}]} |
200（已存在） | hostname 已存在 → 依心跳更新處理，action: "update" | {"data":[{"Proc_MSG":"200|Server updated successfully (heartbeat)","lssn":71290,"action":"update","RstVal":200,"RstMsg":"Server updated successfully (heartbeat)"}]} |
400 | 缺少 hostname | {"data":[{"Proc_MSG":"400|Hostname required","RstVal":400,"RstMsg":"Hostname required"}]} |
401 | SK 無效 | {"data":[{"Proc_MSG":"401|Unauthorized - Invalid SK","RstVal":401,"RstMsg":"Unauthorized - Invalid Secret Key"}]} |
註冊成功後，回應中的 lssn 就是該伺服器的唯一編號 —— 之後可用該 lssn 呼叫其他 giip API（例如佇列輪詢）。
冪等性（可安全重複呼叫）
重複呼叫相同請求（相同 hostname、相同 SK）是安全的 —— 首次呼叫會新建記錄（INSERT），此後每次呼叫都會作為心跳處理（UPDATE，刷新最後檢查時間）。因此該呼叫也可直接複用於定期健康檢查/心跳用途。
選填欄位（用於豐富庫存顯示）
可在 jsondata 中追加以下欄位（均為選填，缺省也能註冊成功）：
| 欄位 | 型別 | 說明 |
|---|---|---|
os | string | OS 描述 |
kernel | string | 核心版本 |
cpu | string | CPU 型號 |
cpu_cores | number | CPU 核心數 |
memory_gb | number | 記憶體（GB） |
disk_gb | number | 磁碟（GB） |
agent_version | string | 代理／用戶端版本字串 |
ipv4_global | string | 公網 IPv4 |
ipv4_local | string | 內網 IPv4 |
network | array | [{"name":"eth0","ipv4":"...","mac":"..."}] |
software | array | [{"name":"nginx","version":"1.18.0","vendor":"Ubuntu","type":"DEB"}] |
services | array | [{"name":"nginx","status":"running","start_type":"enabled","port":80}] |
依代理類型的顯示與命名規則（自助註冊約定）
⚠️ 概念變更（2026-09-12）：LSvr（lssn）指的是「一個代理（角色）」，而不是「一台PC」。 同一台實體PC上若運行多個代理，就會相應產生多個不同的 lssn —— 例如同一台PC（
Lowy-DP01）上，Windows 監控代理（giipAgentWin，lssn=71197）與 gissue 自動處理排程器（hostnameLowy-DP01-gissue-hourly-scheduler，lssn=71291）分別以兩個互不相同的 LSvr 註冊。切勿假設存在單一的「這台PC的 lssn」，務必始終明確「這是哪個代理／角色的 lssn」。
lsvrlist 現在不僅顯示實體 giipAgent，還會同時呈現多種代理類型。當 AI 僅憑本文件進行自助註冊時，遵循以下約定即可僅透過 hostname 與 agent_version 就分辨出「哪台機器的 · 哪個工具（模型/版本）· 以何種執行模式」在運行。
代理類型（3 種）
| 類型 | 適用對象 | agent_version 範例 |
|---|---|---|
giipAgentWin | Windows 實體機/虛擬機代理 | giipAgentWin 5.3.1 |
giipAgentLinux | Linux 實體機/虛擬機代理 | giipAgentLinux 2.4.0 |
AI | AI 程式設計/作業代理（Claude Code、GPT 等） | claude-opus-4-8（模型 ID） |
hostname 命名規則 — <機器>-<工具slug>[-<執行模式>]
- 機器: 實際的主機/PC 名稱（例:
Lowy-DP01） - 工具slug: 用於識別代理的小寫連字號 slug（例:
claude-code、giipagentwin、gissue-hourly-scheduler） - 執行模式（可選）:
console（常駐主控台工作階段）·scheduler（cron/排程器驅動）·service（OS 服務/常駐程式） - 實測範例:
Lowy-DP01-claude-code（以主控台執行的 AI）、Lowy-DP01-gissue-hourly-scheduler（以排程器執行的 AI）
建議依類型標註「模型 - 版本 - 執行模式」
| 項目 | giipAgentWin / giipAgentLinux | AI |
|---|---|---|
agent_version | "<類型> <版本>"（例: giipAgentWin 5.3.1） | 模型 ID（例: claude-opus-4-8、gpt-5） |
os | 實際 OS（例: Windows Server 2022、Ubuntu 22.04） | 執行 OS + 工具（例: Windows 10 / Claude Code） |
| 執行模式 | hostname 後綴（例: -service） | hostname 後綴（例: -console、-scheduler） |
依此約定註冊後，即可僅透過 hostname 與 agent_version 區分每一列的類型、模型/版本與執行模式 —— 例: AI · claude-opus-4-8 · scheduler、giipAgentWin · 5.3.1 · service。
AI 自助註冊範例（以排程器執行的 Claude Code）
{"hostname":"Lowy-DP01-claude-code-scheduler","os":"Windows 10 / Claude Code","agent_version":"claude-opus-4-8"}註冊完成後，可在🏢 伺服器列表頁面中搜尋剛註冊的 hostname，它將作為新 lsvr 出現在列表中。
關於註冊 → 佇列輪詢 → 結果回報的完整流程，請參閱代理註冊與佇列 API 規格。
版本: 1.1
最後更新: 2026-09-10
源文件: giipv3/public/help/lsvrlist.zh-TW.md