FR-068 · 需求索引 · 本頁由 build 掃資料夾生成
系統 log 可以在 UI 上設定，直接轉發到客戶自己的 log server。
白話說明：客戶（特別是落地版）機房裡通常已經有一套集中收 log 的平台（ELK、Graylog、rsyslog 之類），希望我們的系統也把 log 送過去，跟其他系統的 log 放在一起看。本案讓管理者在系統設定頁填上「對方主機位址＋埠號＋用哪種協定」，勾選要送哪些內容，按下儲存就開始轉發，不必改設定檔也不必重啟服務；旁邊還有一顆「發送測試 log」按鈕可以當場驗連不連得通。
送的內容分兩條流、各自獨立勾選：應用 log（系統運作紀錄，給工程師排錯用）與稽核事件（誰登入、誰改了什麼，合規客戶接 SIEM 真正要的就是這條）。
轉發是旁路，不會拖垮主服務——網路斷掉、對方主機掛了，本機 log 照常寫，系統照常跑。
| 誰會用到 | 客戶的系統管理者（設定）；客戶的資安／維運團隊（在自己的平台上看我們送過去的紀錄） |
| 原本的痛 | 客戶機房裡每套系統的 log 都進同一個平台，唯獨我們的要另外登入系統看——在客戶的監控網裡是個黑洞；合規客戶的 SIEM 收不到我們的稽核事件 |
| 本案之後 | 在設定頁填對方位址、勾要送什麼、存檔即開始送，不必改設定檔也不必重啟服務 |
| 怎麼驗收 | 進系統管理的「Log 轉發設定」→ 填客戶 log server 的位址與埠號 → 按「發送測試 log」→ 到對方平台上看得到那筆測試訊息 → 存檔後隨便做個操作（例如登入），對方平台收得到對應的稽核事件 |
2026-08-25 需求討論拍板（範圍單純、決策點只有三個，未走 HTML 討論稿），同月完成 BE、FE、手冊與 SPEC，經一輪 STG 驗證與四筆修正後隨 v1.17.0 出貨，188 STG 與 189 POC 皆已升級到位。
design.md 是 2026-08-25 拍板當下的設計定案，內容未隨後續修正回頭改寫；實際落地與設計的差異記在下面「實作與設計的差異」。
完整理由與被排除的方案見 design.md §2。
| # | 決策 | 定案 |
|---|---|---|
| D1 | 協定 | Syslog（RFC 5424，UDP/TCP）＋ GELF（UDP/TCP）兩種。這兩種是 rsyslog／Graylog／ELK 三家的最大公約數；不做各家專屬 API 對接（認證與版本相容坑太多） |
| D2 | 轉發範圍 | 應用 log 與稽核事件兩條流都做，UI 上分開勾選。只做應用 log 會做完才發現不是合規客戶要的東西 |
| D3 | 設定層級 | 系統層全域一份。資料表帶可空的 tenant_id（NULL＝全域）預留租戶層，未來要開只動 UI 與單點 helper |
| D4 | 失敗語意 | 轉發失敗絕不拖垮主服務：掛在 QueueHandler/QueueListener 後面，主執行緒零阻塞；UDP 送出即忘，TCP 斷線靜默降級不重試風暴 |
| D5 | 敏感內容 | 第一版不過濾（信任邊界在客戶內網，手冊註明）。架構預留遮罩掛點 |
| D6 | 生效方式 | 設定改完熱生效，不重啟服務；另給「發送測試 log」按鈕驗連通 |
出貨後的修正，都已併入 v1.17.0：
| 項目 | design.md 原本寫的 | 實際落地 | 卡 |
|---|---|---|---|
| 遮罩開關 | UI 放一顆 disabled 的開關，標「即將推出」 | 整個隱藏——未上線的功能不該在畫面上曝光，客戶會問「這個為什麼點不了」 | CM-1410 |
| syslog 封包格式 | 用 stdlib SysLogHandler 即可 |
stdlib 預設會在封包尾端補一個 NUL byte、時戳也不是真 UTC，兩者都不合 RFC 5424，Graylog 收得到流量卻無法解析。已關掉 NUL 結尾並改送真 UTC 時戳 | CM-1408 |
| 封包的來源主機欄位 | 未著墨 | 原本送出容器 ID（每次重建就變、對方看不懂），改成送站台位址；syslog 與 GELF 兩邊都要改（第一次只改了 syslog 那半邊） | CM-1408 |
| 授權標示 | 未著墨 | 新設定頁被 license 機制誤判為「未授權」功能而擋下，補進基礎設施豁免清單 | CM-1409 |
docs/user-manual/log-forwarding-guide.md）——rsyslog／Graylog／ELK 各一段可直接抄的設定範例以下全部由 build 掃資料夾產生，新增檔案重 build 即自動出現。標題連結指向渲染後的 HTML，md 連向源檔。
由新到舊。每份是某一棒次交接當下的完整現況快照，看某個時間點「當時知道什麼」請從這裡進。
| 日期 | 文件 | 標題 |
|---|---|---|
| 2026-08-29 | 2026-08-29-CM1429-public-site-broken-handoff ／ md | CM-1429 交接：需求文件站公網側欄壞掉，成因未查明 |
卡片內容（決策紀錄、驗收條件）以 Notion 為準，本頁只記座標。
| 關係 | 卡號 | 標題 | 狀態 |
|---|---|---|---|
| 母案 | CM-1389 | FR-068 系統 Log 轉發：UI 設定轉發到客戶 log server（母卡） | Done |
| 子卡 | CM-1390 | T-1 BE：log 轉發設定表＋CRUD＋handler 鏈掛載 | Done |
| 子卡 | CM-1391 | T-2 FE：log 轉發設定頁＋測試按鈕 | Done |
| 子卡 | CM-1392 | T-3 手冊三家對接範例＋SPEC 頁 | Done |
| 子卡 | CM-1406 | T-4 出測試版 image＋188 STG 升級驗證 | Done |
| 子卡 | CM-1408 | syslog 封包不合 RFC 5424（尾端 NUL＋假 UTC 時戳），Graylog 收得到卻無法 ingest | Done |
| 子卡 | CM-1409 | Log 轉發設定頁被 license 誤標「未授權」 | Done |
| 子卡 | CM-1410 | 設定頁隱藏「敏感資料遮罩」開關（未上功能不曝光） | Done |
| 子卡 | CM-1411 | T-5 正式進版打包＋188/189 升級（189 只准升級模式、資料不可掉） | Done |
| 子卡 | CM-1412 | 雲端空間整合操作下放 Tenant Admin——root 旗標守門改能力點 | Done |
牽動的 SPEC 頁（連向線上 SPEC 手冊，開新視窗）：
相關需求：