# FR-184 交接紀錄（LOG）

> append-only。每棒收工追加一個 block，寫完不改。現況看 `FR-184-STATE.md`。

---

## 第 1 棒｜首腦｜2026-11-07～11-08

**做了什麼**
- 需求探脈：compose 十服務、installer、FR-065 §4.8 K8s 預留、FR-173 直接部署、saas 模式影響面、189／190 實測記憶體
- 費用實查（不是記憶值）：Google 定價頁前端渲染，用 test repo 的 Playwright 無視窗切台灣區抓；AWS 抓定價頁背後官方 JSON；DO／Hetzner 官方頁。GCP 台灣 16 GB 約 144／月、8 GB 約 82；K8s 正統約 290、高可用約 770
- 討論稿 → 設計 v1.0 → cards.py 驗批 → 開卡 CM-3643～3651（八張六批）；新 repo `guidant-ai-infra` 骨架並登記進工作坊
- 引導決策者完成：GCP 專案、帳單、API、state bucket、Cloudflare 權杖、Brevo、Turnstile 小工具、Origin 憑證、Secret Manager 12 個、SSL 嚴格規則
- T2 親手 apply：24 資源、VM 35.194.213.124，真機驗開機腳本與防火牆，寫 runbook
- 架構圖（mingrammer diagrams，GCP 官方圖示），補上客戶地端 Agent 區塊

**commits**：BE `db989fcc3`～`811a9ba44`；infra `7ec4f3a`～`08c67b6`（含小弟 T1 `93e0287`）。11-08 決策者授權後兩 repo 都已 push（infra 新建遠端分支）。BE 這次 push 夾帶另一 session 的 `01fb1289e`＋`b0cc9b321`（CM-3653 加開關又撤回，淨效果零），推前已核對

**決策**（理由在 design §3）
- VM 不 K8s；8 GB；host 模式；Turnstile 必開；密碼自帶；序號裝完才貼；SSL 只對單一主機名嚴格

**教訓**
- **費用要實查**：首輪憑記憶報價錯四處（DO 沒有 4 核 16 GB Basic、Hetzner 新加坡缺貨且 4 核只到 8 GB、AWS 台北比東京便宜而非貴、GCP 台灣比美國貴 14%）。決策者原話「你要確認啊，不然幹嘛請你評估」
- **Model 欄留空擋不住工作坊**：T2 被派給小弟、等人回答 3 分鐘後工作坊整個暫停。已記 memory，首腦親手的卡要開成「暫緩」
- **第一個 GCP 帳單帳戶被 Google 風控關閉**：重建帳單帳戶與專案才過。apply 前先看 `billingEnabled`
- **Cloudflare 免費方案「設定規則」在下拉選單的「Configuration Rules」**，左側選單的「設定」是另一個功能；欄位要選「主機名稱」不是「完整 URI」，否則規則永遠比對不到
- **`pbpaste` 搭指令時不要用 Cmd+V 貼指令**，剪貼簿會被指令文字蓋掉

**推翻了什麼**
- 討論稿 D2「Turnstile 先關」→ 決策者推翻，改必開（加 F1／T4）
- 討論稿 D3 建議 16 GB → 決策者裁 8 GB
- 首腦一度要決策者預先放 License 序號 → 決策者指出沒機器碼不能開通，更正為裝完才貼
- 設計 §5.2「從快照還原 License 不用重開」→ T1 小弟實查不成立（machine-id 在系統碟、vTPM 換機解不開），列 O1 待解

**交出時**：1.30.0 包 11-08 10:57 已在 188 出好，T3 前置齊了，未開始裝。

---

## 第 2 棒｜首腦｜2026-11-08

**做了什麼**
- 冷接盤點：pre-flight 全綠（GCP、Secret 12 個、VM 空機、網址 521、188 有 1.30.0 包、Terraform 無漂移）
- 決策者問「雲端版也走線上更新嗎」→ 盤點更新中心與直接部署兩條路，建議主路改線上更新（待裁，記 STATE §4）
- 追 Turnstile 時發現原 F1／T4 做法有兩個洞：升級會把 FE 蓋回關閉版，且前門 CSP 根本會擋 Turnstile 的 script 與 iframe
- 決策者裁「有填 key 就開」並要首腦直接改：BE `a108ab505`、FE `f95a85b8`，已 push
- F1 CM-3650、T4 CM-3651 卡上寫取消理由；T3、V1、母卡補說明；design、README、STATE 更新

