Log 轉發設定使用指南

適用對象：負責維護 Guidant AI 的系統管理員，以及貴單位管理集中式 log 平台（rsyslog / Graylog / ELK）的 IT 人員。 本文用途：說明如何把 Guidant AI 的系統紀錄自動送一份到貴單位自己的 log 伺服器，包含畫面上的操作步驟，以及三種常見 log 平台的接收端設定範例。 不在本文範圍：檢測 Agent 的紀錄（Agent 的紀錄留在 Agent 主機上，本功能不涵蓋）、api_logs 操作日誌頁的查詢（那是站內查詢，見「操作日誌」頁）。

變更紀錄

日期	內容
2026-08-27	首版：功能說明、畫面操作步驟、rsyslog／Graylog／ELK 三家接收端設定範例、送出內容格式、排錯

---

一、這個功能在做什麼

貴單位如果已經有一台集中管理 log 的機器（常見的有 rsyslog、Graylog、ELK），可以讓 Guidant AI 把自己的紀錄也送一份過去，這樣所有系統的紀錄都在同一個地方查、同一套規則保存。

設定完全在畫面上完成，存檔後不需要重開服務。

Guidant AI  ──（Syslog 或 GELF，走 UDP 或 TCP）──▶  貴單位的 log 伺服器
    │                                                （rsyslog / Graylog / ELK）
    └── 本機紀錄照常寫入，完全不受影響

可以送兩種東西，分開勾選

送什麼	內容	誰會要
應用程式 log	系統運作過程與錯誤訊息	工程排錯：把各系統的錯誤集中在一起看
稽核事件	誰登入、誰修改了什麼（帶事件代碼與結構化欄位）	合規／資安：接 SIEM 平台時通常至少要這一項

兩者各有獨立的勾選框，可以只送其中一種。

三件事先講清楚，免得誤會

1. 轉發是旁路，壞掉不會影響系統本身。 log 伺服器連不上、當機、或位址填錯時，Guidant AI 一切照常運作，本機紀錄也照常寫入——只是那份「送出去的副本」會被丟棄。這是刻意的設計：log 轉發不該拖垮主服務。
2. UDP 送得出去，不代表對方收得到。 UDP 這種傳輸方式沒有回執，我們只能確認「已經送出」。想要有連線層的確認，請選 TCP。
3. 存檔後不是瞬間全面生效。 系統內部通常有多個服務程序，存檔當下處理您這次請求的那一個立刻生效，其餘最多 30 秒內跟上。存完馬上去 log 伺服器找不到訊息，先等半分鐘再看。

⚠️ 紀錄內容會原樣送出、不做任何遮蔽。 紀錄中若含 IP、電子郵件或類似 token 的字串，都會照原樣送到您指定的 log 伺服器——請確認該伺服器位於貴單位的信任範圍內。

---

二、畫面操作步驟

位置

登入系統 → 左側選單「系統設定」→「Log 轉發設定」（位置在「通知設定」與「操作日誌」之間）。

看不到這個選單項，代表您的帳號沒有這項權限——這一頁與「郵件伺服器設定」屬於同一組權限，請找系統管理員指派。

建議的操作順序

先在接收端把 input 開好（見第三章），再回來設定，最後用測試按鈕驗證。反過來做的話，測試一定失敗，反而不知道是哪一端的問題。

1. 填寫設定

欄位	說明
啟用 log 轉發	總開關。關閉時完全不對外送出。
協定	Syslog（RFC 5424） 或 GELF（Graylog 原生格式）。選哪個見下方說明。
傳輸方式	UDP 或 TCP。
Log 伺服器位址	接收端的 IP 或網域名稱。
連接埠	接收端 input 所監聽的埠。
轉發內容	勾選要送「應用程式 log」、「稽核事件」，或兩者。

協定怎麼選：接 rsyslog 或 ELK 選 Syslog（三家都吃，是最大公約數）。接 Graylog 兩種都行——選 GELF 可以讓每個欄位（操作者、專案編號、事件類型…）在 Graylog 上各自成為可查詢的欄位，不必用字串搜尋整段訊息；選 Syslog 則所有欄位擠在一行文字裡。

傳輸方式怎麼選：UDP 送出即忘、不佔連線，log 量大時對兩端都輕，但送丟了不會有人知道。TCP 會建立連線，能確認對方接受了連線，代價是接收端必須另外開一個 TCP input。第一次設定建議先用 TCP 測通、確認格式與內容都對，再視需要換成 UDP。

1. 按「儲存」

