跳轉到

系統完整性鎖定與解鎖指南

適用對象：落地部署版客戶端的系統管理員（能登入伺服器主機、操作容器的人）。雲端 SaaS 版不適用本文。 本文用途：看到「系統已鎖定」畫面時該怎麼辦——如何取得回報所需資訊、如何聯繫原廠、收到解鎖憑證後如何完成解鎖。 不在本文範圍：授權（License）到期與停權造成的唯讀／鎖定（那是另一回事，請見《授權管理使用指南》第七、八節）。

變更紀錄

日期 內容
2026-08-16 首版：鎖定畫面說明、取得事件編號與機器指紋、聯繫原廠、解鎖憑證核銷步驟、常見問題

一、什麼是「系統完整性鎖定」

Guidant AI 在每次啟動時、以及運行期間定期，會核對自身程式檔案是否與原廠出廠時的簽章一致。核對不一致時，系統會依約定停止提供服務並進入鎖定狀態。

這是產品的安全設計，不是故障——重新啟動不會恢復，也不需要重灌。解除鎖定的唯一方式，是向原廠取得一份解鎖憑證（一個檔案）。

與授權到期是兩回事。 授權到期或被停權時系統仍可登入、可查閱、可匯出（唯讀）；完整性鎖定則是整個服務不啟動，畫面上會明確顯示「系統已鎖定」。

常見的觸發原因：

  • 部署或升級過程中斷，造成程式檔案不完整
  • 磁碟或檔案系統異常，造成檔案內容毀損
  • 有人在主機層（SSH 登入、進入容器）直接改動了產品檔案

二、你會看到什麼

服務鎖定期間，瀏覽器開啟系統會導向一頁「系統已鎖定」畫面（無論原本要進哪一頁）。畫面上有：

  • 標題「系統已鎖定」與說明文字
  • 事件編號（evt- 開頭的一串字元），旁邊有複製按鈕
  • 一段提示：請聯繫原廠並提供這些資訊以取得解鎖

畫面預設只顯示事件編號。原廠受理時還需要另一項「機器指紋」，取得方式見下一節。

三、取得回報所需的兩項資訊

原廠簽發解鎖憑證需要兩個值：機器指紋與事件編號。

方法一：從鎖定畫面取得（推薦，不需登入主機）

  1. 在鎖定畫面上先複製事件編號。
  2. 在瀏覽器網址列，於目前網址尾端加上 ?details=1，然後重新整理頁面。
  3. 例如網址是 https://<你的系統網址>/system-locked?eid=evt-...，就改成 https://<你的系統網址>/system-locked?eid=evt-...&details=1
  4. 若網址上原本沒有任何 ? 參數，直接在尾端加 ?details=1
  5. 重整後，畫面會多出機器指紋與偵測時間兩列，各自可複製。

為什麼要多這一步：機器指紋與偵測時間並非機密，但預設隱藏，避免一般使用者看到一長串技術資訊而困惑。需要時由原廠客服指引你加上這個參數。

方法二：從伺服器啟動紀錄取得

若無法從畫面取得（例如網址參數被清掉），可登入伺服器查看容器啟動紀錄：

docker logs guidant-api 2>&1 | tail -50

其中會有一段以 [FATAL] 開頭的訊息，包含：

  machine_fingerprint: <64 個十六進位字元>
  tamper_event_id: evt-<...>

把這兩行的值抄下來即可。同一段訊息也會列出不符的檔案清單——回報時一併提供有助原廠研判。

四、聯繫原廠

透過原廠提供的既有聯繫管道（電話／郵件），提供以下資訊：

必須提供 說明
機器指紋 64 個十六進位字元，須完整無誤——這是解鎖憑證綁定的依據，抄錯一個字元憑證就無法使用
事件編號 evt- 開頭；解鎖憑證只對這一次事件有效
有助研判（建議提供） 說明
偵測時間 畫面上或啟動紀錄中的時間
近期操作 最近是否做過升級、部署、主機維護
啟動紀錄 docker logs 中的 [FATAL] 區塊全文

原廠研判後會簽發一份解鎖憑證檔（檔名 unlock.token）給你。

