九、排錯¶
這章在講什麼：東西壞了、或畫面出現看不懂的訊息時，怎麼一步步找出原因並修好。
本章的用法很固定：先看 9.1 的症狀對照表（一張「畫面上看到什麼 → 大概是什麼原因 → 去看哪一節」的查表），找到跟您遇到的狀況最接近的那一列，翻到它指的小節，照著做。不需要從頭讀到尾。
每個小節都是同一個結構：先一句白話講「這是什麼情況造成的」，再給要打的指令，並告訴您跑完應該看到什麼。
什麼時候看：安裝卡住、站台連不上、功能沒反應、畫面出現錯誤訊息的時候。
打電話求助之前，請先備妥兩樣東西：
- 安裝或升級的紀錄檔（
/srv/guidant-ai/log/install-*.log或upgrade-*.log，取日期最新的那一個）sudo guidant status這個指令印在畫面上的內容紀錄檔不含任何密碼，可以直接當郵件附件寄出，不必擔心外洩。
9.1 症狀對照表¶
怎麼用：在左欄找到跟您看到的畫面最接近的一列，往右看最後一欄，翻到那一節。
| 您看到的畫面 | 最可能的原因 | 往哪一節看 |
|---|---|---|
| 瀏覽器顯示「連線不是私人連線」 | 自簽憑證，正常現象 | 2.4 |
| 開站台完全連不上 | 服務沒起來／埠被佔／防火牆 | 9.2 |
| 登入成功，但所有功能都顯示「此模組未在授權範圍內」 | 尚未開通授權，或 設定檔漏了一項關鍵設定 | 9.3 |
| 登入按下去沒反應或一直失敗 | 人機驗證在封閉網路下連不到外部 | 8.3 |
| 設定精靈說「設定碼不正確」但碼是對的 | 設定碼檔案的擁有者不對 | 9.4 |
| 合規框架的 PDF 預覽是空白頁 | 系統內建檔案沒灌進儲存，或已切換過儲存後端 | 9.5 |
| 安裝跑到「啟動服務」那行就不動了 | 已內建防護，見說明 | 9.6 |
| 安裝時說「密碼驗證失敗（cmmgr）」 | 機器上還躺著上一次安裝的資料庫 | 9.7 |
| 安裝時說「已經有一套安裝在使用」 | 正確的保護，見四條出路 | 1.8 |
| 維運指令說「這台主機看起來還沒安裝過」 | 安裝紀錄遺失或資料目錄被搬過 | 9.8 |
| 複製機器碼的按鈕按了沒反應 | 不是 HTTPS 連線 | 9.9 |
| 主機重開機後系統沒回來 | Docker 沒設開機自起 | 9.10 |
| 上傳檔案失敗／下載不到 | 檔案儲存服務異常 | 9.11 |
| 檢測 Agent 註冊失敗／顯示「雲端未回傳憑證」 | 系統這一側的對接設定有缺 | 9.12 |
| 派送檢測任務說「本租戶尚無可用的檢測 Agent」 | 沒有在線 Agent 回報過檢測能力 | 9.13 |
| 系統設定四頁（儲存／郵件／LDAP／通知）按儲存被拒 | 角色沒勾到該頁的修改權限 | 9.14 |
租戶 是系統裡代表「一個單位／組織」的概念。同一套系統可以服務多個單位，資料彼此隔離，租戶就是用來區分誰是誰的。
9.2 開站台完全連不上¶
這是什麼情況造成的：可能是服務根本沒起來、可能是網站的埠被別的程式佔走、也可能是防火牆把外面的人擋在門外。三種原因的畫面表現一樣，所以要用下面三個指令依序把範圍縮小。
這三步在做什麼：第一步看服務有沒有在跑，第二步看門有沒有開，第三步從主機自己連自己——連得到就代表系統本身沒問題，是外部網路的事。
# ① 服務是否都在跑
sudo guidant status
# ② 埠是否有在監聽
sudo ss -ltn | grep -E ':(80|443)\s'
# ③ 從主機本機測（排除防火牆因素）
curl -k -I https://localhost
接下來看哪一步出問題，對號入座：
- ① 有服務不是 running →
sudo guidant start，仍失敗就看sudo guidant logs <該服務名> - ② 沒有監聽 →
guidant-fe沒起來，看它的記錄 - ③ 本機測得到、外部連不到 → 是防火牆或網路路由問題，不是系統問題。請檢查主機防火牆（
firewalld／ufw／iptables）與網段設定
9.3 登入成功，但所有功能都說「此模組未在授權範圍內」¶
這是什麼情況造成的：這裡要特別小心——同一句訊息背後有兩種完全不同的成因，而且畫面表現一模一樣，光看畫面分不出來。請照下面的順序，先確認成因 A，再查成因 B。
成因 A：真的還沒開通（最常見）¶
正常狀態。左側選單只剩下不受授權管制的少數幾項（「專案儀表板」「待辦任務」「我的授權狀態」），其餘功能不可用。
處理：完成 第三章 的開通流程。
成因 B：設定檔漏了 ENABLE_MULTI_TENANT¶
🔴 這是一個訊息完全指向錯誤方向的狀況。 服務全綠、登入也成功拿得到憑證，但所有功能都回這個訊息——看起來像授權沒裝好或已過期，實際上是設定檔少了一項。
原因：授權判定需要讀取單位（租戶）資訊，這項設定關閉時讀不到單位資訊，於是一律判定為「無授權」。
這一步在做什麼：從設定檔裡把那一行撈出來看。
成功長什麼樣：ENABLE_MULTI_TENANT=true
失敗長什麼樣：什麼都沒印出來（代表沒有這一行），或印出來的值不是 true。正常安裝不會發生這種事，通常是設定檔被人手動編輯過。
這兩行在做什麼：把那一行補到設定檔最後（若原本已經有一行但值是錯的，請先手動把錯的那行改掉，再補），然後用 start 套用新設定。
# 補上（若已有錯誤的值請先手動改掉）
echo 'ENABLE_MULTI_TENANT=true' | sudo tee -a /srv/guidant-ai/guidant.env
sudo guidant start
🔴 改過設定檔要用
start不是restart——restart不會重建容器，讀到的還是舊值。詳見 4.3。
成功長什麼樣：重新登入後功能恢復正常。
排查這個症狀時，請先確認已完成開通（成因 A），再查這一項。
9.4 設定精靈說「設定碼不正確」，但碼確實是對的¶
這是什麼情況造成的：碼沒錯，是檔案的擁有者不對——後端程式沒有權限讀那個檔，讀不到就當成碼錯。
擁有者 指的是「這個檔案屬於哪一個系統帳號」。Linux 上每個檔案都有擁有者，只有對的帳號才讀得到。
這兩步在做什麼：第一行看目前擁有者是誰，第二行把擁有者改成後端程式使用的那一個。
ls -l /srv/guidant-ai/pki/setup-token
# 擁有者應為 1000:1000
sudo chown 1000:1000 /srv/guidant-ai/pki/setup-token
成功長什麼樣：第一行印出的那筆資料，擁有者欄位是 1000 1000。改完直接回瀏覽器重試就會通過，不需要重啟服務。
安裝程式會自動設好這個擁有者，設不成功時會印警告。若您看過那行警告，這裡就是它的後果。
9.5 合規框架的 PDF 預覽是空白頁¶
這是什麼情況造成的：這幾份 PDF 是系統出廠時就準備好、要灌進檔案儲存的內建檔案。預覽空白代表「該有的檔案不在儲存裡」，有三種可能，請依序排查。
(A) 出貨包沒帶系統內建檔案¶
安裝時畫面上會有一行警告：「出貨包內無 storage-seed/……合規框架的 PDF 預覽會是空白」。
這一步在做什麼：回頭翻安裝紀錄，看當時是不是印過那行警告。
成功長什麼樣：印出的內容裡帶有上述警告字樣，就確認是這個原因。
處理：向原廠索取完整的出貨包（測試包可能不帶系統檔）。
(B) 灌入失敗¶
安裝紀錄裡會有「系統檔灌入失敗」的警告。這一步是可以重複執行的，重跑安裝程式即可（沿用既有設定）：
這一步在做什麼：用既有的設定重跑一次安裝，把沒灌成功的內建檔補灌進去。不會動到您現有的資料。
成功長什麼樣：跑完後重新整理瀏覽器，PDF 預覽就出得來。
(C) 曾經切換過儲存後端¶
系統內建檔案讀的是「當下設定的儲存後端」，切換後就會立刻讀不到。這是已知且有警語的行為，見 第七章 7.2 警語 ③。
處理：把系統內建檔案複製到新儲存（保持相同路徑），或聯繫原廠協助。若當初只是誤切、想直接切回系統內建儲存，見 第七章 7.4 的「恢復系統內建儲存」。
三種情形都只影響框架 PDF 的預覽，系統其餘功能完全不受影響。
9.6 安裝跑到「啟動服務」那行就不動了¶
這是什麼情況造成的：容器其實已經起來、而且是健康的，只是某些 Docker 版本組合下，發出去的那道指令自己不會回應。這不是當機。
這個情形已經內建防護：安裝程式會在等待一段時間後放掉那個指令，改直接去問 Docker「容器到底在不在跑」，然後繼續往下。所以請先耐心等待（最長約 5 分鐘），不要按 Ctrl-C。
這一步在做什麼：另外開一個終端機視窗，即時看安裝紀錄，確認它其實還在動。
成功長什麼樣：畫面持續有新的一行行冒出來，代表安裝還在跑。
🔴 不要按 Ctrl-C。中斷之後重跑會掉進下一節那個情形（資料庫已建立、設定檔還沒寫），處理起來更麻煩。
9.7 安裝時說「密碼驗證失敗（cmmgr）」¶
這是什麼情況造成的：這台機器上還躺著上一次安裝留下的資料庫，但當時的設定檔已經不在了。
資料庫的密碼是建立當下就固定的，新產生的密碼永遠連不上舊資料庫。安裝程式會偵測到這個組合並停下，給您兩條路——先決定舊資料還要不要，再往下看。
(A) 要保留舊資料¶
從備份還原這兩個檔後重跑安裝：
(B) 舊資料不要了，要全新安裝¶
🔴 下面的指令會永久刪除舊資料庫。 執行前請確定舊資料真的不再需要——刪掉之後沒有任何辦法救回來。
這兩行在做什麼：第一行移除舊的資料庫容器，第二行刪掉它存放資料的地方。
若上一次安裝已把其他服務也起起來了，一併移除（沒有的會回 No such container，可忽略）：
sudo docker rm -f guidant-api guidant-socketio guidant-fe guidant-redis guidant-seaweedfs
sudo docker network rm guidant_default
成功長什麼樣：每一行印出被移除項目的名稱，或印出 No such container（代表本來就沒有，屬正常）。
然後重跑 sudo ./install.sh。
為什麼不用
docker compose down：那個指令需要.env才能解析，而「.env不在」正是您現在的處境。而且資料區必須先移除容器才刪得掉。直接對容器與資料區下手，兩個問題都不存在。
9.8 維運指令說「這台主機看起來還沒安裝過」¶
這是什麼情況造成的：系統其實裝過，只是安裝紀錄（/etc/guidant-ai/install.conf）不見了，或資料目錄被人手動搬過位置，所以維運指令找不到它。
這一步在做什麼：直接告訴指令「資料目錄在這裡」，繞過自動尋找。
成功長什麼樣：正常印出各服務的狀態表。
若是找不到服務定義檔（docker-compose.yml）：這個檔在安裝／升級時就會被複製到資料目錄下（<資料目錄>/docker-compose.yml），與出貨包無關、正常情況不會不見。會出現這個訊息通常是兩種情形：
- 它被手動刪掉了 → 用同版出貨包重跑一次升級即可補回（資料不受影響）：
- 這台機器是舊版裝的（1.17.0 之前，那時還沒有這個複製機制）→ 同上，升級一次就會補齊；或臨時指定既有的那份：
9.9 「複製機器碼」按了沒反應¶
這是什麼情況造成的：不是按鈕壞了。瀏覽器的剪貼簿功能只在 HTTPS 連線下可用，用純 HTTP 進站時按下去既不會有反應、也不會跳任何錯誤，所以看起來像沒作用。
怎麼確認：看網址列開頭是不是 https://。
處理：改用 https:// 網址進站。或直接用滑鼠選取那串文字手動複製，也可以在主機上執行 sudo guidant fingerprint 取得同一串。
9.10 主機重開機後系統沒回來¶
這是什麼情況造成的：Docker 沒有設定成開機自動啟動。Docker 沒起來，整套系統自然也不會回來。
這三行在做什麼：第一行查目前有沒有設定自起，第二行把它設起來並立刻啟動 Docker，第三行把系統的服務叫回來。
成功長什麼樣：第一行回 enabled；跑完第三行後，站台可以正常開啟。
安裝時若沒設定，畫面上會有警告（但不擋安裝）。
9.11 上傳檔案失敗、下載不到¶
這是什麼情況造成的：負責存放檔案的服務（guidant-seaweedfs）出了狀況。最常見的是它的一個設定檔沒被正確建立起來。
這兩步在做什麼：第一行看該服務健不健康，第二行看它的記錄找線索。
常見原因是憑證檔的問題：
這一步在做什麼：確認 s3.json 到底是一個檔案，還是被錯建成了目錄。
成功長什麼樣：印出來的那一行開頭是 -，代表它是一個檔案。
失敗長什麼樣：開頭是 d，代表它是目錄。這表示安裝過程中該檔沒被建立，Docker 就把掛載點建成了空目錄。
掛載 是把主機上的一個目錄或檔案「接進容器裡」，讓容器內的程式讀得到。接的來源如果不存在，Docker 會自作主張建一個空目錄頂替，於是程式就讀到一個不是它要的東西。
處理：
這兩行在做什麼：先把錯建的目錄砍掉，再用既有設定重跑安裝，讓它把正確的檔案建出來。
成功長什麼樣：跑完後再 ls -l 一次，開頭變成 -；上傳與下載恢復正常。
仍然失敗請附上安裝紀錄與該服務的記錄聯繫原廠。
9.12 檢測 Agent 註冊失敗、或顯示「雲端未回傳憑證」¶
這是什麼情況造成的：這條路徑上任何一環出錯，畫面看起來幾乎都一樣，光看訊息猜不出真因（可能是認證模式、金鑰缺件、檔案擁有者不對、對外位址空白或帶錯、金鑰目錄沒掛進容器）。所以不要逐項自己猜——系統內建了一個一次檢查完的指令。
這一步在做什麼：在系統主機上把這一側所有相關設定檢查一遍。它是唯讀的，只看不改，很安全。
成功長什麼樣：所有項目都標通過。
失敗長什麼樣：把有問題的項目一次列齊，每一項後面附上該怎麼修。詳見 第四章 4.9。
9.13 派送檢測任務時說「本租戶尚無可用的檢測 Agent」¶
這是什麼情況造成的：系統沒有收到任何一台在線 Agent 說「我會做檢測」。可能是 Agent 根本沒上線，也可能是它上線了但版本太舊、不會回報自己的能力。
依序確認：
- 「系統管理」→「Agent 管理」裡有沒有那台 Agent、狀態是不是在線？
- 不在線 → 到 Agent 主機確認它的服務有在跑、且連得到本系統站台網址。
- 在線但仍不能派工 → 多半是 Agent 版本太舊。能力是由 Agent 自己隨定期回報宣告的，過舊的版本不會回報，系統就不知道它會做檢測。請向原廠索取新版 Agent 更新後再試。
這件事不需要任何人工開通動作。若有人告訴您要下 SQL 開通，那是舊版的作法，已不適用。
9.14 系統設定四頁按「儲存」被拒絕¶
這是什麼情況造成的：不是系統壞了，是這個帳號的角色沒有被勾到「那一頁」的修改權限。
指「儲存設備設定」「郵件伺服器設定」「LDAP伺服器設定」「通知設定」這四頁。
怎麼確認：到「系統管理」→「權限管理」，看該使用者的角色有沒有勾到那一頁的「修改」權限。四頁各自獨立，勾了其中一頁不代表其他三頁也能改；只勾讀取的人看得到內容但存不下去。指派方式見 第三章 3.9。
1.15.0 版之前有一個已修正的問題：即使角色已正確勾選，仍只有最高權限的帳號能儲存。若貴單位的系統版本低於 1.15.0（
sudo guidant status第一行可看），升級即可解決。
9.15 各步驟的退出碼¶
退出碼 是指令跑完之後回給系統的一個數字，用來表示「這次是成功還是哪一類失敗」。腳本失敗時的退出碼指出失敗在哪一類，見 第二章 2.7。
sudo guidant agent-check也用同一組退出碼：全部通過為0，有項目未通過為2。