啟用狀態下，位址與連接埠是必填（沒填會擋下並標紅）。關閉狀態下可以留空——先關掉總開關再慢慢改設定是正常流程。

存檔成功後畫面會提示：本機已生效，其餘程序最多 30 秒內跟上。

1. 按「發送測試 log」

🔴 測試用的是「已儲存」的設定，不是畫面上剛打的字。 表單只要有還沒存的變更，這顆按鈕就會反灰並提示「請先儲存再測試」。這是刻意的——否則您改了位址、按測試看到綠燈，其實測的是舊位址。

結果分三種，措辭不同，請照字面理解：

顯示	意思
「已送出，且與 log 伺服器連線成功」（TCP）	對方接受了連線，訊息已交出去
「已送出。UDP 無法確認對方是否收到，請至 log 伺服器確認」（UDP）	我們這端沒問題，對方有沒有收到請自己去看
「送出失敗：<原因>」	失敗，後面那段原因（例如「連線被拒絕」）是唯一的診斷線索

1. 到 log 伺服器確認那則測試訊息真的收到了。 這一步不能省——尤其是 UDP，畫面上的成功只代表送出。

---

三、三種 log 平台的接收端設定範例

以下範例都用 5514 這個埠。Linux 上 1024 以下的埠（含 syslog 傳統的 514）需要 root 權限才能監聽，容器化的 log 平台通常也不會直接用 514，所以範例一律用高位埠；貴單位若確定要用 514，把範例中的埠號換掉即可。

3.1 rsyslog

接收端設定（在 log 伺服器上）：新增 /etc/rsyslog.d/10-guidant-ai.conf

# ── 收 Guidant AI 的 syslog（RFC 5424） ─────────────────────────────
# UDP 版
module(load="imudp")
input(type="imudp" port="5514")

# TCP 版（若在畫面上選 TCP，改用這兩行）
# module(load="imtcp")
# input(type="imtcp" port="5514")

# Guidant AI 使用 facility local0，把它單獨寫進一個檔案，
# 不與這台機器自己的系統紀錄混在一起。
local0.*    /var/log/guidant-ai.log

# 已寫進專屬檔案，就不要再往預設的 /var/log/messages 送一份
& stop

套用：

sudo rsyslogd -N1                      # 先驗設定檔語法（不會套用）
sudo systemctl restart rsyslog
sudo ss -lnup | grep 5514              # UDP 應看到 5514 在監聽（TCP 用 ss -lntp）

在 Guidant AI 畫面上填：協定 Syslog、傳輸 UDP（或 TCP）、位址填這台 rsyslog 主機、連接埠 5514。

確認收到：

sudo tail -f /var/log/guidant-ai.log

按下測試按鈕後，這裡應該立刻出現一行 [Guidant AI] log 轉發測試訊息 — 由 <帳號> 於 <時間> 發出。

別忘了防火牆要放行該埠（firewall-cmd --add-port=5514/udp 或對應的 ufw / iptables 規則）。

3.2 Graylog

Graylog 兩種格式都收，建議用 GELF（欄位會自動拆開）。

建 input：Graylog 網頁介面 → System → Inputs → 從下拉選單選擇 input 類型 → Launch new input

想用的協定	選這個 input 類型
GELF + UDP	GELF UDP
GELF + TCP	GELF TCP
Syslog + UDP	Syslog UDP
Syslog + TCP	Syslog TCP

Launch 時的設定：

• Global：勾選（多節點叢集時每個節點都收）
• Bind address：0.0.0.0
• Port：5514
• 其餘保持預設即可

按下 Launch Input，回到 Inputs 清單應看到該 input 狀態為 RUNNING。

在 Guidant AI 畫面上填：協定 GELF（或 Syslog，與上面所選的 input 類型一致）、傳輸與 input 相同、位址填 Graylog 主機、連接埠 5514。

確認收到：Graylog → Search，時間範圍選最近 5 分鐘。按下測試按鈕後應出現該筆訊息。

用 GELF 時，展開任一筆稽核事件可以看到這些獨立欄位（可直接當查詢條件，例如 event_type:PROJECT_CREATED）：

欄位	內容
event_type	事件名稱，例如 LOG_FORWARDING_SETTING_UPDATED
event_code	事件代碼（數字）
user_login_name / user_nickname / user_uid	操作者
logger / file / line / func	這筆紀錄的來源位置
其他	該事件自己帶的欄位（專案編號、任務編號等），依事件而異

