---
title: FR-167 定版交付 — 線上更新現在長什麼樣
brand: Guidant AI · **FR-167** 線上更新
eyebrow: 定版參考文件 · 只寫現況 · 2026-11-01
h1: ▸ 線上更新的最終長相
subtitle: 客戶主機怎麼拿到新版、怎麼升、失敗怎麼回來；原廠怎麼發版；Agent 怎麼跟進
lede: 這頁是 FR-167 的**定版交付**——只回答「現在長什麼樣」。要看「為什麼這樣決定」去 design.md 與 discussion.md；要看每個部件的細節去下方十份技術規格；要看「哪一棒做了什麼」去 handoff/。**本頁不記沿革、不 append 進度**，內容變了就整段改寫。
chips: [{text: 主系統 1.27.10, kind: ok}, {text: Agent 1.4.8, kind: ok}, {text: 更新站已上線, kind: ok}, {text: 正式章未啟用, kind: warn}, {text: 定版參考, kind: accent}]
footer: 本頁只描述現況。決策理由見 design.md，逐棒紀錄見 handoff/fr167-LOG.md 與 git log。
---

## 一句話 {#tldr nav="一句話"}

**客戶主機每 6 小時問一次原廠更新站有沒有新版；有就通知管理員，管理員按下載、系統驗章，有權限的人按「立即」或排程；升級在資料庫複本上做、每步有時限、失敗自動退回，現用那份資料從頭到尾沒動。** 原廠那邊：CI 出包登記草稿，決策者在自己電腦蓋章才算發布；更新站只轉交簽好的清單，沒有私鑰。主系統升完可以勾選讓 Agent 跟著升，先一台再其餘。

## 交付物現況 {#deliverables nav="交付物"}

| 部件 | 在哪 | 現況（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 失敗）。

## 規則 {#rules nav="規則"}

- **版本只有一種**：修正與功能混著出、只維護最新版、安全修正就是發下一版；任何版本都**不自動裝**。
- **授權管能用什麼、不管能不能裝**：授權過期仍可升同主版號最新版；換主版號要重新授權。
- **升級不可中途取消**：服務停掉之前取消等於沒發生；停掉之後每步有時限，失敗自動退回更新前。
- **主機不多任何常駐程式、不開新埠**：主系統只寫更新單，systemd path 看到才呼叫 `guidantai upgrade`。
- **客戶端不信任更新站**：只信 `/etc/guidant/release-keys/*.pub`；驗簽章→kid→版號遞增→主版號→sha256 四道（清單**不設有效期**）。
- **Agent 跟進可選**：「更新到 X」確認視窗預設勾「接著更新 Agent」、可選台；不勾之後在 Agent 區自己推或排程，另有「稍後提醒」7 天。
- **停機時間不寫數字**：畫面與文案寫「升級期間將看到維護頁」。

## 怎麼用 {#howto nav="怎麼用"}

| 你是誰 | 看哪份 |
|---|---|
| 客戶管理員：想知道畫面怎麼按 | 手冊 `docs/user-manual/onprem/05-upgrade-rollback.md`、`agent/07-upgrade.md` |
| 原廠：要發一版 | [發版操作手冊](release-runbook.html) |
| 原廠：升級失敗要救 | [主機升級程式](upgrade-runner-spec.html)「退回與 recover」段、手冊 5.7 |

## 這一輪沒做完的 {#remaining nav="沒做完的"}

| 沒做完 | 白話 | 誰接 |
|---|---|---|
| 正式出版路徑 | 正式章還沒產（`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 {#downstream nav="延伸 FR"}

| FR | 在做什麼 | 為什麼長出來 | 狀態 |
|---|---|---|---|
| [FR-171](../FR-171-2610-agent-command-channel/) | 主系統↔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。

## 這份文件的定位 {#scope nav="本頁定位"}

| 你想知道 | 看哪份 | 性質 |
|---|---|---|
| 現在長什麼樣 | 本頁 | 定版 |
| 主機升級程式每一步做什麼、時限、進度檔、退回 | [主機升級程式](upgrade-runner-spec.html) | 技術規格 |
| 更新單、Agent 跟進列、進度檔的狀態與轉移 | [狀態機](state-machines-spec.html) | 技術規格 |
| 四條主要流程誰打誰、要多久 | [循序圖](sequence-diagrams-spec.html) | 技術規格 |
| 主系統更新中心端點、status 形狀、錯誤碼、事件碼 | [更新中心 API](update-center-api-spec.html) | 技術規格 |
| Agent 怎麼被推、怎麼升、怎麼回報 | [Agent 跟進](agent-rollout-spec.html) | 技術規格 |
| 更新站 Worker 架構、端點、跨版路徑、R2 | [更新站規格](update-site-spec.html) | 技術規格 |
| 更新站七張表 | [更新站資料表](update-site-schema-spec.html) | 技術規格 |
| 信封格式、金鑰、CLI、客戶端驗證、威脅 | [發布簽章](release-signing-spec.html) | 技術規格 |
| 原廠怎麼出包、簽章、發布、升三台 | [發版操作手冊](release-runbook.html) | 操作手冊 |
| 為什麼這樣設計、D1～D31 | [設計文件](design.html)、[討論稿](discussion.html) | 設計（定稿凍結） |
| 整體架構圖 | [架構圖](diagrams/architecture.svg)、[更新站架構圖](diagrams/update-site.svg) | 圖 |
| 給 PM／主管看的 | [PM 簡報](briefing/pm-deck-2026-10-31.html)、[機制問答](briefing/mechanism-qa-2026-11-01.html) | 簡報與問答 |
| 畫面長什麼樣 | [互動雛形](prototype/index.html) | 雛形 |
| 哪一棒做了什麼、為什麼推翻 | [交接現況](handoff/fr167-STATE.html)、[逐棒紀錄](handoff/fr167-LOG.html) | 交接 |
| 頁面行為規格、使用者手冊 | SPEC `system-admin/product-update.md`、手冊 `onprem/05`、`agent/07` | SPEC／手冊 |