五、日常維運¶

這章在講什麼：裝好之後，平常要怎麼看它、怎麼開關它、怎麼備份它。

就像家裡的熱水器——裝好之後平常不用管它，但您要知道開關在哪、指示燈怎麼看、還有哪幾顆按鈕千萬別亂按。本章就是這台機器的操作面板說明。

什麼時候看：裝完之後隨時翻。其中 5.6 備份與 5.7 千萬不要做的事這兩節，建議一開始就先讀過一遍。

裝完之後的所有操作都走同一支指令 guidant-agent-compose——不需要記任何 Docker 語法，也不需要知道安裝目錄在哪。

這支指令是安裝時複製到 /usr/local/bin 的安裝程式副本，在任何目錄下都能用——它靠 /etc/guidant-ai-agent/install.conf 找到安裝位置，所以出貨包刪掉之後照樣運作。

5.1 子命令一覽¶

打這個指令	它會做什麼
`sudo guidant-agent-compose status`	服務狀態、版本、雲端註冊狀況
`sudo guidant-agent-compose logs`	即時查看記錄（Ctrl-C 離開）
`sudo guidant-agent-compose start`	啟動
`sudo guidant-agent-compose stop`	停止（資料完全保留）
`sudo guidant-agent-compose restart`	重啟
`sudo guidant-agent-compose fingerprint`	印出本機設備指紋
`sudo guidant-agent-compose configure-storage`	設定證據檔存到哪（見第六章）
`sudo guidant-agent-compose upgrade <新版出貨包>`	換版升級（見第七章）
`sudo guidant-agent-compose uninstall`	移除（見第八章）

看完整用法：guidant-agent-compose --help（不需要 sudo）。

5.2 查看狀態¶

這步在做什麼：一次看完服務有沒有在跑、用哪個版本、平台認不認得它。

sudo guidant-agent-compose status

成功長什麼樣：畫面內容已在 4.2 說明過。三個要留意的地方：

看這一項	正常應該是
兩個服務	都是 `healthy`
儲存後端	`seaweedfs`（出廠預設）或您切換過去的那一種
雲端註冊	已完成（心跳正常）

失敗長什麼樣：有服務沒在跑。這時畫面最後會直接給您下一步該打什麼指令，不用自己猜。

5.3 啟動、停止、重啟¶

sudo guidant-agent-compose stop      # 停止
sudo guidant-agent-compose start     # 啟動
sudo guidant-agent-compose restart   # 重啟

停止不會遺失任何資料。 證據檔、憑證、索引都存在獨立的資料區（volume，Docker 存放資料的獨立空間，容器砍掉重建資料還在），停止只是把服務關掉而已。重新啟動後 Agent 會直接接回原本的身分，不需要重新註冊。

主機重新開機時 Agent 會自動回來，前提是 Docker 服務設了開機自起（見 1.3）。

5.4 看記錄¶

這步在做什麼：即時看 Agent 正在做什麼、有沒有報錯。

sudo guidant-agent-compose logs                            # Agent 的記錄
sudo guidant-agent-compose logs guidant-agent-seaweedfs    # 內建儲存的記錄

Ctrl-C 離開。回報問題給原廠時，記錄內容是最有價值的資訊。

正常長什麼樣（可作為對照，看到這些就表示一切順利）：

[integrity] 完整性驗證通過（... 個檔案，版本 ...）
device_uuid computed: ...
agent enrolled: agent_uid=...  heartbeat=...
data-plane mTLS listening on 0.0.0.0:8443 (client certificate required)
agent auth ready (mode=full, status=active, ...)
POST .../agents/heartbeat "HTTP/1.1 200 OK"     ← 之後每隔一個心跳週期出現一次

5.5 查設備指紋¶

這步在做什麼：印出這台機器的設備指紋，並順便對帳。

sudo guidant-agent-compose fingerprint

成功長什麼樣：印出一份小報告——兩個來源的值、算出來的指紋、以及與服務實際回報值的對帳結果。用途見 4.3。

5.6 備份：三個資料區都要¶

🔴 這一節是本章最重要的內容。 Agent 的證據檔存在貴單位自己的磁碟上，磁碟壞了就沒有第二份——請務必建立備份機制。責任分工詳見第六章 6.5。

Agent 有三個資料區（Docker 的具名 volume），缺任何一個，證據檔都取不回來：

資料區	裡面存什麼	掉了會怎樣
`seaweed-data`	證據檔本體	證據永久遺失
`agent-db`	檔案索引（哪個檔在哪裡）	有檔案但對不上，等同遺失
`agent-certs`	這台機器的身分憑證	要向平台重新註冊

備份指令¶

這幾行在做什麼：先把服務停下來（確保檔案不是寫到一半的狀態），把三個資料區各打包成一個壓縮檔，最後把服務啟回來。

# 先停服務，確保檔案處於一致狀態
sudo guidant-agent-compose stop

# 三個資料區各備一份
for v in agent-db agent-certs seaweed-data; do
  sudo docker run --rm -v "guidant-ai-agent_${v}:/d" -v "$PWD:/b" alpine \
    tar czf "/b/${v}-$(date +%Y%m%d).tgz" -C /d .
done

sudo guidant-agent-compose start

成功長什麼樣：當前目錄下多出三個 .tgz 壓縮檔，檔名各自帶當天日期。

資料區的實際名稱可用 sudo docker volume ls 查看。1.0.0 起一律是 guidant-ai-agent_agent-db 這種固定名稱（不再隨安裝目錄改變）；0.2.32 以前的安裝則是 <安裝目錄名>_agent-db。

建議的備份策略¶

項目	建議怎麼做
多久備一次	依證據產生頻率而定；有稽核活動期間建議每日
備份放哪裡	另一台機器或另一顆磁碟——與 Agent 同機的備份，機器壞了會一起沒
要留幾份	至少三份不同時間點的（防「壞掉的狀態被備份覆蓋」）
怎麼確認備份有效	定期實際解開一份確認可讀，不要只確認檔案存在

5.7 千萬不要做的事¶

❌ 不要	為什麼
`docker compose down -v`	那個 `-v` 會刪掉全部三個資料區——所有證據檔、身分憑證與索引一次消失，且沒有任何確認提示
刪除或搬移安裝目錄 `/srv/guidant-ai-agent/`	設定檔、服務定義檔都在裡面，刪了維運指令全部失效。（解開出貨包的那個目錄則可以隨意刪，那不是安裝目錄）
手動編輯 `.env`	用 `configure-storage` 等子命令改（它們會驗證、會備份、會正確重建容器）。手改容易踩到「改了但沒生效」
重新產生 `/etc/machine-id`	等於這台機器換了身分

需要停止服務時用 sudo guidant-agent-compose stop——它保證不帶 -v。

5.8 Agent 用掉多少磁碟¶

這步在做什麼：查三個資料區各自佔了多少空間。

sudo docker system df -v | grep -E 'agent-db|agent-certs|seaweed-data'

成功長什麼樣：印出三行，每行是一個資料區與它的用量。

證據檔會持續累積且不會自動清理。建議把 Agent 主機的磁碟用量納入既有的監控機制，設一個警戒水位（例如 80%）。

磁碟滿了長什麼樣：症狀是檢測報告存不進去——記錄裡會出現上傳失敗，而平台端看到的是任務失敗。