一、安裝前的主機需求¶
這章在講什麼：這台機器夠不夠格裝 Guidant AI。
就像搬進新辦公室之前要先確認「電夠不夠、網路通不通、門進得去」，安裝程式在動任何東西之前，也會把整台機器檢查一遍。本章逐項說明它在檢查什麼、不合格會怎樣、以及怎麼補。
什麼時候看：裝機前必讀。想先確認機器沒問題再動手，跑
sudo ./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 位英數字 |
| 網路埠 | 80 與 443 沒有被別的程式佔用（也可以改用其他埠） | sudo ss -ltn |
| 資料目錄 | 建得起來、寫得進去（預設 /srv/guidant-ai） |
用 sudo 執行就會自動處理 |
| 系統指令 | openssl awk sed grep df 都在 |
一般發行版預設都有 |
| 執行身分 | 必須用 sudo 執行 |
— |
埠（port） 是主機上的「門牌號碼」——同一台機器可以跑很多服務，靠埠號區分誰是誰。一個埠同一時間只能給一個程式用，所以要先確認 80 和 443 沒被佔走。
這一步在做什麼：把上面所有項目一次檢查完，不做任何變更。
成功長什麼樣：畫面上每一項會標 ✓（通過）、⚠（警告，可以繼續）或 ✗（不通過，要修），最後一行是總結。
失敗長什麼樣：出現一個或多個 ✗。它會一次把所有問題列齊，不是撞到第一個就停——請把所有 ✗ 一起修完再重跑，不要修一個跑一次。
1.2 為什麼一定要 sudo¶
結論：因為安裝要動到系統層級的東西，一般帳號權限不夠。
具體來說，安裝要在 /srv 下建立系統目錄、寫入只有管理員讀得到的設定檔、設定容器讀得到的檔案擁有者，還要操作 Docker。這些都需要系統管理員權限。
好消息是：用 sudo 執行之後，目錄與檔案的擁有者全部由安裝程式自己設好——您不需要事先 mkdir，也不需要事後 chown。
唯一不需要 sudo 的是看用法：./install.sh --help。
1.3 Docker 沒有安裝怎麼辦¶
先說結論：安裝程式不會替您裝 Docker，它只會擋下並告訴您缺什麼。
這是刻意的。Docker 是主機層級的基礎軟體，由系統管理員依貴單位的政策自行安裝比較妥當——GitLab 等同類型產品的安裝程式也是同樣做法。
有網路的主機¶
以下指令依貴單位的 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
SUSE 官方套件庫的
docker-compose已經是 v2 版，也提供docker compose子命令。裝完請用docker compose version確認。
安裝完成後（所有發行版共通）¶
這三行在做什麼：第一行讓 Docker 開機自動啟動並立刻啟動它，後兩行確認版本夠新。
sudo systemctl enable --now docker
docker version # 應顯示 Server 版本 20.10 以上
docker compose version # 應顯示 v2 以上
成功長什麼樣：後兩行各印出一段版本資訊，數字符合上面的要求。
🔴
systemctl enable這一步不要省略。 沒有設定開機自起，主機重新開機後整套系統不會自動回來——而且您會以為是系統壞了。安裝程式檢查到未設定時會印警告，但不會擋下安裝。
封閉網路（沒有外網）的主機¶
封閉網路（air-gap） 指的是這台機器完全連不到網際網路，只在貴單位內部網路裡。這在政府與金融機關很常見，本系統完整支援。
沒有網路就下載不到 Docker 官方套件，請從下面三條擇一：
(A) 用發行版自帶的套件庫（貴單位有內部鏡像站時）——多數發行版內建的套件庫就有 Docker：
sudo apt-get install -y docker.io docker-compose-v2 # Debian / Ubuntu
sudo dnf -y install docker podman-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 系）。
(C) 用 Docker 官方的靜態二進位包（不分發行版，適合極精簡的系統）
從 https://download.docker.com/linux/static/stable/x86_64/ 下載 docker-<版本>.tgz，以及 compose plugin（https://github.com/docker/compose/releases），依官方說明解開放置。這條路需要自己寫開機啟動設定，建議在前兩條都行不通時才用。
三條路完成後同樣要跑
sudo systemctl enable --now docker，並確認docker compose version有輸出。
1.4 /etc/machine-id：最容易忽略、後果最隱蔽的一項¶
一句話：這個檔是這台機器的身分證號。授權檔是綁在這台機器上的，而「這台機器是誰」就是從這個檔算出來的。
這一步在做什麼：確認身分證號存在。
成功長什麼樣：回一串 32 個字元的英數字。
失敗長什麼樣：空白一行，或顯示檔案不存在。這種情形要先處理才能裝。
怎麼補（極精簡的容器化基底系統偶爾會缺，兩個指令擇一）：
🔴 只在「本來就沒有」的情況下補。
已經有值的機器絕對不要重新產生——重新產生等於這台機器換了一張身分證，既有的授權檔會立刻失效，必須重新向原廠申請。這比缺檔還糟糕。
也因為這個原因，安裝程式不會自動替您產生，只會擋下並提示。
缺檔時硬裝會怎樣（值得知道，因為症狀完全不指向真因）：Docker 會把掛載點建成一個目錄，系統讀不到身分證號，只好退而用網路卡位址代替——而容器每次重啟位址都不一樣，於是機器碼每重啟一次就變一次，原廠簽發的授權檔永遠對不上。您會以為是授權出了問題。所以務必事前檢查。
1.5 硬體建議值（不足只警告，不擋安裝）¶
| 項目 | 建議值 | 不足時會怎樣 |
|---|---|---|
| 磁碟可用空間 | 40 GB 以上（看的是資料目錄所在的那個分割區，不是根目錄） | 映像檔約 3 GB，其餘是資料庫、上傳檔、記錄檔與備份。空間耗盡時資料庫會停止寫入 |
| 記憶體 | 8 GB 以上 | 可能回應緩慢；匯入大檔或匯出報表時可能因記憶體不足被系統強制終止 |
| CPU | 4 核以上 | 多人同時使用、或背景在跑分析時會明顯變慢 |
不足時安裝程式會印黃色警告然後繼續安裝——測試環境、小型試用、切一半的虛擬機都是正常的使用情境，不應該被建議值擋住。
但警告內容請留意：日後若出現效能問題，要能連回這裡。
1.6 時區¶
主機的時區應該跟系統部署的時區一致（預設 Asia/Taipei）。
這一步在做什麼：查目前設定的時區。
成功長什麼樣：回 Asia/Taipei（或貴單位實際使用的時區）。
不一致時安裝程式會印警告。建議統一——系統內部有時間比對的邏輯（例如判斷檢測 Agent「是不是還在線」），時區不一致會讓某些判定出現偏差，而這種故障很難從症狀連回時區。
要改用其他時區，在安裝設定檔的 TZ 欄指定（見 第二章）。
1.7 網路埠¶
結論：系統對外只開一個入口。
只有 guidant-fe（網站）的 80 與 443 對外。其餘服務（資料庫、Redis、後端、檔案儲存）都躲在容器內部網路裡，不對外開放任何埠。
這一步在做什麼：確認 80 與 443 沒被佔用。
成功長什麼樣：什麼都沒印出來。
失敗長什麼樣：印出一行或多行，代表已經有別的服務（例如既有的 nginx、Apache）在用那個埠。這時可以在安裝時改用其他埠——見 第二章 2.5。
1.8 這台機器上已經有一套 Guidant AI 了？¶
安裝程式會偵測資料目錄裡是不是已經有一套安裝（找 guidant.env 或 certs/server.key 這兩個檔）。有就停下、絕不覆寫，並給您四條明確的路：
- 要換版 → 改用
sudo ./install.sh --upgrade（見 第五章） - 要在這台機器重裝一套 → 先備份、確認舊資料真的不再需要之後清空該目錄（🔴 資料會永久消失），再重跑
- 要與既有安裝並存 → 換一個資料目錄
- 先前安裝在後段失敗、要沿用已產生的設定重跑 → 依畫面提示的指令執行
為什麼擋得這麼嚴：覆寫既有安裝的設定檔，會導致原本的資料庫連不上、加密過的資料永遠解不開，而且不會有任何提示。這就是為什麼安裝程式在這件事上完全不肯自作主張。