跳轉到

四、日常維運

這章在講什麼：系統裝好之後，平常要怎麼照顧它。

就像家裡的總電箱——平常不用天天開來看，但要知道開關在哪、跳電時怎麼推回去、電費單（記錄）放在哪個抽屜。本章把「看狀態、開關機、查記錄、查密碼、換密碼、備份」這幾件日常事一次講完。

什麼時候看：裝好之後放在手邊。使用者回報系統怪怪的、主機要維護要先關機、貴單位要求定期換密碼或做備份時，翻這章。

好消息：您不需要記任何 Docker 指令，也不需要知道設定檔放在哪裡。 裝好之後的所有操作都走 guidant 這一個指令，後面接不同的子命令（同一個指令後面加一個詞，決定它這次要做哪件事，像 status、start、stop）。

sudo guidant <子命令>

不必先切換目錄：安裝時已經把 guidant 放進系統路徑（/usr/local/bin/guidant），在任何目錄下都能直接打。

出貨包可以刪掉——維運指令與它需要的設定都已經在安裝時複製到系統目錄，不再依賴出貨包。（建議還是留著壓縮檔備查，但解壓出來的目錄刪掉沒有影響。）

升級之後不用做什麼：新版安裝包會自動把 guidant 一起更新，維運指令永遠跟著目前的系統版本走。

4.1 子命令一覽

先掃一眼有哪些指令可用，細節在後面各節。

這個指令 它會做什麼
sudo guidant status 六個服務的健康狀態一覽（版本／狀態／已執行多久）
sudo guidant start 啟動全部服務（改過設定也用這個才會生效）
sudo guidant stop 停止全部服務（資料完全保留）
sudo guidant restart 逐一重啟六個服務
sudo guidant restart <服務名> 只重啟一個
sudo guidant logs 看後端主程式的記錄（Ctrl-C 離開）
sudo guidant logs <服務名> 看指定服務的記錄
sudo guidant fingerprint 印出本機機器碼（申請授權用；服務沒起來也能查）
sudo guidant rotate-credentials 輪換系統內部服務帳號的密碼（資料庫兩組＋Redis）
sudo guidant agent-check 檢查檢測 Agent 對接是否備妥（唯讀檢查，會直接指出哪裡不對與修法） → 見 4.9
sudo ./install.sh --check-only 只跑環境檢查，不做任何變更（這兩個仍在出貨包的 install.sh）
sudo ./install.sh --upgrade 換版升級 → 見 第五章
sudo guidant uninstall 🔴 移除整套系統與所有資料 → 見 第六章
guidant --help 印出用法（唯一不需 sudo 的指令）

服務名只認這六個：guidant-db、guidant-redis、guidant-seaweedfs、guidant-api、guidant-socketio、guidant-fe。打錯字會直接列出可用的名稱，不會靜靜失敗。

4.2 查看狀態

這是最常用的一支——想知道「系統現在好不好」，先跑它。

這一步在做什麼：把六個服務各自的狀況印出來，不做任何變更。

sudo guidant status

成功長什麼樣：

══ 服務狀態
  版本：1.16.0    資料目錄：/srv/guidant-ai

    guidant-db          running   healthy   已執行 3 天
    guidant-redis       running   healthy   已執行 3 天
    guidant-seaweedfs   running   healthy   已執行 3 天
    guidant-api         running   healthy   已執行 3 天
    guidant-socketio    running             已執行 3 天
    guidant-fe          running   healthy   已執行 3 天

  站台網址：https://192.168.1.50

running 代表服務在跑，healthy 是健康檢查（服務每隔一段時間自我回報「我還活著而且運作正常」）的結果。

有服務沒在跑時：畫面下方會直接給您下一步的指令，不需要自己猜。

guidant-socketio 那一行沒有健康狀態欄，這是正常的——它沒有設健康檢查（它負責即時通知，晚幾秒可用不影響登入）。

4.3 啟動、停止、重啟

這幾行在做什麼：分別是關機、開機、重開，最後一行是只重開其中一個服務。

sudo guidant stop       # 停止（例如主機要維護）
sudo guidant start      # 啟動
sudo guidant restart    # 重啟全部
sudo guidant restart guidant-api    # 只重啟後端

stop 不會刪除任何資料，之後 start 回來一切照舊。

⚠️ restart 與 start 不一樣，改過設定請用 start：

它做什麼 什麼時候用
restart 把現有容器停了再起，不重讀版號、不套用設定檔的變動 服務卡住、要它重來一次
start 依目前設定重新建立容器，設定有變就會生效 改過任何設定之後、換版、回滾

