跳轉到

三、安裝

這章在講什麼：怎麼把一包解開的出貨包，變成「服務跑起來、而且已經跟平台報到上線」的 Agent。

像組裝一台已經預先配好的機器——螺絲、零件、說明書都在箱子裡，您只要照著回答幾個問題，剩下的它自己來。全程不需要輸入任何 Docker 指令，只要回答四個問題。 任何一步失敗都會立刻中止，不會留下裝到一半的爛攤子。

什麼時候看：第一次安裝的時候，以及日後要重跑安裝修正填錯的值時（3.8 節）。

開始之前：請先取得註冊憑證（一次性的入場券，用來證明這台 Agent 屬於貴單位；怎麼拿見下一章 4.1）。第 2 題會用到它。

3.1 七個步驟一次看完

步驟 安裝程式會做什麼 需要您做什麼
① 環境檢查 逐項檢查作業系統、Docker、磁碟、設備指紋來源、網路埠 —
② 載入映像 比對出貨清單，確認檔案沒被改過，再載入 Docker —
③ 回答四題 問您雲端位址／註冊憑證／本機對外位址／顯示名稱 回答四題
④ 產生儲存密碼 內建儲存的帳號密碼由程式亂數產生 —（刻意不讓您自己想密碼）
⑤ 寫入設定 產生一份只有管理員讀得到的設定檔 —
⑥ 啟動服務 把兩個服務啟動起來，等健康檢查轉綠 —
⑦ 印出結果 確認已向平台報到，印出設備指紋與常用指令 抄下設備指紋

3.2 解開出貨包並確認檔案完整

把出貨包與旁邊那個 .sha256 檔一起放到主機上。

這一步在做什麼：確認出貨包在傳輸過程中沒有損壞、也沒有被人動過手腳。

sha256sum -c guidant-agent-compose-<版號>.tar.gz.sha256

成功長什麼樣：畫面印出 guidant-agent-compose-<版號>.tar.gz: OK。

失敗長什麼樣：印出 FAILED。這時請不要繼續，重新向原廠取得出貨包。

這一步在做什麼：把出貨包解開，並進到解開後的目錄。

tar -xzf guidant-agent-compose-<版號>.tar.gz
cd guidant-agent-compose-<版號>

成功長什麼樣：多出一個同名的目錄，而且您已經在裡面。

✅ 這個目錄裝完可以整個刪掉（1.0.0 起），連同 .tar.gz 一起。安裝程式會把需要長期保留的東西複製到固定的系統位置——設定檔、服務定義檔、您日後投放的檢測內容都不在解壓目錄裡。安裝完成的畫面會再告訴您一次可以刪。

裝到哪裡去了（不需要記，維運指令自己知道）：

位置 放什麼
/srv/guidant-ai-agent/ 設定檔、服務定義檔、您投放的檢測內容、雲端憑證
/etc/guidant-ai-agent/ 安裝紀錄（維運指令靠它找到上面那個目錄）
/var/log/guidant-ai-agent/ 安裝與升級的過程紀錄
/usr/local/bin/guidant-agent-compose 維運指令

0.2.32 以前不是這樣：那時候「解開的目錄」就是安裝目錄，所以完成畫面得印「請勿刪除」。若您手上有那種舊安裝，新版安裝程式會自動偵測並搬移（連同證據檔與身分憑證一起搬），不需要您手動處理，也不需要重新註冊。

3.3 先跑一次環境檢查（不會改任何東西）

這一步在做什麼：把整台機器檢查一遍，看有沒有不合格的地方。它不需要管理員權限、也不會做任何變更，可以放心先跑。

./install.sh --check-only

成功長什麼樣：每一項都標 ✓，沒有 ✗。

失敗長什麼樣：出現一個或多個 ✗。它會一次把所有問題列齊，不是撞到第一個就停——請對照 第一章 把所有 ✗ 一起修完再往下走。

3.4 執行安裝

這一步在做什麼：正式安裝。接下來安裝程式會問您四個問題。

sudo ./install.sh

第 1 題：雲端平台位址

  1/4 雲端平台位址（例：https://cloud.example.com）
      >

填 Guidant AI 平台的網址，只填到網域名稱，不要帶後面的路徑。舉例來說，您平常開的平台網址是 https://guidant.example.com/audit/...，這裡就填 https://guidant.example.com。

