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

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

一、動機與範圍

1.1 為什麼需要這個變更

目前 Arova Nexus 與 LibreNMS 的整合僅限於 Webhook 被動接收告警（LibreNMS → Nexus Incident），無法主動查詢設備資訊、即時效能指標或網路拓撲。IT 維運人員仍需在 Nexus 和 LibreNMS 兩套系統之間切換，無法在單一介面完成日常監控工作。客戶泰國廠即將進入 Phase 2 部署，需要在此階段補足 LibreNMS API 主動查詢能力。

1.2 變更內容

1.3 影響模組

模組 影響說明
Integration 新增 LibreNMS Connector（IG-011），擴展 Connector Framework
CMDB 新增 LibreNMS 作為資產來源 source 列舉值，自動探索流程需支援 LibreNMS API 來源
Dashboard DB-006 設備健康卡片需對接 LibreNMS API 即時資料
Analytics 告警趨勢圖需支援 LibreNMS 歷史告警資料源
AI Copilot AIC-002 系統狀態查詢需新增 LibreNMS 效能指標作為回答資料源

1.4 LibreNMS API 依賴

需要 LibreNMS 開放 REST API 存取（預設已啟用），建議建立專用唯讀帳號。客戶泰國廠 LibreNMS 部署在 10.20.92.202，透過 NetBird VPN 可從 Nexus 存取。

二、技術設計

2.1 目標與非目標

Goals:

Non-Goals:

2.2 架構決策

D1：LibreNMS 作為 Integration Connector（而非 CMDB 探索範本）

選擇： 在 Integration 模組實作 LibreNMS Connector，而非在 CMDB 自動探索新增 LibreNMS 範本。

原因：

替代方案： 在 CMDB 新增「LibreNMS」作為探索範本類型。但這只能解決設備同步，無法涵蓋效能指標和告警歷史的需求。

D2：同步排程策略 — 分層頻率

選擇： 不同資料類型使用不同同步頻率。

資料類型 預設頻率 原因
設備清單 每小時 設備增減不頻繁，每小時足夠
效能指標 每 5 分鐘 需接近即時，但不宜過頻造成 LibreNMS 負擔
Port 狀態 每 5 分鐘 同效能指標
告警歷史 每小時 用於趨勢分析，不需即時
拓撲資料 每天 網路拓撲變動不頻繁

替代方案： 統一使用單一排程。但效能指標需要高頻率，設備清單不需要，統一會造成不必要的 API 負擔或資料延遲。

D3：設備比對策略 — 多欄位漸進比對

選擇： 依序使用 serial → hostname + ip → sysName 比對 CMDB 現有資產。

原因：

D4：新設備預設為「待確認」狀態

選擇： 從 LibreNMS 同步的新設備，預設建立為「待確認」，需 IT 管理員核准後才正式納入 CMDB。

原因：

D5：效能指標快取策略

選擇： Nexus 將 LibreNMS 效能指標快取到本地，Dashboard 讀取快取而非即時呼叫 LibreNMS API。

原因：

2.3 風險與緩解

Risk Mitigation
LibreNMS API 無回應或過慢，影響 Dashboard 載入 效能指標使用快取，API 超時 10 秒自動 fallback 到最後快取值，Dashboard 顯示「資料更新於 X 分鐘前」
LibreNMS API Token 洩漏 Token 以加密形式存儲在 Nexus DB，API 傳輸走 HTTPS，建議使用唯讀帳號的 Token
設備同步造成 CMDB 資產重複 三階段比對策略（serial → hostname+ip → sysName），同步前先做 dry-run 顯示預覽
LibreNMS 版本升級導致 API 不相容 僅使用 v0 穩定 API 端點，Connector 啟動時檢查 /api/v0/system 回應驗證版本相容
大量設備同步造成效能問題 分頁查詢（LibreNMS API 支援 ?perpage=50），同步任務在背景佇列執行，不阻塞主 UI
網路拓撲關聯不準確（LLDP 資料不完整） 自動建立的關聯標記為「LibreNMS 探索」，需 IT 管理員確認；不覆蓋手動建立的關聯

三、功能規格

3.1 LibreNMS Connector 連線管理

REQ-C01：LibreNMS Connector 連線設定

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

Scenario WHEN THEN
設定 LibreNMS API 連線 IT 管理員進入 設定 → 整合管理 → Connector 管理，點選 LibreNMS Connector 的「設定」 系統顯示設定表單，包含：API URL（必填）、API Token（必填）、同步排程設定
連線測試成功 IT 管理員填入正確的 API URL 和 API Token，點選「測試連線」 系統呼叫 /api/v0/system 端點，顯示「已連線」以及 LibreNMS 版本資訊
連線測試失敗 IT 管理員填入錯誤的 API URL 或無效的 API Token，點選「測試連線」 系統顯示具體錯誤訊息（連線逾時 / 401 認證失敗 / DNS 無法解析）

REQ-C02：同步排程配置

系統 SHALL 支援為不同資料類型設定不同的同步頻率。

