四、日常維運¶
這章在講什麼：系統裝好之後，平常要怎麼照顧它。
就像家裡的總電箱——平常不用天天開來看，但要知道開關在哪、跳電時怎麼推回去、電費單（記錄）放在哪個抽屜。本章把「看狀態、開關機、查記錄、查密碼、換密碼、備份」這幾件日常事一次講完。
什麼時候看：裝好之後放在手邊。使用者回報系統怪怪的、主機要維護要先關機、貴單位要求定期換密碼或做備份時，翻這章。
好消息：您不需要記任何 Docker 指令，也不需要知道設定檔放在哪裡。 裝好之後的所有操作都走 guidantai 這一個指令，後面接不同的子命令（同一個指令後面加一個詞，決定它這次要做哪件事，像 status、start、stop）。
不必先切換目錄：安裝時已經把 guidantai 放進系統路徑（/usr/local/bin/guidantai），在任何目錄下都能直接打。
出貨包可以刪掉——維運指令與它需要的設定都已經在安裝時複製到系統目錄，不再依賴出貨包。（建議還是留著壓縮檔備查，但解壓出來的目錄刪掉沒有影響。）
升級之後不用做什麼：新版安裝包會自動把
guidantai一起更新，維運指令永遠跟著目前的系統版本走。
4.1 子命令一覽¶
先掃一眼有哪些指令可用，細節在後面各節。
| 這個指令 | 它會做什麼 |
|---|---|
sudo guidantai status |
九個服務的健康狀態一覽（版本／狀態／已執行多久） |
sudo guidantai start |
啟動全部服務（改過設定也用這個才會生效） |
sudo guidantai stop |
停止全部服務（資料完全保留） |
sudo guidantai restart |
逐一重啟九個服務 |
sudo guidantai restart <服務名> |
只重啟一個 |
sudo guidantai logs |
看後端主程式的記錄（Ctrl-C 離開） |
sudo guidantai logs <服務名> |
看指定服務的記錄 |
sudo guidantai fingerprint |
印出本機機器碼（申請授權用；服務沒起來也能查） |
sudo guidantai setup-token |
印出開通精靈第一步要填的「安裝設定碼」；已開通過就不會再印 → 見 4.10 |
sudo guidantai rotate-credentials |
輪換系統內部服務帳號的密碼（資料庫兩組＋Redis） |
sudo guidantai agent-check |
檢查檢測 Agent 對接是否備妥（唯讀檢查，會直接指出哪裡不對與修法） → 見 4.9 |
sudo guidantai diag |
產出診斷包，交給原廠分析問題 → 見 4.11 |
sudo guidantai bugsink-vacuum |
清理錯誤追蹤站的殘留資料，印前後筆數 → 見 4.14 |
sudo guidantai bugsink-set-password |
更改錯誤追蹤站管理員密碼（互動輸入） → 見 4.14 |
sudo ./install.sh --check-only |
只跑環境檢查，不做任何變更（這兩個仍在出貨包的 install.sh） |
sudo ./install.sh --upgrade |
換版升級 → 見 第五章 |
sudo guidantai uninstall |
🔴 移除整套系統與所有資料 → 見 第六章 |
guidantai help |
印出用法（唯一不需 sudo 的指令；打 guidantai --help 也可以） |
服務名只認這九個：guidant-db、guidant-redis、guidant-seaweedfs、guidant-api、guidant-sandbox、guidant-socketio、guidant-worker、guidant-fe、guidant-bugsink。打錯字會直接列出可用的名稱，不會靜靜失敗。
4.2 查看狀態¶
這是最常用的一支——想知道「系統現在好不好」，先跑它。
這一步在做什麼：把九個服務各自的狀況印出來，不做任何變更。
成功長什麼樣：
══ 服務狀態
版本：1.21.0 資料目錄：/srv/guidant-ai
guidant-db healthy （已執行 3 天 2 小時）
guidant-redis healthy （已執行 3 天 2 小時）
guidant-seaweedfs healthy （已執行 3 天 2 小時）
guidant-api healthy （已執行 3 天 2 小時）
guidant-sandbox healthy （已執行 3 天 2 小時）
guidant-socketio healthy （已執行 3 天 2 小時）
guidant-worker healthy （已執行 3 天 2 小時）
guidant-fe healthy （已執行 3 天 2 小時）
guidant-bugsink healthy （已執行 3 天 2 小時）
站台網址：https://192.168.1.50
healthy 是健康檢查（服務每隔一段時間自我回報「我還活著而且運作正常」）通過。其他可能看到的字樣：啟動中（剛啟動、健康檢查還沒跑完，稍等一下再看）、unhealthy（在跑但健康檢查沒過）、已停止、未建立（從沒啟動過或已被移除）、running（無健康檢查）（服務在跑，但沒有設定健康檢查可看）。
有服務沒在跑時：畫面下方會直接給您下一步的指令，不需要自己猜。
guidant-worker（背景工作）與guidant-sandbox（檔案沙箱）合起來負責證據自動分類，隨系統一起啟動；它們不健康時只影響「自動分類證據」功能，登入與其他功能照常。🔴
guidant-worker沒在跑，分類就不會動：使用者按下分類後單子會一直停在「排隊中」，畫面不報錯。遇到「分類一直沒結果」先看status這一行，再看sudo guidantai logs guidant-worker。
guidant-bugsink是錯誤追蹤站（見 4.14）；它不健康時只是錯誤記不下來，系統功能照常。
4.3 啟動、停止、重啟¶
這幾行在做什麼：分別是關機、開機、重開，最後一行是只重開其中一個服務。
sudo guidantai stop # 停止（例如主機要維護）
sudo guidantai start # 啟動
sudo guidantai restart # 重啟全部
sudo guidantai restart guidant-api # 只重啟後端
stop 不會刪除任何資料，之後 start 回來一切照舊。
⚠️
restart與start不一樣，改過設定請用start：
它做什麼 什麼時候用 restart把現有容器停了再起，不重讀版號、不套用設定檔的變動 服務卡住、要它重來一次 start依目前設定重新建立容器，設定有變就會生效 改過任何設定之後、換版、回滾 為什麼會這樣：設定值是在容器「建立」的那一刻寫進去的。
restart沒有重建容器，所以它讀到的還是舊值——即使設定檔裡已經是新的。這個坑不會再靜默發生：
guidantai restart會先比對「設定檔的修改時間」與「容器的建立時間」，發現設定比容器新就直接擋下，並告訴您改用start。也就是說，改完設定誤打restart，您會看到清楚的提示，而不是「指令成功但設定沒生效」。若您確定只是碰過檔案、內容其實沒改（例如用編輯器開起來又存檔），要照原意重啟可以加
--force：sudo guidantai restart --force。
主機重新開機後：服務會自動回來（前提是 Docker 有設定開機自起，見 1.3）。不放心可以開機後跑一次 status 確認。
4.4 看記錄¶
記錄（log） 是服務自己寫下的流水帳，出事時是最直接的線索來源。
這幾行在做什麼：把指定服務的記錄印在畫面上，並持續顯示新進的內容。
sudo guidantai logs # 後端主程式（最常用）
sudo guidantai logs guidant-db # 資料庫
sudo guidantai logs guidant-fe # 網站
sudo guidantai logs guidant-worker # 背景工作（證據自動分類）
sudo guidantai logs guidant-sandbox # 檔案沙箱（拆檔）
sudo guidantai logs guidant-bugsink # 錯誤追蹤站
成功長什麼樣：畫面持續滾動出新的記錄行。看夠了按 Ctrl-C 離開——這只是停止顯示，不會影響服務。
記錄檔本身會自動輪替（寫滿就換新檔、舊檔超過數量就刪掉，每個服務最多保留 5 份、每份 20 MB），不會無限長大佔滿磁碟。
4.5 內部服務憑證¶
憑證在這裡指的是系統內部各服務彼此連線用的帳號密碼與金鑰（金鑰＝加解密用的鑰匙）。這些是安裝當下自動產生、寫入權限 600 的設定檔，服務啟動時自行讀取——日常操作不需要、也不會顯示這些值。
若貴單位的密碼保險庫（Vault、CyberArk、Bitwarden 這類集中保管帳密的系統）政策要求登錄特權帳號，請由具 root 權限的管理者依原廠提供的維運文件自設定檔讀取後登錄；本系統不提供把密碼印到畫面上的指令。
4.6 定期換密¶
輪換密碼就是定期換鎖——即使舊鑰匙曾經外流，換了之後也開不了門。多數資安規範都要求定期做。
這一步在做什麼：重新產生資料庫兩組與 Redis 共三組密碼，同時改掉服務端與設定檔。新值只寫入設定檔，不會顯示在畫面上。
成功長什麼樣：三組密碼各自完成的訊息，過程中服務會短暫重啟。
輪換後使用者不需要重新登入——登入簽章金鑰沒有被動到。
內建檔案儲存的憑證不在輪換範圍內——它是兩個容器之間的內部憑證（不對外開放），而且沒有等價的線上回滾手段。
失敗長什麼樣：畫面印出失敗訊息，並明說「設定檔完全沒有被變更」。這是設計上的保護：換密過程先寫暫存檔、全部成功才覆蓋，任一步失敗時服務端的密碼也會改回舊值，系統維持原狀、不需重啟即可繼續使用。
🔴 登入簽章金鑰與兩支資料加密金鑰刻意不納入輪換：
- 換登入簽章金鑰 = 所有使用者當場登出、進行中的操作全部中斷
- 換資料加密金鑰 = 資料庫裡既有的 Google 雲端硬碟授權與檢測工具憑證都是用舊金鑰加密的，換了就永遠解不開（換鑰不會回頭重新加密）
這幾支（以及檔案儲存憑證）要更換屬於資料遷移等級的作業，請聯繫原廠。
4.7 備份¶
先講重點：備份不是只備資料庫，有四樣東西缺一不可。 只備了資料庫、卻漏掉設定檔或金鑰目錄，還原當天才會發現資料解不開、Agent 全掉線——這是最常見也最痛的失誤。
| 要備份的 | 為什麼一定要備 | 怎麼做 |
|---|---|---|
| 資料庫 | 所有專案、稽核紀錄、帳號 | 見下方指令 |
<資料目錄>/guidant.env |
🔴 內含資料加密金鑰——遺失則備份中的 Google 雲端硬碟授權與檢測工具憑證永遠解不開 | 檔案複製 |
<資料目錄>/.env |
資料庫密碼——遺失則還原後連不上舊庫 | 檔案複製 |
<資料目錄>/pki/agent/ |
🔴 檢測 Agent 對接金鑰。不在上面兩份設定檔內，是獨立目錄，最容易被漏掉——遺失則所有已註冊的檢測 Agent 全部離線且必須逐台重新註冊 | 整個目錄複製 |
這一步在做什麼：把整個資料庫倒出來、壓縮成一個帶日期的檔案。
sudo docker exec guidant-db pg_dump -U cmmgr -d guidant_ai | gzip > guidant-backup-$(date +%Y%m%d).sql.gz
成功長什麼樣：指令跑完沒有錯誤訊息，當前目錄多出一個 guidant-backup-<日期>.sql.gz 檔，檔案大小不是 0。
這三行在做什麼：把兩份設定檔與 Agent 金鑰目錄複製到您的備份位置。
sudo cp /srv/guidant-ai/guidant.env <您的備份位置>/
sudo cp /srv/guidant-ai/.env <您的備份位置>/
sudo cp -a /srv/guidant-ai/pki/agent/ <您的備份位置>/agent/
沒有使用檢測 Agent 的話，第三行可以省略；但備了不會有壞處，日後要接時就省一輪重新註冊。
使用者上傳的檔案（證據、報告、附件）存在 Docker 的資料區（volume）——Docker 專門存放資料的獨立空間，容器砍掉重建，裡面的資料還在。需要完整備份時請聯繫原廠取得該區的備份方式。
🔴 備份的保管等級要比照密碼：備份含
guidant.env，等同持有這台系統的全部憑證。請存放在加密的備份儲存、限制取用者、留存取用紀錄。
這一步在做什麼（還原）：把備份檔解壓縮，灌回資料庫。
gunzip -c guidant-backup-20260818.sql.gz | sudo docker exec -i guidant-db psql -U cmmgr -d guidant_ai
還原時必須有同一份 guidant.env，否則資料庫裡的加密資料解不開。
4.8 憑證是怎麼保管的（供貴單位資安審查參考）¶
一句話結論：所有密碼都存在只有系統管理員（root）讀得到的檔案裡，而且從來不會被放進容器；每一台客戶主機的密碼都是安裝當下各自現場生成的，沒有預設密碼、沒有跨客戶共用的鑰匙。
落地部署最常被資安人員問到的是「為什麼密碼是明文檔？」，簡短回答是：服務啟動時一定要拿到能用的密碼去連資料庫，所以密碼在某一刻必然是明文。 加密儲存只是把解密的鑰匙換個檔名放在同一台機器上，並沒有多出任何實質防護；真正的防線是檔案權限——只有 root 讀得到，而攻擊者一旦拿到 root，加不加密都一樣。這也是同型產品（GitLab、Nextcloud、Jenkins、Zabbix、Keycloak）的一致做法。
以下是給資安人員逐項核對的細節。
存放位置與權限¶
600 代表「只有檔案擁有者讀得寫得，其他人完全看不到」；root:root 代表擁有者是系統管理員。
| 檔案 | 裡面放什麼 | 誰讀得到 |
|---|---|---|
<資料目錄>/.env |
資料庫兩組、Redis、檔案儲存密碼 | root:root 600 |
<資料目錄>/guidant.env |
資料庫業務密碼、Redis 密碼、登入簽章金鑰、兩支資料加密金鑰 | root:root 600 |
<資料目錄>/certs/server.key |
HTTPS 私鑰 | root 600 |
/etc/guidant-ai/install.conf |
安裝路徑紀錄，不含任何密碼 | 644 |
這個設計防什麼、不防什麼¶
| 假想的攻擊情境 | 擋得住嗎 | 為什麼 |
|---|---|---|
| 同機的一般使用者帳號讀取密碼 | ✅ 防 | 600 + root 擁有，非 root 讀不到 |
| 服務容器被入侵後讀到密碼檔 | ✅ 防 | 兩份設定檔從未掛進容器，容器內找不到這些檔 |
| 服務容器被入侵後取得資料庫管理權限 | ✅ 防 | 服務全程只持有低權限的業務帳號；管理帳號建完庫後不再被任何長駐服務持有 |
| 備份外流導致憑證外流 | ⚠️ 需貴單位配合 | 備份含 guidant.env，保管等級須比照密碼（見 4.7） |
| 攻擊者已取得主機 root | ❌ 不防 | 此前提下任何本機儲存方案都無效 |
| 密碼長期不換而累積暴露風險 | ✅ 防 | 提供 rotate-credentials（見 4.6） |
每台安裝的憑證都是獨立的¶
出貨包內不含任何憑證。所有密碼、金鑰與 HTTPS 憑證，全部在貴單位主機上於安裝當下生成。因此沒有預設密碼，也沒有跨客戶共用的私鑰——任一客戶的憑證外流不會波及其他客戶。
最小權限¶
資料庫有兩個帳號、職責分離：管理帳號（只在建庫、備份、還原時使用，建完庫後不再被任何長駐服務持有）與業務帳號（服務天天在用，受資料列級安全政策約束）。兩者密碼各自獨立生成、不共用。
4.9 檢測 Agent 接不上時，先跑這一支¶
檢測 Agent 註冊失敗或連不上時，Agent 那一端看到的訊息幾乎都長一樣（「雲端未回傳憑證」或「連不上」），但真正的原因可能在系統這一側的任何一環。與其一項一項猜，直接跑這支。
這一步在做什麼：把該查的環節一次查完，直接告訴您哪裡不對、以及怎麼修。它是唯讀的——只讀設定與檔案狀態，不改任何東西、不重啟服務，可以安心跑。
成功長什麼樣（一切正常時）：
══ 檢測 Agent 對接檢查
✓ 認證模式：full（會簽發 Agent 憑證）
✓ 金鑰檔：六項齊備，權限與擁有者正確
✓ 容器內可讀取金鑰（…）
✓ 回給 Agent 的雲端位址：https://192.168.1.50
✓ 本機可連到該位址（Agent 端是否連得到仍需在 Agent 主機上確認）
失敗長什麼樣：有任何一項打 ✗。該行下方會接著印出「這會造成什麼症狀」與「修法指令」，照做即可。
修完通常需要重啟後端：
全部通過時退出碼（程式結束時回報的數字代碼，0 代表成功）為
0，有項目未通過為2——需要納入自動化巡檢時可據此判斷。
接 Agent 的完整步驟見 第十章 10.5。
4.10 找回安裝設定碼¶
安裝設定碼是開通精靈第一步要貼的那一串（見 第三章 3.3）。安裝完成的畫面上有印，畫面關掉了用這支找回來。
這一步在做什麼：把設定碼印在畫面上，不做任何變更。
成功長什麼樣：畫面只印出一行設定碼，整行複製貼到精靈即可。
已經開通過時：畫面顯示「系統已完成開通，設定碼已失效，不需要再輸入。」，退出碼為 2。設定碼用過即失效，開通完成後就不會再有。
4.11 產出診斷包¶
遇到查不出原因的問題、原廠請您提供資料時，用這支把分析需要的記錄一次打包。
這一步在做什麼：收集各服務的記錄、系統狀態與設定摘要，打包成一個壓縮檔。密碼與金鑰類欄位已自動遮蔽為 ***，您可以先自行解開檢視內容再交出。
可用的選項：
| 選項 | 作用 |
|---|---|
--since <時間> |
抓多久以內的資料，數字加單位（m 分鐘／h 小時／d 天），預設 24h |
--request-id <編號> |
只抓與某一次請求相關的紀錄。編號在錯誤畫面或回應標頭 X-Request-ID 上，形如 req-xxxxxxxx |
--out <目錄> |
診斷包放在哪個目錄，預設為目前所在目錄 |
--no-limit |
不套用 100MB 大小上限（包可能很大） |
成功長什麼樣：目前目錄（或 --out 指定的目錄）多出一個 guidant-diag-<時間>.tar.gz，請整個交給原廠。
失敗長什麼樣：打錯選項會直接列出可用的選項；產出失敗時退出碼為 5。
4.12 背景工作與 AI 守門規則¶
背景工作（guidant-worker）：證據自動分類這類要跑比較久的 AI 工作，使用者按下去之後是先排進佇列，由 guidant-worker 一筆一筆撿起來做，做的時候把檔案交給 guidant-sandbox（檔案沙箱）拆開檢查。guidant-worker 沒在跑時，單子會一直停在「排隊中」，畫面不會報錯——使用者回報「分類一直沒結果」時，先看 sudo guidantai status 的這一行。
AI 守門規則目錄（/srv/guidant-ai/ai-gateway-rules/）：AI 助理、AI 儀表板、證據自動分類送給外部 AI 之前要過一道守門（遮蔽機敏資料、擋下不該送的內容、偵測操控 AI 的指令），這些規則與 AI 的回答指示都放在這個目錄裡的三個檔，放寬或收緊不必重裝、不必換版：
- 改完要重啟兩個服務才生效：
sudo guidantai restart guidant-api與sudo guidantai restart guidant-worker（前者管 AI 助理與儀表板、後者管證據分類，只重啟一個另一邊還是舊規則）。 - 改壞了（例如 YAML 縮排錯），重啟時服務會起不來並在記錄裡指出哪個檔；同目錄旁的
ai-gateway-rules.default/是出廠原檔，複製回去即可救回。
每一段怎麼改、常見調整食譜、改完怎麼確認 → 《AI 守門調整手冊》（docs/user-manual/ai-guard-tuning-guide.md，可向原廠索取）。
4.14 錯誤追蹤站¶
系統內建一個錯誤追蹤站：系統哪裡出錯，它就把當下的狀況（錯在程式的哪一行、當時的資料、哪位使用者、哪一次操作）記一筆下來，原廠人員看了就知道從哪裡查起。
就像車上的行車記錄器——平常不必看它，出事時才調出來，看當下發生了什麼。
站台只存在您自己的主機上，錯誤資料不會送到原廠。 安裝與升級時會自動建好，不需要另外設定，也不需要多開任何埠。
怎麼開¶
用瀏覽器開：
<主機> 就是平常開系統用的網址或 IP。
| 欄位 | 填什麼 |
|---|---|
| 帳號 | admin@guidantai.com（固定） |
| 密碼 | 存在主機上的檔案裡，用下面這行查 |
資料目錄不是
/srv/guidant-ai的話，改成您安裝時指定的目錄。這個檔只有 root 讀得到。
登入後會看到三個專案：
| 專案 | 收誰的錯誤 |
|---|---|
guidant-ai |
系統後端（含背景工作與證據分類） |
guidant-ai-fe |
使用者的瀏覽器（登入後才會回報，登入頁本身的錯誤收不到） |
guidant-agent |
各台檢測 Agent（每筆會標出是哪一台） |
看一筆錯誤¶
- 點進專案，列表裡每一列是「同一種錯誤」，旁邊有發生次數與最後一次的時間。
- 點進一列，就是最近一次發生的完整內容：
- 堆疊：錯在哪個檔案的哪一行，以及每一層當時的資料。
- 使用者：踩到錯誤的登入帳號。
request_id：這次操作的編號，形如req-xxxxxxxx。
密碼、權杖這類欄位在送進站台前就已經遮成 ***。
用編號找回同一次操作的記錄¶
錯誤追蹤站上的 request_id，與後端記錄裡每一行開頭的編號是同一個。拿它就能找到那次操作前後發生了什麼：
sudo guidantai logs guidant-api # 畫面上搜尋該編號
sudo guidantai diag --request-id req-xxxxxxxx # 或打包這一次操作的記錄交給原廠
背景工作沒有對應的使用者操作，編號會是 - 或 job- 開頭。
預設收哪些錯誤¶
預設全收：程式錯誤，加上使用者這一端的失誤（打錯密碼、沒有權限、找不到資料）都會記。站台被這類失誤灌滿、看不到真正的程式錯誤時，可以只收程式錯誤：
在 <資料目錄>/guidant.env 加上（或改成）：
存檔後套用：
⚠️ 一定要用
start，不要用restart——restart不會讀取新的設定（見 4.3）。
另一個開關 ERROR_TRACKING_LOG_EVENTS（預設 true）決定「記錄裡每一行錯誤訊息是否各自成一筆」，設 false 時那些訊息只附在下一筆錯誤裡當前情參考。
保留多少、怎麼清¶
每個專案最多保留 1 萬筆，超過時站台自己挑較不重要的舊資料淘汰，不會無限長大。
這一步在做什麼：清掉站台裡已刪除問題的殘留與用不到的暫存檔，印出清理前後的事件筆數。
它不會依日期刪除舊事件——事件量由上面的 1 萬筆上限管住。前後筆數一樣是正常的。
改管理員密碼¶
這一步在做什麼：互動輸入兩次新密碼（畫面不顯示），通過站台的密碼規則才會改，成功後 bugsink-admin.secret 會同步更新為新密碼。
失敗長什麼樣：密碼太短或太常見時會直接說明不合格的原因，密碼不會被改。
這組密碼在每一份安裝包裡相同。貴單位若有要求，裝好後可用這支改成自己的密碼；升級不會把它改回去。
用 IP 安裝、之後再掛網域¶
用網域開站台出現 400 時，表示這個網域不在站台的允許清單內（錯誤照樣收得到，只是人進不去）。在 <資料目錄>/.env 找到這一行，把網域加在最後，用逗號隔開：
存檔後：
之後升級會保留您加上的網域。
換了系統網址¶
主機換了 IP 或正式網址時，改 <資料目錄>/guidant.env 的 SYSTEM_URL，然後在出貨包目錄跑一次：
站台網址、允許清單與連線設定會一起依新網址重寫。只改設定不跑這一步，瀏覽器與檢測 Agent 的錯誤會送不進站台，而且不會有任何錯誤訊息。
值得知道的幾件事¶
- 升級或重啟服務的那幾秒內發生的錯誤，可能沒有被記下來。
- 檢測 Agent 升級後會自動開始回報，不需要重新註冊；請先升級本系統，再升級 Agent。
- 站台沒有寄信或通知的功能，要主動打開來看。
- 安裝時沒有建起站台（例如貴單位自備資料庫），安裝畫面會有一行黃色提示，系統其他功能不受影響。