二、安裝¶
這章在講什麼：把系統實際裝進這台機器。
就像組裝一套辦公設備：先確認箱子沒被拆過（校驗）、拆箱（解壓縮）、通電開機（執行安裝）、最後照說明書把機器設定好。整個過程有一支安裝程式全程代勞，您要做的只是回答三個問題，然後看著它跑完。
什麼時候看：第一章的檢查全部通過之後。整個安裝過程約 5～15 分鐘，多數時間花在載入映像檔（安裝母片）。
2.1 解開出貨包¶
先說結論：拆箱之前先驗一次，確認這個檔案跟原廠寄出時一模一樣。
原廠給您的出貨包是一個 .tar.gz 壓縮檔，旁邊會附一個同名的 .sha256 檔。那是校驗檔（原始檔案的指紋紀錄）——把手上這份壓縮檔重新算一次指紋，跟紀錄比對，就知道有沒有在傳遞途中損壞或被人動過手腳。
這兩步在做什麼：第 ① 步驗指紋，第 ② 步解壓縮並進到解開後的資料夾。
# ① 先驗整包沒有在傳輸途中損壞或被替換
sha256sum -c guidant-ai-1.16.0.tar.gz.sha256
# ② 解開
tar -xzf guidant-ai-1.16.0.tar.gz
cd guidant-ai-1.16.0
成功長什麼樣：第 ① 步輸出 guidant-ai-1.16.0.tar.gz: OK。
失敗長什麼樣：第 ① 步輸出 FAILED。這時請不要繼續安裝，直接向原廠重新索取出貨包。
版號會隨出貨版本不同，請以實際檔名為準。
解開後目錄內容見 手冊首頁「出貨包裡有什麼」。
2.2 執行安裝（互動模式）¶
這一步在做什麼：啟動安裝程式。它會先問您三個問題，然後開始安裝。
成功長什麼樣：畫面出現下面三個問題。中括號裡是預設值，直接按 Enter 就是採用預設值。
這三個問題怎麼答：
| 問題 | 這是什麼 | 填錯會怎樣 |
|---|---|---|
| 主機名稱或 IP | 使用者日後在瀏覽器網址列輸入的位址。這個值會寫進 HTTPS 憑證（電子身分證明），也會成為系統寄出的通知信裡連結的基準。有內部網域名稱就填網域，沒有就填 IP。 | 瀏覽器會多一層「憑證名稱不符」的警告，且通知信的連結會指向錯誤位址。 |
| 資料存放目錄 | 上傳的檔案、記錄檔、憑證、設定檔與備份都放這裡。請放在空間足夠的分割區。資料庫本身另外存在 Docker 的資料區，不在這個目錄下。 | 分割區空間不夠時日後會寫不進資料。 |
| 對外 HTTPS port | 系統對外的門牌號碼。主機的 443 已被其他服務佔用時才需要改。 | 沿用被佔用的埠會啟動失敗。 |
安裝程式不會問您密碼。 所有服務之間互連用的密碼，都由安裝程式自動產生、直接寫進只有系統管理員讀得到的設定檔。這是刻意的設計：您手動輸入的密碼會留在終端機畫面與指令歷史紀錄裡，反而不安全。
您自己的管理員帳號密碼是稍後在瀏覽器裡設定的，見 第三章。
2.3 安裝過程中畫面會出現什麼¶
安裝分八個大步驟（其中第 ④ 步分成三小段），每一步都會印出結果。以下逐步說明它在做什麼、成功長什麼樣。
① 環境檢查¶
這一步在做什麼：把 第一章 那些主機條件再逐項檢查一次。
成功長什麼樣：一連串 ✓，最後一行 ✓ 環境檢查通過。
其他情形：出現 ⚠（硬體規格建議值不足）時安裝會繼續。出現 ✗ 時安裝會中止——這一步不做任何變更，修正後可以安心重跑。
② 載入映像¶
這一步在做什麼：把系統的映像檔（安裝母片，六個檔）載進 Docker。載入前逐一比對每個檔的雜湊（sha256，檔案指紋），符合才載。
成功長什麼樣：每個檔案一行 ✓ ... 完整性符合，共六個檔。
🔴 任一檔不符會直接拒絕安裝（不是警告後繼續）。這是防止出貨包在傳遞途中被替換的最後一道防線。遇到這個情形請向原廠重新索取出貨包，不要嘗試繞過。
③ 產生密碼與金鑰¶
這一步在做什麼：替這台機器產生八組互相獨立的憑證——資料庫管理帳號、資料庫業務帳號、Redis、登入簽章金鑰、兩支資料加密金鑰、檔案儲存兩項。
成功長什麼樣：✓ 已產生 8 組獨立憑證，以及「這些值只寫入設定檔（權限 600），不會顯示在畫面上」。
每一台安裝的密碼都是不同的。出貨包裡不含任何憑證，沒有「預設密碼」，也沒有跨客戶共用的私鑰。
④ 寫入設定檔¶
這一步在做什麼：把上一步產生的值，寫成兩份設定檔放進資料目錄。
| 檔案 | 用途 |
|---|---|
<資料目錄>/.env |
建立服務時用（資料庫帳密、版號、路徑） |
<資料目錄>/guidant.env |
系統執行時用（連線帳密、金鑰、功能開關） |
兩者權限都是 600、擁有者 root，也就是只有系統管理員讀得到。
🔴 請把這兩個檔納入備份。 遺失就再也連不上既有的資料庫，而且既有的加密資料（Google 雲端硬碟授權、檢測工具憑證）永遠解不開。
④-2 產生 HTTPS 憑證¶
這一步在做什麼：為這台機器簽一張專用的自簽憑證（自己幫自己簽的身分證明，能加密連線，但瀏覽器不認得它）。
成功長什麼樣：✓ 已產生自簽憑證。
為什麼一定要 HTTPS：不只是「比較安全」。設定精靈裡的「複製機器碼」按鈕用的是瀏覽器的剪貼簿功能，該功能只在 HTTPS 下存在；純 HTTP 下按了不會有任何反應也不會有錯誤訊息。
④-3 產生檢測 Agent 對接金鑰¶
這一步在做什麼：先把「檢測 Agent」要用的金鑰備妥。檢測 Agent 是安裝在被檢測主機上、負責跑組態檢測與收送檔案的小程式；系統這一側需要一組專用金鑰才能跟它對接。安裝程式會自動備妥，您不需要做任何設定。
成功長什麼樣：
金鑰共六個檔，放在 <資料目錄>/pki/agent/。
🔴 這組金鑰請一併納入備份。它不在
.env與guidant.env這兩份設定檔內，是獨立的一個目錄；遺失的後果是所有已註冊的檢測 Agent 全部離線，而且必須逐台重新註冊。重跑安裝或升級時不會覆蓋既有金鑰——覆蓋等於重新簽發，已註冊的 Agent 會全部失效。
不打算使用檢測 Agent 時，這一步產生的金鑰放著不用即可，不影響任何其他功能。要接 Agent 時見 第十章 10.5。
⑤ 建立資料庫¶
這一步在做什麼：啟動資料庫，跑一次性的初始化程序（建立資料表、權限、基礎資料）。這一步耗時較久，約 1～3 分鐘，畫面停住是正常的。
成功長什麼樣：✓ 資料庫初始化完成。
⑥ 設定物件儲存¶
這一步在做什麼：啟動內建的物件儲存（專門放檔案的服務，類似公司內部的雲端硬碟）、建立儲存空間，並把隨包附上的系統內建檔案（合規框架 PDF）灌進去。
成功長什麼樣：✓ 儲存空間 guidant-ai 已備妥、✓ 系統檔已灌入（N 個…）、✓ 檔案儲存已指向內建物件儲存。
⑦ 啟動服務¶
這一步在做什麼：把六個服務一一啟動，並等它們回報健康。
成功長什麼樣：六行 ✓ <服務名> 健康（guidant-socketio 那行是「執行中」，它沒有健康檢查）。
⑧ 安裝完成¶
這一步的畫面請不要關掉，上面有兩樣接下來馬上要用的東西：
════════════════════════════════════════════════════════════
Guidant AI 已安裝完成，接下來請用瀏覽器完成設定
════════════════════════════════════════════════════════════
1. 開啟瀏覽器，前往：https://192.168.1.50
（首次進入會看到憑證安全警告，這是自簽憑證的正常現象，選擇繼續前往即可）
2. 在設定精靈第一步貼上這組一次性設定碼：
a1b2c3d4e5f6...
3. 依精靈指示建立管理員帳號並取得本機授權指紋。
─ 授權指紋 ───────────────────────────────────────────────
申請授權檔時請提供這串（與設定精靈頁顯示的相同）：
9f8e7d6c...（64 個字元）
畫面關掉了也不要緊，兩樣東西都查得回來。
設定碼用過即失效。需要再看一次：
機器碼（授權指紋）隨時可重新查看：
畫面接著還會印出兩段備忘，那些是後續才會用到的資訊，當下不需要做任何事：
接著請翻到 第三章。
2.4 憑證安全警告是正常的¶
先說結論：第一次用瀏覽器開站台一定會跳警告，這是預期行為，不是安裝失敗。
畫面上會寫「您的連線不是私人連線」或「憑證無效」之類的字。原因是安裝程式為這台機器簽的是自簽憑證：它能提供加密連線，但不是由公開的憑證機構簽發的，所以瀏覽器不認識它、只好先警告您。
處理方式：點「進階」→「繼續前往（不安全）」即可。
換成貴單位的正式憑證（選用）¶
若貴單位有內部憑證機構、或已為此網域申請了公開憑證，可以換上，換完瀏覽器就不會再警告。
這三步在做什麼：① 把現在的自簽憑證另存一份備份，② 用您的正式憑證覆蓋過去並設好權限，③ 重啟網站服務讓它讀到新憑證。
# ① 備份現有的自簽憑證
sudo cp /srv/guidant-ai/certs/server.crt /srv/guidant-ai/certs/server.crt.selfsigned
sudo cp /srv/guidant-ai/certs/server.key /srv/guidant-ai/certs/server.key.selfsigned
# ② 換上正式憑證（檔名必須完全一致）
sudo cp <您的憑證檔>.crt /srv/guidant-ai/certs/server.crt
sudo cp <您的私鑰檔>.key /srv/guidant-ai/certs/server.key
sudo chmod 600 /srv/guidant-ai/certs/server.key
sudo chmod 644 /srv/guidant-ai/certs/server.crt
# ③ 重啟網站服務讓它讀新憑證
sudo guidant restart guidant-fe
這裡用
restart是對的：憑證檔是掛進容器的，換檔之後讓服務重讀即可，不需要重建容器。（restart只有在改過設定檔時才不夠用，見 4.3。）
成功長什麼樣：重啟後 guidant-fe 健康，而且用瀏覽器開站台不再出現警告。
注意事項：
- 檔名與路徑不可改（
server.crt／server.key），系統是照這兩個固定路徑讀的。 - 憑證檔若有中繼憑證（憑證機構之間的接力證明），請把伺服器憑證與中繼憑證依序合併在同一個
.crt檔內，否則部分瀏覽器仍會報錯。 - 憑證的名稱（CN／SAN）必須包含使用者實際輸入的網址，否則仍會警告。
- 🔴 私鑰換完之後不要放回一般可讀的位置，權限務必維持 600。
- 憑證到期前記得更換，步驟同上。系統不會提醒您憑證到期。
- 重跑安裝程式時不會覆蓋您換上的正式憑證（偵測到憑證已存在就沿用）。
2.5 非互動安裝（自動化用，一般不需要）¶
先說結論：一般裝一台就用 2.2 的互動模式，這節可以跳過。
要把同一份參數重複用在多台機器，或要納入自動化流程時，才改用設定檔。
這四步在做什麼：① 從範例檔複製一份自己的設定檔，② 編輯它，③ 把權限收緊成只有管理員讀得到，④ 帶著設定檔執行安裝（就不會再問問題）。
cp install.conf.example install.conf
vi install.conf # 編輯下面幾項
chmod 600 install.conf
sudo ./install.sh --config install.conf
install.conf 內常用的幾項：
GUIDANT_HOSTNAME=guidant.example.com # 使用者連線用的網域或 IP
GUIDANT_DATA_DIR=/srv/guidant-ai # 資料存放目錄
GUIDANT_HTTP_PORT=80 # 對外 HTTP 埠
GUIDANT_HTTPS_PORT=443 # 對外 HTTPS 埠
TZ=Asia/Taipei # 時區
⚠️ 對外埠改成非標準值之後，請直接用 https 網址進站。HTTP 的自動轉址是導向不帶埠號的
https://<主機>，非標準埠下會導錯。
自帶密碼（僅在貴單位資安政策要求時使用）¶
先說結論：絕大多數情況不要填，讓安裝程式自動產生就好。
只有在貴單位的資安政策要求「特權帳號密碼一律由自身的發放系統核發」時，才需要在 install.conf 填入：
三行可以只填其中一兩行，沒填的照樣自動產生。
🔴 自帶密碼有四項字元限制，違反會在安裝時被擋下並說明原因：
| 密碼裡不允許 | 為什麼不允許 |
|---|---|
含 $ |
會被設定檔解析器當成變數展開，密碼會少一段——安裝仍然成功、服務也全綠，但您保存的密碼與資料庫實際的密碼不一致 |
| 以引號開頭 | 整份設定檔解析失敗，安裝會在啟動資料庫時中止，而錯誤訊息完全不指向密碼 |
| 前後帶空白 | 會被靜默去掉，同第一項 |
| 含換行或 Tab | 破壞設定檔結構 |
引號在密碼中間或結尾、空白在中間、#、反引號都可以正常使用。
其他注意事項：
- 登入簽章金鑰與兩支資料加密金鑰不開放自帶——它們不是給人登入用的憑證，是程式內部的加密材料。
- 填了密碼之後
install.conf就成為含明文密碼的檔案，權限務必 600，裝完請刪除或收進密碼保險庫。 - 互動安裝一律不問密碼。自帶密碼只能經
--config提供。
2.6 安裝紀錄¶
結論：安裝從頭到尾的畫面輸出，都會同時存成一個檔案。
- 純文字，不含任何密碼，可以直接以郵件附件傳給原廠。
- 權限 600，內容含主機名稱、路徑與機器規格，請比照設定檔保管。
安裝卡在某一步、想知道進度時，另開一個終端機執行下面這行，畫面就會即時跟著跑。
若安裝在很前期就中止、上面的路徑還不存在，紀錄會留在畫面最後印出的
/tmp/...路徑——該檔在主機重開機後會消失，請先複製出來。
2.7 安裝失敗了怎麼辦¶
先說結論：安裝程式結束時會回一個退出碼，那個數字直接告訴您失敗在哪一類。
| 退出碼 | 意義 | 怎麼處理 |
|---|---|---|
0 |
成功 | — |
1 |
參數或前置狀態問題 | 依畫面訊息處理（訊息會給出明確的下一步） |
2 |
環境檢查未通過 | 修正所有 ✗ 項目後重跑。這一步不做任何變更，可安心重試 |
3 |
映像檔完整性或載入失敗 | 向原廠重新索取出貨包 |
4 |
建立資料庫失敗 | 附上安裝紀錄檔聯繫原廠 |
5 |
服務啟動或健康檢查未過 | 先看 sudo guidant logs <服務名>，再附紀錄檔聯繫原廠 |
在後段（⑤ 建庫、⑥ 儲存、⑦ 啟動）失敗、問題修好了想沿用已產生的設定重跑時，用下面這行。
這一步在做什麼：告訴安裝程式「我知道這台已經裝過，請往上面繼續，不要重來」。
這個模式會沿用已產生的密碼、金鑰與憑證，且不會重寫兩份設定檔（您手動調整過的內容會保留）。
為什麼要多這個開關：直接重跑會被「偵測到既有安裝」擋下（那道保護是為了避免覆寫別套系統）。多這一個開關，是要讓「往既有安裝上重跑」變成您當次自覺的動作，不會手滑觸發。