系統架構
Graylog REST API 深度整合 — 實作規格書
Arova Nexus — Phase 0 Product Definition ｜ 2026-03-31

版本： v1.0 ｜ 日期： 2026-03-26 ｜ 狀態： 待實作
關聯 PRD： IG-015 ~ IG-018 ｜ Phase： Phase 2
來源： OpenSpec change graylog-api-deep-integration

一、動機與範圍

1.1 為什麼需要這個變更

目前 Arova Nexus 與 Graylog 的整合僅限於 Webhook 被動接收告警（Graylog HTTP Notification → Nexus Incident），無法主動查詢原始 log、產出統計資料或進行 Incident 根因分析。Graylog 握有 95% 以上的原始資料（日均 2,500 萬筆 log），包含防火牆流量、AD 帳戶行為和基礎架構事件，是每日/週/月報表的核心資料來源。IT 維運人員在處理 Incident 時仍需切換到 Graylog 介面回溯 log，嚴重影響 MTTR。

1.2 變更內容

1.3 影響模組

模組 影響說明
Integration 新增 Graylog Connector（IG-015），擴展 Connector Framework
Incident IN-007 Incident 詳情頁新增「Log 分析」Tab
AI Copilot AIC-002 系統狀態查詢擴展支援 Graylog log 查詢
Analytics AN-009 排程報表新增 Graylog 統計資料源
Dashboard 新增防火牆和 AD 即時統計卡片

1.4 Graylog API 依賴

Graylog 部署在 10.20.92.201（16 核 / 32 GB RAM / 2 TB），透過 NetBird VPN 可從 Nexus 存取。Graylog REST API 在 port 9000 上提供，支援 Token 認證。日均處理約 2,500 萬筆 log，主要來自 PA-450 防火牆（佔 98%）和 Windows AD。建議建立專用 Reader 角色帳號，以最小權限原則取得 API Token。

二、技術設計

2.1 目標與非目標

Goals:

Non-Goals:

2.2 架構決策

D1：查詢即時執行 + 結果快取（而非定期全量同步）

選擇： Log 搜尋採用即時查詢 Graylog API，結果快取 5 分鐘；統計資料定期同步。

原因：

替代方案： 用 Graylog 的 Pipeline 將所有 log 轉發到 Nexus。但會增加 Nexus 儲存壓力，且重複 Graylog 的功能。

D2：Graylog 查詢語法直接透傳（而非抽象化）

選擇： Nexus 的 log 查詢介面直接使用 Graylog 查詢語法（Lucene-based）。

原因：

D3：Stream 權限由 Graylog 側控管

選擇： Nexus 的 Graylog Connector 使用特定使用者的 API Token，該使用者在 Graylog 的 Stream 存取權限決定 Nexus 可查詢的範圍。

原因：

D4：報表統計資料定期快取

選擇： 報表所需的統計資料（Top-N、histogram、stats）定期同步，Dashboard 讀取快取。

資料類型 快取頻率 原因
Dashboard 即時統計 每 5 分鐘 需接近即時
報表統計 每小時 用於日報/週報，不需高頻
告警歷史 每小時 趨勢分析用
Stream/系統健康 每 5 分鐘 監控用

D5：AI Copilot Log 查詢 — Tool-based 架構

選擇： 為 AI Copilot 新增 Graylog Search Tool，AI 負責將自然語言轉為查詢參數。

原因：

2.3 風險與緩解

Risk Mitigation
Graylog API 查詢過慢（大量 log 搜尋） 預設限制回傳 150 筆，支援分頁；UI 顯示查詢進度；超時 30 秒自動取消
Graylog API Token 權限過大 建議使用 Reader 角色的專用帳號；Nexus 設定頁面提示安全建議
Index rotation 導致歷史資料消失 報表查詢前先檢查 /api/system/indices/ranges，提示資料保留範圍
大量並發查詢影響 Graylog 效能 統計查詢結果快取 5 分鐘；同一查詢去重；Dashboard 查詢串行執行
Graylog 查詢語法學習門檻 AI Copilot 作為前端，自然語言查詢降低門檻；提供常用查詢範本

三、功能規格

3.1 Graylog Connector 連線管理

REQ-GC01：Graylog Connector 連線設定

系統 SHALL 在整合管理頁面提供 Graylog Connector 設定介面，IT 管理員可輸入 Graylog REST API 的連線資訊。

