十、選配功能的設定¶

這章在講什麼：六項「要用才設定」的附加功能怎麼開。

系統的核心功能（專案、稽核、證據、報告）安裝完、開通完就能用，不需要看這一章。本章這六項是選配：需要就照著設定，不需要就完全不用管，不設定不會影響其他任何功能。

什麼時候看：想開 AI 功能、想接 Google 雲端硬碟、想讓系統會寄信、想對貴單位主機做組態檢測、想把系統紀錄送進貴單位的 log 平台的時候。查下面那張表找到對應小節即可，不必整章讀完。

功能	需要什麼	封閉網路可用？
10.1 AI 功能	原廠提供的 API 金鑰	❌ 需連外網
10.2 Google 雲端硬碟整合	原廠提供的憑證	❌ 需連外網
10.3 GCB 檢測內容	出廠已內建，免設定	✅ 可用
10.4 寄信設定	貴單位的郵件伺服器	✅ 可用（內網郵件伺服器）
10.5 檢測 Agent	在被檢測主機安裝 Agent；系統這一側免設定	✅ 可用（連的是貴單位內網主機）
10.6 Log 轉發	貴單位自有的 log 伺服器（rsyslog／Graylog／ELK）	✅ 可用（連的是貴單位內網主機）

封閉網路 指的是這台機器完全連不到網際網路，只在貴單位內部網路裡。表格最後一欄就是在說：這項功能在那種環境下能不能用。

10.1 AI 功能¶

系統的 AI 助理與證據自動分類，需要一把外部 AI 服務的 API 金鑰才能運作。

API 金鑰 是呼叫外部服務時用的一組通行密碼。它同時也是計費憑證——外部服務靠它認人、也靠它算錢，所以外流等於別人可以拿去用、帳算在貴單位頭上。

🔴 金鑰不隨出貨包提供。 出貨包內不含任何金鑰——這是刻意的設計（金鑰一旦進了出貨包，就等於散佈給所有拿到出貨包的人）。金鑰在交付時或裝機後由原廠另行提供給貴單位。

設定步驟¶

向原廠索取 API 金鑰。
編輯設定檔（這一步在做什麼：打開系統的設定檔準備加一行）：

sudo vi /srv/guidant-ai/guidant.env

加入一行（把 <金鑰> 換成原廠提供的值）：

ANTHROPIC_API_KEY=<金鑰>

套用設定（這一步在做什麼：讓剛才加的那一行生效）：

sudo guidant start

🔴 這裡要用 start，不是 restart。設定值是在容器「建立」的那一刻寫進去的，restart 沒有重建容器，讀到的還是舊值——而且不會有任何錯誤訊息，看起來一切正常。詳見 4.3。（真的誤打了也不要緊：guidant restart 會偵測到設定比容器新並擋下來。）

成功長什麼樣：重啟後 guidant-api 健康，AI 相關功能可正常回應。

注意事項¶

⚠️ 未設定金鑰時，AI 功能的入口仍然存在。使用者按下去會等到逾時，然後看到一句籠統的「系統錯誤，請稍後再試」——這不代表系統壞了。請告知使用者：未購買／未設定 AI 功能時不要使用該入口。
這項功能需要主機能連上 api.anthropic.com（見第八章）。完全封閉的網路無法使用。
🔴 金鑰是計費憑證，請比照密碼保管。guidant.env 的權限維持 600、納入備份，勿散佈。
升級或重跑安裝不會覆寫您手動加進 guidant.env 的內容。

10.2 Google 雲端硬碟整合¶

這項功能在做什麼：讓系統自動從貴單位的 Google 雲端硬碟資料夾，把證據檔案同步進系統，不必人工一個個上傳。

需要三項憑證，由原廠提供（目前使用原廠的應用程式憑證，未來會替換為正式版本；替換時原廠會通知）：

向原廠索取三項值。
編輯 sudo vi /srv/guidant-ai/guidant.env，加入：

GOOGLE_DRIVE_OAUTH_CLIENT_ID=<原廠提供>
GOOGLE_DRIVE_OAUTH_CLIENT_SECRET=<原廠提供>
GOOGLE_DRIVE_OAUTH_REDIRECT_URI=<原廠提供，須與貴單位的站台網址一致>

套用設定（讓上面三行生效）：sudo guidant start

🔴 用 start 不是 restart——理由同上，見 4.3。 4. 登入系統 → 選單「系統管理」→「雲端空間整合」→ 依畫面指示完成授權。

