主機升級程式

這份寫的是主系統主機側的升級程式：guidantai、install.sh --upgrade、lib/ 底下的步驟檔、systemd 單元、進度檔。主系統後端怎麼寫更新單、怎麼讀進度檔，寫在 state-machines-spec.md 與 sequence-diagrams-spec.md。Agent 主機的升級程式形狀相同，差異在 §11。

子命令

upgrade-host 不是主系統的子命令，是 Agent 安裝程式的子命令（upgrade-host boot-check|order），見 §11。

runner 的參數

出貨包與 --bundle-dir 只能擇一（:198）。

退出碼

以 runner 檔頭為準（upgrade_runner.sh:13-14）：

步驟檔的執行契約

每步以子行程 bash <步驟檔> 執行（upgrade_runner.sh:16-18），環境變數帶：

步驟回 0＝過、回 10（UPG_RC_SKIP，progress.sh:31）＝這次不更新、其他＝失敗；逾時由 runner 判成 124（timeout -k 收掉的 137 也算 124，upgrade_runner.sh:80-82）。

舊版主機上的 guidantai 只負責第 0 步：驗包、把包內新版維運指令裝上去，然後 exec 新版跑第 1 步之後。所以第 1 步以後跑的永遠是新版的步驟檔，修 runner 的錯不必等客戶先升一次維運指令。

