定版參考文件 · 只寫現況 · 2026-11-01
客戶主機怎麼拿到新版、怎麼升、失敗怎麼回來；原廠怎麼發版；Agent 怎麼跟進
這頁是 FR-167 的定版交付——只回答「現在長什麼樣」。要看「為什麼這樣決定」去 design.md 與 discussion.md；要看每個部件的細節去下方十份技術規格；要看「哪一棒做了什麼」去 handoff/。本頁不記沿革、不 append 進度，內容變了就整段改寫。
客戶主機每 6 小時問一次原廠更新站有沒有新版；有就通知管理員，管理員按下載、系統驗章，有權限的人按「立即」或排程；升級在資料庫複本上做、每步有時限、失敗自動退回，現用那份資料從頭到尾沒動。 原廠那邊：CI 出包登記草稿，決策者在自己電腦蓋章才算發布；更新站只轉交簽好的清單，沒有私鑰。主系統升完可以勾選讓 Agent 跟著升，先一台再其餘。
| 部件 | 在哪 | 現況（2026-11-01 實查） |
|---|---|---|
| 主機升級程式 | 主系統包內 guidantai＋lib/，裝到客戶主機 /usr/local/lib/guidant/ |
upgrade／recover／diag／upgrade-host；第 0～7 步＋失敗第 8 步退回；三台都在跑 |
| 主系統更新中心 | BE app/product_update/、FE src/views/product-update/ |
檢查、下載、預檢、立即／排程、離線上傳、更新紀錄、診斷包、Agent 區；能力點 system.product-update.read／update |
| 更新站 | Cloudflare Worker＋D1＋R2，update-center repo |
已上線 guidantai-update.jedicotech.com；D1 七張表；已發布 1.27.1～1.27.10 共十版 |
| 發布工具 | update-center/cli/guidant-release |
init-keys／publish／withdraw／rotate-key／register-draft 可用；正式路徑尚未走過一次（見「沒做完的」） |
| 發布簽章 | 信封 v2、Ed25519、kid 查公鑰表 | 現用測試章 b91819f86eb4b4f8（公鑰在 scripts/installer/release-keys/）；正式章未產 |
| Agent 跟進 | BE agent_rollout_service、Agent guidant_agent/sync/ 與 scripts/install/lib/upgrade_order.sh |
主系統推送→主動通知→Agent 下載驗章→主機升級單六步→回報主系統與更新站；只支援 docker compose 形態 |
| 離線路徑 | 更新中心「離線上傳」收單一檔 | 原廠用 make_offline_bundle.sh 產，客戶上傳走同一條驗證 |
| 環境 | 主系統 | Agent |
|---|---|---|
| 190 測試機 | 1.27.8 | 本機一台 1.4.7 |
| 188 STG | 1.27.8 | — |
| 189 POC | 1.27.10（線上升級） | 121＝1.4.8（線上推送成功）、60.167＝1.4.7（推送失敗，原因磁碟不足，已清） |
更新站 D1 現況：product_releases 十版 published；instance_version_reports 三台各一列；agent_version_reports 兩列（121 成功、60.167 失敗）。
guidantai upgrade。/etc/guidant/release-keys/*.pub；驗簽章→kid→版號遞增→主版號→sha256 四道（清單不設有效期）。| 沒做完 | 白話 | 誰接 |
|---|---|---|
| 正式出版路徑 | 正式章還沒產（init-keys 要決策者在自己電腦跑、章放哪台未裁）；CI register-draft 與 publish 不帶維運小檔的 ops_sha256／ops_size（D1 無欄）；從推 tag 到 publish 沒走通過一次。十版都是測試章直接寫 D1 |
出貨前另開卡 |
| 更新站後台 Agent 三欄永遠 0 | 拿 Agent 版號比主系統版號，永遠不相等 | 等 FR-172 |
重試鈕對 failed＋unchanged 回 412 |
前端顯示重試、後端不收這組合 | 下一版 |
| 升級換接後 redis／seaweedfs／bugsink 的 compose 標籤仍指舊目錄 | 刪舊目錄會讓下次 compose 操作變孤兒 | 下一版 |
| Agent 升級結果靠心跳回報，最晚 5 分鐘 | 已裁「不再用心跳帶訊息」 | FR-171 |
| 更新站自動檢查開關 | BE 有 PUT /auto-check，FE 沒接 |
收尾裁留或拔 |
| e2e 頁物件 | 程式已寫、未實跑 | 暫緩 |
| 1.27.11 結案出包 | 批 32 修正（磁碟預檢、錯誤原因、清舊映像、SeaweedFS 上限、8 格欄位）已合回主線，未出包 | 等 FR-171／172 一起出 |
| FR | 在做什麼 | 為什麼長出來 | 狀態 |
|---|---|---|---|
| FR-171 | 主系統↔︎Agent 通訊重整：指令直推 8443、心跳只表存活、憑證自動換、守門收斂 | 本案 Agent 跟進把指令與結果塞進心跳，推送最長等 5 分鐘、結果晚 5 分鐘回；決策者裁「不再用心跳帶訊息」 | 討論中 |
| FR-172（待開） | Agent 獨立更新：包分開出、更新站多一條 Agent 版本線、R2 分路徑、Agent 主控台自己有更新頁、相容矩陣兩向 | 修一個 Agent bug 得連主系統整包重出、客戶先停機升主系統才推得到 Agent | 需求紀錄在 docs/draft_requirement_spec/2026-11-01-agent-independent-update.md，與 FR-171 同一討論週期 |
閱讀順序：先看本頁 → 要改通訊看 FR-171 → 要改 Agent 出包看 FR-172。
| 你想知道 | 看哪份 | 性質 |
|---|---|---|
| 現在長什麼樣 | 本頁 | 定版 |
| 主機升級程式每一步做什麼、時限、進度檔、退回 | 主機升級程式 | 技術規格 |
| 更新單、Agent 跟進列、進度檔的狀態與轉移 | 狀態機 | 技術規格 |
| 四條主要流程誰打誰、要多久 | 循序圖 | 技術規格 |
| 主系統更新中心端點、status 形狀、錯誤碼、事件碼 | 更新中心 API | 技術規格 |
| Agent 怎麼被推、怎麼升、怎麼回報 | Agent 跟進 | 技術規格 |
| 更新站 Worker 架構、端點、跨版路徑、R2 | 更新站規格 | 技術規格 |
| 更新站七張表 | 更新站資料表 | 技術規格 |
| 信封格式、金鑰、CLI、客戶端驗證、威脅 | 發布簽章 | 技術規格 |
| 原廠怎麼出包、簽章、發布、升三台 | 發版操作手冊 | 操作手冊 |
| 為什麼這樣設計、D1～D31 | 設計文件、討論稿 | 設計（定稿凍結） |
| 整體架構圖 | 架構圖、更新站架構圖 | 圖 |
| 給 PM／主管看的 | PM 簡報、機制問答 | 簡報與問答 |
| 畫面長什麼樣 | 互動雛形 | 雛形 |
| 哪一棒做了什麼、為什麼推翻 | 交接現況、逐棒紀錄 | 交接 |
| 頁面行為規格、使用者手冊 | SPEC system-admin/product-update.md、手冊 onprem/05、agent/07 |
SPEC／手冊 |
