Guidant AI 檢測 Agent — 安裝與維運手冊¶
這本手冊寫給誰：負責在貴單位機房把檢測 Agent 裝起來、之後照顧它的 IT 人員。
需要什麼底子：會用 Linux 終端機、會複製貼上指令，這樣就夠了。不需要懂本系統的內部設計，也不需要用過 Docker——本手冊每一段指令都可以整行複製貼上，而且每一步都寫明「執行前這步在做什麼」與「執行後應該看到什麼」。
適用範圍：Linux 主機，以 Docker 方式安裝的檢測 Agent。同一個單位可以裝多台（不同機房、不同網段各裝一台），每一台都照這本手冊走一遍就好，詳見下面「貴單位可以裝多台 Agent」。
本手冊可向原廠索取最新版本。 出貨包內另附一份極簡版快速指引（
INSTALL.txt）與部署參考（README.md），內容與本手冊一致但比較精簡。
變更紀錄
| 日期 | 內容 |
|---|---|
| 2026-08-23 | 首版：主機需求、檢測環境準備、安裝、開通、日常維運、證據檔儲存位置、升級、解除安裝、網路需求、排錯、憑證與金鑰全景清單 |
| 2026-08-23 | 全書改寫為白話版：每章補「這章在講什麼」導言、術語首次出現加白話註解、指令前後補「這步在做什麼／成功長什麼樣」、結論前置。指令內容一字未改 |
| 2026-09-03 | 對齊 Agent 1.0.0（安裝形態改版＋脫離 0.x 準備發佈，FR-073）：安裝落點由「解開出貨包的目錄」改為固定的 /srv/guidant-ai-agent，解壓目錄裝完可整個刪除（第三章）；過程紀錄移到 /var/log/guidant-ai-agent/ 且不隨解除安裝被刪（三、七、八章）；解除安裝改為一併清掉安裝目錄（第八章）；資料區名稱固定為 guidant-ai-agent_*（五、十章）；升級不再需要記得加參數——安裝程式自行判斷首裝／升級／舊形態遷移（三、七章）。舊形態的安裝由新版安裝程式自動遷移，不需人工處理 |
| 2026-08-27 | 對齊 Agent 0.2.30 出貨版：安裝與開通章的映像名、安裝目錄、status 輸出示例版號更新（0.2.28 → 0.2.30）。新增「貴單位可以裝多台 Agent」一節（適用範圍、逐台裝機的差異、顯示名稱命名建議），第一章補逐台檢查提醒——對應 v1.16.0 起平台端支援一個檢測任務指派多台 Agent |
先看這一頁：Agent 是什麼、為什麼需要它¶
一句話：Agent 是貴單位派駐在自己網路裡的一名檢測員。
Guidant AI 平台本身不會直接連進貴單位的機器做掃描。所有檢測動作都由這支「檢測 Agent」代為執行——它裝在貴單位自己的網路內，主動向平台領取工作、在貴單位內部完成掃描、把報告存回來。
Guidant AI 平台 貴單位內部網路
┌──────────────┐ ┌──────────────────────────────┐
│ │ ① Agent 主動撥出 │ 檢測 Agent（本手冊安裝的） │
│ （雲端或 │ ◀──────────────────│ │
│ 貴單位自建 │ 領工作、回報狀態 │ │ │
│ 的落地版） │ │ │ ② 由這裡發動掃描 │
│ │ ③ 平台回頭取證據檔 │ ▼ │
│ │ ──────────────────▶ │ 受測主機／網段／自建服務 │
└──────────────┘ （雙向憑證驗證） └──────────────────────────────┘
這樣設計的好處：貴單位不需要把內部主機開放給外部連線。只要讓 Agent 這一台機器連得出去、以及讓平台連得回這一台機器就夠了。
雙向憑證驗證（mTLS）：兩邊互相出示電子身分證明才放行的加密連線——就像門禁卡，不是只有訪客要刷卡，門也要向訪客證明自己是對的那扇門。平台與 Agent 之間全程走這種連線。
Agent 由兩個服務組成：
| 服務名 | 白話：它負責什麼 |
|---|---|
guidant-ai-agent |
Agent 主程式——領工作、跑檢測、把證據檔交給平台 |
guidant-agent-seaweedfs |
內建的證據檔倉庫（可以改用貴單位自有的儲存，見第六章） |
您不需要分別操作這兩個服務。 安裝、啟動、停止、升級、移除——全部走同一支腳本 install.sh 的子命令。
第一次安裝要走完這五步¶
第二章可以跟其他步驟同時進行——受測主機的準備工作通常由不同的人負責，而且不影響 Agent 本身裝不裝得起來。但沒做完就跑不了檢測任務，請不要略過。
貴單位可以裝多台 Agent¶
一句話：一台 Agent 只掃得到它自己連得上的範圍，所以網段被切開時就多裝幾台。
常見的情形是這樣：貴單位有台北、台中兩個機房，兩邊網路互不相通；或是同一棟樓裡辦公網段與伺服器網段被防火牆隔開。這時一台 Agent 掃不到另一邊——不是它壞了，是網路本來就走不過去。做法是兩邊各裝一台，各自負責自己碰得到的那一段。
自 v1.16.0 起，平台端可以在同一個檢測任務裡指定多台 Agent，每一台各自負責一組掃描目標，按一次「開始執行」就同時派工出去，全部回報完才算這次檢測完成。
裝多台跟裝一台的差別¶
裝機這一側幾乎沒有差別——每一台都是獨立的一台機器，各走各的流程：
| 步驟 | 多台的時候怎麼做 |
|---|---|
| ① 檢查主機（第一章） | 每一台各自檢查。硬性前提是逐台認定的，一台過不代表另一台過 |
| ② 準備檢測環境（第二章） | 各自準備自己要掃的那一段受測主機 |
| ③ 取得註冊憑證（4.1） | 同一組憑證可以重複用，不必每台各要一組（憑證屬於整個單位，不是屬於某一台） |
| ④ 執行安裝（第三章） | 每一台各自跑一次 install.sh。要裝很多台時可用 3.5 的設定檔方式省下逐題作答 |
| ⑤ 註冊上線（4.2） | 每一台各自向平台報到，平台清單上會出現各自獨立的一列 |
🔴 顯示名稱請取得一眼分得出來（安裝時的第 4 題，例如「台北機房-掃描」「台中機房-掃描」）。平台端指派工作時，畫面上就是靠這個名字挑機器的；全部叫預設主機名會很難分。
⚠️ 從同一份虛擬機模板複製出多台時，
/etc/machine-id會整批相同，第二台註冊會被平台擋下。預防方式見 4.3 的說明。
平台端要做什麼¶
裝好、註冊上線之後，剩下的都在平台上操作：進任務設置的檢測工具設定，加上幾組「哪一台 Agent、掃哪些目標」，儲存後按開始執行即可。
平台端的操作細節不在本手冊範圍——這本手冊只講裝機這一側。請參閱產品使用手冊的檢測工具章節，或洽原廠。
章節導覽¶
| 章 | 這章在講什麼 | 什麼時候看 |
|---|---|---|
| 一、安裝前的主機需求 | 這台機器夠不夠格裝：作業系統、Docker、機器身分、網路埠、硬體建議值 | 裝機前必讀 |
| 二、檢測環境準備 | 哪個檢測工具的引擎裝在哪裡、受測主機要準備什麼、稽核帳號的最小權限建議 | 裝機前必讀，可與其他步驟同時做 |
| 三、安裝 | 解開出貨包 → 回答四個問題 → 看懂每一步的畫面 | 第一次安裝 |
| 四、開通（與平台綁定） | 取得註冊憑證、核對平台憑證指紋、確認上線、在平台端指定這台 Agent | 安裝前後 |
| 五、日常維運 | 查狀態／看記錄／重啟／查設備指紋／備份 | 平時 |
| 六、證據檔存在哪裡 | 出廠預設、改用自有儲存、恢復內建、資料保護的責任分工 | 要換儲存時、規劃備份時 |
| 七、升級 | 一條指令換版；資料完全不動 | 收到新版出貨包時 |
| 八、解除安裝 | 移除 Agent | 要下線或重裝時 |
| 九、網路需求與對外連線 | 要開哪些埠、完全沒有外網可不可以用 | 規劃防火牆時 |
| 十、排錯 | 常見症狀對照表、要傳給原廠的紀錄檔 | 出狀況時 |
| 十一、附錄：憑證與金鑰全景 | 整套系統一共有哪些憑證與金鑰、各自放哪、換掉會影響什麼 | 資安審查、換憑證、深入排錯時 |
出貨包裡有什麼¶
出貨包解開之後，會看到這些東西：
guidant-agent-compose-<版號>/
├── install.sh ← 您要執行的就是這一支
├── INSTALL.txt ← 極簡版快速指引（三步）
├── README.md ← 部署參考手冊
├── docker-compose.yml ← 服務定義（不需要手動編輯）
├── .env.example ← 設定檔範本（安裝程式會自動產生實際的 .env）
├── image-manifest.sha256 ← 映像檔的出貨清單（安裝時逐一比對）
├── guidant-ai-agent-<版號>.image.tar ← Agent 程式映像（約 1.3 GB）
├── chrislusf-seaweedfs-<版號>.image.tar ← 內建儲存服務映像
└── content/cache/ ← 檢測內容的快取目錄（必須存在，勿刪）
映像檔（image） 是容器的「安裝母片」——安裝時會把它載進 Docker 裡變成實際在跑的服務。出貨清單（
image-manifest.sha256） 記的是每個檔案的指紋，安裝時逐一比對，用來確認檔案沒有在傳送途中損壞、也沒有被人換過。
安裝過程還會在同一個目錄下產生：.env（設定檔，只有管理員讀得到）、certs-in/（平台憑證信任檔）、factory/（出廠儲存設定快照）、install-<日期時間>.log（安裝紀錄）。
交付包只有一種，第一次安裝與日後升級都用同一顆。 向原廠索取出貨包時不需要說明「我是要裝新的還是要升級」。
求助時請提供什麼¶
聯繫原廠技術支援時，一併附上這三樣，可以省掉一輪來回：
- 安裝紀錄檔：安裝目錄下的
install-*.log（升級的話是upgrade-*.log，取最新的那一個）。這個檔不含任何密碼，可以直接當郵件附件寄出。 - 服務狀態：
sudo guidant-agent-compose status的畫面內容。 - 症狀描述與發生時間。
🔴 請勿提供設定檔（
.env）的內容、註冊憑證，或儲存空間的帳號密碼。原廠協助排錯用不到這些。