十、排錯¶
這章在講什麼：Agent 出狀況時，怎麼從「看到的症狀」找到「真正的原因」。
這一章不需要從頭讀。它的用法是三步：① 先在 10.1 的症狀對照表裡找到跟您畫面上最像的那一行 → ② 跟著它指的小節過去 → ③ 照那一節寫的做。
每一節都會先講「這個症狀通常是什麼原因」，再給指令，指令前後都寫明「這步在做什麼」與「成功長什麼樣」。
什麼時候看：出狀況時。平時不用讀。
有幾個症狀的表面訊息完全不指向真正的原因（例如時鐘不準會表現成「下載證據檔失敗」），所以請務必先查對照表，不要照著錯誤訊息的字面去猜。
10.1 症狀對照表¶
先在「症狀」欄找到跟您遇到的情況最接近的一行。
| 您看到的狀況 | 通常是什麼原因 | 到哪一節處理 |
|---|---|---|
| 安裝時說「映像檔內容與出貨清單不符」 | 出貨包在傳輸中損壞，或曾被改過 | 10.2 |
| 安裝時說「埠已被其他程式佔用」 | 8443 或內部埠被別的服務用了 | 10.2 |
| 安裝跑完但沒看到「已向雲端註冊成功」 | 註冊憑證過期／位址填錯／防火牆 | 10.3 |
| 平台上看不到這台 Agent | 同上 | 10.3 |
| 平台顯示在線，但下載證據檔失敗 | 8443 沒放行／位址填錯／主機時鐘不準 | 10.4 |
| 下載某些舊檔失敗、新檔正常 | 換過儲存位置，舊檔沒搬 | 第六章 6.3 |
| 檢測任務失敗，說目標主機沒裝某工具 | 受測機的準備工作沒做 | 第二章 |
| 檢測報告存不進去 | 磁碟滿了 | 10.5 |
| 平台上這台的名稱是一串 12 碼英數字 | 舊版問題，升級即修正 | 10.6 |
| 註冊被拒，說指紋已被另一台使用 | 兩台機器從同一個虛擬機模板複製 | 10.6 |
| 維運指令說「這台主機看起來還沒安裝過」 | 安裝目錄被搬走 | 10.6 |
服務起不來，訊息提到 /var/lib/docker/rootfs |
安裝目錄缺 content/cache 子目錄 |
10.6 |
設備指紋是平台用來認出「這是哪一台 Agent」的一組識別值，由這台機器的兩個身分識別檔算出來，作用就像人的指紋。詳見 第一章 1.4。
10.2 安裝階段¶
「映像檔內容與出貨清單不符」¶
先說結論：安裝已經中止了，那個檔案不會被載入，機器上沒有留下任何東西。
出貨包裡附了一份清單，記著每個檔案的雜湊 SHA-256（檔案指紋，內容只要差一個位元，指紋就完全不同）。安裝時逐檔比對，對不上就停。這代表檔案在傳送過程中損壞，或曾被修改過。
請重新取得原始出貨包。重新下載後仍不符，請立刻聯繫原廠——那可能不是傳輸問題。
「埠已被其他程式佔用」¶
這步在做什麼：查出是哪個程式佔用了 Agent 要用的埠。
成功長什麼樣：印出一到多行，每行最後會顯示佔用該埠的程式名稱與編號——這就是您要找的兇手。
沒有輸出代表這幾個埠其實都是空的，那問題不在這裡，請回對照表找別的可能。
兩條路：停掉那個服務，或用設定檔指定其他埠（見 3.5）。
環境檢查有 ✗ 項目¶
對照 第一章 逐項修正。檢查程式會一次列齊所有問題，請全部修完再重跑，不要修一個跑一次。
10.3 註冊與上線¶
「註冊」是 Agent 第一次向平台報到、換取自己身分憑證（電子身分證明）的動作。註冊沒成功，平台上就看不到這台。
這步在做什麼：把 Agent 的執行記錄叫出來，看它到底卡在哪一步。不要憑畫面猜，先看記錄。
成功長什麼樣：畫面捲出一長串記錄。往下找關鍵字，對照下表判斷原因。
| 記錄裡看到 | 原因 | 處理 |
|---|---|---|
| 註冊被拒、憑證無效之類 | 註冊憑證過期或已被使用 | 回平台重新產生一組，重跑 sudo ./install.sh（第 2 題填新的，其餘按 Enter） |
| 連線逾時、連不上 | 雲端位址填錯，或防火牆擋住連出 | 確認位址；檢查防火牆（9.1） |
CERTIFICATE_VERIFY_FAILED |
平台換過 https 憑證，Agent 的信任檔還是舊的 | 見 11.5 |
雲端 register 未回傳憑證 |
平台端的 Agent 對接設定沒開啟 | 請平台管理者確認平台端設定 |
data-plane TLS not started: certificate not ready |
註冊還沒成功，憑證尚未簽回 | 先解決註冊問題；註冊成功後 sudo guidant-agent-compose restart |
表中的英文訊息請照原樣在記錄裡搜尋，那是程式印出的原文。
確認註冊到底成功了沒¶
這步在做什麼：查目前的服務狀態，其中包含註冊結果。
成功長什麼樣：畫面最後的「雲端註冊」那一行顯示已註冊。
還沒顯示成功也先別急：剛裝好時第一次心跳最長要等一個週期（預設 5 分鐘），請稍候再查一次。
10.4 平台取不到證據檔¶
特徵：註冊正常、平台顯示在線，但一下載或預覽證據檔就失敗。
先說結論：這一類問題全都出在「平台連回 Agent」這條路上，跟 Agent 連出去那條路無關——所以才會出現「明明在線卻取不到檔」這種看起來矛盾的現象。
下面四項依可能性排序，請由上往下查。
① 防火牆沒放行 8443 的連入¶
最常見。
這步在做什麼：從平台主機上（不是從 Agent 這台）試著連 Agent 的 8443，確認這條路通不通。
成功長什麼樣：印出 400。這代表連得到，而且 Agent 的身分驗證有在守門（沒帶憑證所以被擋，是正常的）。
失敗長什麼樣：印出 000，代表根本連不到 → 請開放防火牆讓平台連進 8443。
② 安裝第 3 題的「本機對外位址」填錯¶
常見的填錯方式：填成 http://、填錯埠、或填了平台連不到的內部位址。
這步在做什麼：重跑安裝，只修正這一題。
成功長什麼樣：安裝流程跑完，沒有錯誤。
⚠️ 只改設定還不夠：Agent 的憑證在註冊當下就把位址寫進去了，本機憑證還在的話重跑安裝會直接沿用舊憑證（裡面還是舊位址）。要讓新位址生效，必須讓它重新註冊一次——見 10.6 的「強制重新註冊」。
③ 主機時鐘不準¶
平台每次來取檔，都會現場簽發一張通行證（JWT）——一張短效的電子通行證，上面寫明「誰、可以取哪個檔、有效到幾點」。這張通行證效期只有 60 秒。
兩端時鐘差超過一分鐘，這張通行證就永遠對不上——症狀跟上面兩項一模一樣，但檢查前兩項都正常。
這兩步在做什麼：確認主機有在自動對時，並把時間拿去跟平台端比對。
成功長什麼樣：第一行回 yes；第二行印出的時間跟平台端相差不到幾秒。
失敗長什麼樣：第一行回 no，或第二行的時間跟平台明顯差了一分鐘以上。
這步在做什麼：打開自動對時。
成功長什麼樣：沒有任何輸出。稍候再跑一次上面那行檢查，應該就會回 yes。
④ 換過儲存位置，舊檔沒搬¶
特徵是新檔正常、某個時間點以前的舊檔全部失敗。見 第六章 6.3。
10.5 磁碟與儲存¶
檢測報告存不進去¶
這步在做什麼：看放證據檔的那個磁碟分割區還剩多少空間。
成功長什麼樣：Use% 欄的數字明顯低於 100%，Avail 欄還有可觀的剩餘空間。
失敗長什麼樣：Use% 是 100% 或接近 100%。
滿了就清空間或擴充磁碟。證據檔不會自動清理，請把磁碟用量納入監控（5.8）。
上傳回報「儲存空間沒有可寫入的區域」¶
內建儲存的容量配置用盡。請聯繫原廠協助調整。
切換儲存位置時驗證一直不過¶
configure-storage 的錯誤訊息會直接指出是哪一類問題（連不上／帳密錯／權限不足），照訊息處理即可。最常見的是 SeaweedFS 的埠填成 9333（管理介面）而不是 8333（S3 介面）。
這個情況可以放心重試：驗證未過時設定完全不會被寫入，服務也不重啟——既有設定原封不動。
10.6 其他¶
平台上這台 Agent 的名稱是 12 碼英數字¶
舊版本的已知問題（顯示的是容器編號而非機器名稱）。升級到新版即修正，或重跑 sudo ./install.sh 在第 4 題填名稱。
維運指令說「這台主機看起來還沒安裝過」¶
安裝目錄 /srv/guidant-ai-agent/ 被搬移或刪除了，或 /etc/guidant-ai-agent/install.conf 這份安裝紀錄不見了。維運指令找不到安裝位置，所以以為沒裝過。
（刪掉解開出貨包的那個目錄不會造成這個症狀——1.0.0 起那個目錄本來就可以刪。）
這步在做什麼：臨時告訴維運指令「實際的安裝目錄在這裡」，讓它這一次能正常運作。
成功長什麼樣：正常印出服務狀態。
這只是應急。長久之計是把目錄搬回原位，或到新位置重跑一次 sudo ./install.sh。
服務起不來，訊息提到 /var/lib/docker/rootfs¶
真正的原因是：安裝目錄下缺了 content/cache 這個子目錄（自行搬移目錄時容易漏掉）。訊息完全不會指向真正的原因。
這兩步在做什麼：把缺掉的目錄補回來，然後重新啟動服務。
成功長什麼樣：服務正常啟動，不再出現那則訊息。
content/cache裡面純粹是快取，要回收空間可以直接刪掉底下的內容，下次派工會重新取得，不會遺失任何狀態。（這與三個資料區完全不同，那些刪掉是災難。）
註冊被拒：「此設備指紋已被另一台在線的 agent 使用」¶
兩台不同的機器算出了相同的設備指紋——最常見的原因是這兩台是從同一個虛擬機模板複製出來的，/etc/machine-id 整批相同。
平台當場拒絕而不是讓兩台共用同一列，是刻意的：共用會導致派工隨機落到其中一台、稽核追不出是誰做的。
修法——在新複製出來的那台機器上重新產生機器識別碼。請務必確認自己登入的是新複製的那台，不要在原本正常的那台上執行。
這幾步在做什麼：刪掉重複的機器識別碼、產生一個新的、確認真的變了，最後重啟 Agent 讓新指紋生效。
sudo rm -f /etc/machine-id
sudo systemd-machine-id-setup # 沒有這個指令：sudo sh -c 'dbus-uuidgen > /etc/machine-id'
cat /etc/machine-id # 確認與被撞的那台不同
sudo guidant-agent-compose restart
成功長什麼樣：第三行印出一串 32 個字元的英數字，而且跟被撞的那台不一樣；重啟後回平台看，這台會正常上線。
失敗長什麼樣：第三行印出的值仍與另一台相同，或是空白——這時不要繼續，請重跑一次產生指令。
💡 這其實是製作虛擬機模板時該做的標準化步驟，不是本產品的特殊要求——machine-id 相同會影響任何以它識別主機的系統。做模板時把
/etc/machine-id清成空檔，開機時系統會自動產生新的。
強制重新註冊¶
多數情況不需要做這件事——升級、重啟、換 IP、指紋改變，平台都會自動處理。
只有這些情況才需要：改了「本機對外位址」要讓新憑證生效、或平台的內部 CA（憑證頒發機構，替其他憑證背書的那個「發證單位」）／通行證金鑰換過（見 第十一章 11.6）。
動手前請先讀完下面兩則警語，尤其是關於證據檔的那一則。
這幾步在做什麼：停掉服務、清掉這台機器目前的身分憑證，然後重跑安裝去換一組新的。
# ① 確認平台上的註冊憑證仍有效，需要的話先重新產生一組（見 4.1）
# ② 停服務
sudo guidant-agent-compose stop
# ③ 清掉本機的身分憑證（🔴 只刪這四個檔，不要動整個資料區）
sudo docker run --rm -v "guidant-ai-agent_agent-certs:/c" alpine sh -c 'rm -f /c/agent.key /c/agent.crt /c/ca.crt /c/jwt_public.pem /c/agent.json'
# ④ 重跑安裝（第 2 題填有效的註冊憑證，其餘依需要調整）
cd <安裝目錄> && sudo ./install.sh
成功長什麼樣：安裝流程跑完並顯示註冊成功，平台上出現一列新的 Agent。
⚠️ 重新註冊會拿到一個新的身分編號，平台上會多出一列新的 Agent，舊那列不會自動消失（會顯示為永遠離線）。請到「檔案 Agent 管理」頁手動刪除或撤銷舊的那列，並到「儲存設定」頁改指向新的這一台。
🔴 證據檔不受影響（存在另一個資料區），但平台記的是「哪個 Agent 有哪些檔」，改指新的那台之後，舊 Agent 名下的證據檔會取不回來。若機器上已有證據檔，請先聯繫原廠評估，不要自行執行。
啟動時說「產物完整性驗證未通過」¶
意思是：Agent 程式本身被改動過。
請不要嘗試繞過——重新取得原廠出貨包重裝，並聯繫原廠說明狀況。
10.7 求助時請提供什麼¶
聯繫原廠技術支援時一併附上這五樣，可以省掉一輪來回：
- 安裝／升級紀錄檔：安裝目錄下的
install-*.log或upgrade-*.log（取最新一個）。不含任何密碼，可直接以郵件附件傳送。 - 服務狀態：
sudo guidant-agent-compose status的完整畫面。 - 記錄：
sudo guidant-agent-compose logs的最後一兩百行。 - 設備指紋：
sudo guidant-agent-compose fingerprint。 - 症狀描述與發生時間（有時間才對得上記錄）。
🔴 請勿提供設定檔（
.env）內容、註冊憑證或儲存空間的帳號密碼。原廠協助排錯不需要這些。