**決策**
- Turnstile：兩把都填真 key 才開（Cloudflare 測試 key 視同沒填），`TURNSTILE_ENABLED=false` 可強制關；後端驗 token、`/setup/status`、前門 CSP 三處同一判定（`common/util/turnstile_state.py`）
- key 放 compose `.env`（`GUIDANT_TURNSTILE_SITE_KEY`／`_SECRET_KEY`），不放 `guidant.env`：前門要 site key 決定 CSP，compose 只能從 `.env` 插值，且不能把整份 `guidant.env` 掛給前門
- 沿用既有未登入端點 `/setup/status` 帶 Turnstile 狀態，不另開 API（登入頁本來就會打）
- 升級健康檢查：Turnstile 開著時接受 `CAPTCHA_400001`，只在 `/setup/status` 說開著時才放寬
- 舊機器 `guidant.env` 的 `TURNSTILE_ENABLED=false` 升級時不自動刪：客戶可能有意強制關，沒填 key 本來就是關
- admin 後台設定之後另做

**教訓**
- **「要另出一顆 image」的方案先檢查前門擋不擋**：F1／T4 開卡時只查了 FE build 與 BE 開關，沒看 nginx CSP，方案本身就開不起來
- **build 時寫死的開關搭配會被升級覆蓋的產物，等於每次升級都要人補一步**：同一包靠執行期設定切換才是對的形狀
- 首腦這棒自己動手改主產品，是決策者當次明示（「你直接改」），不是常態

**推翻了什麼**
- design v1.0「程式零改動」→ 主產品改了 Turnstile 開關
- design D2「F1 出 `build:CLOUD`、T4 換雲端 FE image、每次升級後重跑」→ 取消，改有填 key 就開
- design §5.2「先寫 `/srv/guidant-ai/.env` 再跑 install.sh」→ 走不通（`install.sh:933` 看到 `guidant.env` 或 `certs/server.key` 就停），改 `install.conf`；這點第 1 棒 STATE §3 已發現，本棒同步進 design

**交出時**：BE、FE 已 push。188 上 10:57 的 1.30.0 包不含 Turnstile 改動，T3 要等重出包。
- 同棒追加：決策者裁「升級走線上更新，出包我自己跑」。design D8 改為平常走更新中心、只收正式發版，P1 直接部署定位救火用；§5.3、§8 第 7 項、兩張架構圖標籤同步。P1 CM-3647、母卡補說明。雲端版機器指紋不登記內部主機清單、不加 `PRODUCT_UPDATE_ALLOW_SAME_VERSION`，寫進 STATE T3 步驟 8
- 同棒追加（13:20～14:05）：**T3 系統裝好**。決策者重出 1.30.0（13:09）→ 開包核過含 Turnstile 改動 → 188 直接 scp 到 VM → Mac 組 install.conf → `--check-only` → 安裝。踩三個坑：①Ubuntu 24.04 要先 apt 裝 tpm2-tools（`--check-only` 不擋、正式才擋，記 §4 另開卡）②vulndb 檔 600，容器 uid 1000 讀不到，第⑥-3 步失敗；根因 188 的 zstd 1.4.8 從 stdin 寫檔一律 600，`457f2964a` 修出包腳本；VM 上 chmod 644 後 `GUIDANT_REUSE_EXISTING_INSTALL=1` 重跑通過 ③手跑出包沒帶 `DEFAULT_UPDATE_SITE_URL`，`guidantai config edit` 補 `UPDATE_SITE_URL`。另：決策者 Secret Manager 的 db-admin 與 db-app 原本同一組，首腦指出後決策者換了 db-app。裝完換 Origin 憑證、外驗 200／Turnstile enabled／CSP 放行／直打 IP 擋；installer 自產九組回寫 Secret Manager；VM 家目錄安裝包刪除（先查過無容器與單元參照）
- 教訓：**手跑出包與 CI 出包有差異**（`DEFAULT_UPDATE_SITE_URL` 只有 CI 帶），用手跑的包裝正式環境要對照 CI 變數補；**讀含祕密的安裝輸出時過濾要以「一行裡的長十六進位」為準**，不要只過濾標籤（設定碼單獨一行，本棒漏過濾印進對話，一次性、已用途內，影響小）
- 同棒追加（14:05～15:30）：**T3 完成**——決策者跑設定精靈（`Billows` tenant 3、另建 `Jedicogy` tenant 4）、License 開通、Brevo 填好測試信寄出成功（`/mail/test` 200）。首腦另做：①出包權限根因查到底——包內 19 檔 600，只有 vulndb 掛給容器讀會壞，`9086e8ad8` 改接既有 `dist_perms.sh` 整包正規化＋斷言（188 實包＋`guidant-ai-be:1.30.0` 端對端驗：600 讀不到、644 讀得到），已 push；決策者要出 1.30.1 帶上 ②預算告警 Terraform（infra `724e9c0`），第一次 USD 回 400——帳單帳戶是 TWD，改 6,500 TWD 成功 ③查清楚雲端連更新站不需 Zero Trust token（Access 只守 `/admin/*`，`/v1/*` 靠 LC 簽的身分票＋指紋驗章）；更新站 `/v1/*` 沒有限流，建議 Cloudflare 加一條（未做） ④郵件與儲存設定的多租戶行為（寫進 STATE §4）
- 教訓：**STATE 裡「等某張卡出新版」這類依賴要開工前實查**——本棒照 STATE 說「Agent 接雲端要等 CM-3654」，被決策者問才去查，修正早已含在 Agent 1.7.0 並發佈；跨 session 的依賴狀態會過期，回報前 `git branch --contains`／`git tag --contains` 一下
- 決策：雲端版 `Billows`（安裝精靈建的總部）留給自家用，外部試用客戶另開租戶——host 模式下總部管理員能改全站寄信／LDAP；根治在 saas FR
- 同棒追加（15:30～16:00）：決策者要求「安裝後手動處理」能進自動化的都做、併 1.30.1 出。主產品 `b3b21a950`：`--check-only` 與正式安裝共用「出貨包 tpm2-tools 適不適用這台」判斷（只修誠實度，不改成自動連網 apt——installer 只裝本地檔）；infra `8194fb0`：開機腳本預裝 tpm2-tools、時區走 metadata。Origin 憑證刻意不進開機腳本（VM 服務帳號不該讀私鑰；升級會保留），寫進 runbook。手動處理清單 10 項，剩重建 VM 時的憑證與 188 known_hosts
- 同棒追加（16:00～17:20）：**1.30.1 經更新中心線上更新成功**（發版 session 發、決策者按更新，首腦監看八步；健康檢查在 Turnstile 開著時通過）。決策者覺得慢，實測拆解：VM 內 API 80～130 ms、外部 0.65～1.3 秒，差額是 Cloudflare 分到 SJC 繞路；升級後記憶體用 6.2／7.75 GB（三個後端各載一份 AI 守門模型約 1.5 GB）、CPU pressure 28%。決策者裁升 **e2-standard-4**（infra `5fe59da`）：先 `guidantai stop` 再 apply，重開後手動 `guidantai start`；VM 內降到 17～24 ms、CPU pressure 4%、可用記憶體 9.4 GB。Cloudflare 靜態檔快取：雜湊檔已在快取、固定檔名的主題檔有 4 小時舊版風險，**決策者裁先不動、看客戶反應**
- 教訓：**升級中與平常的資源數字差很多**——首腦先依決策者在升級中截的 htop（後端全停、851 MB）說「記憶體完全沒壓力」，服務起來後實際 6.2 GB，當場更正。判規格要在服務穩定後量

