系統完整性鎖定 → 解鎖 SOP（原廠內部作業文件）

適用對象：原廠客服／技術支援／授權簽發人員（坐在 License Center 後台前受理客戶回報的人）。 本文用途：客戶回報系統鎖定後，從研判到簽出 unlock token、交付客戶的完整作業流程。 不在本文範圍：防竄改機制的設計理由與決策（見同資料夾 design.md §2 D5/D6/D11、§4.2–4.4）；客戶端操作（見 docs/user-manual/system-integrity-lockdown-guide.md）。 ⚠️ 本文不含任何密碼、passphrase、token 值。需要 passphrase 時一律查部署文件或 .env。

變更紀錄

Guidant AI 落地部署版在啟動時與運行期間會比對產物檔案的 SHA-256 與原廠簽章 manifest。比對失敗即進入鎖定：正常服務不啟動，改由一個極簡的 lockdown 殼回應所有請求（HTTP 503），客戶端看到一頁「系統已鎖定」。

解鎖的唯一途徑，是原廠用 License Center 私鑰簽出的一次性 unlock token。沒有其他後門、沒有旁路開關——這是刻意的設計（design.md D6/D8）。

客戶端偵測到完整性驗證失敗
        │
        ▼
服務鎖定（lockdown 殼回 503，畫面顯示事件編號）
        │
        ▼
客戶透過人工通道（電話／郵件）回報 ── 提供 machine_fingerprint ＋ tamper_event_id
        │
        ▼
【原廠】研判（誤鎖 or 真竄改）→ 兩者都走同一條簽發路徑，但研判紀錄要留
        │
        ▼
【原廠】License Center 簽發 unlock token（後台頁 或 CLI）
        │
        ▼
交付客戶（token 檔）
        │
        ▼
客戶把檔案放進主機 pki 目錄 → docker restart → 啟動時核銷四關 → 解鎖

🔴 解鎖不豁免當次的完整性驗證。 核銷成功後啟動流程仍會往下跑完整 manifest 比對——被改動的檔案若沒還原，會立刻再次鎖定（新的事件編號、新的 token）。因此交付 token 前必須先確認客戶已把產物還原（或已重新部署原廠 image）。

2.1 兩種情況、同一條路徑

兩者走同一條簽發路徑（D6 定案）——技術上不做區分，因為機器端無從自證。差別在紀錄：簽發表單的「研判備註」欄必須寫清楚 ①客戶回報管道與時間 ②判定為誤鎖或真竄改 ③判定依據。這欄會與 token 一起落進 License Center 的 unlock_token_issuance 稽核帳（append-only），日後「誰為什麼簽了什麼」要答得出來。

2.2 邊界：不要承諾查明「是誰改的」

產品沒有、也不可能有「是誰改了檔案」這個答案——竄改動作走 SSH／docker exec 等主機層管道，不經過任何業務邏輯（design.md §4.4.3）。

系統蒐集到的是檔案證據（不符檔案的 mtime／ctime／owner／size）與若剛好有業務 session 在跑時的旁證，不是身分溯源。對客戶溝通時：

• ✅ 可以說：「產品完整性驗證失敗，事件編號 evt-…，不符檔案 N 個，最近修改時間為 …」
• ❌ 不要說：「我們查到是誰改的」「這是某某帳號做的」

契約層面綁的是「完整性驗證失敗即構成違約事由」這個客觀事實，不以查明具體操作人員為前提（措辭見 design.md §4.4.3）。

2.3 蒐集研判材料

要客戶提供（或自行從回報事件查）：

D9 在線回報：客戶端偵測到竄改時會 best-effort 把事件 POST 給 License Center（POST /api/internal/report-tamper，存於 tamper_events 表）。發得出就發、發不出不重試——所以「LC 這邊查不到事件」不代表客戶沒被鎖定，離線環境本來就送不出來。

3.1 進入位置

License Center 後台 → 導覽列「解鎖 token」（路徑 /unlock），需登入。

服務位址：http://<LC 主機>:5062（STG 在 188 /opt/license_center，systemd unit license-center.service）。

3.2 填寫欄位

服務端守門（三個入口共用，抄漏一段會在這裡就被擋下）：

• 機器指紋必須是 64 個十六進位字元
• 事件編號必須以 evt- 開頭
• 效期必須在 1～336 小時之間

這些守門刻意放在服務層而非表單層：抄漏一段的值若放行簽出，客戶端拒收的原因會顯示成「這是為另一台機器簽發的 token」，現場查不出真因。

3.3 簽發後

送出成功會跳到結果頁，顯示 token_id、有效期限與完整 payload。按「下載」取得檔案：

• 檔名固定 unlock.token（客戶下載完直接丟進目錄，不必改名）
• 內容是 v2 信封裸 JSON，刻意不套 v3 armor——armor 標頭寫的是 GUIDANT LICENSE，套上去會讓客戶誤以為是授權照而拿去「授權管理」頁上傳

下載動作本身也落 log（誰拿走了哪一張）。

簽發站的 Web 後台不可達，或作業環境完全離線時使用。與後台頁同一條 code path、同一把私鑰、同樣寫稽核帳。

在 LC 部署目錄（如 /opt/license_center）執行：

poetry run python -m license_center.cli.main issue-unlock-token \
  --machine-fingerprint <客戶回報的 64 hex> \
  --tamper-event-id evt-xxxxxxxx \
  --issuer <簽發人> \
  --valid-hours 72 \
  --remark "客戶電話回報；判定為部署中斷造成的誤鎖" \
  --output /tmp/unlock.token

執行時會互動式要求輸入私鑰 passphrase（不接受命令列參數帶入，避免落進 shell history）。

⚠️ 簽出 token 等於解除客戶端該次鎖定——請先完成研判再執行。

指定 --output 時，CLI 會提示：交付客戶後請其將檔案更名為 unlock.token 放進竄改標記目錄（預設 /opt/guidant/pki/）並重啟服務。

再加上綁事件：tamper_event_id 必須等於客戶端目前標記檔內的事件編號——每一次鎖定都要原廠重新研判簽發，舊 token 不能沿用。

過期或作廢後的重簽流程

token 過期、客戶弄丟、或「解鎖後檔案沒還原導致立刻再次鎖定」時：

1. 請客戶重新回報當前畫面上的事件編號（再次鎖定會產生新的 tamper_event_id，舊的那張 token 對它無效）
2. 機器指紋通常不變（同一台機器），但仍請客戶一併確認
3. 依 §3 或 §4 重新簽一張，研判備註註明是重簽及原因

1. 透過既有安全管道（郵件／客戶入口）交付 unlock.token 檔
2. 同時提醒客戶三件事：
   • 先把被改動的檔案還原（或重新部署原廠 image），否則解鎖後會立刻再次鎖定
   • 放檔位置與重啟方式見客戶手冊（docs/user-manual/system-integrity-lockdown-guide.md）
   • 🔴 重啟必須用 docker restart，不可 docker rm 後重建容器——重建可能改變機器指紋，token 隨即作廢
3. 指引客戶完成後回報結果；若失敗，請其提供啟動 log 的 [INTEGRITY] 區塊（失敗訊息會明確指出是四關中的哪一關）

客戶端核銷會印出明確的失敗原因（[INTEGRITY] ⛔ 解鎖 token 核銷未通過）。對照處置：

四種失敗訊息刻意各不相同且含處置建議——含糊的訊息會讓現場把「指紋抄錯」誤判成「原廠簽錯了」，來回數輪查不出來。