月度工作報告

雨水花園資料拉取與資料中樞架構

主題：資料接收方式之架構升級、開發工作、測試與驗證

一、專案背景與目的

本報告說明雨水花園專案在本期針對資料接收方式所做的調整，以及相關的開發、測試與驗證工作。基於資訊安全要求，原本對外接收資料的方式必須調整，因此我們改採由伺服器端主動向資料中樞拉取資料的新做法，並導入漸進式（灰度）測試，讓系統能夠平順、可控地逐步轉移到新架構。

二、系統架構與資料流

整個系統由三個角色組成，各司其職。以下用白話說明這三個角色，以及一筆資料從產生到入庫的流動方式。

三個角色

  • 現場感測設備（樹莓派感測器，現場 OT 端）：部署在現場各站點的感測站，負責量測並定時把資料往外送出。
  • 資料中樞伺服器：位於中間的緩衝與中繼伺服器，負責暫存與轉交資料，本身不做任何業務判讀或計算，只忠實保存收到的原始資料。
  • 雨水花園伺服器（執行於 Windows 虛擬主機）：最終落地入庫的伺服器端，負責把資料解析、校正、判斷告警，並寫入資料庫永久保存。

資料如何流動

  • 第一段：現場感測設備將量測資料推送至資料中樞伺服器，由資料中樞先行暫存。
  • 第二段：雨水花園伺服器定時主動向資料中樞拉取尚未取走的資料。
  • 第三段：雨水花園伺服器拿到資料後，完整跑過後端處理流程，最後寫入資料庫。
  • 簡述：現場感測設備 → 資料中樞伺服器 ← 雨水花園伺服器（感測設備推送、伺服器端主動拉取）。

三、本期完成的工作

本期的工作重點，是在不更動既有後端處理邏輯的前提下，為雨水花園伺服器新增主動拉取資料的能力，並同步強化資料中樞、日誌維運與系統穩定性。以下分類條列。

雨水花園伺服器：新增定時主動拉取功能

  • 在原有伺服器基礎上新增「定時主動向資料中樞拉取資料」的功能，可依設定的時間間隔自動執行。
  • 拉取到的資料，與原本被動接收資料走完全相同的後端處理流程，確保兩種接收方式行為一致、結果一致。
  • 兩種接收方式並存：原本的被動接收介面仍保留可用，新增的主動拉取為平行新增，不破壞既有相容性，風險可控。
  • 嚴格分工：拉取功能本身只負責「把資料取回並轉成可處理的格式」，所有業務判斷與資料庫寫入一律交由共用的後端處理流程，避免重複與不一致。

資料中樞伺服器：緩衝、中繼與保護

  • 作為資料的緩衝與中繼，忠實保存現場感測設備推送的原始資料，本身不解讀、不轉換、不做業務計算。
  • 提供讓伺服器端拉取資料的介面，並以游標方式只交付尚未被取走的資料，避免漏取或亂序。
  • 對來源端加上連線速率限制保護，避免短時間大量連線造成負載過高；超量時以友善的方式回應，讓來源端維持原有的重試行為。
  • 對外只開放必要介面，內部維運與敏感檔案的存取在對外層一律阻擋。

日誌與維運強化

  • 日誌詳細程度可即時調整、不需重啟服務：平時記重點，排查問題時可臨時切到最詳細，查完再切回，全程不中斷服務。
  • 日誌檔案自動輪替與磁碟用量上限控管：舊檔自動壓縮、限制保留數量與天數，最壞情況下磁碟占用有明確上限，對磁碟空間吃緊的環境友善。
  • 針對伺服器異常結束的診斷強化：補上開機階段紀錄與異常結束時的獨立診斷紀錄，並整理排查手冊，方便事後追查（此類無畫面的伺服器，異常訊息原本容易遺失）。
  • 結構化日誌：每筆紀錄帶有可追蹤的識別碼，能把同一筆資料從拉取到入庫的整段過程串起來查詢，方便追查。