接下來可能會跳出一個憑證確認畫面（貴單位自建的落地版平台通常會出現）：

  請確認雲端憑證
      這個雲端使用的憑證無法由公認的憑證機構驗證（自簽憑證，落地部署常見）。
      請與雲端管理者核對下面這串指紋，確認無誤後才選擇信任。

      位址        https://guidant.example.com
      憑證主體    ...
      簽發者      ...
      有效期至    ...
      SHA-256     AA:BB:CC:...

      是否信任此憑證？(y/N) >

🔴 請真的去核對這串指紋，不要直接按 y。

憑證指紋是那張憑證算出來的一串摘要值，用途就是逐字核對「這張憑證是不是對的那一張」。請向平台管理者索取平台憑證的 SHA-256 指紋，跟畫面上這串一個字一個字比對，完全相符才輸入 y。

這一步在做的事，跟您第一次用 SSH 連一台新伺服器時要確認金鑰指紋是同一件事：由現場的人親自認定一次「這個平台是可信的」，之後 Agent 就靠這張憑證來驗證平台身分。

指紋對不上就直接按 Enter 拒絕——安裝會中止，而且不會對這台機器做任何變更。指紋不符代表您連到了錯的位址，或者連線在中途被攔截了，先釐清原因再說。

平台如果用的是公認憑證機構簽發的憑證，這一步不會出現，那是正常的。

第 2 題：註冊憑證

  2/4 註冊 token（雲端管理頁產生，用於證明這台 agent 屬於貴公司）
      >

貼上您從平台取得的註冊憑證（怎麼拿見 第四章 4.1）。這串字的作用是證明這台 Agent 屬於貴單位。

第 3 題：本機對外位址

  3/4 本機對外位址
      雲端要連回這台機器抓證據檔時，用的就是這個位址；它會寫進本機憑證。
      偵測到本機對雲端的位址是 https://192.168.1.50:8443
      [直接按 Enter 使用；若貴環境要走 NAT 位址或 DNS 名稱，請直接輸入]
      >

安裝程式會自動偵測這台機器連往平台時用的是哪個位址，並且顯示出來讓您確認。

  • 偵測出來的值正確 → 直接按 Enter。
  • 貴單位環境有 NAT（對外位址與內部位址不同）、或平台要走網域名稱連回來 → 直接輸入正確的位址。

⚠️ 格式必須是 https://<位址>:8443。這一題填錯，症狀不會馬上出現——要等到「平台要下載證據檔」那一刻才會浮現，屆時很難聯想回這一步。所以請當場確認清楚。

判斷方法很簡單：問自己「平台要連到這台機器，要打什麼位址？」——答案就是這一題要填的。

第 4 題：Agent 顯示名稱（選填）

  4/4 Agent 顯示名稱（選填）
      雲端後台的 agent 清單、以及「儲存設備設定」的下拉選單，顯示的就是這個名字。
      [直接按 Enter 使用本機名稱：taipei-file-01]
      >

這個名字會出現在平台的 Agent 清單裡。預設會用這台機器的主機名，直接按 Enter 就好。如果貴單位有好幾台 Agent，取一個一眼認得出來的名字（例如「台北機房-檔案主機」）會比較好管理。

3.5 大量部署：不用一題一題回答的安裝方式

要在很多台機器上重複佈建時，可以先把答案寫進一個設定檔，安裝程式直接讀。

這一段在做什麼：先寫出一個叫 agent.conf 的設定檔，把權限鎖成只有自己讀得到，然後用它來安裝。

cat > agent.conf <<'EOF'
CLOUD_ENDPOINT=https://guidant.example.com
REGISTRATION_TOKEN=<註冊憑證>
AGENT_BASE_URL=https://192.168.1.50:8443
CLOUD_CA_SHA256=AA:BB:CC:...          # 平台為自簽憑證時必填（要信任的那張的指紋）
AGENT_HOSTNAME=taipei-file-01         # 可省略，省略時用本機名稱
AGENT_DATA_PLANE_PORT=8443            # 可省略，8443 被佔用時才改
EOF
chmod 600 agent.conf
sudo ./install.sh --config agent.conf

