FR-059 檢測工具 Profile / Content 庫 — STG / POC 部署 Runbook

給部署執行者的自包含操作手冊：照本文件由上到下依序執行即可，不需閱讀 design.md 或其他文件。 撰寫日期：2026-08-01｜對應 SUMMARY：handoff/2026-08-01-fr059-arc-SUMMARY.md

• 本 runbook 適用 STG / POC 上版。執行前必須取得決策者「當次」明確放行——之前放行過別的版不算，這一次要有這一次的放行。
• DEV（192.168.50.188 / guidant_ai_dev）已全部完成，勿在 DEV 重複執行本文件任何步驟。
• STG 與 POC 是兩個獨立環境，各自需要放行、各自完整走一遍本文件。POC 等同 production（對外 demo / 客戶試玩），尤其謹慎。
• 執行中任何一步結果與本文件描述不符：停下回報，不要自行補救或跳步。

本功能跨三個 repo，部署前確認目標環境拿到的版本包含以下 commit（請開發者或版控管理者確認，不確定就問）：

其他前置：

• 目標環境 DB 連線資訊（host / port / DB 名）見下表；密碼一律查該環境部署文件或 BE 主機上的 .env（DB_SECRET），本文件不記載密碼。
• BE migration 一律用 cmmgr 帳號執行（不是 cm_app）。
• 目標環境 DB 座標：

⚠️ port 是 25432 不是預設 5432，指令漏 -p 25432 會像連不上 / DB 不存在。

① BE 程式碼更新（含 FR-059 commits，migration 檔與 seed script 都在裡面）
② migration fr059-1（表 + RLS + 權限）
③ migration fr059-2（capability + 角色授予）
④ migration fr059-3-detection-profile-menu-route（選單）
⑤ seed script（10 筆系統公版 profile）
⑥ migration fr059-3-param-schema-options-source（下拉切換到庫）★ 必須在 ⑤ 之後
⑦ agent 部署 0.2.27（cache 掛載點目錄要先建）
⑧ FE 部署新版
⑨ 部署後驗收 checklist

⑤ 和 ⑥ 的順序不可對調：⑥ 會把任務抽屜下拉的靜態選項整批拿掉、改成讀 Profile 庫；若庫裡還沒有 ⑤ 灌的資料，下拉會直接空掉，使用者立刻受影響。照「先 seed、後切換」的順序執行，切換瞬間庫裡已有完整資料，使用者完全無感。

四支檔案都在 BE repo 的 scripts/sql/ 底下：

⚠️ 第 3、4 支檔名編號同為 fr059-3（歷史命名，不影響執行）；執行順序一律照本清單，第 4 支必須排在 seed（第 3 節）之後——原因見上方第 1 節。 兩支的內容不同：-menu-route 是選單、-param-schema-options-source 是下拉切換，看檔名主體區分。

指令模板（在能連到目標 DB 的機器上、BE repo 根目錄執行；<host> / <db> 依第 0 節的表帶入）：

psql -h <host> -p 25432 -U cmmgr -d <db> --single-transaction -v ON_ERROR_STOP=1 \
  -f scripts/sql/2026-08-01-fr059-1-detection-tool-profiles.sql

依序換檔名執行第 1〜3 支（第 4 支先跳過，等第 3 節 seed 完成後再回來跑）。

每支跑完確認 migration 有落帳：

psql -h <host> -p 25432 -U cmmgr -d <db> \
  -c "SELECT filename FROM public.schema_migrations WHERE filename LIKE '2026-08-01-fr059%' ORDER BY filename;"

跑完第 1〜3 支應看到 3 列；第 4 支跑完後共 4 列。少列＝該支沒成功，停下回報。

在目標環境的 BE 主機上、以該環境的 .env 執行（腳本讀 .env 的 DB_HOST / DB_NAME 決定寫進哪個 DB——務必確認 .env 指向的是你要部署的環境）。

3.1 環境防呆（必看）

腳本內建 D10 護欄：預設只允許在 DEV 執行。要在 STG / POC 執行，必須加 --db-name <目標 DB 名> 顯式確認——這個參數不改變連線目標（連線一律由 .env 決定），它的作用是要求執行者「逐字說出」自己要動哪個 DB，名稱與 .env 的 DB_NAME 不一致就拒絕執行。不需要修改腳本。

