更新中心 API

更新中心是主系統的一頁設定頁，做五件事：問原廠更新站有沒有新版、下載並驗證更新包、寫「更新單」交給主機、顯示主機升級進度、管 Agent 跟進。

🔴 主系統不碰 docker、不跑升級。主系統容器只做兩件事：把更新包放進 incoming/、把更新單寫進 orders/。真正換版的是主機上的 systemd 單元與 guidantai upgrade；主機把進度寫成檔案，主系統每分鐘讀一次回寫紀錄。主機不打主系統 API，主系統也不呼叫主機（單向：主系統寫單、主機寫檔）。

%%{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'}}}%%
flowchart LR
    FE["FE 更新中心頁<br/>UpdateCenter.vue"] -->|"REST /system/product-update/*"| API["guidant-api"]
    API -->|"入列 product_update_download"| WK["guidant-worker"]
    SITE["原廠更新站<br/>/v1/check · /v1/download-url · /v1/report"]
    API -->|"立即檢查"| SITE
    WK -->|"預簽網址下載"| SITE
    WK -->|"驗章＋雜湊後改名"| INC[("upgrade/incoming/<br/>容器 rw")]
    API -->|"寫 &lt;job_id&gt;.json"| ORD[("upgrade/orders/<br/>容器 rw、730")]
    ORD -->|"PathChanged"| UNIT["guidant-upgrade-order.path<br/>→ guidantai upgrade --from-order"]
    UNIT -->|"讀包"| INC
    UNIT -->|"寫"| PROG[("upgrade/upgrade-progress.json<br/>draining · last-switch.json · diag/")]
    PROG -->|"唯讀掛載，每分鐘同步"| API
    PROG -->|"維護頁直讀"| NGX["guidant-fe nginx"]

守門分兩層：

1. Route：@jwt_required → @require_capability(...)（product_update_route.py:31-32）。不掛 require_license——product-update 列在 common/authz/license.py:127 的基礎設施模組，授權過期仍能升級。
2. App service：所有寫入先 _assert_may_write()（product_update_app_service.py:102-105）——非落地版（SaaS）一律要平台管理員，因為換版是整台機器的事，任何租戶都不准換掉全機共用的版本。

status.can_update（product_update_app_service.py:107-116）＝持 update 能力點 且 通過上面第 2 層。前端用它藏寫入鈕；按鈕本身另掛 v-can="CAP.SYSTEM_PRODUCT_UPDATE_UPDATE"（src/config/capabilities.js:212-213）。

選單：ui_routes.name='product-update'、/system/product-update、掛在 group-system-config 下、sort 43；route_capabilities 綁 read（ALL）與 update（ANY）。

前綴一律 /api/1.0。信封照全站：成功 {"status": true, "data": …}；失敗 HTTP 4xx／5xx、{"error_code", "msg"}。

16～20 是 Agent 跟進，契約寫在 agent-rollout-spec.md §5。

ProductUpdateStatusRoute（product_update_route.py:37）→ ProductUpdateAppService.status()（product_update_app_service.py:131-151）。這支有副作用：先呼叫 order.after_switch(progress, recheck=False)——主機剛換接完成時，同步紀錄、清掉舊版本那次檢查，不等每分鐘排程（不重問更新站，免得卡住請求）。

4.1 頂層欄位

4.2 last_check 與 available

last_check（product_update_flow.py:241-269）：

available 形狀：{latest, path[], releases[], found_at}，releases 同上。

更新站回的每一段清單都要用本機印樣（/etc/guidant/release-keys）驗過才採信，並檢查每段都能從前一段直升（min_base_version）。任一段驗不過整個不認，記 error_code=PRODUCT_UPDATE_400001（product_update_flow.py:217-231）。

4.3 latest_job（紀錄列）

欄位照 ProductUpdateJobSchema（serializers/product_update.py:8-42）：uid、job_id、from_version、to_version、path[]、status、source（online／offline）、downloaded_by／applied_by／cancelled_by（login）與對應 *_name（暱稱）、*_at、not_before、started_at、ended_at、error、with_agents、agent_uids[]、審計四欄與 *_name。

status 的畫面換算（upgrade_order.py:192-204）：DB 是 scheduled、時間已到、主機還沒為這個 job_id 寫進度檔時，回應換成 submitted。只換回應不寫 DB，取消與重複按的擋法照舊認 scheduled。

%%{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'}}}%%
stateDiagram-v2
    [*] --> downloading: POST download／apply（還沒下載）
    [*] --> ready: 離線上傳 complete
    downloading --> ready: worker 驗章＋雜湊通過
    downloading --> failed: 下載失敗／驗不過（包已刪）
    downloading --> cancelled: DELETE download
    ready --> cancelled: DELETE download
    ready --> scheduled: apply／下載完自動寫單
    scheduled --> ready: DELETE apply（第 0～2 步前）
    scheduled --> running: 進度檔 status=running
    running --> succeeded: 最後一段 succeeded
    running --> rolled_back: failed＋result=rolled_back
    running --> failed: failed／timeout
    running --> skipped: 主機這次不更新（包還在）
    rolled_back --> scheduled: POST retry
    skipped --> scheduled: POST retry

• checking 在 DB CHECK 內但程式不寫入。
• failed 與 skipped 的分界：failed＝包已刪、下一步是重新下載；skipped＝這次沒動、包還在、可重試（product_update_flow.py:49-51）。
• 跨版時每段各寫一份進度檔、job_id 相同；中間段的 succeeded 仍當 running，直到 to 等於最後一段（upgrade_order.py:432-447）。
• 已回 ready 的列（管理員取消）不會被主機事後寫的 skipped 蓋掉（upgrade_order.py:450-472）。

4.4 progress（主機進度檔）

原樣轉交，欄位由主機 scripts/installer/lib/progress.sh:116 決定：job_id、from、to、path、segment{n,of}（跨版第幾段，非跨版為 null）、triggered_by{kind,user,mode,at}、started_at、status（running／succeeded／failed／timeout／skipped／preflight）、db、prev_images、result（upgraded／rolled_back／rollback_failed／unchanged／passed／failed）、error、rolled_back_at、updated_at、steps[]。步驟編號與名稱見 upgrade-runner-spec.md。

5.1 GET history

5.2 POST check

送出的身分：有更新站身分票只送 {ticket, fingerprint, current_version}；沒有才送授權檔原文（update_site_client.py:99-104）。

5.3 PUT auto-check

5.4 POST／DELETE download

POST：只下最近一次檢查驗過、且是以目前版本問到的那條路徑。建一列 downloading、入列 product_update_download 背景工作（max_attempts=1，斷線重試在 handler 內做）。回 {uid, version, path[], status}（product_update_flow.py:406-418）。

DELETE：downloading 或 ready（還沒寫單）的列改 cancelled、刪 incoming/ 裡這條路徑的所有檔。worker 每收 64MB 看一次狀態，看到 cancelled 自己停手刪檔。回 {uid, status:"cancelled"}。沒有可取消的 → 404 PRODUCT_UPDATE_404001。

下載流程（worker，product_update_flow.py:474-513）：

1. 以 last_check 存的簽好清單逐段重驗：每段比前一段新、前一段夠格直升它（不信更新站排的順序）。
2. 空間檢查：剩餘總大小＋2GB（package_downloader.py:41、95-100）。
3. 每段向 /v1/download-url 拿短效預簽網址，只接受 DOWNLOAD_HOSTS 白名單主機；下到 incoming/guidant-ai-<版>.tar.gz.part，Range 續傳，斷線最多重試 5 次、每次重拿網址（package_downloader.py:39、190-227）。
4. 下完驗 sha256 與大小；先寫 .release.json（簽好的信封原文）與 .tar.gz.sha256，最後才把 .part 改名成 .tar.gz——主機看到 .tar.gz 時旁邊兩檔一定在。
5. 清單有 ops_sha256 時另下維運指令小檔 guidant-ai-<版>.ops.tar.gz；拿不到不算失敗。
6. 驗不過、連線用盡、授權缺 → 列改 failed、包已刪（驗不過）或 .part 保留（斷線）。
7. 成功 → 列改 ready、記實測下載速率（PRODUCT_UPDATE/download_rate），接著：這列是「更新到 X」建的就自動寫更新單（§5.6）；否則寫一張 type=preflight 預檢單，就緒卡片就有預檢結果。

5.5 離線上傳（uploads 三端點）

主機連不到外網時，客戶向原廠取得單一離線檔 guidant-ai-<版>-offline.tar（檔內恰好是同版號的更新包與發布清單兩個檔）上傳。

限制（product_update_flow.py:569-573）：單塊 ≤50MB、總量 ≤8GB、塊數上限 ceil(8GB/50MB)。暫存在 incoming/.uploads/pkg-*。空間：兩檔送法要 1 倍包大小，單一離線檔要 2 倍（合併檔與拆出的包同時在磁碟上），再加 2GB 餘裕。

單一離線檔（product_update_flow.py:660-680）：先只讀檔內清單驗章，過了才把包抽到系統自產的檔名，再走跟線上下載同一段核雜湊。檔內附的維運指令小檔不符只丟掉它、不拒整份。上傳完但驗不過會留一列 failed（紀錄頁看得到、畫面給「重新上傳」而不是重試）。成功後同樣寫一張預檢單。

5.6 POST apply（寫更新單）

Response（ProductUpdateOrderSchema）：{uid, job_id, version, path[], status, mode, not_before, with_agents, agent_uids}。

判斷順序（upgrade_order.py:279-307）：

下載途中排定時間已過，不改成立即：包留在就緒、error 記原因讓管理員重選（upgrade_order.py:342-365）。

更新單（upgrade_order.py:83-95，主機端 scripts/installer/lib/upgrade_order.sh:13-14 同欄位）：

{"job_id": "20261101-1430-a1b2", "type": "upgrade", "mode": "now",
 "version": "1.27.11", "path": ["1.27.11"], "not_before": null,
 "requested_by": "admin", "requested_at": "2026-11-01T06:30:00+00:00"}

• 寫到 upgrade/orders/<job_id>.json，先寫 .<名>.tmp 再 os.replace——path 單元一看到檔就觸發，不能讓主機讀到半份。
• job_id 形狀 YYYYmmdd-HHMM-<4～8 位 hex>，主機 ord_valid_job_id 認同一個樣式。
• type：upgrade／preflight／diag。
• 主機只信三件事：job_id 與版號的格式、包在本機 incoming/ 且用本機印樣驗得過、版號真的比現行新。單上不接受任何路徑。
• 主機端單檔上限 8192 bytes（ORD_MAX_BYTES），超過不讀。
• orders/ 對容器是 730（root:1000）：能建檔、能刪知道名字的檔，但列不出目錄——取消只能靠紀錄上的 job_id 拼檔名。
• 主機 guidant-upgrade-order.path（PathChanged=<資料目錄>/upgrade/orders）觸發 guidant-upgrade-order.service → guidantai upgrade --from-order。立即單撿到就刪單、開跑；排程單用 systemd-run --on-calendar 排一次性 timer，到點以 --run 回來（單留在 orders/ 等）。

5.7 DELETE apply（取消）

成功後列改 ready、記 cancelled_by，包保留可重排。回 {uid, status:"ready"}。

5.8 POST retry

只對 rolled_back、skipped 有效（否則 412 412007）。用 incoming/ 裡同一個包從預檢重跑，不重下載；只跑比現行版新的那幾段（跨版第二段失敗停在中間版，重試從中間版接著跑）。沒有剩下的段 → 412005。mode 固定 now，Agent 跟進的勾選沿用上次。

5.9 診斷包

FE 每 3 秒問一次、最多 100 次（src/composables/useProductUpdate.js:14-15）。

5.10 GET notice（全站提醒）

FE UpdateScheduleReminder.vue 每 60 秒問一次，開始前 30 分與 5 分各提醒一次（src/views/product-update/updateNoticeState.js:34-48）。

core/scheduler_update.py。gunicorn preload_app=True，排程在 master fork 前建立，只跑一份。

ROOT 租戶 system_configs 群組 PRODUCT_UPDATE 的鍵：

回報更新站（upgrade_order.py:486-512）：POST /v1/report，body 為身分＋{result, from_version, to_version}，result 只收 succeeded／rolled_back／failed／skipped。不掛在「狀態有變」那一刻——畫面輪詢的 status 請求也會同步紀錄，它先收成終態，排程就看不到變化、永遠不報；所以改看「單是終態且沒報過」。

7.1 deriveView 的畫面狀態

src/views/product-update/productUpdateState.js:73-91，由上往下第一個成立的勝出：

effectiveJob（:58-64）：紀錄還寫 scheduled／submitted／running、但同 job_id 的進度檔已是 failed／timeout／skipped 的那一分鐘，以進度檔為準換成結果，畫面不會卡在轉圈。成功不在前端換（跨版中間段也寫 succeeded）。

畫面另有一層 screen（UpdateCenter.vue:55-58）：按下更新後、後端回應前是 sending。

失敗另判、不佔主狀態：lastFailure 回最新一列是 rolled_back／skipped／failed 的那筆，頁首放失敗說明；canRetry 只對 rolled_back、skipped、或 failed 且進度檔 result=unchanged 給重試鈕（:104-117）。

7.2 輪詢

7.3 步驟名

STEP_NAMES（productUpdateState.js:15）＝進度檔步驟 0～7：self_replace、preflight、drain、db_copy、apply_on_copy、health、switch、cleanup；第 8 步 rollback 插在失敗那步之後。白話名走 i18n lang.product_update.step_<代號>，與後端 upgrade_order.STEP_EVENTS、主機 progress_step_label 是同一套，改要三邊一起改。可取消：view 為 scheduled／submitted，或 running 且目前步驟在 db_copy 之前（:212-216）。

7.4 i18n key 對照（src/config/locales/i18n/zh-tw/product-update.json）

錯誤碼訊息在 src/config/locales/i18n/zh-tw/error-code.json（PRODUCT_UPDATE_* 共 34 條，與後端一一對應）。

common/code/product_update_error_code.py。HTTP 欄寫「—」的只出現在 last_check.error_code，不當 HTTP 錯誤回。

common/enum/event_code.py:239-251。

6239～6248 不是即時寫：升級期間服務是停的，主機的 log 只在主機檔案裡。服務回來後由每分鐘排程在紀錄收成終態時補寫，每個 job_id 只寫一次（upgrade_steps_logged_job 記著）。跨版升級只看得到最後一段的步驟。

docker/production/docker-compose.yml。api、socketio、worker 共用 x-guidant-common（:151），volumes 清單無法在單一 service 追加，所以三個都掛（socketio 掛了不用）。

🔴 upgrade:ro 與 orders:rw 兩行都要在：只掛 orders/ 時 api 讀不到進度檔與旗標，且不報錯（狀態永遠 null、永遠不停接單）。目錄由主機 scripts/installer/lib/systemd_units.sh:20-29 建。

設定（config/config.py:204-209）：GUIDANT_UPGRADE_DIR（預設 /guidant/upgrade）、GUIDANT_RELEASE_KEYS_DIR（預設 /etc/guidant/release-keys）、UPDATE_SITE_URL（預設空字串＝沒設站，只能離線更新）。

建表 scripts/sql/2026-10-29-fr167-product-update-jobs.sql，加 failed 狀態 2026-10-29-fr167-product-update-jobs-failed-status.sql，加 Agent 跟進欄 2026-10-30-fr167-agent-follow-optional.sql。ORM infra/product_update/model/product_update_job.py。

cm_app 只有 SELECT／INSERT／UPDATE，沒有 DELETE。

• 設計文件：定案與取捨（本文件與 design 不一致時以程式碼與本文件為準）
• Agent 跟進規格
• 主機升級指令規格
• 原廠更新站規格
• 發布與簽章規格
• 狀態機
• 時序圖