OAuth 授權 是「讓系統代您去存取另一個服務」的標準授權流程：您在 Google 的畫面上按同意，Google 就發一張通行證給系統，系統日後拿這張通行證去讀資料夾，全程不需要、也拿不到您的 Google 密碼。第 4 步做的就是這件事。

成功長什麼樣：授權流程走完後回到系統畫面，該頁顯示已連結；之後系統就會自動同步指定資料夾的檔案。

注意事項¶

🔴 GOOGLE_DRIVE_OAUTH_REDIRECT_URI 必須與貴單位實際的站台網址一致（含通訊協定與埠），否則授權會被 Google 拒絕。索取時請把站台網址一併告知原廠。
授權完成後，系統會把存取權杖加密存進資料庫，加密金鑰在 guidant.env 內。該檔遺失 = 既有授權永遠解不開，必須重新授權（見第四章 4.7）。
需要連外網（googleapis.com 等）。封閉網路不啟用即可，不影響其他功能。

10.3 政府組態基準（GCB）檢測內容¶

這項功能在做什麼：系統可以檢查一台主機的設定有沒有符合安全規範。判斷依據就叫檢測基準（也稱 profile）——一份「這台機器該符合哪些設定」的檢查清單。

系統出廠就已內建 10 套檢測基準，安裝完成後直接可用，不需要任何匯入步驟：

政府組態基準（TWGCB）8 套：Windows Server 2016／2019／2022、Windows 11、Red Hat Enterprise Linux 8／9（兩版）、Ubuntu 22.04 LTS
dev-sec 公開範例 2 套：Linux 基準、Windows 基準

上面列的是被檢測的目標作業系統，也就是這些基準各自適用於哪一種機器，與 Guidant AI 本身裝在哪裡無關。

確認方式¶

以管理員身分登入 → 選單「合規與稽核」→「掃描設定檔管理」，應看到上述 10 套設定檔，狀態皆為可用；建立檢測任務時，「檢測 Profile 位置」下拉選單也會直接列出它們。

每套基準的控制項數與版本可在該頁查看，也可下載原始基準檔留存。

進階：自行上傳新的基準檔¶

若貴單位需要匯入自有的或更新版的基準檔（.tar.gz），系統支援在「掃描設定檔管理」頁自行上傳。

但請注意：上傳新檔需要主機端具備 CINC Auditor 解析工具。出廠映像檔為了縮減體積並未內含（內建的 10 套基準已在出廠前解析完成，故不受影響）。若需要此功能，請依下列步驟為主機加掛：

在宿主主機安裝 CINC Auditor（自 cinc.sh 取得對應作業系統的套件）。
在部署目錄建立（或編輯）docker-compose.override.yml，為後端服務加上唯讀掛載——這段設定在做什麼：把主機上剛裝好的 CINC Auditor 目錄接進容器裡，讓容器內的程式讀得到（:ro 代表唯讀，容器只能讀不能改）：

services:
  guidant-api:
    volumes:
      - /opt/cinc-auditor:/opt/cinc-auditor:ro

重新啟動後端服務（讓上面的掛載生效）：docker compose up -d guidant-api

成功長什麼樣：重啟後回「掃描設定檔管理」頁上傳基準檔，能成功解析並出現在清單裡。

掛載路徑固定為 /opt/cinc-auditor——系統的解析器原生就會搜尋此路徑，不需要另外設定環境變數。

未加掛 CINC 時，內建的 10 套基準完全不受影響（瀏覽、派送掃描、下載原始檔皆正常），只有「上傳新基準檔」這個動作會失敗。

10.4 寄信（SMTP）設定¶

這項功能在做什麼：系統要寄密碼重設信、到期通知這類信件，得先知道要透過哪一台郵件伺服器寄。這通常是貴單位內網的郵件伺服器，封閉網路一樣可用。

登入系統 → 選單「系統設定」→「郵件伺服器設定」→ 填入郵件伺服器位址、連接埠、帳號密碼、寄件者位址與名稱、是否使用 TLS。

填完請按該頁的「寄送測試信」，輸入一個收得到的信箱驗證真的寄得出去。

成功長什麼樣：那個信箱幾秒內收到一封測試信。這一步千萬別跳過——比等到有人忘記密碼才發現寄不出去好得多。

不設定的話系統不會寄任何信——使用者忘記密碼時需要由管理員在「系統管理」→「帳號管理」重設。

這一頁全系統共用同一組設定，不論由哪個單位維護，改的都是同一份。

這一頁與「LDAP伺服器設定」自 1.15.0 起可以下放給貴單位的管理員自行維護，不再限於原廠帳號；權限指派方式見第三章 3.9。

