設計文件：D1～D31 與各部件設計

狀態：v1 定案，待開卡｜日期：2026-10-29｜母卡：待建｜前作：FR-065（install.sh --upgrade、guidantai）、FR-066（Agent 安裝包）、FR-062（授權中心、Ed25519 簽章、kid 公鑰表）、FR-064（簽章驗證）、FR-134（弱點資料更新頁：更新中心的版面與 chunk 上傳的範本）、FR-166（Agent outbox：結果送不出先存著已做掉） 討論稿（選項推演、業界對照、排除方案）：discussion.html｜雛形：prototype/index.html（10 頁） 開發 branch：BE／FE／jedi-python-package／evidence-agent／license_center 2026-10-29 查皆在 feature/FR-139；update-center 是新 repo（已建、branch main，P2-1 從它長出）；runner 開工 git branch --show-current 再確認，不對就停下問，不切

🔴 這份是設計決策，不是現況。 內文的行號、檔名、數字停在 2026-10-29 定稿當時，之後實作改動的結果不回頭改寫這裡。上線後的畫面與 API 現況看 SPEC 頁與 FINAL-SPEC。

現在每出一版，客戶要自己把 2.9GB 的出貨包搬上主機、照手冊敲 install.sh --upgrade；它直接在現在那份資料庫上套 migration，失敗靠事前備份還原，還原是寫入動作、本身會失敗。客戶在國外時這條路走不通。決策者的要求：按下確認之後全自動、看得到進度、不可以卡住、卡住也要能復原、資料絕對不掉、不靠人到現場、不自動裝、客戶主機上不多常駐程式不開新的埠。

做完之後

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
sequenceDiagram
    participant CI as 188 CI
    participant US as 更新站（Worker＋R2）
    participant DM as 決策者電腦
    participant BE as 客戶主系統
    participant H as 客戶主機 guidantai
    participant AG as Agent
    CI->>US: 出包→上傳 R2→登記草稿（CI token 只能到這）
    DM->>US: guidant-release publish：核內部先裝→蓋章→已發布
    BE->>US: 每天 03:00 出示授權檔問有沒有新版
    US-->>BE: 已發布清單（決策者簽章、90 天有效）
    BE->>BE: 驗章、版號>現行、主版號相同→通知系統管理員
    Note over BE: 管理員按「下載」→背景下載、驗雜湊→已就緒
    BE->>H: 有權限的人按立即／排程→寫 upgrade-order.json
    H->>H: systemd path 看到單→guidantai upgrade --from-order
    H->>H: 先換成新版的自己（D30）→預檢→停接新工作等做完→停服務
    H->>H: 複製資料庫→在複本上載映像、套 migration→健康檢查
    alt 任一步失敗／超時／斷電
        H->>H: 自動退回：丟複本、接回原份、起舊映像
    else 全過
        H->>H: 換接：複本轉正、原份留作升級前快照、前門最後換
    end
    H-->>BE: 進度檔 upgrade-progress.json（維護頁與更新中心都讀它）
    BE-->>AG: 心跳回 target_version（先 1 台，成功再其餘）
    AG->>BE: 下載 Agent 包→寫單→主機 systemd 觸發 install.sh upgrade→回報結果

做完之後長這樣（對照雛形 10 頁）：儀表板冒出「有新版」橫幅（⓪）；更新中心看版本說明、預檢、按下載（①）；下載中服務照常（①b）；就緒後選立即或排程（①c）；停機期間打開原網址是維護頁，每 3 秒更新步驟與時限（②）；失敗自動退回並給診斷包（③）；成功後 Agent 先一台再其餘（④，僅在確認視窗勾了「接著更新 Agent」時自動跟進）；跨版兩段（⑤）；例外狀態各一張卡（⑥）；更新站後台只給原廠看（⑦）。

依賴：一與二可以同時開（批 1 混排）；三要等一的骨架（P1-1）與二的更新站（P2-1）；四要等三的更新單；五最後。決策者功課（都不卡開發期，測試期前備妥即可）：①更新站網域（建議 update.<公司網域>，加進 Cloudflare 那個帳號的 zone）；R2 bucket 已有，Worker／D1／Access 由首腦用 wrangler 建；②在自己電腦跑 guidant-release init-keys 產一正一備，備用封存，PROD 印樣交給結案卡 P5-5；③R2 的 API token（只給該 bucket 物件讀寫）與更新站 CI token 填進 GitLab CI 變數（masked、不勾 Protect），不進 repo。CRA 兩題先不管，不列功課。

定案一字內容以討論稿 callout 原文為準，本表為設計文件形狀的收斂。排序按主題不按編號。

