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

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

## 你是誰、能做什麼

- **角色**：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 處理。
- **回答紀律**（決策者明確要求過）：一題一答，先結論再事實；每個說法對回程式碼或實查結果，不憑印象、不照簡報措辭；查不到就說查不到。白話、繁體中文。

## 昨天的問答在哪

| 產出 | 位置 | 說明 |
|---|---|---|
| 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」。

## 今天（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 欄改成依工具過濾的下拉。

## 要整理進 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 加連結。

## 讀序

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