為什麼會這樣：設定值是在容器「建立」的那一刻寫進去的。restart 沒有重建容器，所以它讀到的還是舊值——即使設定檔裡已經是新的。

這個坑不會再靜默發生：guidant restart 會先比對「設定檔的修改時間」與「容器的建立時間」，發現設定比容器新就直接擋下，並告訴您改用 start。也就是說，改完設定誤打 restart，您會看到清楚的提示，而不是「指令成功但設定沒生效」。

若您確定只是碰過檔案、內容其實沒改（例如用編輯器開起來又存檔），要照原意重啟可以加 --force：sudo guidant restart --force。

主機重新開機後：服務會自動回來（前提是 Docker 有設定開機自起，見 1.3）。不放心可以開機後跑一次 status 確認。

4.4 看記錄

記錄（log） 是服務自己寫下的流水帳，出事時是最直接的線索來源。

這幾行在做什麼：把指定服務的記錄印在畫面上，並持續顯示新進的內容。

sudo guidant logs                # 後端主程式（最常用）
sudo guidant logs guidant-db     # 資料庫
sudo guidant logs guidant-fe     # 網站

成功長什麼樣：畫面持續滾動出新的記錄行。看夠了按 Ctrl-C 離開——這只是停止顯示，不會影響服務。

記錄檔本身會自動輪替（寫滿就換新檔、舊檔超過數量就刪掉，每個服務最多保留 5 份、每份 20 MB），不會無限長大佔滿磁碟。

4.5 內部服務憑證

憑證在這裡指的是系統內部各服務彼此連線用的帳號密碼與金鑰（金鑰＝加解密用的鑰匙）。這些是安裝當下自動產生、寫入權限 600 的設定檔，服務啟動時自行讀取——日常操作不需要、也不會顯示這些值。

若貴單位的密碼保險庫（Vault、CyberArk、Bitwarden 這類集中保管帳密的系統）政策要求登錄特權帳號，請由具 root 權限的管理者依原廠提供的維運文件自設定檔讀取後登錄；本系統不提供把密碼印到畫面上的指令。

4.6 定期換密

輪換密碼就是定期換鎖——即使舊鑰匙曾經外流，換了之後也開不了門。多數資安規範都要求定期做。

這一步在做什麼：重新產生資料庫兩組與 Redis 共三組密碼，同時改掉服務端與設定檔。新值只寫入設定檔，不會顯示在畫面上。

sudo guidant rotate-credentials

成功長什麼樣：三組密碼各自完成的訊息，過程中服務會短暫重啟。

輪換後使用者不需要重新登入——登入簽章金鑰沒有被動到。

內建檔案儲存的憑證不在輪換範圍內——它是兩個容器之間的內部憑證（不對外開放），而且沒有等價的線上回滾手段。

失敗長什麼樣：畫面印出失敗訊息，並明說「設定檔完全沒有被變更」。這是設計上的保護：換密過程先寫暫存檔、全部成功才覆蓋，任一步失敗時服務端的密碼也會改回舊值，系統維持原狀、不需重啟即可繼續使用。

🔴 登入簽章金鑰與兩支資料加密金鑰刻意不納入輪換：

  • 換登入簽章金鑰 = 所有使用者當場登出、進行中的操作全部中斷
  • 換資料加密金鑰 = 資料庫裡既有的 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 那一端看到的訊息幾乎都長一樣（「雲端未回傳憑證」或「連不上」），但真正的原因可能在系統這一側的任何一環。與其一項一項猜，直接跑這支。

這一步在做什麼：把該查的環節一次查完，直接告訴您哪裡不對、以及怎麼修。它是唯讀的——只讀設定與檔案狀態，不改任何東西、不重啟服務，可以安心跑。

sudo guidant agent-check

成功長什麼樣（一切正常時）：

══ 檢測 Agent 對接檢查
  ✓ 認證模式：full（會簽發 Agent 憑證）
  ✓ 金鑰檔：六項齊備，權限與擁有者正確
  ✓ 容器內可讀取金鑰（…）
  ✓ 回給 Agent 的雲端位址：https://192.168.1.50
  ✓ 本機可連到該位址（Agent 端是否連得到仍需在 Agent 主機上確認）

失敗長什麼樣：有任何一項打 ✗。該行下方會接著印出「這會造成什麼症狀」與「修法指令」，照做即可。

修完通常需要重啟後端：

sudo guidant restart guidant-api

全部通過時退出碼（程式結束時回報的數字代碼，0 代表成功）為 0，有項目未通過為 2——需要納入自動化巡檢時可據此判斷。

接 Agent 的完整步驟見 第十章 10.5。