3.2 執行

先 dry-run 確認（只檢查不寫入；STG / POC 連 dry-run 也要帶 --db-name）：

# STG 為例（POC 用 guidant_ai_poc）
poetry run python scripts/seed_2026-08-01_fr059_detection_profiles.py --db-name guidant_ai_stg

輸出開頭會印 DB : <db 名> @ <host>——核對這一行就是目標環境，再實際執行：

poetry run python scripts/seed_2026-08-01_fr059_detection_profiles.py --apply --db-name guidant_ai_stg

行為說明：

• 走與使用者相同的上傳管線（真 HTTP 端點）建 10 筆 SYSTEM 公版：8 支 TWGCB（file 型，綁 GCB 工具）＋2 條 dev-sec（url 型，綁 CINC 工具）。
• 可重跑：已存在的同名 profile 會印 [skip] 跳過，不會疊加、不會報錯。
• 腳本以平台管理員帳號登入（預設帳號 admin，密碼預設值寫在腳本內；若目標環境的管理員帳密不同，用環境變數 FR059_SEED_USER / FR059_SEED_PASS 覆寫，不要把密碼改寫進腳本）。
• 結尾自帶零回歸驗證：印出 [gcb] menu 8 筆… / [inspec] menu 2 筆… 即成功。

期望結果：結果：建立 10｜跳過 0｜失敗 0（重跑時建立與跳過數互補）。有任何 [fail]：停下回報，不要接著跑第 4 支 migration。

3.3 回頭跑第 4 支 migration

seed 成功後，回到第 2 節的指令模板執行：

psql -h <host> -p 25432 -U cmmgr -d <db> --single-transaction -v ON_ERROR_STOP=1 \
  -f scripts/sql/2026-08-01-fr059-3-param-schema-options-source.sql

並照 2 節末的查詢確認 schema_migrations 共 4 列。

在目標環境的 agent 主機（evidence-agent 的 deploy/ 目錄）操作。image 取得方式二擇一：依既有流程重建 0.2.27，或從 DEV 主機 docker save / docker load 搬運（版本以 0.2.27 為準）。

4.1 ⚠️ 啟動前必做：建 cache 掛載點目錄

cd /opt/evidence-agent/deploy
mkdir -p content/cache

少這一步容器起不來，且錯誤訊息（read-only file system、指向 /var/lib/docker/rootfs/...）完全看不出跟這個目錄有關——這是 2026-08-01 首次部署實際踩到的坑。原因與完整說明見 evidence-agent repo deploy/README.md §6.1。若容器起不來且錯誤長那樣，先檢查這個目錄存不存在。

4.2 更新與啟動

compose 操作必須指定 service 名（不帶名的 docker compose up -d 會把同一 compose 檔裡的其他 service 一起 recreate）：

docker compose up -d guidant-ai-agent

4.3 部署後驗證

• 平台管理頁（檢測工具 / agent 管理處）該 agent 版號顯示 0.2.27。
• agent 心跳正常（管理頁上線狀態，或等一個心跳週期約 5 分鐘後確認最後心跳時間有更新）。

照 FE 既有部署流程出新版即可（版本需含第 0 節列的兩個 commit）。本功能無 FE 端額外設定。

以該環境的系統管理員帳號登入平台，逐項打勾：

• 側邊選單「系統管理」群組下出現新頁「掃描設定檔管理」（位置在檢測工具管理附近）
• 進入該頁，列表看到 10 筆系統公版：8 筆 TWGCB（名稱如「TWGCB-01-007 Windows Server 2016 v1.3（540 項自動檢查）」）＋2 筆 dev-sec 基準
• 開任一專案的 GCB 檢測任務抽屜，profile 下拉有 8 個選項，名稱與改版前完全一致（TWGCB 系列）
• 開 CINC Auditor 檢測任務抽屜，profile 下拉有 2 個選項（dev-sec Linux / Windows 基準）
• 下拉欄位仍可自行手動輸入文字（手填能力保留）
• （若該環境有可掃目標主機）從下拉選一支 TWGCB profile 派一次 GCB 掃描 → 執行成功、產出報告

任何一項不符：停下回報，附上該項的畫面截圖。

回滾操作若涉及直接改 DB（第一列），請由開發者執行或在開發者指導下執行，執行前先備份該兩列資料。