一、安裝前的主機需求¶
這章在講什麼：這台機器夠不夠格裝檢測 Agent。
就像新人報到前要先確認「座位有沒有、門禁卡辦了沒、網路通不通」，安裝程式在動任何東西之前，也會把整台機器檢查一遍。本章逐項說明它在檢查什麼、不合格會怎樣、以及怎麼補。
什麼時候看：裝機前必讀。想先確認機器沒問題再動手，跑
./install.sh --check-only就好——那個指令只看不改，也不需要管理員權限，很安全。
檢查項目分成兩類，先分清楚可以省很多焦慮：
- 硬性前提：不符合就裝不起來，安裝程式會擋下不讓您繼續。
- 建議值：不符合只會印一行警告，安裝照常進行——影響的是快不快、穩不穩，不是能不能用。
貴單位要裝好幾台的話：本章的檢查每一台都要各自跑一次——硬性前提是逐台認定的，一台通過不代表另一台也通過（磁碟、埠、機器識別碼都是各機器獨立的）。裝多台的整體說明見手冊首頁。
1.1 硬性前提（不符合會被擋下）¶
| 要檢查的 | 要求是什麼 | 自己先確認的指令 |
|---|---|---|
| 作業系統 | Linux | uname -s 應回 Linux |
| CPU 架構 | x86_64（amd64），一般伺服器用的架構 | uname -m 應回 x86_64 |
| Docker Engine | 20.10 以上，而且服務正在執行 | docker version |
| Docker Compose | plugin v2（指令是 docker compose，中間是空格不是減號） |
docker compose version |
| 機器識別碼 | /etc/machine-id 存在且不是空檔 |
cat /etc/machine-id 應回一串 32 位英數字 |
| 硬體序號 | /sys/class/dmi/id/product_uuid 存在且不是空檔 |
sudo cat /sys/class/dmi/id/product_uuid |
| 網路埠 | 8443 沒有被別的程式佔用（另有三個只給本機用的埠，見 1.6） | sudo ss -ltn |
| 磁碟空間 | 12 GB 以上（看的是 Docker 儲存目錄所在的那個分割區） | df -h /var/lib/docker |
| 系統指令 | openssl sha256sum awk sed grep df date install 都在 |
一般發行版預設都有 |
| 執行身分 | 安裝必須用 sudo 執行 |
— |
Docker 是一種把程式連同它需要的環境整包起來執行的軟體，是業界標準工具。您不需要懂 Docker 才能操作 Agent。
埠（port） 是主機上的「門牌號碼」——同一台機器可以跑很多服務，靠埠號區分誰是誰。一個埠同一時間只能給一個程式用。
這一步在做什麼：把上面所有項目一次檢查完，不做任何變更。
成功長什麼樣：畫面上每一項會標 ✓（通過）、⚠／—（警告或未驗，可以繼續）或 ✗（不通過，要修）。
失敗長什麼樣：出現一個或多個 ✗。它會一次把所有問題列齊，不是撞到第一個就停——請把所有 ✗ 一起修完再重跑，不要修一個跑一次。
用一般帳號跑
--check-only時，硬體序號那一項會標成「未驗」（那個檔只有系統管理員讀得到）。這是正常的，實際安裝時用sudo執行就會驗到。
1.2 為什麼安裝要 sudo¶
結論：因為安裝要動到系統層級的東西，一般帳號權限不夠。
具體來說，安裝要操作 Docker、寫入只有管理員讀得到的設定檔、在 /etc 下留一份安裝位置紀錄，還要讀取只有管理員讀得到的硬體序號（/sys/class/dmi/id/product_uuid，那是設備指紋的來源之一）。
用一般帳號執行會跑到一半才失敗，所以安裝程式乾脆在開頭就先擋下。
唯二不需要 sudo 的是 ./install.sh --help（看用法）與 ./install.sh --check-only（檢查機器）。
1.3 Docker 沒有安裝怎麼辦¶
先說結論：安裝程式不會替您裝 Docker，它只會擋下並告訴您缺什麼。
這是刻意的。Docker 是主機層級的基礎軟體，由系統管理員依貴單位的政策自行安裝比較妥當。
有網路的主機¶
以下指令依貴單位的 Linux 發行版擇一。每一種都需要 docker-compose-plugin（它提供 docker compose 指令），不是舊版那個獨立的 docker-compose。
這幾行在做什麼：把 Docker 官方套件庫加進系統，然後安裝 Docker 與相關元件。
Ubuntu / Debian
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" \
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Debian 主機請把上面兩處
linux/ubuntu改成linux/debian。
RHEL / Rocky Linux / AlmaLinux / CentOS Stream
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
SUSE Linux Enterprise / openSUSE
安裝完成後（所有發行版共通）¶
這三行在做什麼：第一行讓 Docker 開機自動啟動並立刻啟動它，後兩行確認版本夠新。
sudo systemctl enable --now docker
docker version # 應顯示 Server 版本 20.10 以上
docker compose version # 應顯示 v2 以上
成功長什麼樣：後兩行各印出一段版本資訊，數字符合上面的要求。
🔴
systemctl enable這一步不要省略。 沒有設定開機自起，主機重新開機後 Agent 不會自動回來——平台會把它標成離線，排定的檢測任務全部不會執行，而且不會有人通知您。
封閉網路（沒有外網）的主機¶
封閉網路（air-gap） 指的是這台機器完全連不到網際網路，只在貴單位內部網路裡。這在政府與金融機關很常見，Agent 完整支援。
沒有網路就下載不到 Docker 官方套件，請從下面兩條擇一：
(A) 用發行版自帶的套件庫（貴單位有內部鏡像站時）：
sudo apt-get install -y docker.io docker-compose-v2 # Debian / Ubuntu
sudo dnf -y install docker # RHEL 系（需確認版本 ≥ 20.10）
(B) 從有網路的機器下載離線安裝包，再帶進來
- 在有網路的同發行版、同版本機器上下載套件：
- Debian / Ubuntu：
sudo apt-get install --download-only docker-ce docker-ce-cli containerd.io docker-compose-plugin，套件會落在/var/cache/apt/archives/*.deb - RHEL 系：
sudo dnf download --resolve docker-ce docker-ce-cli containerd.io docker-compose-plugin - 把
.deb/.rpm檔複製到目標主機（隨身碟即可）。 - 安裝：
sudo dpkg -i *.deb（Debian 系）或sudo rpm -Uvh *.rpm（RHEL 系）。
兩條路完成後同樣要跑 sudo systemctl enable --now docker，並確認 docker compose version 有輸出。
Agent 本身完全不需要連外網——出貨包內已經含全部映像檔，安裝過程離線自足。需要連外網的只有「安裝 Docker」這一步而已。
1.4 設備指紋的兩個來源：最容易忽略、後果最隱蔽的一項¶
一句話：平台用「設備指紋」認出這是哪一台 Agent，就像用指紋認人。這個指紋是由這台機器的兩個身分識別檔算出來的。
| 檔案 | 白話：它是什麼 |
|---|---|
/sys/class/dmi/id/product_uuid |
主機板（或虛擬機）的硬體序號 |
/etc/machine-id |
作業系統安裝當下產生的機器識別碼 |
這一步在做什麼：確認兩個來源都在。
成功長什麼樣：兩行各印出一串字。
失敗長什麼樣：其中一行是空白，或顯示檔案不存在。
/etc/machine-id 缺了怎麼補（極精簡的基底系統偶爾會缺，兩個指令擇一）：
🔴 只在「本來就沒有」的情況下補。
已經有值的機器絕對不要重新產生——那等於這台機器換了一張身分證，平台會把它當成一台全新的 Agent，原本這台的證據檔索引與儲存設定都會對不上。
也因為這個原因，安裝程式不會自動替您產生，只會擋下並提示。
缺檔時硬裝會怎樣（值得知道，因為症狀完全不指向真因）：Agent 會拿空字串去算指紋，安靜地算出另一個身分。症狀是「平台上莫名多出一台陌生的新 Agent」，而錯誤訊息完全不會提到這個檔。所以安裝程式在這一項採硬擋。
1.5 硬體建議值（不足只警告，不擋安裝）¶
| 項目 | 建議值 | 不足時會怎樣 |
|---|---|---|
| 磁碟可用空間 | 12 GB 是硬性下限；實際請依證據檔的量估算，建議預留 50 GB 以上 | 映像檔約 3.3 GB、出貨包本身約 1.3 GB，其餘全是證據檔。空間耗盡時檢測報告會存不進去 |
| 記憶體 | 4 GB 以上 | 大型掃描（尤其是原始碼分析）可能因記憶體不足被系統強制終止 |
| CPU | 2 核以上 | 多個檢測任務同時跑時會明顯變慢 |
磁碟空間要看得比下限遠。 12 GB 只是「裝得起來」的門檻。證據檔會持續累積而且不會自動清理，請依貴單位的稽核頻率與保存年限估算實際需要多少。
1.6 網路埠¶
結論：Agent 用到四個埠，但只有一個對外。
| 埠 | 開給誰 | 用途 | 誰會來連 |
|---|---|---|---|
| 8443 | 所有介面（對外） | 平台回頭取證據檔（雙向憑證驗證） | Guidant AI 平台 |
| 8333 | 只綁 127.0.0.1（只有本機） |
內建儲存的檔案存取介面 | 只有本機的 Agent 自己 |
| 8888 | 只綁 127.0.0.1 |
內建儲存的檔案瀏覽介面 | 只有本機 |
| 9333 | 只綁 127.0.0.1 |
內建儲存的管理介面 | 只有本機 |
127.0.0.1是「這台機器自己」的固定位址。綁在這個位址上的服務，外面的機器一律連不到，不需要為它們做任何防火牆設定。
這一步在做什麼：確認 8443 沒被佔用。
成功長什麼樣：什麼都沒印出來。
失敗長什麼樣：印出一行，代表已經有別的服務在用 8443。這時可以在安裝時用設定檔改用其他埠（見 第三章 3.5）。
防火牆要放行 8443 的連入，來源限定 Guidant AI 平台的位址就好。詳見 第九章。
1.7 時區與時間¶
主機的時區應該跟平台一致（通常是 Asia/Taipei）。
但更重要的是時間本身要準：
成功長什麼樣：回 yes，代表主機有在跟時間伺服器對時。
🔴 主機時鐘偏差會讓 Agent 取不到證據檔，而且症狀完全不指向時間。
平台每次來取檔都會現場簽發一張效期只有 60 秒的通行證，Agent 收到後會核對時間。兩端時鐘差超過一分鐘，這張通行證在 Agent 眼中不是「還沒生效」就是「已經過期」——結果是：註冊與心跳一切正常、平台上顯示在線，但一下載證據檔就失敗。
請確認主機有啟用 NTP 校時（一種讓電腦自動跟標準時間伺服器對時的機制）。
1.8 這台機器上已經有一個 Agent 了？¶
安裝程式會偵測安裝目錄裡是不是已經有設定檔（.env）。有的話，它會沿用現有答案當預設值重跑一次，資料完全不動。
所以「重跑安裝來修正某一個填錯的值」是被支援的做法——直接重跑即可，要改的那題填新值、其餘按 Enter 沿用。
要在同一台機器上裝第二個獨立的 Agent（很少見）請聯繫原廠：兩個 Agent 在同一台機器上會算出相同的設備指紋，需要另行規劃。