需求討論稿：為什麼這樣決定

D22 先通知，管理員確認後才下載（跟 iPhone 一樣）

系統每天只問「有沒有新版」，拿回的是幾 KB 的版本資訊，不下載。管理員按「下載」後才開始下載 2.9GB；下載時服務照常，下載完驗過簽名才算就緒。不先下載的理由：客戶不一定要升這一版，先下載會白佔頻寬與硬碟。

D23 離線更新：管理員自己上傳

連不到外網的客戶，我們把更新包交給客戶，管理員在更新中心「離線更新」上傳。上傳後從驗簽名開始，跟線上下載完全同一條路。

D24 記錄是誰更新的

每一次更新都記：誰按的下載、誰按的更新（主系統帳號與名稱、時間、立即或排程）、誰取消的；若是 IT 在主機上手動執行或用 guidantai recover，記主機登入帳號（由指令寫進進度檔）。主系統走既有稽核事件；指令這邊寫在進度檔，主系統恢復後同步回稽核紀錄。更新中心的更新紀錄表每一列都顯示操作人。

D13 客戶機上由 guidantai upgrade 換版，主系統不碰 docker

主系統跑在容器裡，換不掉自己。換版的是裝機時已經放在主機上的 guidantai 指令（bash，/usr/local/bin/guidantai，隨出貨包更新），用 root 跑。主系統容器沒有 docker 權限，只負責通知、下載、驗簽名、顯示、寫一張更新單；能停容器、換版本的權限等於整台主機的最高權限，不交給對外的網頁服務。

D19 跑到一半的工作：等它做完，永遠不強制停

更新開始先停止接新工作，等進行中的證據分類、檢測派送做完。超過 30 分鐘還沒完，通知管理員「還有 N 筆在跑」，繼續等。等到維護時段結束還沒完，這次就不更新：什麼都沒動，恢復接新工作，通知管理員改約時間。理由：等待發生在服務停掉之前，放棄更新等於什麼事都沒發生，最壞只是延期；而半夜排程沒人能回答「要不要強制停」，延期是系統唯一不會傷到東西的決定。

D20 不做救援頁，不開第二道門

一個能退回、能重啟容器的網頁，等於拿著主機最高權限，又開在另一個埠、用另一組裝機時產生的固定密碼——對外就是多一道門，而管理埠正是攻擊者最愛掃的目標。它原本要解的情況，幾乎都已經由「時限＋自動退回＋開機檢查」自動處理；剩下真的要人出手的，走客戶本來就有的主機登入（guidantai recover）。詳見 §7。

D21 不做常駐的更新助手；執行者就是 guidantai upgrade，由 systemd 觸發

不新增容器、不新增獨立執行檔、不給任何容器 docker 權限。主系統寫更新單，主機上一個 systemd 檔案觸發器（兩個十行的設定檔）看到更新單幾秒內就呼叫 guidantai upgrade，排程的話到點才叫——Debian 的自動安全更新就是這個形狀。install.sh 本來就要求主機有 systemd、本來就在主機上裝 guidantai，所以這不是新成本。GitLab Runner、Ansible 這類現成工具能代勞的只有「等到時間、把腳本跑起來」這件小事，代價卻是客戶主機上多一條我們能下任意指令的通道，不划算。

D25 服務停掉之後不給取消鈕，靠時限自動判失敗、自動退回

服務停掉之前（下載中、等工作做完）隨時能取消，什麼都沒動。服務停掉之後（複製資料庫、升級、健康檢查）每一步各有時限（見 §5），任何一條觸發就自動退回，管理員不用按任何東西，最多等到時限就有結果。不給取消鈕的理由：那幾分鐘資料庫是停的，網頁沒辦法確認按的人是不是管理員，要做就得另發票或另開一道門；為了提早幾分鐘退回不值得。真要在這幾分鐘人工介入，IT 在主機敲 guidantai recover。

D26 沒有「敲指令」這件事：有「系統更新」權限的人在畫面上按

權限系統加一個「系統更新」能力，預設給系統管理員，可以另外授權。按「立即更新」或選排程時間後，主系統只做一件事：在主機上寫一張更新單（版本、時間、誰按的）。主機上的 systemd 檔案觸發器看到更新單就呼叫 guidantai upgrade，排程的到點才叫。主系統拿到的權限只有「寫一個檔」。指令本身仍在，IT 想手動跑也可以，當備援。

D14 失敗處理：開放使用前一律退回；開放使用後不退回，發修正版

開放使用那一刻是唯一的「不可退回點」。在那之前資料沒有變過，退回不掉資料；在那之後退回一定會丟掉這段時間的新資料。

D15 下載要管理員確認；更新要有「系統更新」權限的人按，可立即也可排程；任何版本都不自動裝

更新會停機、會改功能，時間由客戶挑；客戶不更新是客戶的事。D28 說明為什麼連安全修正也不自動裝。