Scenario WHEN THEN
設定 Graylog API 連線 IT 管理員進入 設定 → 整合管理 → Connector 管理，點選 Graylog Connector 的「設定」 系統顯示設定表單，包含：API URL（必填，含 port 9000）、API Token（必填）、可存取 Stream 清單
連線測試成功 IT 管理員填入正確的 API URL 和 API Token，點選「測試連線」 系統呼叫 /api/system 端點，顯示「已連線」、Graylog 版本、Elasticsearch 狀態
連線測試失敗 IT 管理員填入錯誤的 API URL 或無效的 API Token，點選「測試連線」 系統顯示具體錯誤訊息（連線逾時 / 401 認證失敗 / DNS 無法解析）
Stream 權限驗證 連線測試成功 系統呼叫 /api/streams 取得該 Token 可存取的 Stream 清單，顯示在設定頁面供 IT 管理員確認

REQ-GC02：連線健康監控

Graylog Connector 的連線狀態 SHALL 納入整合管理的健康監控（IG-010）。

Scenario WHEN THEN
連線健康正常 IT 管理員查看整合管理頁面 Graylog Connector 顯示：連線狀態為「已連線」、Elasticsearch 健康（green/yellow/red）、最後成功查詢時間
連線異常通知 Graylog Connector 連續 3 次查詢失敗或 Elasticsearch 健康為 red 系統自動通知 IT 管理員

REQ-GC03：API Token 安全存儲

系統 SHALL 以加密形式存儲 Graylog API Token。

Scenario WHEN THEN
Token 存儲加密 IT 管理員儲存 Graylog Connector 設定 API Token 以 AES-256 加密存儲在資料庫，設定頁面僅顯示 Token 末 4 碼

3.2 Incident Log 回溯查詢與 AI Copilot

REQ-GS01：Incident Log 回溯查詢

系統 SHALL 在 Incident 詳情頁面提供 Graylog log 回溯查詢功能。

Scenario WHEN THEN
自動組裝查詢條件 IT 維運人員開啟 Incident 詳情的「Log 分析」Tab 系統自動依 Incident 的來源（source）和觸發時間（triggered_at），組裝 Graylog 查詢條件，搜尋事件前 30 分鐘到後 10 分鐘的 log
顯示查詢結果 查詢完成 結果以時間順序顯示 log 列表，每筆包含：timestamp、source、message、severity；預設回傳 150 筆，支援分頁載入更多
手動調整查詢 IT 維運人員修改查詢條件（時間範圍、關鍵字、Stream） 系統重新執行 Graylog API 查詢並更新結果
查詢逾時處理 Graylog API 查詢超過 30 秒未回應 系統顯示「查詢逾時，請縮小時間範圍或精確查詢條件」，取消當前查詢

REQ-GS02：AI Copilot Log 查詢

AI Copilot SHALL 能用自然語言查詢 Graylog log。

Scenario WHEN THEN
自然語言查詢轉換 使用者問「過去 1 小時 PA-450 的 deny log 有哪些？」 AI Copilot 將自然語言轉換為 Graylog 查詢（query=source:PA-450 AND action:deny, range=3600），執行查詢並回答結果摘要
Incident 情境查詢 使用者在 Incident 上下文中問「這個 Incident 發生前後有什麼異常 log？」 AI Copilot 自動參考 Incident 的來源和時間，查詢相關 log 並分析異常模式
AD 安全查詢 使用者問「TH-DCVer1 今天有哪些登入失敗紀錄？」 AI Copilot 查詢 Windows AD Stream（query=source:TH-DCVer1 AND EventID:4625, range=86400），回答失敗帳戶和次數
查詢結果摘要 AI Copilot 取得查詢結果 AI 自動分析結果，提供摘要（總筆數、異常模式、關鍵發現），而非僅列出原始 log

3.3 自動化報表資料源與 Dashboard

REQ-GR01：防火牆統計資料源

系統 SHALL 定期從 Graylog API 取得防火牆統計資料，供報表和 Dashboard 使用。

Scenario WHEN THEN
取得 allow/deny 統計 統計資料同步排程觸發 系統呼叫 /api/search/universal/relative/stats 取得指定時間範圍的 allow/deny 計數和比例
取得 deny 趨勢直方圖 統計資料同步排程觸發 系統呼叫 /api/search/universal/relative/histogram 取得 deny 按小時分布的趨勢資料
取得 Top-N 被阻擋 IP 統計資料同步排程觸發 系統呼叫 /api/search/universal/relative/terms 取得 Top 10 被阻擋的來源 IP

REQ-GR02：AD 安全統計資料源