成功長什麼樣：安裝程式不再逐題發問，直接跑完並印出 3.6 節的完成畫面。

🔴 沒有「略過憑證驗證」這個選項。 平台是自簽憑證時，互動模式走現場逐字核對指紋、這種非互動模式走 CLOUD_CA_SHA256 事先指定要信任哪一張——指紋確認取代的是盲目信任，不是取代驗證本身。指紋對不上，安裝一律中止。

agent.conf 裡面有註冊憑證，所以權限要設成 600，而且佈建完成後請把它刪掉。

8443 這個埠被其他服務佔用時，用 AGENT_DATA_PLANE_PORT 指定改用別的埠——記得第 3 題（AGENT_BASE_URL）的埠號要跟著一起改，而且防火牆要放行的也變成新的那個埠。

3.6 安裝完成的畫面

安裝完成

  映像        guidant-ai-agent:1.0.0
  安裝目錄    /srv/guidant-ai-agent
  設定檔      /srv/guidant-ai-agent/.env（權限 600）
  雲端位址    https://guidant.example.com
  本機位址    https://192.168.1.50:8443
  顯示名稱    taipei-file-01（雲端後台與儲存設定下拉看到的名字）
  設備指紋    3f2a9c...（64 個十六進位字元）
  過程紀錄    /var/log/guidant-ai-agent/

  對外連線：本機需開放 8443/tcp 供雲端連入（雙向憑證認證）
  資料存放：docker volume（guidant-ai-agent_agent-db／_agent-certs／_seaweed-data）
            🔴 關鍵狀態，請納入備份

  常用指令（不需要記任何 docker 語法）：
    sudo guidant-agent-compose status              查看服務、版本與雲端註冊狀態
    ...

  可回收空間：下列映像檔已載入 docker，可以刪除（共約 1.4G）
              cd ... && rm guidant-ai-agent-0.2.30.image.tar chrislusf-seaweedfs-3.99.image.tar
              🔴 其餘檔案與目錄請保留。

  下一步（在雲端平台）：儲存設定頁選「使用 Agent 服務」→ 選這台 agent。

請抄下「設備指紋」那一行。 這是這台機器在平台上的身分識別，日後排錯與核對都會用到。

如果最後顯示的不是「已向雲端註冊成功」

安裝程式會誠實區分不同狀況，不會一律報成功：

畫面訊息 意思 怎麼辦
已向雲端註冊成功 完成了 往下走 第四章 4.4
尚未在記錄中看到註冊成功的訊息 註冊還在重試中，或是失敗了 等一兩分鐘後跑 sudo guidant-agent-compose status 再確認一次；仍未成功見下面

註冊一直失敗，最常見的原因依序是：

  1. 註冊憑證過期或已經被用掉了 → 回平台重新產生一組。
  2. 雲端位址填錯 → 重跑 sudo ./install.sh，第 1 題填正確的位址（其餘題按 Enter 沿用就好）。
  3. 防火牆擋住 Agent 連出去 → 見 第九章。

這一步在做什麼：查看服務記錄，找出註冊失敗的真正原因。

sudo guidant-agent-compose logs

成功長什麼樣：畫面印出服務的執行記錄，可以從裡面找到錯誤訊息。

3.7 安裝紀錄

安裝的全程輸出都會寫進 /var/log/guidant-ai-agent/install-<日期時間>.log，是純文字檔，而且不含任何密碼。要向原廠回報安裝問題時，請附上這個檔。

這個目錄不會隨著解除安裝被刪掉——「上次移除為什麼失敗」正是最需要留著的紀錄。不需要時您可以自己刪。

3.8 填錯了？重跑安裝就好

發現某一題填錯了，不用重裝，直接重跑安裝程式：

sudo ./install.sh

它會偵測到既有的設定，把您現在的答案當成每一題的預設值——要改的那一題填新值，其餘按 Enter 沿用。資料完全不會動（證據檔、憑證、索引都保留），內建儲存的帳號密碼也會沿用，不會重新產生。

安裝程式自己知道這台機器是什麼狀況（1.0.0 起）：全新的機器就走全新安裝、已經裝過的就走升級、還是舊形態的就先搬到新位置。您不需要判斷該加哪個參數——先前得靠您選對指令來區分，選錯會裝出「看起來成功、其實還是舊版」的結果。