D16 Agent 先推 1 台，正常再推其餘

Agent 失敗只影響那 1 台，主系統不受影響。Agent 版本永遠不比主系統新。

D17 必經版本只有三種情況才設

資料要分兩步搬、基線重整、升級流程本身改了。寫 migration 的人在 manifest 標記，封包時自動算出「從哪版可直升」寫進更新包；CI 用比必經版本更舊的庫試升必須被擋、用必經版本的庫試升必須成功。

D18 資料不掉的做法：在複本上升級

詳見 §6。

D2 更新站與授權中心分開

授權中心可能不對客戶開放；更新來源與簽發站合在一起，攻破一個等於兩個都破。客戶出示本機簽好的授權檔，更新站用授權中心的公鑰驗，不連授權中心、不存客戶名單。

D7 授權過期的客戶仍可升到同一個主版號的最新版；換主版號（2.0）要重新授權

授權擋的是「能用什麼」，不是「能裝什麼」：產品現在就有這道門，授權過期系統進唯讀、模組照授權檔鎖。過期客戶升到最新版，拿到的是一套唯讀的最新版，新功能照樣鎖著，我們沒有少收錢；而過期客戶的系統還在跑、還連著網路，有洞不補對雙方都是風險。所以更新站不看授權到期日，只看兩件事：這是不是一台合法安裝的機器（本機授權檔由授權中心簽過）、有沒有在拒絕名單。主版號是唯一的範圍限制：授權檔簽的是「1.x」，出 2.0 時過期客戶就停在 1.x 的最後一版，這是買斷軟體「含同代升級、換代另購」的常見做法（JetBrains、Sublime、Beyond Compare）。現在只有 1.x，這條規則目前零成本，先寫下來免得出 2.0 再吵。詳見 §10 CRA。

D27 只維護最新版；安全修正就是發下一版；五年支援靠「永遠可以免費升到最新版」達成；要找懂 CRA 的人確認兩題

我們每一版都是修正加功能混著出，從沒出過「只修安全」的版，以後也不打算分：有洞就修、修完出下一個版號，release note 寫明是安全修正。舊版的洞靠「免費升到最新版、升級保證資料不掉」解決，不另外維護舊版本線。「五年支援」寫成「五年內永遠有一條免費、不掉資料的路徑升到有修正的版本」。要拿去問懂 CRA 的人的兩題：①我們到底受不受 CRA 管（客戶在台灣、產品沒賣進歐盟的話整節 §10 可以拆掉）；②若受管，「單一版本線、安全修正與功能一起出、新功能由授權鎖」這種寫法是否滿足「安全更新與功能更新分開提供」那條（CRA 原文有「技術上可行時」的但書）。CRA 主要義務 2027 年 12 月適用，design 定案前先問。

D28 一律人按，不做自動安裝；安全修正也不例外

決策者裁示：「絕對不要自動裝，客戶不更新是他的事。」理由站得住：落地企業軟體更新要停機、客戶有自己的維護時段、裝了出事是客戶的 IT 要收拾，GitLab、Jira、Sentry 這些自架產品也都不自動裝；而且我們沒有「只修安全、不動資料庫」的小版（D27），每一版都可能帶 migration，自動裝的風險跟功能版一樣大。CRA 那條原文是「適用時」才要預設自動裝，CRA 文件寫一段「本類產品不適用自動裝」的理由即可（併進 D27 第②題一起問）。代價：有洞的客戶拖著不升，我們只能在更新中心一直提醒，不能替他按。

D29 每一版的更新包至少保留 10 年

CRA 第 13 條第 9 項要求安全更新至少 10 年可下載；我們不分安全版，所以每一版都留。放 R2，一年十幾版也才幾十 GB，費用可以忽略。

D30 升級指令開跑第一步先換成新版的自己，再跑剩下的步驟；畫面上不顯示指令版本

主機上的 guidantai 是裝機時從出貨包複製到 /usr/local/bin/ 的，客戶跑 1.24.1 時那支指令也是 1.24.1 版。新版的升級流程（複本升級、每步時限、自動退回）寫在新版指令裡，舊指令不會做。所以 guidantai upgrade 第一件事是從已驗過簽名與雜湊的新更新包取出新版指令、換掉 /usr/local/bin/guidantai、再以新版接著跑；之後每次升級跑的都是「目標版本的升級流程」，舊版指令只要會「驗包、換自己」就夠（GitLab omnibus、Docker installer 都這樣）。代價：第一期出去那版指令要把「換自己」這一步做對，之後才不會再卡；換自己失敗就當預檢不過，什麼都不動。這是指令內部的事，更新中心頁不顯示「指令版本」「相容」之類的欄位，客戶不需要知道有這支指令。

D31 發布清單 90 天有效，過期重新蓋章；不做「回應 24 小時內」