系統 SHALL 定期從 Graylog API 取得 AD 安全統計資料。

Scenario WHEN THEN
取得登入成功/失敗統計 統計資料同步排程觸發 系統分別統計 EventID=4624（成功）和 EventID=4625（失敗）的計數
取得 Top 失敗帳戶 統計資料同步排程觸發 系統呼叫 terms API 取得 Top 5 登入失敗的帳戶名稱和次數
取得特權帳戶活動 統計資料同步排程觸發 系統查詢 EventID 4672/4728/4732 的特權帳戶操作紀錄

REQ-GR03：Dashboard 即時統計卡片

Dashboard SHALL 顯示從 Graylog 取得的即時統計資料。

Scenario WHEN THEN
防火牆統計卡片 IT 維運人員開啟 Dashboard 顯示：過去 24h allow/deny 比例圓餅圖、deny 趨勢線圖、當前小時 deny 數量
AD 登入統計卡片 IT 維運人員開啟 Dashboard 顯示：過去 24h 登入成功/失敗比例、失敗趨勢線圖、當前帳戶鎖定數
Log 量統計卡片 IT 維運人員開啟 Dashboard 顯示：今日 log 總量、與昨日比較、各 Stream 佔比

3.4 告警歷史與系統健康

REQ-GE01：告警歷史同步

系統 SHALL 從 Graylog API 取得歷史事件資料，整合到 Analytics 模組。

Scenario WHEN THEN
同步歷史事件 排程同步執行 系統呼叫 /api/events/search 取得歷史事件，存儲到 Nexus 本地資料庫
事件趨勢圖 IT 管理員進入 分析報表 → 告警趨勢 Graylog 歷史事件與 Webhook 即時告警合併顯示在趨勢圖中，標記不同來源

REQ-GE02：Stream 配置同步

系統 SHALL 從 Graylog API 取得 Stream 清單，在 Nexus 顯示資料來源概覽。

Scenario WHEN THEN
Stream 清單顯示 IT 管理員查看 Graylog Connector 詳情 顯示所有可存取的 Stream 清單，每個 Stream 顯示：名稱、描述、最後收到 log 的時間
Stream 資料量統計 IT 管理員查看 Stream 清單 每個 Stream 顯示過去 24h 的 log 數量，用於了解各資料來源的活躍程度

REQ-GE03：Graylog 系統健康監控

系統 SHALL 監控 Graylog 的系統健康狀態。

Scenario WHEN THEN
Elasticsearch 健康 健康檢查排程執行 系統呼叫 /api/system/indexer/cluster/health 取得 ES 叢集狀態（green/yellow/red），異常時通知 IT 管理員
處理速率監控 健康檢查排程執行 系統呼叫 /api/system/metrics 取得 Graylog 的 log 處理速率和佇列深度，異常時告警
日均 log 量追蹤 每日排程執行 系統呼叫 /api/count/total 記錄當日 log 總量，用於 KPI 追蹤和容量規劃

四、Graylog API 端點總覽

API 端點 用途 同步頻率 對應功能
GET /api/system 連線測試、版本驗證 手動 REQ-GC01
GET /api/streams Stream 清單同步 每天 REQ-GC01, REQ-GE02
GET /api/search/universal/absolute Incident log 回溯查詢 即時（按需） REQ-GS01
GET /api/search/universal/keyword 關鍵字搜尋 即時（按需） REQ-GS02
GET /api/search/universal/relative/stats 欄位統計 每 5 分鐘 REQ-GR01, REQ-GR02
GET /api/search/universal/relative/histogram 趨勢直方圖 每 5 分鐘 REQ-GR01
GET /api/search/universal/relative/terms Top-N 統計 每 5 分鐘 REQ-GR01, REQ-GR02
GET /api/events/search 歷史事件 每小時 REQ-GE01
GET /api/events/definitions 告警規則清單 每天 REQ-GE01
GET /api/system/indexer/cluster/health ES 健康 每 5 分鐘 REQ-GC02, REQ-GE03
GET /api/system/metrics 系統指標 每 5 分鐘 REQ-GE03
GET /api/count/total 日均 log 量 每小時 REQ-GE03

五、實作任務清單

5.1 Graylog Connector 基礎設施

5.2 Incident Log 回溯查詢

5.3 AI Copilot Log 查詢

5.4 自動化報表資料源

5.5 Dashboard 即時統計

5.6 告警歷史與系統健康

5.7 測試與文件

← 上一篇自訂報表功能設計 下一篇 →LibreNMS REST API 深度整合 — 實作規格書