5.1 升級指令：步驟、時限、進度檔（P1）

guidantai upgrade <包 | --from-order> 由 lib/upgrade_runner.sh 逐步呼叫，每步一個 lib 檔、一個時限、一個進度檔狀態。runner 是唯一寫進度檔的地方。

總上限 60 分（步 3～6）。進度檔 <資料目錄>/upgrade/upgrade-progress.json：

{"job_id":"20261031-2200-a1b2","from":"1.24.1","to":"1.27.0","path":["1.27.0"],
 "triggered_by":{"kind":"order","user":"wang.dm","mode":"scheduled","at":"2026-10-29T09:25:00+08:00"},
 "started_at":"2026-10-31T22:00:04+08:00","status":"running",
 "steps":[{"n":1,"name":"preflight","status":"ok","started":"…","ended":"…","detail":"空間 42GB 需 8GB"},
          {"n":4,"name":"apply_on_copy","status":"running","started":"…","limit_s":600,"progress":"migration 31/47 2026-10-14-fr162-mapping-index.sql","last_progress_at":"…"}],
 "db":{"current":"pgdata","copy":"pgdata-next"},"prev_images":["guidant-ai-be:1.24.1","…"],
 "result":null,"error":null,"rolled_back_at":null}

欄位只增不改名；維護頁、更新中心、開機檢查、診斷包四邊都讀這一份。

開機檢查：guidant-upgrade-boot-check.service（oneshot，After=docker.service）跑 guidantai upgrade --boot-check：讀進度檔，status=running 且步 3～6 → 呼叫 rollback；其他狀態不動。guidantai recover 走同一支 rollback，給 docker 當掉自動退回沒跑的情況。

5.2 資料不掉：複本、退回、換接（P1-4／P1-6／P1-7）

• 服務停掉（步 3）到換接（步 6）之間沒有任何寫入進現在那份；退回＝刪 pgdata-next、以 GUIDANT_PGDATA_DIR=pgdata 起舊映像、健康檢查。沒有還原動作。
• 換接後 pgdata-prev-<舊版> 是升級前快照，只給災難救援、不是回滾（D14）；下次升級成功時清掉。
• 證據檔（SeaweedFS）不複製：升級過程禁止改寫既有檔，守衛是 migration 與 init image 不掛 SeaweedFS 卷；真要改檔的版本標成特殊版另案。
• 設定檔與憑證目錄步 3 一起 cp -a，退回時一起換回。
• 進行中的背景工作不會被中斷：步 2 等它做完才停服務（D19）。
• Agent 送不出的結果：FR-166 的 outbox 已在（core/enroll.py 每次心跳 outbox.drain()），本案不另做。

5.3 停接新工作（P1-3b／P1-3a）

旗標檔 <資料目錄>/upgrade/draining（主系統唯讀掛載看得到）。core/maintenance_gate.py 一個函式 is_draining()；三個消費者：worker 撿單前判一次、core/plugins/remote_agent.py 把它接進 jedi-remote-agent 的 dispatch_gate port（心跳不帶 pending 任務、結果照收）、更新中心 status 回 draining: true 給前端顯示「正在等 N 件做完」。不新開端點、不改任務狀態機。

5.4 更新站（P2）

Repo update-center（新；本機 ~/Projects/Billows/Audit-Manager/update-center、遠端 gitlab.com/auditmanager/update-center、branch main；.claude/workshop.toml 登記 update-center）。TypeScript Worker（wrangler 4，Node 22；決策者 2026-10-29 選 TS，Python Worker 仍是測試版）、D1（SQLite）六張表、R2 一個 bucket。發布 CLI 同 repo 用 TS 寫（Node 內建 Ed25519 與 PKCS8 加密私鑰），一個 repo 一套工具鏈。

Cloudflare 既有資源（決策者帳號，2026-10-29 確認）：帳號 ID 6b1da966062f9093782aefa99c1e68d1；R2 bucket guidant-ai-release 已建好（S3 端點 https://6b1da966062f9093782aefa99c1e68d1.r2.cloudflarestorage.com/guidant-ai-release）。Worker、D1、Access 由 P2-1／P2-2 的 wrangler.toml 宣告、首腦部署時建。開發期用 Cloudflare 自動給的 *.raymond-jedicotech.workers.dev，正式網域出貨前再定（P5-5 檢查項）。API 權杖（D1／Workers／R2／Access 編輯）與 R2 S3 金鑰已由決策者備妥、權限已驗，放 update-center/.env（不入版控）。後台 Access 政策只放行決策者信箱（值在 wrangler.toml 的 ACCESS_ALLOWED_EMAILS 變數，首腦部署時填；信箱不是祕密但不進文件）。