解鎖憑證是一次性、綁定這台機器、且有使用期限的（預設 72 小時）。請於收到後儘快完成解鎖；逾期需請原廠重新簽發。

五、解鎖步驟

步驟 0：先還原檔案（重要）

解鎖憑證解除的是「鎖定狀態」，不是「檔案與出廠狀態不符」這件事本身。若程式檔案沒有先還原，解鎖後系統仍會在同一次啟動中再次驗證、再次鎖定。

因此請先確認：

  • 若因部署／升級中斷造成，請重新部署原廠提供的 image
  • 若因人為改動造成，請將改動還原
  • 不確定時，請與原廠確認後再進行下一步

步驟 1：把憑證檔放進指定目錄

把原廠給的檔案以 unlock.token 為檔名（下載時即為此名，不需改名）放進主機上的產品資料目錄下的 pki 子目錄：

# 預設路徑（若部署時有調整 GUIDANT_DATA_DIR，請依實際設定）
cp unlock.token /srv/guidant-ai/pki/unlock.token

這個目錄就是容器內的 /opt/guidant/pki（掛載對應關係定義在部署用的 docker-compose.yml）。系統在啟動時會到這裡找 unlock.token 這個檔名。

步驟 2：重新啟動服務

docker restart guidant-api

🔴 必須使用 docker restart，不可以用 docker rm 刪除容器再重建。 重建容器可能改變機器指紋，一旦指紋改變，原廠簽給你的解鎖憑證就會失效（顯示「此 token 是為另一台機器簽發的」），必須重新申請。

步驟 3：確認解鎖結果

docker logs guidant-api 2>&1 | tail -30

成功時會看到：

[INTEGRITY] ✅ 解鎖 token 核銷成功，竄改鎖定已解除。

之後系統會繼續完成啟動並恢復正常服務。憑證檔會在核銷成功後自動移除（已用過，留著無用）。

失敗時會看到 [INTEGRITY] ⛔ 解鎖 token 核銷未通過，並附上明確原因——請將該段訊息完整提供給原廠。

六、常見狀況

解鎖成功後，系統立刻又鎖定了

這是設計行為，不是解鎖失敗。 系統檔案仍與出廠狀態不符時會再次鎖定——請確認程式檔案已完整還原（或重新部署原廠 image），並聯絡原廠取得新的解鎖憑證（再次鎖定會產生新的事件編號，原本那張憑證對它無效）。

憑證放進去了，但重啟後沒反應

請確認：

  • 檔名是否為 unlock.token（大小寫相符）
  • 放置路徑是否為主機上對應到容器 /opt/guidant/pki 的目錄
  • 該目錄是否為可寫的持久掛載——系統需要在其中記錄「這張憑證已使用」，寫不進去時會拒絕解鎖並明確提示

收到「已經使用過，不可重複使用」

每張解鎖憑證只能用一次。請聯絡原廠重新申請。

收到「已過期」

解鎖憑證有使用期限。請聯絡原廠重新簽發。

憑證檔可以用文字編輯器打開修改嗎

不可以。 憑證帶有原廠數位簽章，任何改動（包括編輯器自動加上的換行或編碼轉換）都會使簽章驗證失敗。請保持原始下載檔案不動。

這個檔案跟「授權檔」是同一種東西嗎

不是。 解鎖憑證（unlock.token）用於解除完整性鎖定，放進主機目錄後由系統自行讀取；授權檔（.license）用於開通功能模組，是在系統畫面上傳的。兩者不可互換，也不要拿解鎖憑證去授權管理頁上傳。

附錄：名詞對照

名詞 意思
完整性驗證 系統核對自身程式檔案是否與原廠出廠簽章一致
系統完整性鎖定 驗證失敗時，系統依約定停止服務並鎖定的狀態
事件編號 單次鎖定的識別碼，evt- 開頭；解鎖憑證只對特定一次事件有效
機器指紋 這台伺服器的識別碼（64 個十六進位字元）；解鎖憑證綁定它，不能跨機使用
解鎖憑證（unlock token） 原廠簽發的一次性、綁機、有期限的檔案，檔名 unlock.token