線上更新機制問答

安裝部署做哪些事、路徑在哪、用哪個帳號、權限多大

全程以 root 執行（sudo ./install.sh）。理由：要建系統目錄、寫 600 權限的設定檔、把容器要讀的檔 chown 給容器內的 uid、操作 docker daemon，這些都需要 root；安裝完後日常維運指令 sudo guidantai 同樣以 root 跑。

安裝八步與落點：

資料目錄 /srv/guidant-ai 是唯一要備份的地方：設定、憑證、資料庫、物件儲存、升級進度全在裡面。/etc/guidant-ai/install.conf 只記「資料目錄在哪、compose 檔在哪」，給維運指令定位用。

升級用的公鑰為什麼放 /etc/guidant/？什麼時候放進去的？

安裝時就放，不是之後補的。190 實查 /etc/guidant/release-keys/b91819f86eb4b4f8.pub 建檔 2026-10-30 19:52:00，與同台安裝紀錄 install-20261030-194622.log 收尾同一分鐘，即 install.sh 第 ⑦ 步「裝維運指令」做的：install.sh:639 呼叫 lib/self_replace.sh --install-from，self_replace.sh:180 再呼叫 release_keys_install（lib/release_keys.sh:99），把出貨包內 release-keys/*.pub 複製到 /etc/guidant/release-keys/。之後每次升級第 0 步走同一支，新鑰隨新包進來、舊的保留。

為什麼放 /etc 不放資料目錄：這把鑰是「用來驗新包能不能信」的。驗章鐵則（release_keys.sh:6）：只用這台機器上已經裝好的印樣，不用新包裡帶來的，拿包裡的鑰驗包裡的清單等於沒驗。所以它要與出貨包、資料目錄都脫鉤，放系統設定目錄，root 持有 644 唯讀，與 /usr/local/bin/guidantai、/usr/local/lib/guidant/ 同屬「與包脫鉤的系統層資產」。後端容器以唯讀掛載讀它（docker inspect：/etc/guidant/release-keys (ro)），自己改不了。

安裝目錄結構：每個資料夾放什麼、什麼可以清、什麼不能動

依 190（10/30 乾淨重裝）與 189（8 月裝到現在、11 次舊式升級再接新式）實查整理。先看結構圖，再看三級清單，最後是兩台對照。

/srv/guidant-ai/                      資料目錄：唯一要備份的地方
├── pgdata/                           不能動  PostgreSQL 現用資料
├── .env                              不能動  compose 用的全部密碼（Q7）
├── guidant.env                       不能動  後端設定、JWT、三把加密金鑰
├── pki/  certs/  seaweedfs/s3.json   不能動  Agent CA、HTTPS 憑證、物件儲存金鑰
├── docker-compose.yml                不能動  部署定義（已與出貨包脫鉤的副本）
├── bugsink-admin.secret              不能動  錯誤追蹤站管理密碼
│
├── pgdata-prev-<舊版>/              自管    上一版快照，退回用；下次成功第 7 步自動刪
├── .upgrade-config-prev/             自管    升級前設定與憑證備份，每次覆寫
├── ai-gateway-rules/  .default/      自管    AI 閘道規則：客戶改過的 ／ 隨包預設
├── home/  static/                    自管    容器掛載的工作目錄與靜態檔
├── log/                              自管
│   ├── app.log  app.log.<日期>        後端 log，按日輪替保留 30 天（LOG_RETENTION_DAYS）
│   ├── install-<時間>.log             安裝紀錄
│   ├── upgrade-migrate-<單號>.log     每次升級的 migration 輸出
│   └── upgrade-<時間>.log             舊式 install.sh --upgrade 才寫 可清
│
├── upgrade/
│   ├── upgrade-progress.json         自管    進度檔：更新中心、維護頁、開機檢查都讀（Q18）
│   ├── last-switch.json  progress.d/ 自管    換接紀錄、每步明細
│   ├── maintenance/                  自管    新版維護頁（第 0 步放進來）
│   ├── orders/  .upgrade.lock        自管    更新單落地點（平時空）、防重入鎖
│   ├── incoming/                     可清    下載的更新包 tar.gz＋清單＋sha256＋ops，每包 5 GB
│   │                                           第 7 步只留本次；留著是給「重跑同版」，成功後可手刪
│   ├── bundles/guidant-ai-<版>/      可清    解開的包；成功後只剩 agent/ 1.7 GB（Agent 推送用）
│   └── diag/                         可清    歷次診斷包暫存，寄過就能刪
│
├── backup/  backup-manual/           可清    舊流程每次升級前的 pg_dump；新流程不寫不讀。只有老機器有
└── *.bak-*                           可清    人手改設定前的備份，確認現行設定正常後刪

/etc/guidant/release-keys/<kid>.pub  不能動  發布印樣，丟了升級包驗不過
/etc/guidant-ai/install.conf          不能動  記資料目錄在哪，維運指令靠它定位
/usr/local/bin/guidantai              不能動  維運指令
/usr/local/lib/guidant/               不能動  升級函式庫（八步腳本）
/etc/systemd/system/guidant-upgrade-* 不能動  接單、開機檢查的 systemd 單元

docker volume
├── guidant_guidant-seaweedfs-data    不能動  證據檔
├── guidant_guidant-bugsink-data      不能動  錯誤追蹤資料
├── guidant_guidant-classifier-jobs   不能動  分類工作
├── guidant_guidant-scan-vulndb       不能動  弱點庫
└── guidant_guidant-pgdata            自管    第一次升級前的舊資料庫 volume，下次成功自動刪

docker 映像
├── guidant-ai-be／fe／init           自管    第 7 步留本版＋上一版，更早自動刪
├── postgres  redis  seaweedfs  bugsink  evidence-classifier   第三方，升級流程不動
└── guidant-ai-agent:<版>             可清    Agent 容器自己升級留下的，主系統不管（190 五顆 21 GB）

🔴 不能動（丟了等於資料或系統沒了）

🟡 系統自己管（刪了會變難查或退不回，不用手清）

🟢 可以清（磁碟緊時先看這裡）

189 與 190 對照（2026-11-01 12:15 實查）

189 的清理動作屬「改 POC 狀態」，由首腦執行；本 session 只列清單。

密碼放在哪、怎麼加密、金鑰在哪、怎麼輪換

密碼與金鑰分兩個檔，都是 600、root 持有、明文存放：

為什麼明文：這兩個檔是「開機要用的鑰匙」，加密它們就需要另一把鑰匙放在同一台機器，等於沒加密。業界落地版的常規做法同樣是檔案權限 600 加 root，資料庫裡的敏感欄位才加密。

資料庫裡什麼有加密：Google Drive 授權 token、檢測工具帳密、AI 供應商 API key 三類，用 Fernet（AES-128-CBC 加 HMAC-SHA256，Python cryptography 套件的標準封裝），各自一把 32 bytes 金鑰（openssl rand -base64 32 產生）。密碼本身是 openssl rand -base64 24 產的 24 字元。

輪換：sudo guidantai rotate-credentials 換資料庫管理帳號、業務帳號、Redis 三組密碼，服務短暫重啟。刻意不輪換：JWT 金鑰（換了所有人當場登出）、三支加密金鑰（既有資料用舊鑰加密，換鑰不會回頭重加密，換了就永遠解不開）。要換加密金鑰需要另做「讀舊寫新」的遷移工具，目前沒有。

內部連線：Redis 與 SeaweedFS 走 TLS，憑證由主機上的 Agent CA 簽。SeaweedFS 內的檔案在 Agent 1.4.4 起靜態加密；主系統側的靜態加密狀態我還沒逐一核實，列為待確認。

.env 裡的資料庫、Redis、「業務帳號」密碼都是明文？業務帳號是 admin 密碼嗎？

是明文，沒有加密；業務帳號不是 admin，是資料庫服務帳號。

/srv/guidant-ai/.env 實際有的密碼（scripts/installer/install.sh:1397 起寫檔那段；原 Q7 少列了後兩類）：

保護只有一層：600、root 持有（install.sh:1430）。這些全是「機器對機器」的連線密碼。

人登入的密碼不在這裡。root admin 密碼：安裝時若有填，install.sh 以「只傳變數名不傳值」交給 init 容器（install.sh:1791），容器內 init.sh:134 當場轉 bcrypt 雜湊寫進使用者表，跑完 unset；不上命令列、不進 .env、不進安裝紀錄。沒填用 06-admin.sql 預設雜湊，首次登入改。之後所有使用者密碼都是 bcrypt 雜湊在資料庫，無處有明文。

診斷包只收 guidant.env 不收 .env，收的那份由核心統一遮罩（guidantai:728）。

明文太可怕，有辦法加密嗎？

檔案能加密，但在這種落地版主機上幾乎沒有實質保護力，該花力氣的是別的地方。三個查到的事實：

• 能讀這檔的人就是 root，而 root 可以 docker inspect guidant-api 直接看容器環境變數裡的密碼（後端用環境變數讀，config/config_loader.py:77），也能直接讀 /srv/guidant-ai/pgdata 整個資料庫目錄，根本不需要密碼。.env 加密了，資料還是明文躺在同一顆磁碟。
• 解密鑰匙沒地方放。190 實查：Ubuntu 22.04、systemd 249、沒有 TPM、沒有全碟加密。能把鑰匙鎖進硬體的 systemd-creds 要 systemd 250 以上加 TPM2，一般 VM 多半沒 TPM。沒硬體可鎖，鑰匙只能放檔案，等於沒加密。
• 每次開機由人輸入密碼是唯一真正不落地的方式，但服務不能無人值守重啟，升級第 6 步自動起服務也會卡住。

問題：威脅不是「檔案是明文」，是「拿到 root 或拿到磁碟的人看得到一切」，加密 .env 擋不住這兩種人。

建議（三層）：

1. 進裝機手冊給客戶：主機開全碟加密（LUKS），擋磁碟被搬走或 VM 映像被複製；限制誰能 sudo。屬客戶主機設定，進手冊不進資安報告。
2. 我們自己可改，縮小曝露面：密碼不走環境變數，改掛檔案進容器、程式讀檔。docker inspect、容器 crash dump、子程序都看不到密碼。磁碟上仍明文，但「不小心外洩」的路少一大半。中等大小一張卡，動 install.sh、compose、config_loader.py。
3. 客戶主機撐得住再做：Ubuntu 24.04 以上且有 TPM2 時，可選用 systemd-creds 把密碼封進 TPM，開機自動解、磁碟上只有密文、搬到別台解不開。真正的加密，但看客戶環境，不能當預設。

理由：資料庫本體 pgdata 明文、證據檔在 SeaweedFS 明文，.env 那幾串只是進門的鑰匙，門後的東西本來沒鎖。先鎖門後（全碟加密），再縮小鑰匙曝露面（檔案掛載），最後才談把鑰匙鎖進保險箱（TPM）。

docker 用什麼身分跑？當初掃描有警告「不能 root」？系統被入侵怎麼處理？

docker 引擎本身是 root，沒用 rootless 模式；這是刻意的決定，理由見資安報告 SR-09.5「不採用 rootless docker」。容器裡的程式全部非 root、cap_drop ALL、no-new-privileges（docker/production/docker-compose.yml、Agent deploy/docker-compose.yml）：

裝好的主機上要逐顆核實，跑 scripts/build/audit_nonroot_stack.sh（Agent 端加 --agent）。維運要以 root 進容器時明寫 docker exec -u 0。

「rootless」與「容器內非 root」是兩個層次：

系統被入侵怎麼處理：目前沒有寫成文件的處置流程（docs/user-manual/ 與資安報告都沒有事件應變章節）。照現有機制能做的：

• 圍堵：主機層拔網路或防火牆封鎖；sudo guidantai rotate-credentials 換資料庫與 Redis 全部密碼（JWT 與加密金鑰不在內，見 Q7）；授權中心把這張授權加進更新站拒絕名單。
• 鑑識：sudo guidantai diag 出診斷包（容器 log、system_logs、遮罩後設定檔）；主機 journalctl；api_logs 表是每個 HTTP 請求的流水，可追誰在何時打了什麼。
• 重建：image 有簽章與雜湊、安裝包有清單，做法是乾淨機器重新 install.sh，把 /srv/guidant-ai 的 pgdata 與 seaweedfs 資料接回。但資料目錄可能已被動過，接回前要先與快照或備份比對。

缺的：事件應變手冊、「JWT 金鑰一鍵換掉讓全部 session 失效」的指令、定期備份（Q5／Q20）、檔案完整性監控。屬規劃，列待討論。

docker compose 裡有什麼、參數與環境變數放在哪

本頁範圍：說明落地版的 docker-compose.yml 定義了哪些服務、各自的設定，以及所有參數與環境變數放在哪個檔、由誰寫、誰讀。依 repo docker/production/docker-compose.yml（779 行）、scripts/installer/install.sh 與 190 實機整理，2026-11-02。

結論：一份 compose 定義 10 個服務，設定分成兩個檔，用途不同：

compose 檔本身與兩個設定檔都放在資料目錄 /srv/guidant-ai/，是安裝時從出貨包複製過來的副本，與解開的出貨包脫鉤；/etc/guidant-ai/install.conf 記錄 compose 檔位置，維運指令靠它找到。

一、十個服務

網段：預設網段所有服務都在；另有兩個 internal 不出網的網段：guidant-sandbox（只有 worker 與沙箱，沙箱經此收工作）、guidant-sandbox-errors（只有沙箱與錯誤追蹤站，沙箱經此送錯誤事件，看不到資料庫、Redis、物件儲存）。

啟動順序：資料庫、Redis、物件儲存都 healthy 後才起三個後端容器（depends_on: condition: service_healthy）。所以資料庫與後端刻意放在同一個 compose project，跨 project 表達不了這個順序。

二、compose 檔裡共用的三段設定

三、三個後端容器掛了哪些主機目錄

四、.env：compose 讀的參數

由 install.sh:1397 起產生，之後部分鍵由安裝與升級流程補上。190 實機共 27 個鍵：

compose 檔另有一批只有預設值、.env 沒寫的可調參數：RUN_ENV（預設 prod）、GUIDANT_API_MEM_LIMIT（6g）、GUIDANT_SOCKETIO_MEM_LIMIT／GUIDANT_WORKER_MEM_LIMIT（3g）、各自的 PIDS_LIMIT、GUIDANT_WORKER_REPLICAS（1）。要調就在 .env 加一行，sudo guidantai start 套用。

五、guidant.env：後端程式讀的設定

由 install.sh:1436 產生，之後安裝流程補 Agent、錯誤追蹤、更新站。190 實機共 39 個鍵：

六、優先序與兩個容易踩的地方

• compose 的 environment 蓋過 guidant.env。例如 RUN_ENV、Redis 帳密、REDIS_SSL 在 compose 裡也寫了，以 compose 為準；guidant.env 那份只給自備 compose 的部署當後備。所以三個後端容器實際用的是各自的 Redis 帳號，不是 guidant.env 裡那組。
• 同一組密碼寫在兩處：資料庫與 Redis 帳密在 .env（建服務）與 guidant.env（連線）各一份，必須一致。安裝程式一次產生、同時寫兩處；手動只改一邊的症狀是「後端起得來但連不上」。要換密碼用 sudo guidantai rotate-credentials，會兩邊一起改。
• 改完設定要用 start 不是 restart：restart 只重啟現有容器、不讀新設定；維運指令偵測到設定檔比容器新，會擋下並提示改用 start。
• 不要裸打 docker compose up -d：不帶服務名時，任何一項設定變更都會連資料庫一起重建，造成數十秒中斷。維運指令與升級流程都帶服務名。

七、刻意不在 compose 裡的

• 後端健康檢查：寫在映像的 Dockerfile 裡，compose 不重複定義，避免兩處漂移。
• 前端 nginx 設定：build 進前端映像（nginx.onprem.conf），不外掛；設定與該版前端是一組，外掛會讓兩者版本對不上。
• 資料庫、Redis 對外埠：刻意不開，唯一對外入口是 80／443。要進資料庫排錯用 docker compose exec guidant-db psql。
• 自備資料庫或 Redis 的參數：安裝程式不提供外接模式。客戶要用既有的服務，就自己改 compose：把那段服務註解掉、改 guidant.env 的連線位址；自備 Redis 必須開 TLS。

發版流程：腳本在哪、流程怎麼走、什麼時候簽章

本頁範圍：說明一個新版本從程式碼到客戶「更新中心」看得到為止，經過哪些階段、各階段由哪支腳本在哪裡執行、簽章在哪一刻發生。分兩段：現行做法（1.27.x 實際在用）與改版後做法（FR-172 Agent 獨立出版、FR-173 出版管線定稿，設計已定、實作中）。依程式碼、CI 設定與三案設計文件整理，2026-11-02。

設計原則：私鑰不進 CI、更新站沒有私鑰。CI 能做的只到「草稿」，草稿客戶看不到；要讓客戶看得到，一定要經過簽章，簽章的鑰匙放在 CI 拿不出來的地方。客戶主機用安裝時就放好的公鑰驗章，驗不過就拒裝。

一、現行做法（1.27.x）

發版分三個階段，腳本放在兩個 repo，在三個地方執行：

①② 在 .gitlab-ci.yml 的 package 段連續跑：sbom.sh（弱點放行門，白名單外 Critical 就停）→ build_bundle.sh（不准加跳過正式公鑰檢查的參數）→ push_harbor.sh → publish_draft.sh。③ 必須等人執行。

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','lineColor':'#4A5A5C','textColor':'#14201F','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#F6EBD5','labelBoxBorderColor':'#9C6B12','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF','fontSize':'13px'}}}%%
sequenceDiagram
    autonumber
    participant D as 開發者
    participant G as GitLab CI（188 build 機）
    participant R as Cloudflare R2
    participant U as 更新站（Worker＋D1）
    participant K as 決策者電腦
    participant C as 客戶主機
    rect rgb(246,235,213)
    Note over D,C: ① 出包（CI，無私鑰）
    end
    D->>G: 推 commit／手動觸發
    G->>G: verify：守衛測試、pip-audit
    G->>G: build：Nuitka 編譯、BE／FE／init 映像
    G->>G: rehearse：用同一支 build_bundle 打的包在 190 做升級排練
    G->>G: package：sbom 弱點放行門 → build_bundle 打包 → release_json 產未簽清單
    rect rgb(246,235,213)
    Note over D,C: ② 上傳登記（CI，用 R2 金鑰與更新站 CI token）
    end
    G->>U: register-draft（版號、雜湊、大小）
    U-->>G: 回 R2 物件路徑 v1/版號/…
    G->>R: 上傳 tar.gz、.sha256、未簽 release.json
    Note over U: 狀態 draft：只有指定的內部測試機看得到
    rect rgb(226,240,241)
    Note over D,C: ③ 蓋章發布（決策者電腦，唯一有私鑰的地方）
    end
    K->>U: guidant-release publish 版號：取草稿
    K->>K: 輸入私鑰密碼 → 解開私鑰 → 對清單簽 Ed25519
    K->>U: 送回簽好的清單
    Note over U: 狀態 published：同主版號客戶都看得到
    rect rgb(236,236,236)
    Note over D,C: 客戶端（見 Q11、Q12 與執行流程）
    end
    C->>U: 每日檢查有沒有新版
    U-->>C: 有 1.27.x、附簽好的清單
    C->>R: 用 15 分鐘預簽網址下載
    C->>C: 用本機 /etc/guidant/release-keys 公鑰驗章、比對雜湊

圖 1　現行發版循序圖（從程式碼到客戶）。①② 在 CI 自動連續跑，CI 沒有私鑰，只能產出草稿；③ 由決策者在自己電腦執行，是唯一能讓客戶看得到新版的動作。

現行 CI 流程（BE .gitlab-ci.yml）

觸發方式：只有人主動發才跑，push、MR、打 tag 一律不觸發。兩種發法：GitLab 網頁按「Run pipeline」，或指令 glab ci run。另有一條每日排程，只負責發布弱點資料庫，與出版互斥。定版 tag 由決策者手打，CI 不碰 tag。

在哪跑：全部 job 跑在 188 build 機（runner tag guidantai-build，shell 執行），不另外 clone，直接在 188 的 /opt/guidant-ai-be 工作樹裡跑。開跑前檢查兩件事：188 上有人在手跑 build 就拒跑（兩條 Nuitka 同跑會 crash）；工作樹不乾淨就拒跑，不悄悄 reset 掉別人的東西。這個檔只寫「什麼時候、在哪台、呼叫哪支」，邏輯全在 scripts/build/*.sh，所以 188 手跑與 CI 跑是同一條路。

按 Run pipeline 時可選的參數：

五個 stage：

%%{init: {'theme':'base','themeVariables':{'darkMode':false,'background':'#FBFCFC','primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','secondaryColor':'#EEF2F3','tertiaryColor':'#FBFCFC','lineColor':'#4A5A5C','textColor':'#14201F','titleColor':'#14201F','edgeLabelBackground':'#FBFCFC','clusterBkg':'#F6F7F5','clusterBorder':'#C7D1D2','fontSize':'13px'}}}%%
flowchart LR
    T["人按 Run pipeline
或 glab ci run"] --> V
    subgraph S1["verify"]
      V["同步 188 工作樹
sbom 原始碼層
audit_deps 套件弱掃"]
    end
    subgraph S2["build（平行）"]
      BE["build-be
Nuitka＋smoke＋映像"]
      FE["build-fe"]
      CL["build-classifier"]
      IN["build-init"]
    end
    subgraph S3["rehearse"]
      RH["打一次包
190 舊版→新版排練"]
    end
    subgraph S4["package"]
      PK["映像弱點放行門
build_bundle
推 Harbor
publish_draft 草稿＋R2"]
    end
    subgraph S5["deploy"]
      DE["e2e 190"]
      DS["stg 188"]
      DP["poc 189
再按一次"]
    end
    V --> BE & FE & CL
    BE --> IN
    BE & FE & IN & CL --> RH --> PK
    PK --> DE & DS & DP
    PK -. 草稿 .-> SIGN["決策者電腦
guidant-release publish
（不在 CI 內）"]

圖 1-1　現行 CI 流程。任一段紅，後面全部不跑；簽章不在 CI 內。

Agent 怎麼出：現行 Agent 沒有自己的發版流程，跟著主系統包一起出。build_bundle.sh 把 evidence-agent repo 的 build_compose_bundle.sh 產的 Agent 交付包放進主系統包的 agent/ 資料夾（build_bundle.sh:465）。客戶主系統升級完，第 7 步清理只保留 bundles/<版>/agent/，之後由更新中心推給各台 Agent。所以修一個 Agent 的 bug，要重出整個主系統、客戶主系統也要停機升一次。

測試期的實況：正式私鑰還沒產（決策者尚未執行 init-keys），188、189、190 裝的都是 10/30 產的測試章 b91819f86eb4b4f8。測試期由首腦用 ~/Projects/Billows/Audit-Manager/.fr167-dev/publish/publish-<版>.sh 直接簽，沒走正式 guidant-release publish。正式出貨前要換正式章；build_bundle.sh:187 沒有正式公鑰就拒絕出包，CI package 段不准加跳過參數。

二、改版後做法（FR-172＋FR-173）

兩個改變：主系統與 Agent 分開出版（FR-172），簽章從決策者電腦搬到自架金庫（FR-173）。

改版後的 CI 流程（FR-173 設計）

跟現行最大的三個差別：觸發改成推保護 tag（現行是人按 Run pipeline）；前端與 Agent 各有自己的 pipeline（現行全塞在 BE 一支）；簽章進 CI，變成最後一個手動按鈕（現行在決策者電腦）。建置期祕密（R2、Harbor、更新站 token、Nexus）從 188 的 .env 與 GitLab 變數搬進 Vault，job 執行時才拿、結束即失效。

%%{init: {'theme':'base','themeVariables':{'darkMode':false,'background':'#FBFCFC','primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','secondaryColor':'#EEF2F3','tertiaryColor':'#FBFCFC','lineColor':'#4A5A5C','textColor':'#14201F','titleColor':'#14201F','edgeLabelBackground':'#FBFCFC','clusterBkg':'#F6F7F5','clusterBorder':'#C7D1D2','fontSize':'13px'}}}%%
flowchart LR
    subgraph trig["觸發（人做的第一件事）"]
      T1["推保護 tag
v1.28.0（BE）"]
      T2["推保護 tag
v1.5.0（Agent）"]
      T3["FE／jedi 任意 push"]
    end
    subgraph be["BE pipeline（188，與 Agent 串行）"]
      B1["verify
守衛 pytest 弱掃"]
      B2["觸發 FE 下游
等它綠"]
      B4["build
Nuitka BE／init 映像"]
      B5["rehearse
190 升級排練"]
      B6["package
弱點放行門 打包
Harbor 草稿 R2 v1/"]
      B7["簽章並發布
（手動按鈕）"]
      B1 --> B2 --> B4 --> B5 --> B6 --> B7
    end
    subgraph fe["FE pipeline（docker runner）"]
      F1["verify
lint vitest npm 弱掃"]
      F2["打 FE 映像
主控台前端產物"]
      F1 --> F2
    end
    subgraph ag["Agent pipeline（188，與 BE 串行）"]
      G1["verify"]
      G2["build
Nuitka 取主控台前端"]
      G3["rehearse
舊包 --upgrade"]
      G4["package
打包 Harbor
草稿 R2 agent/v1/"]
      G5["簽章並發布
（手動按鈕）"]
      G1 --> G2 --> G3 --> G4 --> G5
    end
    VA["自架 Vault
Ed25519 鑰匙不可匯出
建置期祕密"]
    T1 --> B1
    T2 --> G1
    T3 --> F1
    B2 -.觸發.-> F1
    F2 -.前端產物.-> G2
    B6 -.取祕密.-> VA
    G4 -.取祕密.-> VA
    B7 -.要簽名.-> VA
    G5 -.要簽名.-> VA

圖 2-1　改版後三條 CI。BE 與 Agent 都跑在 188（Nuitka 需要 188 環境），排同一個佇列不併跑；FE 跑 docker runner。人要做的只有兩件：推保護 tag、按「簽章並發布」。

部署到 190／188／189 那段在 FR-173 設計裡沒有改，沿用現行 deploy_e2e.sh；STG／POC 改成走線上更新還是維持 install.sh --upgrade，設計文件沒寫，要另外確認。

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','lineColor':'#4A5A5C','textColor':'#14201F','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#F6EBD5','labelBoxBorderColor':'#9C6B12','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF','fontSize':'13px'}}}%%
sequenceDiagram
    autonumber
    participant M as 維護者
    participant B as BE CI
    participant F as FE CI
    participant A as Agent CI
    participant V as 自架 Vault（192.168.50.172）
    participant R as R2
    participant U as 更新站
    rect rgb(246,235,213)
    Note over M,U: 主系統發版
    end
    M->>B: 推保護 tag v1.28.0
    B->>B: verify：守衛、pytest、弱掃
    B->>F: 觸發 FE 下游，等它綠
    F-->>B: FE 映像 tag
    B->>B: build → rehearse 排練 → package 弱掃放行門與打包
    B->>V: 用 GitLab OIDC 取 R2、更新站 token 等建置期祕密
    B->>U: register-draft product=host
    B->>R: 上傳到 v1/1.28.0/
    M->>B: 按「簽章並發布」（手動按鈕，只在保護 tag）
    B->>V: OIDC 換短效身分 → transit/sign 要簽名
    V-->>B: 簽名（鑰匙不離開 Vault，每次簽章記稽核 log）
    B->>U: 送簽好的清單 → published
    rect rgb(226,240,241)
    Note over M,U: Agent 發版（獨立，不需重出主系統）
    end
    M->>A: 推保護 tag v1.5.0
    A->>A: verify → build（主控台前端拿 FE artifact）→ rehearse → package
    A->>U: register-draft product=agent
    A->>R: 上傳到 agent/v1/1.5.0/
    M->>A: 按「簽章並發布」
    A->>V: transit/sign
    V-->>A: 簽名
    A->>U: 送簽好的清單 → published

圖 2　改版後發版循序圖（從程式碼到更新站）。主系統與 Agent 各一條 pipeline、各自觸發；簽章改由 CI 手動按鈕向 Vault 要簽名，鑰匙拿不出 Vault。仍要人按的只有兩個：推保護 tag、按「簽章並發布」。

Agent 包怎麼到客戶的 Agent 主機（FR-172 已裁）：Agent 不連外網、不連更新站。主系統代為檢查與下載 Agent 新版，驗過章存到 upgrade/agent-bundles/<版>/，再推給各台；Agent 主控台也能請主系統更新這一台，或在離線時直接上傳包，用現行版帶的公鑰驗章。所以修 Agent 的 bug，主系統不必出版、不必停機。

為什麼簽章要從決策者電腦搬走（FR-173 D1）：決策者出差就出不了版，與無人值守自動化方向相反。但不能把私鑰放 GitLab CI 變數：CI 變數讀得到就等於私鑰外流。改用 Vault 的「Transit」：鑰匙建在 Vault 裡設成不可匯出，CI 只能拿資料去請 Vault 簽，拿不到鑰匙本身；而且 Vault 只認「保護 tag 觸發的 BE、Agent 兩個專案」的 GitLab 身分。客戶端驗章程式不用改：還是 Ed25519，只是多一把公鑰。

三、進度（2026-11-02）

最低相容版本怎麼決定

可直升起始版（min_base）不是人填的數字，是從 migration 清單推算：scripts/sql/manifest.tsv 每支 migration 有一欄 min_base，寫 migration 的人只在「這支依賴某版才建的東西，從更舊的版直跳會壞」時填那個版號。出包時取全部的最大值寫進清單。目前沒有任何一支填，所以每版都是 1.0.0，任何版都能一跳升上來。

主系統與 Agent 互相要求的最低版本（FR-172 起）是人填的一行檔：主系統 scripts/build/min_agent_version、Agent scripts/build/min_host_version。只擋一個方向：Agent 新版要求的主系統版本比客戶現行版新，就不讓推（灰鈕加原因）；主系統新版要求的 Agent 版本比某台新，只在那台標「必須更新」，不擋主系統升級。

簡報「一條指令打一次密碼」是什麼意思

決策者在自己電腦執行 guidant-release publish 1.27.8。程式會要求輸入私鑰檔的密碼，輸入一次後：解開私鑰、對清單簽章、把簽好的清單送到更新站、狀態改為「已發布」。密碼不存、不進參數、不進環境變數。簡報那句已改寫。

這是現行做法。FR-173 改版後，正式簽章改由 CI 的「簽章並發布」按鈕向自架 Vault 要簽名，不再需要決策者電腦與密碼；決策者電腦那把私鑰保留當備用章（見 Q8 第二段）。

15 分鐘下載網址怎麼產生、用什麼服務

更新包放在 Cloudflare R2（S3 相容物件儲存），bucket 不公開。客戶主機要下載時向更新站要網址，更新站用 R2 的存取金鑰對該物件簽一個 AWS SigV4 預簽網址，有效期 X-Amz-Expires=900（15 分鐘）。網址帶著簽名，R2 驗簽放行，過期就 403。主機程式只接受指向固定 R2 主機名的網址，更新站給別的網址一律拒。5 GB 的包下載不經更新站，直接從 R2 拉，更新站沒有流量負擔。

這是 Cloudflare 的機制嗎？是我們用 API 產一個臨時網址給主機下載？

是。更新站（Cloudflare Worker）替這台主機簽一個 15 分鐘有效的臨時網址，主機拿著它直接向 R2 拉包，更新站本身不經手檔案。嚴格說這是 S3 體系通用的「預簽網址」，R2 相容 S3 API 所以照用，不是 Cloudflare 獨有功能。

補一點：這個網址是主機程式拿去下載用的，不是給人點的。使用者在更新中心按「下載」，是後端去跟更新站要網址再自己拉，使用者看不到網址。Worker 只做「驗身分、查版、簽名」三件小事，5 GB 流量全走 R2。

拿到的網址長什麼樣

以 1.27.9 整包為例（主機名、bucket、物件路徑是查到的真值；金鑰 ID 與簽章用佔位）：

https://6b1da966062f9093782aefa99c1e68d1.r2.cloudflarestorage.com/guidant-ai-release/v1/1.27.9/guidant-ai-1.27.9.tar.gz
  ?X-Amz-Expires=900
  &X-Amz-Date=20261101T083000Z
  &X-Amz-Algorithm=AWS4-HMAC-SHA256
  &X-Amz-Credential=<R2 存取金鑰 ID>%2F20261101%2Fauto%2Fs3%2Faws4_request
  &X-Amz-SignedHeaders=host
  &X-Amz-Signature=<64 位十六進位簽章>

更新站回給主系統的整包回應（src/routes/client.ts:76）：

{ "version": "1.27.9", "sha256": "6810fdfd…", "size": 5262333964,
  "url": "https://…（上面那串）", "expires_in": 900 }

查不到的地方：真實網址沒有落在任何 log。主系統只在拒絕時 log 主機名（update_site_client.py:143），正常路徑不印網址；更新站也沒記。上面是照程式與套件拼出來的格式，不是從某台機器抓下來的實例。要看真的只能在下載當下抓後端對 R2 的連線或臨時加 debug log，超出問答 session 界線。

跨主版號（1.x → 2.x）怎麼處理

設計定案 D7：換主版號要重新授權。更新站只回「與客戶授權主版號相同」的版本，1.x 授權的客戶永遠看不到 2.0.0。客戶實際流程：

1. 原廠在授權中心為該客戶簽發新授權（主版號 2）。
2. 客戶在產品內匯入新授權。
3. 下一次「檢查更新」帶新授權問更新站，才看到 2.0.0。
4. 主機端再驗一次：包的主版號要等於現行主版號，否則拒裝。這一條在 2.0 要放寬成「等於授權主版號」。

資料庫 schema 從 1.x 到 2.x 的 migration 本身與小版相同，照 manifest 順序跑在複本上；差別只在授權門與主版號判斷。

1.x → 2.x 是不是還沒討論過？如果 2.0.0 只是 UI 大改、底層沒變，應該要允許更新，差別只在授權放不放行？

討論過、定案了、也寫進程式了：設計決策 D7「主版號＝授權邊界，換主版號要重新授權」（design.md D7、discussion.md 第 184 行起）。所以「2.0.0 只是大號、想讓客戶免費升」跟現行設計衝突，不是沒規則，是規則說不行。要讓它行是決策問題，不是機制問題。

現在有兩道門，查的東西不一樣：

授權檔那欄在授權中心簽發表單叫「產品主版號」，預設 1（license_center schema.py:183、issue_form.html:77）；更早簽的授權沒這欄，更新站一律當 1。

「差別只在授權放行」對一半：那只是第一道。第二道查「現行版」不查「授權」，所以今天就算重簽主版號 2 的授權給客戶，主機仍拒裝 2.0.0，因為他現在跑 1.x。上面 Q12 第 4 點「要放寬成等於授權主版號」就是這個待辦，目前沒做；現在沒有 2.0 不會踩到，列入文末「發現的問題」。

決策者 2026-11-01 確認的理解

• 跨主版號本身不是限制，限制是授權怎麼判。規則是「主版號要相同」，不是「授權要有效」：授權到期的客戶照樣能升 1.x 最新版（D7 刻意如此），但沒人能跨主版號，不管授權有沒有效。
• 要開放做得到，技術上沒障礙。例如改成「有買維護就能一直升」：更新站的門從「主版號相同」改成「維護期內」，是改規則不是改架構。
• 當初討論的做法是出 2.0 再由授權中心簽一張主版號 2 的新授權給客戶（D7 立論是買斷軟體「含同代升級、換代另購」）。維護期模式與它不衝突，只是把「重簽」換成「看授權檔的維護到期日」。兩種都接得住，等商業模式定了再選，本輪只探討做法。
• 不管選哪種，主機端那道都要改：它現在比「現行版號」不看授權，授權怎麼放行主機都拒，出 2.0 前必須改成「看授權」（見文末發現的問題）。

migration 不受影響：1.x → 2.x 的 schema 升級與小版一樣照 manifest 順序跑在複本上。

線上升級執行流程（主系統與 Agent）

本頁範圍：主系統與 Agent 是兩個安裝包、兩條版本線，各自升級。本頁用三張循序圖說明：圖 1 主系統自己升級、圖 2 主系統發動 Agent 升級、圖 3 Agent 主控台發動 Agent 升級；後面兩張逐步表列出每一步跑哪支程式、畫面看到什麼。適用主系統 1.28.3、Agent 1.5.5，依程式碼與 190 實機紀錄整理，2026-11-03。

設計原則：

• 容器不動 docker，主機才動：主系統後端與 Agent 都只寫一張「升級單」交給自己那台主機，停容器、換版、退回全部由主機上的 systemd 單元以 root 執行。容器在升級中會被換掉，不能當執行者。
• 狀態只有一個來源：主機每步改寫進度檔，畫面、維護頁、開機檢查都讀這一份，所以容器停了進度照樣會動。
• Agent 不連外網：Agent 的包一律由主系統向更新站下載、驗章，再交給 Agent。
• 不靠心跳：主系統直接連 Agent 的 8443 推指令；Agent 主動送事件回報進度。心跳只表示「活著」。

一、主系統升級

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','lineColor':'#4A5A5C','textColor':'#14201F','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#F6EBD5','labelBoxBorderColor':'#9C6B12','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF','fontSize':'13px'}}}%%
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

圖 1　主系統升級。編號為時間順序；灰色區段後端與資料庫停機，畫面由前門 nginx 的維護頁提供，維護頁直接讀進度檔。190 實測 1.28.2→1.28.3 整次 6 分 42 秒，停機約 4.5 分鐘。

二、主系統發動 Agent 升級

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','lineColor':'#4A5A5C','textColor':'#14201F','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#F6EBD5','labelBoxBorderColor':'#9C6B12','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF','fontSize':'13px'}}}%%
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: 版本換了 → 整頁重新載入回原頁（不必重登）

圖 2　主系統發動 Agent 升級。按更新不必先預先下載；Agent 當時離線，主系統會在它下次心跳回來時補推。開著的主控台最慢 30 秒內鎖住（平常輪詢間隔），鎖住後每 3 秒更新進度。

三、Agent 主控台發動 Agent 升級

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','lineColor':'#4A5A5C','textColor':'#14201F','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#F6EBD5','labelBoxBorderColor':'#9C6B12','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF','fontSize':'13px'}}}%%
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

圖 3　Agent 主控台發動。主控台的「更新到 X」只是請主系統替這一台做圖 2 的事；主系統斷線時只能離線上傳。

主系統逐步說明

Agent 逐步說明

常見問題

• 主系統停機時，畫面是誰在服務？前門 guidant-fe（nginx）從不停。它探到後端不通就改送維護頁，維護頁每 3 秒直接讀進度檔，不經後端、不經資料庫。
• Agent 升級時還能派掃描嗎？不能。從收到 /update 起 Agent 就停收新工作，直到換版完成。
• Agent 主控台為什麼有時慢一點才鎖？主控台平常每 30 秒問一次狀態；由主系統發動時最慢 30 秒才鎖，在主控台自己按的當下就鎖。這段時間 Agent 已經停收新工作。
• Agent 不連外網，包怎麼來？一律由主系統向更新站下載、驗章後交給 Agent；離線時才由現場人員上傳離線包，驗章用 Agent 現行版的公鑰，不用包裡附的。
• 升級中有人又按更新？主系統更新單同時只跑一張；Agent 下載中再有人按，會併入同一份待推清單，不覆蓋先按的人。
• 測試機想重看升級流程？兩個環境變數都開才出現「重新套用目前版本」：主系統 PRODUCT_UPDATE_ALLOW_SAME_VERSION=1、Agent AGENT_UPDATE_ALLOW_SAME_VERSION=1。出貨範本不帶這兩個鍵，正式環境不會出現。

完整程式清單與優化項目見 FR-172 定版交付（docs/features/FR-172-2611-agent-independent-update/FINAL-SPEC.md）。

升級觸發機制：更新單與主機監看服務

結論：這是一種「用檔案當 API」的觸發方式。後端在容器裡沒有 root、不能動 docker，它唯一能做的是把一張更新單（JSON）寫進主機的 /srv/guidant-ai/upgrade/orders/。主機上的 Linux 內建服務管理程式 systemd 監看這個資料夾，一有新檔就以 root 啟動升級程式。升級程式是主機上的一組 bash 腳本，不是一顆專門的升級容器。

與一般 API 呼叫的對照

差別：不開埠、不走網路，只靠同一台機器上的檔案；而且是單向非同步，後端丟完就走。這是刻意的：後端在升級中會被停掉，同步 API 會在那一刻斷線。

更新單與進度檔的差異

兩個檔以同一個單號關聯，更新中心據此把「送出的單」對應到「主機回報的進度」。

更新單格式

{
  "job_id": "20261101-0413-0139",
  "type": "upgrade",
  "mode": "now",
  "version": "1.27.10",
  "path": ["1.27.10"],
  "not_before": null,
  "requested_by": "blsadmin",
  "requested_at": "2026-11-01T04:13:52+00:00"
}

單上沒有包的路徑、沒有任何指令。後端寫單時先寫暫存檔再改名（_write_atomic），主機看到檔案那一刻內容就是完整的。

主機 systemd 服務單元

systemd 是 Linux 開機第一個跑的程式，docker、ssh、資料庫都靠它管。往 /etc/systemd/system/ 放服務設定檔是它的標準用法，Ubuntu 自己也有同類的資料夾監看器（189 上有 apport-autoreport.path、systemd-ask-password-*.path）。底層用核心的 inotify 事件通知，不是定時去掃。

它怎麼知道盯哪個資料夾：repo 原檔 scripts/installer/systemd/guidant-upgrade-order.path 寫佔位字 @GUIDANT_DATA_DIR@。安裝程式 lib/systemd_units.sh:52 讀這台的 /etc/guidant-ai/install.conf，用 sed 換成真實路徑後寫進 /etc/systemd/system/，再 systemctl daemon-reload 與 systemctl enable --now（:62）。

什麼時候裝的：全新安裝第 ⑦ 步與每次升級第 0 步都會重寫並啟用。和公鑰放進 /etc/guidant/ 是同一步。

客戶主機自己查：

systemctl status guidant-upgrade-order.path     # 有沒有在盯
systemctl cat guidant-upgrade-order.path        # 設定內容與檔案位置
journalctl -u guidant-upgrade-order.service     # 每次被叫醒做了什麼

升級程式組成

/usr/local/bin/guidantai upgrade --from-order   維運指令總入口（status、restart、diag 也在這支）
└── lib/upgrade_order.sh                        讀單、驗包、分派：立即跑／排程／診斷包
    └── lib/upgrade_runner.sh                   升級總指揮：依序跑八步、每步計時、失敗就退回
        ├── 第 0 步  self_replace.sh            換成新版的自己
        ├── 第 1 步  upgrade_preflight.sh       預檢
        ├── 第 2 步  upgrade_drain.sh           停接新工作
        ├── 第 3 步  upgrade_db_copy.sh         停服務、複製資料庫
        ├── 第 4 步  upgrade_apply_on_copy.sh   在複本上跑 migration
        ├── 第 5 步  upgrade_health.sh          健康檢查
        ├── 第 6 步  upgrade_switch.sh          換接
        ├── 第 7 步  upgrade_cleanup.sh         清理
        └── 失敗時   upgrade_rollback.sh        退回
    （每一步都透過 progress.sh 寫進度檔）

全部放在主機 /usr/local/lib/guidant/，以 root 執行。管理員登主機手動跑 sudo guidantai upgrade 走的也是同一個 upgrade_runner.sh，進度檔 triggered_by.kind 記 cli 而不是 order。

升級途中會借用三種臨時容器，都是腳本叫起來、用完就收：

為什麼不做成一顆升級專用容器

結論：容器其實停得了別的容器，只要把主機的 /var/run/docker.sock 掛進去（Portainer、Watchtower 都這樣做）。問題是拿到 docker.sock 的程式可以叫 docker 開一顆新容器、把主機根目錄整個掛進去，等於主機 root。升級要停容器、搬 pgdata、改 600 權限的 .env，本來就是 root 的事；包成容器不會比較安全，只是換一個入口給它 root。所以讓主機 root 做 root 的事，平常什麼都不在跑。

書面依據（被問時可指）：

常駐型升級容器的四個問題：

1. 權限沒變小：要掛 docker.sock 加整個資料目錄，合起來就是主機 root。
2. 得常駐：要接更新單就得一直開著，一個長期掛 docker.sock 的容器資安審查會直接點名。現行做法平常沒有任何程式在跑，systemd 只是設定，被叫醒才執行。
3. 升級不了自己：D30 要求第 0 步先換成新版升級程式；容器在「停掉自己」那一刻流程就斷。
4. 斷電救不回：開機檢查要在 docker 起來前判斷要不要退回；docker 起來時舊容器可能已照 restart 策略起來，半套狀態被當成正常。

一定會被問的反問：「不要常駐，systemd 被叫醒時跑一次 docker run --rm 升級容器:新版 不就好了？」這個反問成立，它解掉第 2、3 點。誠實的回答：

• 權限一樣大：照樣要掛 docker.sock 與整個 /srv/guidant-ai，安全上打平。
• 開機檢查還是得在主機上：等於主機留一份 shell、容器再一份，兩套。
• 唯一實際好處是環境一致：不用管客戶主機有沒有 rsync、python3。現行代價是程式裡處處寫退路、預檢擋缺 python3 的主機。
• 已拿到這好處的一部分：需要新版程式碼的工作（migration、健康檢查）都借新版映像起臨時容器做，用完就刪。

所以這是取捨，不是「容器做不到」：一次性升級容器安全上打平、多一套東西要維護，好處只有環境一致。GitLab、Sentry 的自架升級同樣是主機 shell 加 docker compose。

安全邊界

• 後端碰不到 root。orders/ 權限 730 root:1000：容器能放檔、能刪自己知道名字的檔（取消未被撿走的單），但列不出內容。
• 主機不信單上內容（upgrade_order.sh:19）。只拿單號與版號，正規式驗格式；包一律由版號在本機 incoming/ 拼出路徑，用本機公鑰重驗簽章與雜湊、確認比現行新。任何一項不過就不跑，進度檔記 skipped 與原因。用 Python json.load 解析，不用 grep 拼字串。
• 取消：單還沒被撿走，後端直接刪單；已開跑，後端寫 <單號>.cancel，主機在第 0～2 步每步檢查、看到就收手。第 3 步停服務後不能取消。
• 殘餘風險：後端被攻破時，攻擊者能挑時間叫主機升到 incoming/ 裡任一個簽章合法、比現行新的版本。版本不能造假，但可以被拿來挑時間停機。

執行權限與業界做法

安裝一定要 root（install.sh:454 開頭就擋）：要在 /srv 建目錄、寫 600 設定檔、把目錄 chown 給容器內 uid 1000、操作 docker、寫 /usr/local/bin、/etc/guidant*、/etc/systemd/system/，這些都只有 root 能做。GitLab、Sentry、Harbor 的自架安裝同樣要 sudo。改成加入 docker 群組的一般帳號裝也可以，但 docker 群組能掛載任何主機目錄，實際權限等於 root，沒有比較安全。手冊 docs/user-manual/onprem/01-prerequisites.md「1.2 為什麼一定要 sudo」有寫理由。

網頁觸發主機升級的三種做法：

機制本身是 Linux 標準做法；「網頁能觸發主機 root 動作」在落地版產品屬少數派，部分企業的主機管理規範會擋。既然要網頁一鍵升級，我們選的是比較收斂的做法。實作上不夠好的地方列在「發現的問題」。

複製資料庫怎麼做、資料庫名稱會改嗎、設定檔會動嗎

資料庫名稱不變（一直是 guidant_ai），動的是「資料目錄」。流程：

1. 第 3 步停 api、worker、socketio，再停 db。把現用資料目錄整個複製（rsync）到 /srv/guidant-ai/pgdata-next.partial，完成核對後改名 pgdata-next。「pgdata-next 存在」就代表「複本完整」。
2. 第 4 步用環境變數把 db 容器指到 pgdata-next 起來，先核對容器掛的真的是複本，再用 init 映像跑 migration。現用那份從頭到尾沒動。
3. 第 6 步換接：先改 .env 的 GUIDANT_PGDATA_DIR 指向新目錄，再搬目錄（順序刻意：搬完沒寫就斷電，開機會接回舊的，複本等於沒升）。舊的改名 pgdata-prev-<舊版>，pgdata-next 改名 pgdata。

設定檔動了什麼：.env 的 GUIDANT_VERSION 與 GUIDANT_PGDATA_DIR；docker-compose.yml 換成新包那份（複製到資料目錄，與解開的包脫鉤）；guidant.env 只補新增的鍵，既有值不動。升級前的設定與憑證另留一份在 .upgrade-config-prev/。

複本轉正後，舊的快照存在哪裡

兩種情況：

• 第一次從舊版升級（舊版資料庫在 docker named volume）：volume 改不了名，原封留著當快照，進度檔記 prev_kind=volume。188、189、190 都是這種。
• 之後的升級：現用目錄改名 /srv/guidant-ai/pgdata-prev-<舊版>，進度檔記 prev_kind=dir。三台現在都有 pgdata-prev-1.27.7。

只留一代：下一次升級成功的第 7 步會刪更早的快照（含第一次留下的 volume）。這是「退回用」不是「備份」，見 Q20。

停服務停什麼、為什麼資料庫還能健康檢查與 migration、資料庫引擎要升版怎麼辦

停的是：api、worker、socketio（第 3 步開頭），接著 db（複製前）。不停的是：前門 fe（切維護頁）、redis、seaweedfs、錯誤追蹤站。

資料庫為什麼還能用：第 4 步把 db 容器用「指向複本」的方式重新起來，migration 用另一個 init 容器連這顆 db 跑。第 5 步再把新版 api 也用複本起來做健康檢查。所以升級中跑著的 db 連的是複本，不是現用資料。

資料庫停兩次：怎麼複製、怎麼指到複本、升完名稱怎麼改回來

結論：資料庫在第 3 步停、第 4 步掛複本重新起來跑 migration、第 6 步再停一次改資料夾名、然後掛新的 pgdata 起正式服務。現用那份從第 3 步停下後就沒再被任何東西寫過。

怎麼複製（第 3 步，upgrade_db_copy.sh）

直接複製 PostgreSQL 資料夾（冷備份），不用 pg_dump。資料庫正常關機後資料夾是一致的完整狀態，整份 cp -a 就能在別處起來用。先寫 pgdata-next.partial，比對兩邊檔案數一致後才改名成 pgdata-next；「看到 pgdata-next」才代表複本完整。失敗、逾時、被中止都會先起回舊版服務再刪複本。189 這次：686 MB，10 秒。

證據檔（物件儲存）不複製，升級不改它們（D18）。

怎麼指到複本（第 4 步）

compose 的資料庫掛載本來就是變數（docker/production/docker-compose.yml:302）：

guidant-db:
  image: postgres:16
  volumes:
    - ${GUIDANT_PGDATA_DIR:-guidant-pgdata}:/var/lib/postgresql/data

升級程式在指令前臨時帶環境變數蓋掉 .env 的值（upgrade_common.sh:52），不改任何檔案：

env GUIDANT_VERSION=1.27.10 GUIDANT_PGDATA_DIR=/srv/guidant-ai/pgdata-next \
    docker compose --env-file /srv/guidant-ai/.env -f <新版包>/docker-compose.yml \
    up -d guidant-db

起來後用 docker inspect 反查實際掛載來源，不是 pgdata-next 就拒絕跑 migration（程式註解：「掛錯就是直接改客戶現在那份資料，退回救不回來」）。migration 用新版 guidant-ai-init 映像起臨時容器，帶 GUIDANT_INIT_MODE=migrate、MIGRATE_APPLY=1（預設 0 只印不寫）；單支超過 10 分鐘沒進度判卡住、整次退回。189 這次：4 分 45 秒，migration 3/3。

升完名稱改回來（第 6 步，upgrade_switch.sh）

升級前   pgdata                  正式在用（1.27.9）
第 3 步  pgdata                  停著不動
         pgdata-next             複製出來的
第 4 步  pgdata-next             跑 migration，變 1.27.10
第 6 步  pgdata-prev-1.27.9      舊的改名成快照
         pgdata                  pgdata-next 改名回來，正式在用（1.27.10）

.env 改兩行：GUIDANT_PGDATA_DIR（資料庫掛哪）與 GUIDANT_VERSION（用哪版映像）。順序是先改 .env 再搬資料夾，每一步搬不動都把前面還原、.env 從 .env.upgswitch 放回。改名在同一顆磁碟是瞬間完成，不會再複製一次。路徑永遠叫 pgdata，.env、compose、維運指令都不用知道「現在是第幾代複本」。

清理映像清哪些

第 7 步 upgrade_cleanup.sh，三類：

• 映像：自家三顆（be、fe、init）凡是 tag 不等於「這次目標版」也不等於「升級前那版」的全部刪。第三方映像（postgres、redis、seaweedfs、bugsink、分類器）不動。
• 資料庫快照：pgdata-prev-* 只留這次留下的那一份；第一次升級留下的 volume 若已不是現用就刪。
• 更新包：incoming/ 留本次的 tar.gz、清單、ops 小檔；bundles/ 更早版本整個刪，本次解開的只留 agent/（Agent 推送要用），其餘大檔刪。

清理失敗不影響升級結果，只記警告，下次成功時再清。

升級 log 放哪、每步內容有沒有存、停機期間的紀錄怎麼回系統

三個地方：

• 主機逐行輸出：線上更新由 systemd 跑，每一行（停哪個容器、載哪顆映像、健康檢查打了什麼）在 journal：journalctl -u guidant-upgrade-order。migration 另落 /srv/guidant-ai/log/upgrade-migrate-<單號>.log。用 install.sh --upgrade 走的舊路徑才會寫 log/upgrade-<時間>.log。
• 機器讀的進度：/srv/guidant-ai/upgrade/upgrade-progress.json，每步的狀態、起訖時間、時限、摘要。
• 系統內的稽核紀錄：換接完成後，新版後端的每分鐘排程讀進度檔，把每一步各寫一筆 system_logs（事件碼 6239～6247，含花了幾秒與起訖時間）加一筆整次結果（6248，從哪版到哪版、誰觸發、成功或退回），只寫一次。停機期間後端沒跑所以寫不進去，這是「事後補登」。

診斷包收：db/system_logs.csv（近 24 小時全部等級，含上面十筆）、log/upgrade-*.log 與 install-*.log 最近三支、last-switch.json。缺口：線上更新的 journal 逐行輸出目前沒落檔、診斷包也沒收，原廠要看停容器到健康檢查那段細節仍要登主機。待開卡：runner 起跑時同步落一支 log/upgrade-<單號>.log。

進度檔放哪、完成後刪還是留

/srv/guidant-ai/upgrade/upgrade-progress.json，由主機升級程式寫，容器唯讀掛載。留著不刪，下次升級開跑時覆寫。留著的理由：更新中心頁與維護頁都讀它顯示最近一次結果；開機檢查靠它判斷上次有沒有收尾；退回也失敗時 guidantai recover 靠它知道該退到哪。

健康檢查實打哪些

第 5 步用複本起一顆新版後端（容器名 guidant-upgrade-api，不叫 guidant-api，前端導不過去），在容器裡打它自己 http://127.0.0.1:8000：

後三支回 401 才算過：代表路由存在、登入驗證有掛上；回 404 代表整組功能沒進新版程式。任一不過就不換接、自動退回。

侷限：只驗「程式起得來、路由齊全、資料庫連得上」，不驗業務資料是否正確。migration 把某張表資料改壞，這五支照樣會過（列入發現的問題）。

/srv/guidant-ai/backup 為什麼升級後沒有新檔；備份機制現況本輪不做

檔案沒有不見，是機制換了。backup/ 裡的 .sql.gz 是舊版 install.sh --upgrade（1.14 到 1.19 時期）每次升級前 pg_dump 出來的。三台現況：

FR-167 的升級流程改成「整個資料目錄複製、舊的留一代快照」，不再 dump。這個快照只為退回服務，下次成功就刪，不是備份。所以目前的事實是：

• 升級前有保護：複本上做、失敗退回、現用資料不動。
• 沒有定期備份、沒有異地備份、沒有手動備份指令（維運指令說明裡只給一行 pg_dump 範例）。

建議方案（等裁示後開卡）：升級第 3 步複製資料庫時順便 pg_dump | gzip 到 backup/，檔名帶版號與時間；加 guidantai backup 手動指令與每日排程；保留份數可設（建議 7）；物件儲存（證據檔）也要納入，不只資料庫；手冊補還原步驟。

• 私鑰保管與換電腦：主力章在決策者電腦、備用章離線封存是現行設計；換電腦就是把加密的私鑰檔搬過去（密碼另記）。要不要改成硬體金鑰或兩人保管，屬流程決定。
• 本體與 Agent 分開獨立更新、Agent 自己的更新中心：第二期範圍，牽涉更新站多一類成品、Agent 獨立版本線、Agent 主控台新頁。
• PostgreSQL 引擎大版升級：見 Q15，要另外設計。
• 三台主機指紋相同：更新站回報表顯示 188、189、190 指紋一樣，三台是同範本複製的 VM。不影響升級，影響統計與按指紋封鎖，要查指紋算法。
• 事件應變：見 Q7 補問 3。沒有入侵處置手冊、沒有 JWT 金鑰一鍵換掉的指令、沒有檔案完整性監控；加上 Q5／Q20 的備份一起規劃。
• 祕密存放三層方案：見 Q7 補問 2。手冊要求客戶全碟加密；我們改成密碼掛檔案不走環境變數（一張卡）；有 TPM2 的主機可選 systemd-creds。
• 2.0 的授權模式：見 Q12 補問。現行 D7 是「換代另購、重簽新授權」；決策者傾向「有買維護就能一直升」。兩種技術上都接得住，差在更新站的門比什麼（主版號相同／維護期內），等商業模式定了再調。不管哪種，主機端主版號檢查都要改成看授權。
• 資料庫快照的空間：快照平常佔一份與資料庫同大的空間，到下次升級成功才刪；升級第 3 步最多同時三份（現用、快照、複本），預檢會先擋空間不足。189 快照 687 MB，gzip 壓縮後約 127 MB。決策者擔心資料長大後很可觀。建議不壓縮（退回要先解壓、拖慢最需要快的時刻），改成：升級成功後保留 7 天自動刪、更新中心顯示快照佔多少與何時清；資料真長到幾十 GB 再改用 pg_dump 加壓縮，兼作備份，與 Q5／Q20 一起規劃。日誌表保留期限（見發現的問題）影響更大，應先做。
• 升級觸發改成客戶可選：見「執行流程」補問。網頁觸發主機 root 動作在部分企業規範會被擋；建議安裝時可選要不要裝監看器，關掉就只能 sudo guidantai upgrade，且升級不再自動打開。

• 主機端主版號檢查比的是「現行版」不是「授權主版號」（app/product_update/service/package_verifier.py:214）。後果：出 2.0.0 時就算客戶已重簽主版號 2 的授權，更新站看得到 2.0.0、也下載得到，主機端 verify_manifest 仍以 major_mismatch 拒裝，客戶永遠卡在 1.x 最後一版。現在只有 1.x 不會踩到，出 2.0 前必須改成「等於授權檔 product_major」（Q12 第 4 點已預告，尚未開卡）。修正由線上更新首腦 session 處理。
• 三台測試機主機層有不屬於產品的服務對整個網路開（188／189／190 實查 ss -ltn）：系統套件 redis-server 6.0.16 以 redis 使用者監聽 0.0.0.0:6379，NFS 的 111／2049 也對外，三台 ufw 皆 inactive。這個 Redis 不是產品的（產品 guidant-redis 不綁主機埠、走 TLS 加 ACL），是主機殘留套件，但跟服務住同一台；Ubuntu 套件版預設 protected-mode 擋遠端、無密碼，設定若被改過就是不用密碼進主機的門。測試機由首腦查處置；裝機手冊應要求客戶主機只開 22、80、443，install.sh 第 ① 步環境檢查可加「主機層有其他服務對外」的警告。
• 189 一顆 guidant-redis 容器的 compose 標籤仍指 /home/jedi/guidant-ai-1.27.7（實查 docker inspect 的 com.docker.compose.project.working_dir）；同台 fe 指 bundles/guidant-ai-1.27.9、sandbox 指 bundles/guidant-ai-1.27.8，三顆容器三個 working_dir。原因：第 3 步刻意不停 redis，所以它的 compose 標籤留在最早起它的那次（10/31 手動 install.sh --upgrade）。功能沒壞，但清 /home/jedi/guidant-ai-1.27.7/ 8.4 GB 前要先重建那顆 redis（照 10/31 誤刪 188 目錄的教訓）。建議第 6 步換接時把不停的三顆（redis、seaweedfs、fe）也用 up -d --no-deps 重掛一次 compose 標籤，或至少在手冊寫明。
• 老機器累的舊流程殘留沒人清：189 有 backup/ 410 MB、12 支舊式 upgrade-*.log、4 支 *.bak-*、/home/jedi/ 兩支舊 tar.gz 7.7 GB；190 有 Agent 舊映像 1.4.3～1.4.6 四顆 17 GB。新流程第 7 步只管自己產的東西。建議 upgrade_cleanup.sh 加一段「舊流程殘留」：backup/、backup-manual/、log/upgrade-<時間>.log 列出並提示可刪（不自動刪，客戶可能還想留 dump）；Agent 舊映像由 Agent 升級流程自己清。
• 190 docker-compose.yml 擁有者是 jedi 不是 root，189 同樣。應是手動操作留下的。功能不受影響，但資料目錄其他檔都是 root，升級第 6 步複製新 compose 時會不會因擁有者不同出問題要核一下。

2026-11-02 追加

另開卡，出貨前修 升級失敗時，真正的錯誤訊息進不了系統

失敗時 system_logs 只有各步驟腳本預先寫好的一句中文原因加退出碼（upgrade_runner.sh:91），例如「新版後端啟動後就結束了，見 docker logs guidant-upgrade-api」。程式或系統噴出的錯誤原文一樣都沒有，管理員與原廠無從判斷錯在哪。實查錯誤輸出的去向：

建議：①主機升級程式所有輸出（含每個指令的錯誤輸出）完整落檔 log/upgrade-<單號>.log，拿掉丟到 /dev/null 的寫法；②受檢容器失敗時先把 docker logs 存檔再刪；③進度檔加欄位放失敗那一步錯誤原文最後 50～100 行，後端回寫成一筆 error 等級 system_logs，正常步驟維持 info；④以上檔案全收進診斷包。界線：錯誤原文寫入前過遮罩；維護頁（免登入）只顯示一行摘要，原文只放登入後的系統紀錄與診斷包。②是最該先修的一個。

健康檢查不驗業務資料

第 5 步只驗「新版程式起得來、路由齊全、資料庫連得上」（見 Q19 更正）。migration 把某張表資料改壞，健康檢查照樣會過。可考慮第 4 步 migration 後加幾個關鍵表的筆數比對或 PostgreSQL 完整性檢查。

api_logs_old、system_logs_old 殘留表該刪

9/28 2026-09-27-fr121-log-act-time-timestamptz.sql 把日誌表改時區格式時，舊表改名 _old 留一版，註解寫「下一版 migration 再 DROP」，但一直沒寫那支。189 唯讀實查：

決策者裁「沒用，直接刪」。建議由首腦開卡寫一支 migration DROP TABLE IF EXISTS public.api_logs_old, public.system_logs_old CASCADE; 走正常出版流程，所有環境升級時自動清掉；不在 POC 手動下指令。

日誌表沒有自動清舊月份

189 資料庫 586 MB，前 8 大表全是 system_logs、api_logs 月分區（合計約 490 MB），8 月的分區還在。分割 migration（2026-06-03-log-tables-partitioning.sql）寫了 maintain_log_partitions() 維護函式，但註解寫「排程未接」。資料量長大的主因是這兩張表，跟升級複製、快照佔空間直接相關。要查清楚目前有沒有排程在呼叫它，沒有就接上，可與上一條同一張卡。

升級觸發機制的四個實作缺點

• 客戶停用後會被重新打開：客戶 systemctl disable --now guidant-upgrade-order.path 後，下次升級第 0 步無條件 enable --now（lib/systemd_units.sh:62），推翻客戶主機管理員的決定。出貨前修。
• orders/ 權限借用主機 uid 1000 的帳號：群組是 uid 1000，189 上是 jedi（有 sudo 的登入帳號），客戶主機通常是第一個管理員。此人不經網頁、不經權限檢查就能丟單。包仍要簽章驗得過，拿不到任意 root 指令，但邊界不乾淨。建議改用專屬系統群組。
• 安裝時沒告知：install.sh 不印裝了哪三支 systemd 服務，手冊只有一行。建議安裝與升級時印出檔名與用途，手冊先決條件段列出。出貨前修。
• 寫不進 systemd 時整個安裝中止：self_replace.sh:181 失敗會讓 install.sh 中止，而不是只少線上升級。建議改成警告，印清楚「線上升級與開機自動退回不可用，請用 sudo guidantai upgrade」。

另：guidantai uninstall 不會 systemctl disable、不刪 /etc/systemd/system/guidant-upgrade-* 三支，也不刪 /etc/guidant/release-keys/。

進度檔對外人可讀到版本號與帳號名稱

維護頁免登入讀 /upgrade-progress.json，內網任何人可得知現行版本、升到哪版、何時、requested_by 帳號名稱；沒升級時檔案也在，看得到上一次紀錄。寫入方只有主機 root，從網頁改不了（nginx 只讀、三顆容器對 upgrade/ 皆 rw=false、檔案 644 root）。建議：進度檔不寫帳號名稱；nginx 只在升級進行中才回這個檔，平時 404。

失敗退回後的日誌回寫還沒在真環境驗過

程式邏輯：失敗退回後由舊版後端每分鐘排程照抄進度檔，寫每一步加第 8 步「自動退回」（6247）與整次結果（6248）。189 三次升級全成功；190 唯一一筆 failed（10/30，1.27.0 → 1.27.1）發生在 1.27.9 補寫功能上線前，7 天內無 6247／6248。建議在 190 故意讓健康檢查失敗跑一次驗證。