**第 2 棒 commits 總表（交出時補）**
- BE（本棒）：`a108ab505` Turnstile 有填 key 就開、`457f2964a`＋`9086e8ad8` 出包整包權限正規化、`b3b21a950` installer tpm2-tools 判斷一致；文件 `b8365df40`、`0a6cd990c`、`3fa60590c`、`b250ffca0`、`33272a8e6`、`79049c878`、`7c2c531c7`
- BE（發版 session，1.30.1）：`0134d23f5` 進版、`f2066a58c` 正式發版帶預設更新站網址、`2aeb13257` 弱點白名單
- FE：`f95a85b8` 登入頁問後端決定 Turnstile＋前門 CSP；`d9b1221d` 版號 1.30.1（發版 session）
- infra：`724e9c0` 預算告警、`8194fb0` 開機腳本補時區與 tpm2-tools、`5fe59da` 升 e2-standard-4、`7caae4a` Terraform 導讀

**推翻了什麼（第 2 棒）**
- design D2「F1 出 build:CLOUD、T4 換雲端 FE image」→ 取消，主產品改有填 key 就開
- design D8「升級走 CI 直接部署」→ 平常走更新中心，P1 改救火用
- design D3／T1「e2-standard-2 8 GB」→ 決策者 11-08 裁升 e2-standard-4（三個後端行程各載 AI 守門模型，8 GB 平常就用到 80%）
- 首腦說「CI 正式發版會帶 DEFAULT_UPDATE_SITE_URL」→ 實際 CI 變數名與出包腳本讀的名字沒對上，發版 session 在 1.30.1 才修（`f2066a58c`）；雲端 VM 的 `UPDATE_SITE_URL` 是首腦手動補的、1.30.1 升級後保留
- STATE「Agent 接雲端要等 CM-3654」→ 早已含在 Agent 1.7.0

**交出時**：雲端版 1.30.1、e2-standard-4，決策者先給客戶試用。下一棒 Q&A：決策者要看懂 Terraform 回答 PM，導讀在 infra `docs/terraform-walkthrough.md`。之後 P1 → O1 → V1。