bucket 內一個 bucket 不分、物件 key 分主版號資料夾：v<主版號>/<完整版號>/guidant-ai-<完整版號>.tar.gz＋同目錄 release.json、.sha256，例如 v1/1.27.0/guidant-ai-1.27.0.tar.gz、v2/2.0.0/…。理由：主版號是授權邊界（D7），同一層資料夾就是「這把授權拿得到的全部」，後台與人工查檔都一眼分清；CRA 十年保留（D29）要整個 v1/ 一起設保留規則。key 只在更新站內部拼（download-url 回預簽網址），客戶端與 CI 腳本都不寫死路徑：CI 把包交給 register-draft 時只給版號，上傳目標 key 由 Worker 算好回給它。換主版號不用改任何客戶端程式。

表：product_releases（version、major、min_base_version、sha256、size、r2_key（v<major>/<version>/…，Worker 填）、status draft／published／withdrawn、internal_fingerprints[]、has_security_fix、signed_manifest、kid、retain_until）、instance_version_reports（license_id、fingerprint、current_version、last_seen、last_upgrade_result；無客戶名稱）、release_download_log、license_denylist（license_id、reason、added_by、at）、signing_keys（kid、pubkey、status primary／backup／revoked）、ci_tokens。

客戶端信任（P3-2b package_verifier.py）：只信 /etc/guidant/release-keys/*.pub；清單簽章驗過 → issued_at+90d 未過（D31）→ version > 現行 → major 相同 → 下載後 sha256 等於清單。更新站回什麼都不信任。

發布 CLI（P2-3，決策者電腦）：guidant-release init-keys（產 primary＋backup，私鑰檔 passphrase 加密 600，印備用封存說明）、publish <版>（取草稿、核 internal_fingerprints 全部回報成功、填 issued_at、蓋章、送回）、withdraw <版>、rotate-key（新鑰進包內 release-keys/、清單用舊鑰與新鑰各簽；舊鑰再簽一版後作廢）。passphrase 由決策者輸入，不進檔、不進 log、不給任何 session。

5.5 更新中心（P3）

BE 模組 product_update（DDD 四層；照 app/source_scan_vulndb 的 settings service 形狀）。能力點 system.product-update.read（看）／update（下載、立即、排程、取消、重試、上傳、Agent 區）。

更新單（P3-2c）：<資料目錄>/upgrade/orders/<job_id>.json {job_id, version|path[], mode, not_before, requested_by, type: upgrade|diag}。主系統容器對 upgrade/orders/ 只有寫權（compose 掛 :rw 但目錄 chmod 730、chown root:guidant），對 upgrade/ 其餘唯讀。主機 guidant-upgrade-order.path（PathChanged=）觸發 guidant-upgrade-order.service → guidantai upgrade --from-order <檔>：立即就跑；排程則 systemd-run --on-calendar 排一次性 timer。執行前重驗包與簽章（過期或被刪就寫 skipped 並通知）。

每日檢查（P3-2b）：core/scheduler_update.py 每 6 小時一次（CHECK_INTERVAL_HOURS），主系統啟動時另跑一次，update_site_client.check()；連不到安靜略過、status 顯示「最近一次檢查失敗」；關閉開關存系統設定（唯一開關，D10）。

畫面狀態：status 回應把「單已寫、時間已到、主機還沒為這張單寫進度檔」換成 submitted（已送單等主機），只換回應、DB 仍是 scheduled，取消與重複按的擋法照舊認它。失敗終態三種：skipped（這次沒開始，系統沒動）、rolled_back（已自動退回）、進度檔 result=rollback_failed（退回也失敗，畫面紅色並顯示 sudo guidantai recover、停止輪詢）。

資料表 product_update_jobs：from／to／path／status（checking／downloading／ready／scheduled／running／succeeded／rolled_back／skipped／cancelled）／downloaded_by（login＋nickname＋at）／applied_by／cancelled_by／source（online／offline）／not_before／started／ended／error／job_id。結束後從進度檔同步結果。審計欄位照規範回 *_name。

FE（P3-3、P3-4）：views/product-update/UpdateCenter.vue（照 VulndbManage.vue 版面）、UpdateHistory.vue、ReadyDialog.vue（立即／排程）、NewVersionBanner.vue；AgentRolloutPanel.vue（P4-4）。沒有 update 能力點只看不到按鈕。分段用 SegmentButtons、不自訂字級、無 border-left。

5.6 版本與授權（D7／D27）

• 版本只有一種；release.json 多一個 has_security_fix 讓更新說明多「影響範圍」「建議動作」兩段，其餘行為一樣。
• 授權檔 product_major（P2-5，缺欄視為 1）。更新站 check 只比主版號、不看 expires_at。產品內授權過期的行為（唯讀、模組鎖）不變，本案不碰 common/authz/license.py。
• CRA 文件（P5-1）照 D27 寫；CRA 兩題決策者裁示先不管，之後有答案只影響 P5-1 措辭。

5.7 Agent 跟進（P4）

• 是否自動跟進由管理員在「更新到 X」確認視窗決定（勾選「主系統更新完成後，接著更新 Agent」，預設勾）；不勾則 Agent 與主系統分開，管理員之後在 Agent 區自己按（立即、排程，或稍後提醒 7 天）。「必須更新」標示只在新版 min_agent_version 高於該台現行版時出現。
• 勾選時，主系統開放使用後 agent_rollout_service 建 agent_update_rollouts（agent_id、target_version、batch、status pending／dispatched／succeeded／failed／paused、source following／manual／agent-only）：batch 1 一台（最近心跳最新的那台）；成功 → 其餘 batch 2 全部 dispatched；失敗 → 其餘 paused。
• 心跳：_agent_update.py 的 update_extra 只對 dispatched 的 Agent 回 {target_version, sha256, size}；Agent 回 upgrade_result 推進狀態。
• 主動通知：下發列轉成 dispatched 且交易提交後，主系統背景呼叫 Agent 的 POST /update/notify（同一道 mTLS＋綁 op 短效 JWT，5 秒逾時）叫它立刻心跳；連不到只記 warning、退回等下一次心跳，不擋推送 API 與排程。版本約束：Agent 主線版號 ≤ 主系統現行版，否則不派。
• Agent 側 core/update_sync.py（照 vulndb_sync.py）：下載 GET /agents/update/bundle（資料面 JWT、續傳、驗 sha）→ 寫 agent-upgrade-order.json → 主機 guidant-agent-upgrade-order.path 觸發 install.sh upgrade <包>（P4-5 加時限、進度檔、自動退回）→ 結果隨心跳回。Agent 不連外網、不連更新站、不多常駐程式。
• 只升 Agent：主系統已升、某幾台落後 → 更新中心「推選定」建 manual rollout；Agent 單獨修正版（更新站 release.json 標 agent_only）→ 主系統下載存著不升自己，建 agent-only rollout。第一版先做前者，後者欄位先留。

5.8 安全規則對照

批（Stage）＝工作坊同時開幾個小弟一起跑的那一組：同一批不改同一個既有檔、不依賴對方產出、不搶同一外部資源。階段（P1～P5）只是分組標籤。底表在 handoff/cards.py，兩個斷言已過：依賴都在更早的批；同批同 repo 無兩張卡改同一既有檔。

登記型檔先佔位：scripts/installer/guidantai 與 install.sh 由 P1-1 一次開好 lib/ 全部步驟空殼與子命令派送，後面十張 P1 卡只填自己的 lib 檔；config/app_modules.py 與 di_containers/ 由 P3-2a 一次登記；evidence-agent core/enroll.py 只有 P4-3 碰；core/plugins/remote_agent.py 兩張卡各加一行但在不同批（P1-3b 批 3、P4-2 批 6）。

repo 分布：BE 23、FE 4、update-center（新） 3、evidence-agent 2、jedi 套件 1、License Center 1、test 1。環境卡 E-1（批 2）：P1-3a 改完心跳契約直接發 beta 版（1.10.0b1，決策者授權小弟在工作坊可 push 自己的 ws branch、套件可發 beta），E-1 把主 repo 釘到 beta 並只 poetry update jedi-remote-agent；結案卡 P5-5 發正式版、改釘正式版。開發期與測試期分開：每張卡的「驗收」只寫小弟在本機／DEV 8003／本機 docker／wrangler dev 就驗得完的事，工作坊無人時不會卡；要 190、pipeline、真 Cloudflare、PROD 印樣的情境寫在「測試期（190）」欄，由首腦操作、決策者看畫面（§7）。套件異動（發版前統一確認）：jedi-remote-agent（心跳契約兩個 port）；License Center（授權檔加 product_major）。新 repo update-center（已建）：開卡時登記 .claude/workshop.toml 與 Notion「Repo」選項。

全部在 190 e2e 目標或 DEV 做，不碰 STG／POC。這一節是測試期：開發期卡片全部驗收通過、決策者 push 並出一包之後，由首腦在 190 逐條操作、決策者看畫面；每條對應的卡在 §6 最後一欄。190 會被重灌與重開機多次，測試期間不拿它做別的。