來源主機（source）欄位顯示什麼：Guidant AI 送出的是站台對外的位址（安裝時填的系統網址）。若貴單位想在 Graylog 上顯示自訂名稱（例如 guidant-prod 而不是一組 IP），在系統的環境設定檔加一行 LOG_FORWARDING_HOSTNAME=guidant-prod 後重啟後端即可。

3.3 ELK（Elasticsearch + Logstash + Kibana）

ELK 沒有原生的 GELF input，走 Syslog 格式，由 Logstash 負責接收與解析。

Logstash pipeline：新增 /etc/logstash/conf.d/guidant-ai.conf

input {
  syslog {
    port  => 5514
    type  => "guidant-ai"
    # Guidant AI 送的是 RFC 5424；Logstash 的 syslog input 預設用 RFC 3164 的
    # grok 規則解，會解不開而把整筆丟進 _grokparsefailure。關掉內建解析，
    # 改由下面的 grok 依 5424 結構自己解。
    grok_pattern => "%{GREEDYDATA:raw_message}"
  }
}

filter {
  if [type] == "guidant-ai" {
    grok {
      match => {
        "raw_message" => "<%{NONNEGINT:syslog_pri}>1 %{TIMESTAMP_ISO8601:event_time} %{NOTSPACE:source_host} %{NOTSPACE:app_name} %{NOTSPACE:pid} %{NOTSPACE:msgid} %{NOTSPACE:structured_data} %{GREEDYDATA:log_message}"
      }
    }

    # 時戳是 UTC，轉成 Logstash 的 @timestamp
    date {
      match  => [ "event_time", "ISO8601" ]
      timezone => "UTC"
    }

    # 稽核事件的訊息以 [AUDIT:<事件名>] 開頭，msgid 欄位帶事件代碼；
    # 把它們挑出來，方便在 Kibana 上只看稽核軌跡。
    if [msgid] != "-" {
      mutate { add_field => { "record_kind" => "audit_event" } }
      grok {
        match => { "log_message" => "\[AUDIT:%{WORD:event_type}\]%{GREEDYDATA:audit_fields}" }
        tag_on_failure => []
      }
    } else {
      mutate { add_field => { "record_kind" => "app_log" } }
    }
  }
}

output {
  if [type] == "guidant-ai" {
    elasticsearch {
      hosts => ["http://localhost:9200"]
      index => "guidant-ai-%{+YYYY.MM.dd}"
    }
  }
}

套用：

# 先驗設定檔語法（不會啟動 pipeline）
sudo /usr/share/logstash/bin/logstash --path.settings /etc/logstash -t

sudo systemctl restart logstash
sudo ss -lnup | grep 5514

Logstash 的 syslog input 同時監聽 UDP 與 TCP 的同一個埠，所以畫面上選 UDP 或 TCP 都收得到。

在 Guidant AI 畫面上填：協定 Syslog、傳輸 UDP 或 TCP、位址填 Logstash 主機、連接埠 5514。

確認收到：Kibana → Discover，建立 index pattern guidant-ai-* 後查詢最近 5 分鐘。

---

四、送出去的內容長什麼樣

知道格式才好在接收端寫解析規則與告警條件。

4.1 Syslog（RFC 5424）

一筆訊息的結構：

<134>1 2026-08-27T09:56:05.728Z 10.0.0.50 guidant-ai 42 6100 - [2026-08-27 17:56:05,728] INFO [app.log_forwarding] [alice] [log_forwarding_app_service.update_settings:78]: [AUDIT:LOG_FORWARDING_SETTING_UPDATED] enabled=True protocol=syslog host=10.0.0.60 port=5514 operator=alice

欄位	值	說明
<134>	PRI	facility local0 × 嚴重程度算出來的數字
1	版本	RFC 5424 固定為 1
時戳	2026-08-27T09:56:05.728Z	UTC（尾端 Z），不是本地時間
HOSTNAME	站台位址	見 3.2 節末的說明
APP-NAME	guidant-ai	可用 LOG_FORWARDING_APP_NAME 改
PROCID	程序編號
MSGID	事件代碼或 -	有數字＝稽核事件，-＝一般應用 log。這是在接收端分流兩種紀錄最省事的判準
-	結構化資料	本版不使用（固定為 nil）
訊息本體		格式見下

訊息本體的格式與本機 log 檔一致，方便對照：

[時間] 層級 [模組] [操作者帳號] [程式位置]: 訊息內容

稽核事件的訊息內容一律以 [AUDIT:<事件名稱>] 開頭，後面接 欄位=值 形式的細節。