更新站手上沒有私鑰（D3），簽章是決策者發版時離線蓋的，更新站只是原樣轉交，沒辦法對每次回應重新簽時間。所以「回應超過 24 小時拒收」做不到。改成清單本身帶簽發時間與有效期 90 天，客戶端超過就拒收；一版發出去 90 天內沒下一版，決策者跑一次 guidant-release publish 重新蓋章延長。這是 TUF 的 timestamp 角色的簡化版：防的是有人把過期的舊清單一直餵給客戶讓他升不上來，90 天是「被卡的最長時間」。

D1 更新包放在 S3 相容的私有空間，用 Cloudflare R2

程式只認 S3 介面，換供應商改一個網址。R2 對外下載流量不收費：客戶每次更新抓 2.9GB，放別家每出一版都要付一次流量費。

D2a 更新站跑在 Cloudflare Worker，先用免費方案

更新站是我們這邊唯一對客戶開放的服務：回答「有沒有新版、你能不能拿」（合法安裝、不在拒絕名單、同主版號）、產短效下載網址、收客戶回報的版號。對外服務最花的是守機器的人力，不是寫程式的時間；R2、弱點資料網域、文件站都已在 Cloudflare，多開一個功能不多一家帳務。先用免費方案（每天 10 萬次請求，我們一天不到 100 次），跑一段時間再看要不要升付費方案（每月 5 美元）或改成自己養一台。代價：驗章要改呼叫 Cloudflare 的加密函式，多一份驗章實作，用授權中心真簽出來的檔當守衛測試。排除：跟授權中心同一台（D2）、自己養一台對外主機（長期要守）、完全不寫程式只在 R2 放清單檔（做不到 D6、D9、D12）。

D3 發版的最後一步在決策者電腦蓋章；發布印章一正一備，跟授權中心的印章分開

更新包要帶一個只有我們蓋得出來的印章（Ed25519 簽章），客戶系統用程式裡的印樣（公鑰）對章，對不上整包丟掉。CI 在 188 出包、上傳 R2、在更新站登記成「草稿」，客戶看不到；決策者在自己電腦跑 guidant-release publish <版> 蓋章，才變「已發布」。印章（私鑰）只在決策者電腦，188 被攻破的人出得了包、發不了版——這是「上版要決策者明示放行」鐵律的程式化。

印章怎麼保護、怎麼換（業界標準做法，TUF、apt、Android 系統更新都這樣）：

• 一開始刻兩顆：主力那顆放決策者電腦，備用那顆產完就封存放別處，不在任何電腦上。產品出貨時兩顆的印樣都帶著。
• 每顆印章有編號，發布清單寫「這版是幾號印章蓋的」，客戶系統拿對應編號的印樣對章；沒那個編號直接判驗證失敗。主產品驗授權檔已經是這樣做（PUBLIC_KEYS 以 kid 認公鑰），照搬。
• 換印樣只能藏在一次「對章通過」的更新裡：用客戶現在認的印章蓋一版包，包裡印新印樣；客戶系統先拿手上的舊印樣對章，對得上才裝、裝完才收下新印樣。包裡的印樣在對章失敗那一刻跟整包一起被丟掉，進不了門。更新站、R2、管理員畫面都不能換印樣。
• 新舊印樣重疊一版：換印樣那版裝完客戶兩個都認，下一版才拿掉舊的，中間漏一版的客戶也認得。
• 主印章丟了或被偷：拆封備用印章，發一版宣告舊印章作廢、帶一顆新的備用印樣。已經裝好的舊版完全不受影響，對章只發生在下載新版那一刻。
• 兩顆都丟了，才需要人到客戶那邊重裝，所以備用那顆不跟主印章放同一台電腦。
• 很久沒更新的客戶，中間我們換過兩次印章，先裝換第一次印章那版再往上升，就是必經版本規則（D17），不另外做東西。

D6 不做頻道；草稿可以指定給幾台內部機器先裝

本意是 STG、POC 比客戶早拿到新版當白老鼠。頻道是給客戶看的概念，但客戶永遠只該看到正式版；改成草稿在後台指定「哪幾台機器看得到」，一個欄位解決，後台也少一欄。

D8 不做差異更新；D9 客戶只回報授權編號、機器指紋、現行版號、最近一次升級結果；D10 每天檢查一次、管理員可關；D11 客戶出示本機授權檔、更新站用授權中心公鑰驗

四項在流程表（§5）、安全原則（§11）與 D2 已寫定，這裡只登記。D10 補一句：每日檢查是唯一的開關；關了會在更新中心一直顯示提醒。

D12 拒絕名單，第一版決策者在更新站後台手動加

授權過期也能升同主版號最新版（D7）之後，拒絕名單只剩「我們主動要切斷某客戶」這一種情況，不常用，不值得自動化。