# FR-133 錯誤追蹤站隨產品出貨 — arc 收尾 SUMMARY（2026-10-10）

> 由 `FR-133-LOG.md` 兩個 block 濃縮。母卡 CM-2601，子卡 CM-2602～2623（22 張，20 張 Done、G1 暫緩、T-E 文件另批處理）。**未進版**：主專案仍 1.26.0，三環境 image tag 為 1.26.0＋`aba953f67`。

## 為什麼做

產品進客戶 UAT，客戶機房我們進不去。出錯時要在客戶自己的機器上看得到錯在哪一行、當下變數值、誰踩的、哪一筆請求。後端送錯誤報告的接線 v1.26.0 已在產品內，但沒有收件站：FR-071 時選過 GlitchTip 隨包出貨，2026-09-18 又拔掉（只留 SDK 接線）。本案改用 Bugsink 2.6.1（單一容器）隨安裝包出貨，裝機全自動，前端、受檢主機 Agent、證據分類沙箱也一起接上。

## 做了什麼（行為差異）

| 面向 | 升級前 | 升級後 |
|---|---|---|
| 收件站 | 無；要收錯誤得自己架站、手填 `SENTRY_DSN` | 安裝包自帶 Bugsink 2.6.1，`https://<主機>/bugsink/`（走 443，不多開 port），共用 `guidant-db` 另開 `bugsink` 庫 |
| 裝機 | — | 首裝自動建管理員 `admin@guidantai.com`（密碼 build 時烙進包、存 `${GUIDANT_DATA_DIR}/bugsink-admin.secret`）、三個專案、三組 DSN 與讀取 token 寫進 guidant.env；升級時缺了才補，網址相關設定每次重寫，現場補的允許主機名保留 |
| 送什麼 | 有 DSN 時全送，log 的 ERROR 行另開一條 | **預設全收**：程式錯誤、4xx 使用者失誤、ERROR log 行都送；設 `ERROR_TRACKING_CAPTURE_CLIENT_ERRORS=false` 回到只收程式錯誤 |
| 遮罩 | 欄位名＋請求內容 | 加上 Bearer 值（1.3.5）與堆疊裡的無名位置參數 `args`／`kwargs`、含字串的清單（1.3.6）；登入失敗事件不再帶出密碼 |
| worker／socketio | 錯誤沒送 | 背景工作與即時通道的錯誤也送 |
| 前端 | 錯誤回報停用（免登入端點 9 月因資安拆掉） | 登入後經後端轉送端點送進 `guidant-ai-fe` 專案；登入前的錯誤收不到（接受） |
| 受檢主機 Agent | 無錯誤回報 | 1.4.1 起經同一支轉送端點送進 `guidant-agent` 專案；連線設定隨註冊與心跳回應下發，升版不必重註冊 |
| 證據分類沙箱 | 無 | 多一個只通站台的內部網段，內網直送 |
| 診斷包 | 撈 GlitchTip 式 API（實際無站台可撈） | 改打 Bugsink 讀取 API，三個專案都撈；收 bugsink 容器 log；`GLITCHTIP_*` 三變數移除 |
| 維運指令 | — | `guidantai bugsink-vacuum`（清理）、`bugsink-set-password`（互動改密碼，不走命令列參數）；服務清單納入 bugsink |

## 四個 repo 的 commits

- **BE**（`84e293101..aba953f67`，27 筆，含文件）：B0 `a5bd492b2`、B2 `333e5c22d`、A2 `1f45680c6`、B1 `4fadd8add`、D `16fd0f110`、C1 `98cc3c934`、B3 `1631d4f27`、B3b `aa084603f`、B4 `ace6a5f1a`、C1b `5dc3dd6cb`、C4 `ca6b743de`、C3 `2795930fb`、發版流程拿掉 e2e gate `387035254`、T-R 釘版 `fdec6b758`、弱點白名單 `df999ed90`、CI verify `478db0876`、B5 `a614be494`、T-R2 釘版 `b19358521`、預設全收 `aba953f67`。
- **FE**：`9e4e5d18`（前門 `/bugsink/` 子路徑）、`6d2d4e56`（轉送端點錯誤碼 i18n）、`7d1f64a0`（登入後接回）。
- **jedi-python-package**：jedi-log `6d815fec`（1.3.4）、`9a943a54`（1.3.5，Bearer）、`95ffe840`（1.3.6，位置參數）；classifier `e6574acf`（1.6.4）、`be05c2e4`（1.6.5）。
- **evidence-agent**：`2dea7c8`（1.4.1 錯誤回報）、`a26464c`（出包整包收 sentry_sdk）、`7e6e1e3`（smoke 第 4 項）、`4b088a4`（1.4.2 遮罩）。
- 版號：jedi-log 1.3.6、jedi-evidence-classification 1.6.5（Nexus）；Agent 1.4.2；Bugsink 2.6.1 釘 digest。四個 repo 的 `feature/FR-133` 已併回 main。

## 驗證