Scenario WHEN THEN
設定分層同步排程 IT 管理員在 LibreNMS Connector 設定頁面配置同步排程 可分別為以下資料類型設定頻率：設備清單（預設每小時）、效能指標（預設每 5 分鐘）、告警歷史（預設每小時）、拓撲資料（預設每天）
手動觸發同步 IT 管理員點選「立即同步」按鈕 系統立即執行所有資料類型的同步，並顯示同步進度和結果

REQ-C03：連線健康監控

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

Scenario WHEN THEN
連線健康正常 IT 管理員查看整合管理頁面 LibreNMS Connector 顯示：連線狀態為「已連線」、最後成功同步時間、各資料類型的最後同步時間
連線異常通知 LibreNMS Connector 連續 3 次同步失敗 系統自動通知 IT 管理員，錯誤日誌記錄失敗原因

REQ-C04：API Token 安全存儲

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

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

3.2 設備清單同步至 CMDB

REQ-D01：設備清單同步

系統 SHALL 定期呼叫 LibreNMS REST API 取得設備清單，並同步到 CMDB 模組。

Scenario WHEN THEN
首次同步 — 匯入所有設備 LibreNMS Connector 首次啟用並執行同步 系統呼叫 /api/v0/devices 取得所有設備，每台設備建立為 CMDB「待確認」資產，來源標記為「LibreNMS」
增量同步 — 偵測新設備 排程同步執行，LibreNMS 中出現 CMDB 不存在的設備 系統建立新的「待確認」資產，並通知 IT 管理員有新設備待確認
增量同步 — 更新既有設備 排程同步執行，LibreNMS 中設備的資訊有變更（韌體版本、OS、IP 等） 系統自動更新 CMDB 對應資產的欄位，記錄變更日誌
增量同步 — 設備下線偵測 排程同步執行，LibreNMS 中設備的 status 為 0（離線） 系統在 CMDB 標記該資產為「異常」狀態，通知 IT 維運人員

REQ-D02：設備比對策略

系統 SHALL 使用多欄位漸進比對策略，避免 CMDB 產生重複資產。

Scenario WHEN THEN
以序號比對 LibreNMS 設備有 serial 欄位，且 CMDB 中存在相同序號的資產 系統判定為同一資產，執行更新而非新增
以 hostname + IP 比對 LibreNMS 設備無 serial 欄位，但 CMDB 中存在相同 hostname 和 IP 的資產 系統判定為同一資產，執行更新而非新增
無法比對 LibreNMS 設備無法匹配 CMDB 任何現有資產 系統建立為新的「待確認」資產

REQ-D03：欄位對應

系統 SHALL 將 LibreNMS API 回傳的欄位自動對應到 CMDB 資產欄位。

標準欄位對應表：

LibreNMS API 欄位 CMDB 資產欄位 來源 API
hostname 資產名稱 /api/v0/devices
sysName 系統名稱 /api/v0/devices
hardware 型號 /api/v0/devices
os 作業系統 /api/v0/devices
version 韌體/OS 版本 /api/v0/devices
serial 序號 /api/v0/devices
ip IP 位址 /api/v0/devices
location 位置 /api/v0/devices

資產類型自動推斷：

LibreNMS os / type 含有 CMDB 資產類型
linux / windows / vmware Server
ios / junos / aruba / routeros Network
drac / ilo Server（管理介面）

REQ-D04：同步預覽與確認

系統 SHALL 在首次同步前提供預覽功能。

Scenario WHEN THEN
首次同步預覽 IT 管理員點選「預覽同步結果」 系統顯示將會匯入的設備清單，每筆標記比對狀態（🆕 新增 / 🔄 更新 / ✅ 無變化），IT 管理員確認後才執行
自動核准模式 IT 管理員在 Connector 設定中啟用「自動核准新設備」 新發現的設備直接建立為正式 CMDB 資產，不需手動確認

3.3 即時效能指標與 Dashboard

REQ-M01：即時效能指標查詢

系統 SHALL 定期從 LibreNMS API 取得設備效能指標，快取到本地供 Dashboard 和 AI Copilot 使用。

Scenario WHEN THEN
取得設備健康指標 同步排程觸發效能指標同步 系統呼叫 /api/v0/devices/{id}/health 取得每台設備的 CPU 使用率、記憶體使用率、磁碟使用率、溫度，並快取到本地
取得 Port 流量和狀態 同步排程觸發效能指標同步 系統呼叫 /api/v0/ports?columns=ifName,ifInOctets_rate,ifOutOctets_rate,ifOperStatus 取得所有 Port 的流量速率和狀態
快取過期處理 快取資料超過同步頻率時間（預設 5 分鐘）且新同步尚未完成 Dashboard 顯示最後快取值，並標註「資料更新於 X 分鐘前」

REQ-M02：Dashboard 設備健康卡片

Dashboard 的設備健康區塊（DB-006）SHALL 顯示 LibreNMS 的即時效能指標。