「通知設定」是另一頁，管的是 Discord／Telegram 這類即時通知管道，與寄信無關。兩頁不要混淆。

10.5 檢測 Agent（選用）¶

這項功能在做什麼：要對貴單位的主機做組態檢測（政府組態基準等基準掃描），或要讓上傳的檔案留在貴單位自己的主機上，就需要在那些主機安裝「檢測 Agent」——一支小程式，負責跑檢測與收送檔案。

系統這一側不需要任何設定：安裝程式在裝機時就已把對接金鑰、認證模式與對外位址備妥（見第二章 2.3 ④-3）。

接一台 Agent 的步驟¶

登入系統 → 選單「系統管理」→「Agent 管理」→ 產生一組註冊 token（一次性的通行碼，用來證明這台 Agent 是您授權接進來的；彈窗會一併顯示要填的雲端位址）。
到要安裝 Agent 的那台主機，執行 Agent 安裝程式，填入該 token 與雲端位址。
回到「Agent 管理」確認該台已出現且狀態為在線。

成功長什麼樣：第 3 步在清單裡看到那台主機，狀態顯示在線。

Agent 能做什麼是它自己回報的：Agent 上線後會隨著定期回報告訴系統它具備哪些能力（檔案儲存、組態檢測）。不需要任何人工開通步驟——裝對版本、正常上線，該用到它的地方（派送檢測任務、儲存設定的「使用 Agent 服務」選項）就會出現它。

派送檢測任務時若顯示「本租戶尚無可用的檢測 Agent」，代表沒有任何在線 Agent 回報過檢測能力。請確認 Agent 已上線，並確認它的版本夠新（過舊的版本不會回報能力，請向原廠索取新版）。

接不上時¶

這一步在做什麼：在系統主機上把這一側所有相關設定檢查一遍，找出是哪裡沒接好。

sudo guidant agent-check

成功長什麼樣：所有項目都標通過。有問題時它會逐項指出問題與修法，詳見第四章 4.9。

要備份的¶

Agent 對接金鑰在 <資料目錄>/pki/agent/，不在兩份設定檔內，請確認備份有涵蓋（見第四章 4.7）。遺失的後果是所有已註冊的 Agent 全部離線並需逐台重新註冊。

10.6 Log 轉發（選用）¶

這項功能在做什麼：把系統的紀錄自動送一份到貴單位自己的集中 log 平台（rsyslog／Graylog／ELK 這類）。接 SIEM 的客戶通常要的是「稽核事件」那一項——誰登入、誰改了什麼。這連的是貴單位內網的機器，封閉網路一樣可用。

系統這一側不需要任何安裝步驟，全部在畫面上設定，存檔後不必重啟服務。

設定步驟¶

先在貴單位的 log 伺服器上把接收端開好（rsyslog 的 input、Graylog 的 GELF／Syslog input、Logstash 的 syslog pipeline）。設定範例見《Log 轉發設定使用指南》第三章。
登入系統 → 選單「系統設定」→「Log 轉發設定」→ 填入協定（Syslog／GELF）、傳輸方式（UDP／TCP）、log 伺服器位址與連接埠，並勾選要送的內容（應用程式 log／稽核事件）。
按儲存，再按發送測試 log。
到 log 伺服器確認那則測試訊息真的收到了。

成功長什麼樣：第 4 步在 log 伺服器上看到一行 [Guidant AI] log 轉發測試訊息。

三個要先知道的行為¶

測試按鈕測的是「已儲存」的設定，不是畫面上剛打的字。表單有未儲存的變更時按鈕會反灰。
UDP 送出成功不等於對方收到（UDP 沒有回執）。畫面上會如實這樣寫，不會一律顯示「測試成功」。想要連線層的確認請選 TCP。
存檔後最多 30 秒全面生效（系統有多個服務程序，各自跟上）。存完立刻去 log 伺服器找不到訊息，先等半分鐘。

網路需求¶

貴單位主機之間需放行所選的埠與傳輸方式（UDP 或 TCP）。傳統的 syslog 埠 514 在 Linux 上需 root 權限才能監聽，手冊範例一律用高位埠 5514。

出狀況時¶

log 伺服器連不上、當機或位址填錯，都不會影響系統本身——本機紀錄照常寫入，只有送出去的那份副本會被丟棄。要確認系統這端有沒有在轉發：

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

完整的三家對接範例、送出內容格式與排錯對照表 → 《Log 轉發設定使用指南》（docs/user-manual/log-forwarding-guide.md，隨出貨包附上）。