系統穩定性

  • 服務可優雅關閉：收到關閉指令時會有序收尾，處理中的工作完成或安全中止，不留殘留程序。
  • 未預期錯誤可自動記錄並復原：發生異常時會自動留下完整紀錄並繼續運作，不會整個服務崩潰。
  • 開機階段紀錄完整：啟動各階段都有紀錄，方便事後追查啟動相關問題。
  • 資料中樞短暫不可用時，伺服器端不會崩潰；待資料中樞恢復後可自動接續拉取。

四、資料留存與傳輸原理

以下用白話說明資料如何被保存、傳遞，以及如何確保不遺漏、不重複。

五、測試與驗證

本期針對新功能與既有功能進行了多面向的測試與驗證，包含自動化檢查腳本、本地端到端的完整流程驗證，以及品質驗收。以下分類說明。

自動化檢查腳本

  • 服務健康檢查：自動呼叫對外與內部讀取介面，確認回應內容正常、非空、非全為零值或空值。
  • 資料中樞壓力與穩定性測試：以真實量測點模擬現場推送，連續向資料中樞送出批次資料，驗證其在持續負載下的穩定性與資料正確入庫。
  • 與既有系統的資料比對核對：對多個站點同時呼叫新舊系統介面並逐欄位比對，記錄結果為共通欄位數值完全一致，少數未對上的欄位僅為命名差異、非數值差異。
  • 服務時間檢查：呼叫多個讀取介面、檢視最後更新時間，標記異常並產出健康報告。

本地端到端驗證

  • 在本地 Windows 11 環境，將感測資料推送（POST）到正式環境的資料中樞。
  • 再由本地的雨水花園伺服器，向同一個正式資料中樞拉取同一批資料。
  • 完整跑過「拉取 → 解析 → 後端處理 → 寫入資料庫」整段流程，並確認資料成功入庫。
  • 驗證結果：模擬送出的資料全數成功送達；伺服器端成功拉取並處理；資料庫主表更新時間如預期前進、量測點紀錄表如預期新增資料；單筆追蹤案例也確認校正後數值正確、時間對齊到分鐘、並新增一筆紀錄。

品質驗收

  • 以黑箱、整合、回歸三類測試進行驗收，整體結果為通過（符合所有驗收標準）。
  • 涵蓋範圍包含：被動接收路徑的回歸測試、主動拉取路徑、後端處理共用一致性、日誌即時調整、日誌設定載入、日誌分級、拉取稽核、告警鏈、重複資料處理、時效控管、優雅關閉、環境變數覆寫與跨平台編譯。
  • 少數日誌輪替的極端負載情境（依大小、保留數量、保留天數自動清理）因時間成本標記為本期未實測；對應機制已實作，僅未在極端負載下逐項演練。

已驗證的具體行為

  • 重複資料不重複入庫：相同資料送兩次，資料庫僅留一筆，第二次由系統自動吸收。
  • 日誌即時調整：切到最詳細立即看到細部追蹤、切回一般即恢復，過程中服務不重啟。
  • 優雅關閉：收到關閉訊號後依序收尾，處理中工作完成或安全中止，乾淨退出。
  • 日誌輪替與磁碟上限：依設定載入並反映於啟動紀錄，最壞磁碟占用有明確上限。
  • 資料中樞中斷韌性：資料中樞不可用時伺服器端不崩潰、恢復後自動接續。
  • 連線速率限制：以連續請求驗證，符合預期的每分鐘上限門檻。
  • 跨平台編譯：成功產出可在 Windows 虛擬主機獨立執行的程式，不需額外相依檔案。

六、漸進式（灰度）轉移可行性

由於新增的主動拉取功能，與既有的後端處理流程完全一致，因此具備平順、可控逐步轉移的條件。

七、結論

以下為本期成果與目前狀態的事實彙整。