Skip to main content

​
GET /api/overview

回傳整個機群的高層摘要，包括代理數量、威脅統計和啟用的策略版本。專為儀表板 UI 和監控整合設計。 
curl -X GET https://localhost:8443/api/overview \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "ok": true,
  "data": {
    "totalAgents": 12,
    "onlineAgents": 10,
    "staleAgents": 1,
    "offlineAgents": 1,
    "threatSummary": {
      "last24h": {
        "total": 47,
        "critical": 2,
        "high": 8,
        "medium": 15,
        "low": 22
      },
      "last7d": {
        "total": 234,
        "critical": 5,
        "high": 42,
        "medium": 89,
        "low": 98
      }
    },
    "activePolicyVersion": "v3",
    "topThreats": [
      { "type": "brute_force", "count": 52 },
      { "type": "port_scan", "count": 38 },
      { "type": "suspicious_process", "count": 21 }
    ],
    "agentsByOs": {
      "linux": 8,
      "darwin": 3,
      "win32": 1
    },
    "updatedAt": "2026-03-07T12:05:00.000Z"
  }
}

​
回應欄位

欄位類型說明
totalAgentsnumber已註冊的代理總數
onlineAgentsnumber有最近心跳的代理
staleAgentsnumber錯過心跳窗口但尚未離線的代理
offlineAgentsnumber超過逾時仍無法連線的代理
threatSummaryobject過去 24 小時和 7 天依嚴重程度的威脅計數
activePolicyVersionstring目前啟用的策略版本（例如 v3）
topThreatsarray機群中最頻繁的威脅類型
agentsByOsobject依作業系統分組的代理數量
updatedAtstring最後資料更新的 ISO 8601 時間戳

​
代理狀態定義

代理在設定的逾時窗口內（預設：120 秒）已發送心跳。代理正常運作。
代理錯過了預期的心跳，但尚未超過離線閾值（預設：5 分鐘）。這可能表示網路問題或高負載。
代理在超過離線閾值後仍未發送心跳。它可能已停止、當機或機器無法連線。
使用此端點建立自訂儀表板或整合 Grafana 等監控工具。以合理的間隔（每 30—60 秒）進行輪詢以保持資料更新，而不會過度載入 API。

​
整合範例

以下是一個最小化的儀表板輪詢腳本： 
async function pollDashboard() {
  const response = await fetch('https://localhost:8443/api/overview', {
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' },
  });
  const { data } = await response.json();

  // Alert if any agents are offline
  if (data.offlineAgents > 0) {
    console.warn(`${data.offlineAgents} agent(s) offline`);
  }

  // Alert on critical threats
  if (data.threatSummary.last24h.critical > 0) {
    console.warn(`${data.threatSummary.last24h.critical} critical threat(s) in last 24h`);
  }
}

// Poll every 60 seconds
setInterval(pollDashboard, 60_000);
pollDashboard();
如需無需輪詢的即時更新，請改用 SSE 事件串流。