Scenario WHEN THEN
設備健康卡片顯示 IT 維運人員開啟 Dashboard 設備健康區塊顯示所有 LibreNMS 監控設備的健康卡片，每張卡片顯示：設備名稱、CPU/Memory 使用率、整體狀態（🟢 正常 / 🟡 警告 / 🔴 異常）
展開設備詳情 IT 維運人員點擊某台設備的健康卡片 展開顯示：CPU 使用率趨勢線（過去 24h）、記憶體使用率趨勢線、磁碟使用率列表、各 Port 流量和狀態
異常設備優先排序 Dashboard 載入設備健康區塊 異常（🔴）設備排在最上方，其次是警告（🟡），最後是正常（🟢）

REQ-M03：AI Copilot 效能指標查詢

AI Copilot（AIC-002）SHALL 能查詢 LibreNMS 效能指標回答自然語言問題。

Scenario WHEN THEN
查詢特定設備的 CPU 使用者問「TH-DCVer1 的 CPU 使用率是多少？」 AI Copilot 從快取取得該設備的最新 CPU 使用率，回答即時數值並附上資料來源和更新時間
查詢超閾值設備 使用者問「哪些設備的磁碟使用率超過 80%？」 AI Copilot 從快取篩選符合條件的設備，回答設備清單和各自的磁碟使用率
查詢 Port 狀態 使用者問「Aruba 6200 的各 Port 流量狀況？」 AI Copilot 回答該設備所有 Port 的名稱、上下行流量速率、連線狀態

3.4 告警歷史與網路拓撲

REQ-A01：告警歷史整合

系統 SHALL 從 LibreNMS API 取得歷史告警資料，整合到 Analytics 模組的趨勢圖。

Scenario WHEN THEN
同步歷史告警 排程同步執行告警歷史同步 系統呼叫 /api/v0/alerts 取得所有狀態的告警（活躍 + 已恢復），存儲到 Nexus 本地資料庫
告警趨勢圖 IT 管理員進入 分析報表 → 設備告警趨勢 顯示 LibreNMS 歷史告警的趨勢圖，支援按設備、嚴重度、時間範圍篩選
告警來源標記 Analytics 顯示告警趨勢 來自 LibreNMS API 的歷史告警與來自 Webhook 即時告警合併顯示，標記不同來源便於區分

REQ-A02：網路拓撲自動探索

系統 SHALL 從 LibreNMS API 取得 LLDP/CDP 鄰居資訊和 ARP/FDB 表，自動建立 CMDB 設備間的連接關聯。

Scenario WHEN THEN
LLDP 鄰居探索 排程同步執行拓撲資料同步 系統呼叫 /api/v0/resources/links 取得 LLDP/CDP 鄰居資料，自動在 CMDB 中建立對應設備之間的 connected_to 關聯
拓撲關聯標記 系統自動建立 CMDB 關聯 關聯來源標記為「LibreNMS 探索」，與手動建立的關聯區分
不覆蓋手動關聯 系統探索到的連接關聯與 IT 管理員手動建立的關聯重複 系統保留手動關聯不覆蓋，跳過該筆自動關聯
拓撲圖即時更新 拓撲資料同步完成 CMDB 拓撲圖（CM-022）自動反映最新的網路連接關聯

REQ-A03：設備群組同步

系統 SHALL 從 LibreNMS 取得設備群組資訊，自動套用為 CMDB 標籤。

Scenario WHEN THEN
群組同步為標籤 排程同步執行拓撲資料同步 系統呼叫 /api/v0/devicegroups 取得設備群組，將群組名稱自動套用為 CMDB 資產標籤（前綴 librenms:）
群組變更同步 LibreNMS 中設備被加入或移出群組 下次同步時自動新增或移除對應的 CMDB 標籤

四、LibreNMS API 端點總覽

API 端點 用途 同步頻率 對應功能
GET /api/v0/system 連線測試、版本驗證 手動 REQ-C01
GET /api/v0/devices 設備清單同步 每小時 REQ-D01
GET /api/v0/devices/{id}/health CPU/Memory/Disk/溫度 每 5 分鐘 REQ-M01
GET /api/v0/ports Port 流量和狀態 每 5 分鐘 REQ-M01
GET /api/v0/alerts 告警歷史 每小時 REQ-A01
GET /api/v0/resources/links LLDP/CDP 鄰居 每天 REQ-A02
GET /api/v0/resources/fdb ARP/FDB 表 每天 REQ-A02
GET /api/v0/devicegroups 設備群組 每天 REQ-A03

五、實作任務清單

5.1 LibreNMS Connector 基礎設施

5.2 同步排程引擎

5.3 設備清單同步至 CMDB

5.4 即時效能指標

5.5 AI Copilot 整合

5.6 告警歷史整合

5.7 網路拓撲自動探索

5.8 測試與文件

← 上一篇Graylog REST API 深度整合 — 實作規格書 下一篇 →Arova Nexus MVP — 客戶泰國廠 UX 規劃藍圖