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。

§1

為什麼做

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

§2

做了什麼(行為差異)

面向 升級前 升級後
收件站 無;要收錯誤得自己架站、手填 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
§3

四個 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。
§4

驗證

  • 每張實作卡首腦從 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 命中。
§5

驗收打折處總表

項目 卡片要求 實際
本機 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 實打 沒實打
§6

規範文件清單

  • 設計: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。
§7

已知 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 要涵蓋。
§8

部署 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。
§9

✓ 已更新 / ✗ 漏做

✓ 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(不進版)。