升級執行流程

%%{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
    autonumber
    participant B as 瀏覽器（更新中心）
    participant N as 前門 guidant-fe（nginx）
    participant M as 後端 guidant-api／worker
    participant S as 更新站＋R2
    participant H as 主機 systemd（root）
    participant P as 進度檔 upgrade-progress.json
    B->>M: 立即檢查（另有每日排程）
    M->>S: /v1/check product=host
    S-->>M: 新版、簽好的清單、三段說明
    B->>M: POST …/apply「更新到 X」
    Note over B: 全頁遮罩，只顯示進度
    M->>S: /v1/download-url（15 分鐘預簽網址）
    M->>S: 下載整包與 ops 小檔（背景工作、可續傳）
    M->>M: 本機公鑰驗章、比對雜湊
    M->>H: 寫更新單 upgrade/orders/<job>.json
    H->>H: guidant-upgrade-order.path 看到檔 → .service → guidantai upgrade --from-order
    H->>H: 重驗包與章（容器寫的單不全信）
    H->>P: 第 0 步 換新版維運指令與維護頁
    H->>P: 第 1 步 預檢、第 2 步 放 draining 旗標等工作歸零
    Note over M: worker 不撿新單、不推新工作給 Agent；API 照常
    rect rgb(236,236,236)
    Note over B,P: 第 3～6 步：後端與資料庫停機，畫面由前門維護頁提供
    H->>H: 第 3 步 停 api／worker／socketio／db，複製資料庫
    B->>N: 輪詢拿到 502 → 整頁 reload
    N-->>B: 探後端不通 → 送維護頁
    B->>N: 每 3 秒 GET /upgrade-progress.json
    N->>P: 直接讀唯讀掛載的檔（不經後端）
    H->>H: 第 4 步 在複本 load 映像、跑 migration
    H->>H: 第 5 步 用複本起新版，打 version／login／三支 API
    H->>H: 第 6 步 改 .env、換目錄、依序起服務，最後重建 fe
    end
    H->>P: 第 7 步 清理舊映像、舊快照；status=succeeded
    N-->>B: 探後端通了 → 跳回更新中心 ?upgraded=1
    M->>P: 排程每分鐘讀：同步單終態、補寫系統日誌、回報更新站
    M->>M: agent-bundles 有相容新版 → 自動建 Agent 推送列（接圖 2）
    rect rgb(253,236,236)
    Note over B,P: 任一步失敗或逾時
    H->>H: 第 8 步 rollback：.env 寫回舊值、起舊版
    H->>P: rolled_back（退回也失敗寫 rollback_failed）
    end

%%{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
    autonumber
    participant B as 瀏覽器（更新中心 Agent 區）
    participant M as 主系統後端
    participant S as 更新站＋R2
    participant A as Agent 容器（8443）
    participant H as Agent 主機 systemd（root）
    participant C as Agent 主控台（8444）
    B->>M: 勾選 N 台，「更新選取的 N 台到 X」
    alt 手上沒有包，或手上的包比更新站查到的舊
    M->>S: 下載 Agent X（背景工作，畫面有進度、可取消）
    M->>M: 驗 agent_release_manifest 章與雜湊 → agent-bundles/X/
    Note over M: 下載中再有人按更新，併入待推清單（各記操作者）
    end
    M->>M: 建推送列：先推 1 台，成功再推其餘
    M->>A: 直推 POST /update {版號, sha256, 大小}（mTLS＋60 秒 JWT）
    Note over A: 進入維護模式：停收新工作
    C->>A: 每 30 秒問狀態 → 拿到 in_progress → 整頁鎖住
    A->>M: GET /agents/update/bundle 下載包（可續傳）
    A-->>M: 事件 update_download
    A->>A: 核大小與雜湊，寫升級單 agent-upgrade-order.json
    H->>H: guidant-agent-upgrade-order.path 看到單 → upgrade-host order
    H->>H: 從現行 Agent 映像讀出 upgrade_order.sh，用舊版 Agent 驗新版程式樹的章
    H->>H: 預檢 → 等工作做完 → 換上新版設定 → 重建容器 → 健康檢查 → 清理
    A-->>M: 事件 update_step（每一步，失敗帶錯誤輸出末 20 行）
    A-->>M: 新容器起來：事件 update_result＋上傳升級紀錄
    M-->>B: 每台八步進度與結果；整批成功後清用不到的包
    C->>A: 版本換了 → 整頁重新載入回原頁（不必重登）

%%{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
    autonumber
    participant O as 操作者（Agent 主控台 8444）
    participant A as Agent
    participant M as 主系統後端
    participant S as 更新站
    O->>A: 立即檢查
    A->>M: POST /agents/update/check（通行證＋DPoP）
    M->>S: 查 Agent 版本線（全機 5 分鐘節流）
    A->>M: GET /agents/update/available
    M-->>A: 有新版 X（主系統手上還沒有包也照報）
    O->>A: 更新到 X
    Note over O: 按下當下整頁鎖住
    A->>M: POST /agents/update/request（操作者名稱）
    M->>M: 手上不是最新 → 排下載，推送人記「agent-console:操作者」
    M->>A: 下載完直推 POST /update（之後同圖 2 第 7 步起）
    rect rgb(236,236,236)
    Note over O,S: 與主系統斷線時
    O->>A: 離線上傳 .offline.tar.gz
    A->>A: 用現行版公鑰驗章 → 雜湊 → 版本 → 磁碟 → 寫升級單（同圖 2 第 12 步起）
    end