4.2 GELF 1.1

一筆訊息是一包 JSON：

{
  "version": "1.1",
  "host": "10.0.0.50",
  "short_message": "[AUDIT:LOG_FORWARDING_SETTING_UPDATED] enabled=True protocol=syslog operator=alice",
  "timestamp": 1787824565.728,
  "level": 6,
  "_logger": "app.log_forwarding",
  "_file": "/app/app/log_forwarding/service/log_forwarding_app_service.py",
  "_line": 78,
  "_func": "update_settings",
  "_event_code": 6100,
  "_event_type": "LOG_FORWARDING_SETTING_UPDATED",
  "_user_login_name": "alice",
  "_enabled": true,
  "_protocol": "syslog"
}

• level 用的是 syslog 的嚴重程度（2＝嚴重、3＝錯誤、4＝警告、6＝一般），不是 Python 的數字。
• 底線開頭的都是額外欄位，Graylog 會自動拆成可查詢的欄位（畫面上顯示時會去掉底線）。
• 一般應用 log 沒有 _event_code / _event_type 這幾個欄位。
• UDP 走 gzip 壓縮、TCP 不壓縮（GELF 規格如此，接收端會自動辨識）。
• 單筆訊息超過 8 KiB 會被截斷，尾端標 …[truncated]；本系統不使用 GELF 的分段（chunking）機制。

---

五、排錯

症狀	可能原因與處置
測試按鈕是反灰的	①表單有未儲存的變更 → 先按儲存；②您的帳號沒有修改權限 → 找系統管理員指派。滑鼠移到按鈕上會顯示是哪一種。
測試顯示「連線被拒絕」	接收端沒有在那個埠監聽，或監聽的是另一種傳輸方式（例如接收端只開了 TCP，畫面上卻選 UDP）。到接收端用 ss -lnup／ss -lntp 確認。
測試顯示「已送出」，但 log 伺服器什麼都沒有（UDP）	UDP 沒有回執，「已送出」只代表我們這端送出了。依序檢查：①位址與埠有沒有填錯；②中間的防火牆有沒有放行該 UDP 埠；③接收端的 input 是不是真的在跑。必要時改用 TCP 測一次——TCP 會回報連線層的失敗，比 UDP 好查得多。
存完檔，log 伺服器一直沒有新訊息進來	①先等 30 秒（其餘服務程序需要一輪才跟上）；②確認「轉發內容」至少勾了一項；③確認總開關是開的。
只收得到稽核事件，收不到一般紀錄（或反過來）	「轉發內容」那兩個勾選框是獨立的，檢查是不是只勾了一項。
Graylog 收到流量但一筆都沒存下來	送出格式與 input 類型不搭（例如畫面選 GELF、Graylog 開的卻是 Syslog input）。兩邊必須一致。
Kibana 上的紀錄全被標記 _grokparsefailure	Logstash 的 syslog input 預設按舊版（RFC 3164）規則解析，而本系統送的是 RFC 5424。請照 3.3 節的範例加上 grok_pattern => "%{GREEDYDATA:raw_message}" 並自行 grok。
log 伺服器上的時間比實際早／晚幾個小時	送出的時戳是 UTC。請確認接收端有把它當 UTC 解析（Logstash 範例已設 timezone => "UTC"），而不是當成本地時間。
來源主機顯示成一串看不懂的英數字	舊版才有的問題（顯示的是容器編號）。請升級到 1.16.0 之後的版本。
log 伺服器掛掉了，會影響系統嗎	不會。 系統照常運作、本機紀錄照常寫入，只有「送出去的那一份」會被丟棄。

想知道系統這端有沒有在轉發

在系統主機上查後端紀錄：

sudo grep 'log 轉發' /srv/guidant-ai/log/app.log | tail -20

• log 轉發已啟用：syslog over udp → 10.0.0.60:5514（app_log=True, audit=True） → 已掛上
• log 轉發已卸載 → 已關閉或改設定中
• log 轉發掛載失敗 → 位址解析不到或埠有問題，後面會附原因
• log 轉發佇列已滿，累計丟棄 N 筆轉發訊息 → 接收端跟不上送出的速度，這只影響轉發的副本，本機紀錄完整無缺。若持續出現，請檢查接收端的效能或改用 UDP。

---

六、相關文件

• 落地部署版的其他選配功能設定 → 《Guidant AI 落地部署版 — 安裝與維運手冊》第十章
• 站內操作紀錄的查詢（不需要 log 伺服器）→ 系統選單「系統設定 › 操作日誌」