- 每張實作卡首腦從 HEAD 核 diff；遮罩三份（jedi-log／Agent／分類器）都有「真 SDK 收到的事件」測試與突變測試，斷言一律是「整個事件找不到原始值」。
- 三環境升級後批次驗：api log「錯誤追蹤已啟用」帶新 commit、sandbox 1.6.5、三專案在、站台可登入。
- 端到端：Agent 觸發 ERROR → 轉送 204 → `guidant-agent` 專案收到，無 Bearer／JWT；188、189 用假密碼打登入，401 事件全文找不到假密碼。
- 開包驗：包內有 bugsink image、600 密碼檔；密碼值在 build log、SBOM、GitLab job log 全部 0 命中。

## 驗收打折處總表

| 項目 | 卡片要求 | 實際 |
|---|---|---|
| 本機 compose 驗收（B1／B3／B3b／C4） | 真機安裝 | Mac arm64 無產品 image，只起部分容器、後端用替身；installer 在 Linux 容器只載入函式 |
| T-V 乾淨機首裝 | 乾淨機與升級機各跑一次 | 決策者裁以三環境升級實跑代替，**乾淨機首裝沒在真機跑過** |
| A3 Bearer 遮罩 | DEV 製造事件 | 本機用 jedi-log 1.3.5 送 190 新站驗，不是沙箱真實失敗路徑 |
| A4 位置參數遮罩 | DEV 全收打錯密碼 | 改在 188／189 真環境做；分類器測試跑在暫存 venv |
| 「沒設就預設全收」 | 三環境 | 只在 188 驗到；190 有手動 false、189 有手動 true |
| Agent 錯誤回報 | 對 DEV 註冊驗 | 改在 190 真環境驗 |
| A2 socketio | 實打 | 沒實打 |

## 規範文件清單

- 設計：`docs/features/FR-133-2610-bugsink-bundled-error-tracking/design.md`（v2，D1–D10）、`discussion.md`、`b0-findings.md`、`b0-bootstrap-snippet.sh`。
- 交接：`handoff/FR-133-STATE.md`（結案版）、`handoff/FR-133-LOG.md`（兩個 block）。
- 決策歸檔：`docs/analysis/2026-10-10-fr133-bugsink-bundled-and-masking-copies.md`。
- T-E 文件（收尾批另一支 agent 產出）：`docs/claude/error-tracking-integration.md`（D9 接入規範）、`docs/user-manual/onprem/`（客戶手冊錯誤追蹤站一節）、`docs/spec-site/current/system-admin/error-tracking-site.md`（spec 頁）。
- 設定範本：`.env.sample`、`docs/features-site/docs/FR-063-2608-nuitka-packaging/deployment-env.md`（已隨實作卡與 `aba953f67` 同步）。
- memory：`feedback_error_tracking_masking_three_copies_sync`、`feedback_nexus_npm_proxy_cache_and_third_party_image_prepull`、`project_fr133_bugsink_shipped`。

## 已知 follow-up

- **G1 暫緩**（CM-2622）：Agent 1.1.0 直升時跑舊版升級程式、seaweedfs 憑證不產生；處置是移除重裝新版。出貨後若有跨版升級需求再開。
- **三份遮罩複製品**：改一處要同步三處；收斂條件見 analysis。
- **Agent 升級不清 `/tmp` 暫存解包**，失敗訊息誤導成「檔案損毀」（待決策者決定是否開卡）。
- 告警（D8）下一版；登入前、Agent 註冊前的錯誤不收。
- reviewer 對 C1b 兩條建議（守門 docstring、`CONTROL_TOKEN_TYPE` 對外匯出），見 design.md §9。
- 既存紅燈兩條（`GET /survey` 未登記、錯誤碼鏡像），與本案無關。
- 進版：FR-133 全部內容尚未進版號，下次進版 release note 要涵蓋。

## 部署 handover

- 三環境（190 e2e、188 STG、189 POC）：1.26.0＋`aba953f67`、classifier 1.6.5、bugsink 2.6.1、三專案。
- 四台外部 Agent（.166／.122／.167／.121）1.4.2；190 本機 Agent 仍 1.4.1。
- 190 guidant.env 有手動兩行（關閉全收）；要回到預設需 sudo 刪行後 `sudo guidantai start`（不是 restart）。
- 188、189、.166 待重開機；重開後 `status` 確認。
- 安裝包 188 `/opt/guidant-ai-be/.build/bundle/guidant-ai-1.26.0.tar.gz`（2.94GB，以 `aba953f67` 出）；Agent 交付包 188 `/opt/guidant-ai-agent/.build/compose/guidant-agent-compose-1.4.2.tar.gz`。
- 新加第三方 image 先在 188 pull；GitLab 變數 `GUIDANT_BUGSINK_ADMIN_PASSWORD` 已設（未保護、14 字）。
- DEV：B1／B0 測試資源仍在，清理見 STATE §1。

## ✓ 已更新 / ✗ 漏做

✓ LOG 第 2 棒、STATE 結案版、本 SUMMARY、analysis、memory 三條（含個人目錄同步）、`docs/features/README.md` 狀態欄；22 張子卡 Notion 狀態（20 Done、1 暫緩）。
✗ 由另一支 agent 處理：spec-site、使用手冊、接入規範、design.md 收尾段。✗ 未做：arc-review、e2e 回歸（site-regression 重建前不以 e2e 為 gate）、release note（不進版）。