↑ 需求首頁 ⌂ 需求中心

FR-167 線上更新：機制問答接手說明（給 QA session）

這個 session 只負責回答決策者對線上更新機制的提問，並把問答整理成文件。 修程式、出包、發布、合回、改 STATE 由另一個 session（線上更新首腦）負責，這裡不做。

§1

你是誰、能做什麼

  • 角色：FR-167 機制問答。決策者會在這裡連續問「某件事是怎麼運作的」，要能對回程式碼那一行回答。
  • 可以做：讀 repo、grep、讀 DB（SELECT）、ssh 唯讀查三台主機與 Agent（docker ps／logs／exec ... cat）、查更新站 D1（wrangler d1 execute --remote 只下 SELECT）、改本資料夾 briefing/ 底下的問答文件。
  • 不要做：改程式、commit 程式、出包、發布、改 STATE／LOG、寫入任何主機或資料庫、碰 STG（188）／POC（189）的狀態。發現 bug 就寫進問答文件的「發現的問題」段並告訴決策者，由首腦 session 處理。
  • 回答紀律（決策者明確要求過）：一題一答，先結論再事實；每個說法對回程式碼或實查結果，不憑印象、不照簡報措辭；查不到就說查不到。白話、繁體中文。
§2

昨天的問答在哪

產出 位置 說明
PM 簡報（10 張） https://claude.ai/artifact/1HqiRVDJkGsJCsKeGiEBfU ；原檔已存 briefing/pm-deck-2026-10-31/project/ 給 PM 的機制總覽：做了什麼、架構、出版流程、簽章、五項驗證、升級八步、狀態、資料不掉、服務架構
機制問答報告 https://claude.ai/artifact/AmUhtjZVptzoqExGEUhjhx ；最新版存 briefing/mechanism-qa-2026-11-01.html 回答 2026-10-31 PM 會議 23 條提問中的機制題：Q5～Q9、Q11～Q20，加文末「待討論」四條

機制問答報告目前有：Q6 安裝做什麼與帳號權限、Q7 密碼與金鑰存放與輪換、Q8 發版腳本與最小版本、Q9 一條指令打一次密碼、Q11 15 分鐘下載網址、Q12 跨主版號、升級接力圖（sequence 圖加逐步表加主管四問）、Q13 複製資料庫、Q14 快照存哪、Q15 停什麼與 PG 大版缺口、Q16 清理清哪些、Q17 升級 log 與 system_logs、Q18 進度檔、Q19 健康檢查、Q5／Q20 備份現況。

決策者對報告的修改紀錄（不要改回去）：

  • Q8 的「現況打折」段已拿掉（2026-11-01）。
  • 頁面固定亮色單一主題，不跟系統深色（暗色下 mermaid 看不見）。
  • 流程圖用 mermaid sequenceDiagram＋autonumber＋階段橫條，跟 discussion.md 圖 1 同一組配色；決策者要「看得出順序、有 1、2、3」。
§3

今天（2026-11-01）新增的已查實事實

這些已對過程式碼或實機，回答時可直接用，不必重查：

  1. 「有沒有新版」只看版號：更新站、主系統、主機預檢三處都是 semver 逐段比數字（1.27.10 正確大於 1.27.9）。同版號重編不會被當新版；主機 guidantai upgrade --force 可同版重跑，但更新中心畫面走不到。
  2. 升級中誰接手畫面：前門容器 guidant-fe（nginx）全程不停。第 3 步停 api／worker／socketio／db；nginx 送首頁前用 auth_request 探 /api/1.0/version，探不到就 error_page 502 503 504 =503 /maintenance.html。維護頁 JS 每 3 秒 GET /upgrade-progress.json，nginx 直接 alias 到唯讀掛載的主機進度檔，不經後端。
  3. 後端單支 API 回 502 不會讓使用者跳維護頁：只有更新中心頁在「已送出／升級中」狀態、輪詢拿到閘道錯誤才整頁 reload；平時 XHR 拿到 503 只當錯誤顯示。（nginx 會把 API 的 502 改寫成 503 加 HTML，排錯時少一層資訊，可列待討論。）
  4. 主機怎麼接單：systemd guidant-upgrade-order.path 監看 /srv/guidant-ai/upgrade/orders/，有檔就起 guidant-upgrade-order.service 執行 guidantai upgrade --from-order（root）。後端只寫單檔、不碰 docker。
  5. 升級 log：線上更新的逐行輸出在 systemd journal（journalctl -u guidant-upgrade-order）；只有第 4 步 migrate 另落 log/upgrade-migrate-<單號>.log。log/upgrade-<時間>.log 只有舊路徑 install.sh --upgrade 才寫。缺口：診斷包沒收 journal，線上升級停容器到健康檢查那段細節要登主機（首腦 session 待開卡）。
  6. system_logs：換接後新版後端每分鐘排程把進度檔每步補寫一筆（事件碼 6239～6247）加整次結果（6248），只寫一次。189 在 2026-11-01 09:42:42 已實際寫入十筆。不在「操作日誌」頁（那頁讀 api_logs，是 HTTP 請求流水）。
  7. 診斷包：db/system_logs.csv 收近 24 小時全部等級（不只錯誤），升級那十筆在內；另收 log/upgrade-*.log、install-*.log 最近三支與 last-switch.json。超過 24 小時才匯，csv 那十筆就不在了。
  8. Agent 升級結果回報更新站：主系統 1.27.9 起，每分鐘撿已結束、未回報的 Agent 推送紀錄，用主機授權代送 POST /v1/report target=agent，更新站寫 agent_version_reports。送到才記已回報，送不到隔分鐘重試，太久放棄。2026-11-01 前沒有新版 Agent 可推，真環境還沒驗過。
  9. Agent 檢測 Profile：主系統每次心跳帶現行 Profile 清單，Agent 背景拉到 /data/content/cache/<file_uid>/v<版>/；121 上 8 支 TWGCB 都在。1.27.10／Agent 1.4.8 起心跳多帶 tool、name，Agent 主控台 CINC／GCB 的 Profile 欄改成依工具過濾的下拉。
§4

要整理進 FR 文件

決策者要求：最後問答都要整理進 FR 文件。做法：

  • 新問題的答案先加進 briefing/mechanism-qa-2026-11-01.html（或另開日期版），格式照現有：每題 <article> 一張卡、題號、<h3> 題目、先結論再事實。
  • 改完用 Artifact 工具發到同一個網址 https://claude.ai/artifact/AmUhtjZVptzoqExGEUhjhx （要先 read 那個網址再發），repo 裡那份同步。
  • 收尾時（決策者下令才做）由首腦把 briefing/ 接進 FR 站（doc-site-build skill），README 加連結。
§5

讀序

  1. 本檔。
  2. briefing/mechanism-qa-2026-11-01.html（用瀏覽器開，或直接讀原始碼）。
  3. 有需要再讀 ../design.md §5、../discussion.md 圖 1 與「更新期間畫面從哪來」段。
  4. 現況盤點看 ../handoff/fr167-STATE.md §1（只讀，不改）。