%%{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
  S0["0 self_replace<br/>換成新版維運指令"] --> S1["1 preflight<br/>預檢"]
  S1 --> S2["2 drain<br/>停接新工作"]
  S2 --> S3["3 db_copy<br/>停服務、複製資料庫"]
  S3 --> S4["4 apply_on_copy<br/>在複本上升級"]
  S4 --> S5["5 health<br/>健康檢查"]
  S5 --> S6["6 switch<br/>換接"]
  S6 --> S7["7 cleanup<br/>清理"]
  S0 -. 失敗 .-> U["skipped／unchanged<br/>退出碼 1"]
  S1 -. 失敗 .-> U
  S2 -. 失敗 .-> U
  S2 -. 時段到 .-> K["skipped／unchanged<br/>退出碼 10"]
  S3 -. 失敗或逾時 .-> R["8 rollback<br/>退回"]
  S4 -. 失敗或逾時 .-> R
  S5 -. 失敗或逾時 .-> R
  S6 -. 寫 succeeded 前失敗 .-> R
  R --> RB["rolled_back 退出碼 3<br/>或 rollback_failed 退出碼 4"]
  S7 -. 失敗 .-> W["只記 warning<br/>結果仍是 upgraded"]

時限常數全在 upgrade_runner.sh:36-47，環境變數覆寫只給測試縮時用。

總上限：第 3～6 步合計 3600 秒（UPG_TOTAL_LIMIT），從第 3 步開始計時（upgrade_runner.sh:150）。每步實際時限＝「該步自己的時限」與「總上限剩餘」取小者，該步沒有自己的時限就用剩餘（:99-105）。

逾時怎麼收：timeout -k 30 <秒>，先送 TERM、再等 30 秒（UPG_KILL_GRACE）送 KILL（:47、:80）。步驟檔都有 TERM trap，收到就清自己的半成品。

失敗原因怎麼留：步驟自己寫的 detail 會保留，runner 只在後面附「（退出碼 N）」（:91-92）。維護頁與更新中心顯示的就是這段。

5.1 第 1 步 預檢

upgrade_preflight.sh:285-306。這一步什麼都不能動：不刪映像、不清快取、不停服務（:7）。每一項都跑完才下結論，不過的項目一次列出（:8）。

空間怎麼算（:194-215）：

停機預估（:259-272）：在複本落點寫 100MB（dd … conv=fsync）量速率，estimate_copy_s＝資料庫大小÷速率，estimate_downtime_s＝estimate_copy_s×3。量不到就不寫，第 3 步用預設 1800 秒。

寫進度檔：步驟 detail（每項一行）、步驟 failures（不過項目的字串陣列）、頂層 estimate_copy_s／estimate_downtime_s（:297-305）。

5.2 第 2 步 停接新工作

upgrade_drain.sh。

5.3 第 3 步 停服務、複製資料庫

upgrade_db_copy.sh:214-226。

設定快照項目（DBC_CONFIG_ITEMS，:31）：.env、guidant.env、docker-compose.yml、certs、pki、seaweedfs/s3.json、ai-gateway-rules。

失敗或被 TERM（:194-212）：先起回舊版服務（成功就刪 draining），再刪複本與這次的設定快照，db 改回 copy:null。別次升級留下的快照不動。

證據檔不複製：物件儲存（SeaweedFS）不在複本範圍（:7-8）。

5.4 第 4 步 在複本上升級

upgrade_apply_on_copy.sh:186-201。

進度怎麼來：init 映像的 migrate.sh 每套一支印一行 PROGRESS<TAB>n/總數<TAB>檔名，這裡轉寫成步驟 progress「migration n/總數 檔名」（:126-141）。

5.5 第 5 步 健康檢查

upgrade_health.sh:129-149。

每次 curl 15 秒逾時（UPG_HEALTH_CURL_TIMEOUT）。受檢容器用完一律刪（:127）。worker 與 socketio 不在這一步起：這時候起 worker 會在還沒驗過的複本上撿單（:29-31）。

5.6 第 6 步 換接

upgrade_switch.sh:120-154。

換接後才逾時：第 6 步若在寫完 succeeded 之後才逾時（前門重建慢），runner 看到 result=upgraded 就不退回、也不改寫結果，退出 0（upgrade_runner.sh:119-123）。

5.7 第 7 步 清理

upgrade_cleanup.sh:114-126。任何一項刪不掉只記 warning，結果仍是 upgraded（upgrade_runner.sh:173）。

bundles/<本版>/agent/ 要留著：主系統升完後 Agent 跟進、推送、下載都從這裡找 Agent 包（:86-88）。

6.1 三個路徑函式

都在 lib/upgrade_common.sh，所有步驟只走這三支，不自己拼路徑。

compose 檔的 db 掛載是 ${GUIDANT_PGDATA_DIR:-guidant-pgdata}:/var/lib/postgresql/data（docker/production/docker-compose.yml:302）。

6.2 兩種情況（prev_kind）

位置：upgrade_switch.sh:7-11、:38-49、:60-89；清理 upgrade_cleanup.sh:65-84。

6.3 設定檔怎麼改

upg_set_kv（upgrade_common.sh:71-79）改一個鍵：整份寫暫存再 rename，值經環境變數交給 awk、不上命令列。.env 寫一半會讓 compose 整份解析失敗、服務全起不來。

步驟起新版服務一律用 upg_new_dc_argv（:52-55）：env GUIDANT_VERSION=<新版> GUIDANT_PGDATA_DIR=<複本或 pgdata> docker compose --env-file <.env> -f <新包的 compose 檔>。shell 環境優先於 --env-file，所以換接前 .env 還是舊版號也起得出新版。

7.1 三個入口，同一支退回

upgrade_rollback.sh:3-7、:329-340。

開機與 recover 先判斷該不該退（rb_decide，:267-280）：

「沒跑完」看 result 不看 status：runner 失敗時先把 status 改成 failed 才開始退回，退回中被打斷就是 status=failed、result=null（:264-266）。

7.2 退回做什麼

rb_rollback（:232-250），每段都先看「現在是什麼樣子」再動，可以重跑。

等待上限：db 與 api 各 180 秒（UPG_ROLLBACK_READY_LIMIT），fe 60 秒（UPG_ROLLBACK_FE_LIMIT）。整個第 8 步 900 秒。

7.3 開機檢查

upgrade_boot_check.sh：rb_standalone boot，任何結果都 exit 0。oneshot 回非零只會讓 systemd 把單元標 failed，docker 的 restart 原則照樣把容器起來；退回失敗的事實記在進度檔，維護頁與 status 看得到（:7-8）。

8.1 位置、寫法、讀者

8.2 頂層欄位

輸出順序是下表前段的固定順序，其餘欄位依字母排在後面（progress.sh:96-117）。

8.3 步驟欄位

步驟白話名（給 error、detail 用）在 progress.sh:35-48；前門維護頁與更新中心各有自己的對照，改一邊要一起改。

8.4 只讀預檢的進度檔

包就緒後主系統會寫一張 type=preflight 的更新單，主機只跑第 1 步（upgrade_order.sh:240-263）。這時進度檔長得不一樣：

拿不到升級鎖（正在升級）就不跑，免得 progress_init 清掉正在升級那次的進度檔（:238-239、:244-248）。

8.5 範例（升級中、第 4 步）

{"job_id":"20261101-2200-a1b2","from":"1.27.6","to":"1.27.7","path":["1.27.7"],"segment":null,
 "triggered_by":{"kind":"order","user":"wang.dm","mode":"scheduled","at":"2026-11-01T21:30:00+08:00"},
 "started_at":"2026-11-01T22:00:04+08:00","status":"running",
 "db":{"current":"pgdata","copy":"pgdata-next"},"prev_images":[],
 "result":null,"error":null,"rolled_back_at":null,"updated_at":"2026-11-01T22:03:12+08:00",
 "estimate_copy_s":41,"estimate_downtime_s":123,
 "steps":[
  {"n":0,"name":"self_replace","status":"ok","started":"…","ended":"…","limit_s":60},
  {"n":1,"name":"preflight","status":"ok","started":"…","ended":"…","limit_s":120,"detail":"…"},
  {"n":2,"name":"drain","status":"ok","started":"…","ended":"…","limit_s":null,"detail":"進行中的工作都已做完","running_agent_tasks":0,"running_jobs":0},
  {"n":3,"name":"db_copy","status":"ok","started":"…","ended":"…","limit_s":423,"detail":"資料庫已複製（7.4GB，38 秒）；現在那份不會再被寫入"},
  {"n":4,"name":"apply_on_copy","status":"running","started":"…","limit_s":3138,"progress":"migration 31/47 2026-10-14-fr162-mapping-index.sql","last_progress_at":"…"}]}

主系統容器只對 upgrade/orders/ 有寫權（目錄 730 root:1000，容器能建檔、刪自己知道名字的檔，但列不出目錄），更新單寫完就由主機的 path 單元接手（systemd_units.sh:20-30）。

9.1 單的形狀

檔名 upgrade/orders/<job_id>.json，上限 8192 bytes（upgrade_order.sh:32）。主系統寫法見 app/product_update/service/upgrade_order.py:83-95。

用 python3 -I 解（值裡可能有任何東西，不用 grep），符號連結不收（:47-72）。

9.2 主機怎麼處理

ord_handle（upgrade_order.sh:266-284）：

跨版：每段各跑一次 runner（各自複本、各自健康檢查），job_id 相同；任一段失敗就停，前面跑完的段留著（停在中間版，那是可以正常使用的版本）（:16-17）。每段開跑前都驗，第二段的包壞了第一段就不跑（:97）。

取消：主系統在主機已開跑後按取消，會寫 orders/<job_id>.cancel。主機每秒看一次，最後一步編號 <3 時才收掉 runner（setsid 的整個行程群組送 TERM），進度檔寫 skipped／unchanged「已由管理員取消…」，回 10；第 3 步起忽略（:185-224）。排程到點時單已被刪＝管理員取消了，什麼都不做（:270-274）。

path 單元只觸發一次：處理途中新進的單不會再觸發，所以處理完要重掃；排程單會留在 orders/ 等 timer，記下處理過的檔名才不會一直重掃（:299-310）。

單元檔在包內 scripts/installer/systemd/，安裝時把 @GUIDANT_DATA_DIR@ 換成這台的資料目錄，寫暫存再 mv（systemd_units.sh:48-57）。全新安裝與每次升級第 0 步都會重裝。三個單元都是本機事件觸發，不開埠、不常駐。

找不到資料目錄（沒有 GUIDANT_DATA_DIR、也沒有安裝紀錄）就不裝，下次升級補上；不猜預設值，猜錯的話 path 單元會監看一個沒人寫的目錄、且不會報錯（systemd_units.sh:12-13、:38-42）。

Agent 升級程式形狀照主系統（步驟名、時限、進度檔同一份契約），在 evidence-agent repo scripts/install/lib/。這裡只列差異；跟進流程見 sequence-diagrams-spec.md 圖 3。

<資料目錄> 由 /etc/guidant-ai/install.conf 的 GUIDANT_DATA_DIR 決定（預設 /srv/guidant-ai）。

容器掛載（docker/production/docker-compose.yml:248-257、:523-525）：api 與 worker 掛 upgrade:ro，orders 與 incoming 以 rw 疊上去，另掛 /etc/guidant/release-keys:ro；前門 fe 只掛 upgrade:ro。

guidantai diag 先在主機蒐料到交換目錄，再交給容器內打包核心產 guidant-diag-<時間>.tar.gz；遮罩由容器內那一套做，主機只複製原檔（lib/diag_upgrade_stage.sh:3-5）。

拿不到的項目照樣寫進索引（unavailable 加原因），不讓整包失敗。從更新中心按「下載診斷包」會寫 type=diag 的更新單，產在 upgrade/diag/<job_id>/。

前門 guidant-fe 從頭到尾不停（第 6 步最後才重建）。後端停掉期間它送維護頁，維護頁讀進度檔自己畫進度。

升級期間服務停著，主機的紀錄只在主機檔案裡。主系統每分鐘排程在更新紀錄收成終態後，把進度檔每一步各寫一筆 system_logs，再寫一筆整次結果；每張單只寫一次（ROOT 租戶 system_configs 的 upgrade_steps_logged_job 記著）（app/product_update/service/upgrade_order.py:516-585）。

事件碼定義在 common/enum/event_code.py:242-251。跨版升級每段各一份進度檔、job_id 相同，這裡只看得到最後一段的步驟。