Bugsink 隨產品出貨 — 設計定案

狀態：設計定案（D1–D11 全數拍板）｜日期：2026-10-10｜前作：FR-071（錯誤追蹤接線與診斷包） 討論稿（現況缺口實證、Bugsink 事實表、連線面）：discussion.html

🔴 這份是設計決策，不是現況。 內文的行號與座標停在 2026-10-09 定稿當時，之後實作改動的結果不回頭改寫這裡——上線後的現況看 FINAL-SPEC.md。

產品進客戶 UAT，客戶環境不受我們控制。出錯時要在客戶自己的機器上看得到：錯在哪一行、當下變數值、誰踩的、哪一筆請求。後端送錯誤報告的接線（sentry-sdk 2.71，經 jedi-log 1.3.3 初始化，含遮罩與每分鐘 60 筆節流）已在產品內，缺的是：

1. 收的站：出貨包不含任何錯誤追蹤站，SENTRY_DSN 預設空。
2. 篩選：一次打錯密碼在站台變三條，ClientError 八種全部會送，UAT 的正常操作失誤會淹掉真正的 500 並吃光節流額度。
3. 前端：免登入的 /client-config、/error-tunnel 因資安項 U3-⑤ 已拆，前端 @sentry/vue 一併移除。
4. 診斷包：infra/support/diag_event_fetcher.py 對著 GlitchTip 式 API 寫，Bugsink 不是那個形狀。

端到端

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
sequenceDiagram
    participant I as install.sh
    participant DB as guidant-db
    participant BS as guidant-bugsink
    participant ENV as guidant.env
    participant BE as 後端三容器
    I->>I: 讀包內 bugsink-admin.secret
    I->>DB: 建 bugsink 庫與帳號（冪等）
    I->>BS: up -d guidant-bugsink（CREATE_SUPERUSER）
    BS->>DB: 自動遷移、建管理員
    I->>BS: 等 /health/ready
    I->>BS: bugsink-manage shell 建 team／project／token
    I->>DB: SQL 讀 project id 與 sentry_key
    I->>ENV: 寫 SENTRY_DSN／SENTRY_PUBLIC_DSN／BUGSINK_API_TOKEN
    I->>BE: up -d 後端
    BE->>BS: 內網送事件

執行期：後端三容器與證據分類沙箱走 docker 內網直送；已登入的瀏覽器與受檢主機 Agent 只打 443，經後端同一支轉送端點進 Bugsink，依身分落到各自的專案；原廠人員從 443 的 /bugsink/ 子路徑看站台；診斷包從內網打 canonical API，撈三個專案。

整案一句話：每套 Guidant AI 自帶錯誤追蹤站，裝好就能用；後端與前端的程式錯誤自動進站，使用者打錯不進站。

依賴：A、B0 平行 → B（B1／B2 平行 → B3 → B4）→ C、D 平行 → 整包實機驗收 → E。

5.1 子需求 A：過濾開關

新環境變數（先 grep config/config.py、.env.sample、全 codebase 與 jedi 套件確認無同義名；現有同族為 SENTRY_DSN、ERROR_TRACKING_RATE_LIMIT）：

布林解析：1/true/yes 為開、0/false/no 為關，沒設或打錯字回預設值（core/plugins/api_log.py::_env_flag）。

BE core/plugins/api_log.py

_extra_before_send(event, hint) 開頭加：

exc_info = (hint or {}).get("exc_info")
exc = exc_info[1] if exc_info else None
if isinstance(exc, ClientError) and not _CAPTURE_CLIENT_ERRORS:
    return None

• ClientError 從 jedi_common.handler.exception import。
• 放在 _attach_actor 之前、_throttle 之前：被濾掉的不該花取脈絡成本，也不該佔節流配額。
• init_error_tracking() 讀 ERROR_TRACKING_LOG_EVENTS 傳給 jedi-log 的 log_events。

jedi-log init_error_tracking

• 新參數 log_events: bool = False。False 時 integrations 加 LoggingIntegration(level=logging.INFO, event_level=None)；True 時不加（維持 SDK 預設：INFO 以上當前情、ERROR 以上當事件）。
• 新公開函式 capture_exception(exc=None) -> None：未啟用時什麼都不做、永不拋錯；啟用時呼叫 sentry_sdk.capture_exception。給宿主在「例外被 catch 後只寫 log」的地方補送。
• 主專案 pin jedi-log[error-tracking]==1.3.6（含下一小節的兩條遮罩規則）。套件發版一律停下等決策者明示。

jedi-log 遮罩：值是 Bearer xxx 也要遮；無名位置參數整個遮

jedi_api_log/error_tracking/masking.py 的 _mask（字串與 JSON 兩處）走 jedi-common 的 mask_secrets_in_text，不自己寫 regex。jedi-log 相依下限 jedi-common>=1.3.6（那支函式從 1.3.6 起才有）。

堆疊變數中名為 args／kwargs，以及任何含字串元素的 tuple／list，整個換成 ***；純數字清單保留。不採「依函式參數名逐位遮」：SDK 送出的 frame 只剩函式名、拿不到簽章，*args 轉手層本身也沒有參數名。代價是除錯時看不到 args 內容。同一規則複製在 Agent 與分類器兩份遮罩（§9）。

驗收（兩開關設 false）：打錯密碼登入三次 → 0 條；故意 1/0 的端點打一次 → 1 條，事件的前情紀錄內看得到前面那幾行 logger.error；故意失敗一筆背景工作 → 1 條。預設（全收）：打錯一次密碼 → 有 401 事件，全文找不到輸入的密碼。

5.2 子需求 B0：可行性實跑

在 DEV 用本機 Postgres 另開 bugsink 庫，docker run bugsink/bugsink:2.6.1 起站台，依序驗下表十項。每項把指令與實際輸出貼進 docs/features/FR-133-2610-bugsink-bundled-error-tracking/b0-findings.md。

實跑結論（全文與輸出見 b0-findings.md）：十項全過，D1、D2 成立。對後續設計有約束的四件：

另兩件：清舊資料的子命令就是 vacuum，但只在站台設了 MAX_EVENT_AGE_DAYS 時才刪舊事件；changepassword 遇到不合格密碼會重問、stdin 讀完即崩潰，改密碼走 ORM（findings 附錄 B）。

建站片段 b0-bootstrap-snippet.sh 冪等（以名稱 get_or_create），輸入只有容器名，輸出 KEY=VALUE，檔內不含密碼；scripts/installer/bugsink.sh 的 bugsink_bootstrap_project 與它同源。

5.3 子需求 B：進出貨包

5.3.1 compose 服務 guidant-bugsink

guidant-bugsink:
  image: bugsink/bugsink:2.6.1
  container_name: guidant-bugsink
  restart: unless-stopped
  logging: *guidant-logging
  depends_on: { guidant-db: { condition: service_healthy } }
  environment:
    SECRET_KEY: ${GUIDANT_BUGSINK_SECRET_KEY:?必填——由 installer 產生}
    BASE_URL: ${GUIDANT_BUGSINK_BASE_URL:?必填——由 installer 依站台網址寫入}
    DATABASE_URL: postgresql://bugsink:${GUIDANT_BUGSINK_DB_PASSWORD:?必填}@guidant-db:5432/bugsink
    CREATE_SUPERUSER: ${GUIDANT_BUGSINK_CREATE_SUPERUSER:-}
    BEHIND_HTTPS_PROXY: "True"
    USER_REGISTRATION: CB_NOBODY
    SINGLE_USER: "True"
    PHONEHOME: "false"
    TIME_ZONE: ${TZ:-Asia/Taipei}
    ALLOWED_HOSTS: ${GUIDANT_BUGSINK_ALLOWED_HOSTS:?必填——由 installer 依站台主機名寫入}
  volumes: [guidant-bugsink-data:/data]
  networks: [default, guidant-sandbox-errors]
  expose: ["8000"]
  cap_drop: [ALL]
  security_opt: ["no-new-privileges:true"]
  mem_limit: 1g
  healthcheck:
    test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/ready', timeout=3)"]
    interval: 15s
    timeout: 5s
    retries: 10
    start_period: 60s

• 不 publish port。容器內埠固定 8000（image 自帶 HEALTHCHECK 寫死這個埠）。
• CREATE_SUPERUSER 由 install.sh 只在首次建站那一次以 -e 帶入（不寫進 .env），平時為空；Bugsink 只在零使用者時才用它。
• cap_drop: ALL、no-new-privileges、mem_limit: 1g 下照常起得來，不必放寬。
• 四個 GUIDANT_BUGSINK_* 變數都是必填：缺了 compose 直接解析失敗，不會靜默起一個壞站。代價是舊客戶的 .env 會讓新 compose 解析失敗，所以升級時 ensure_bugsink_env 要早於第一個 compose 呼叫（§5.3.5）。
• networks 一宣告就離開預設網路，所以 default 要一起列（DB 與 guidant-fe 都在 default）。guidant-sandbox-errors 見 §5.4.5。

5.3.2 前門 nginx（FE repo nginx.onprem.conf）

location /bugsink/ {
    set $bugsink_upstream guidant-bugsink;
    rewrite ^/bugsink/(.*)$ /$1 break;
    proxy_pass http://$bugsink_upstream:8000;
    proxy_set_header Host              $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    client_max_body_size 20m;
    # Bugsink 自己帶 X-Frame-Options／nosniff；只補它沒帶的，避免同名標頭送兩次
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options        $api_frame_options always;
    add_header X-Content-Type-Options $api_nosniff always;
}

location = /bugsink { return 301 /bugsink/; }

• 不加產品的 CSP（$csp_page 會擋 Bugsink 自己的 script）。安全標頭採 conf 既有的「上游沒帶才補」寫法（$api_frame_options 一類的 map 變數）：Bugsink 頁面自帶 X-Frame-Options: DENY 與 nosniff，前門無條件再加會送出兩份同名標頭。
• /bugsink/ 下的 envelope 收件端點（/bugsink/api/<id>/envelope/）對外也開著，這是 Bugsink 本來的形狀；後端與轉送端點都不走它（走內網），所以這裡不另擋。

5.3.3 bugsink 庫與帳號

install.sh 以 docker exec guidant-db psql -U <管理帳號> 冪等執行：

• bugsink 角色：LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOBYPASSRLS，密碼 gen_pw 隨機（存 .env 的 GUIDANT_BUGSINK_DB_PASSWORD，與其他 DB 帳號同慣例）。
• bugsink 資料庫 OWNER bugsink（遷移要建表）、REVOKE ALL ON DATABASE bugsink FROM PUBLIC。
• 已存在就只對齊密碼（ALTER ROLE ... PASSWORD），不重建。
• bugsink 角色對 guidant_ai 沒有任何 GRANT；PG16 的 public schema 已無 PUBLIC 建表權，產品資料讀不到也寫不了。
• 不放進 guidant-db-init：那支 image 的 init／migrate 模式只管產品庫，bugsink 庫的生命週期跟著 install.sh 的建站步驟走，升級補站時不必換 init image。

5.3.4 出貨包與密碼烙印

• build_bundle.sh 的 IMAGES 加 "bugsink/bugsink:2.6.1|bugsink-2.6.1.tar"，PINNED_DIGEST 加對應多架構 index digest（docker buildx imagetools inspect bugsink/bugsink:2.6.1 第三行），照該段註解：先 pull、跑 Trivy／Grype、再填 digest。
• sbom.sh --images 的掃描清單加 bugsink，弱點放行門檻同其他第三方 image。
• 新腳本 scripts/build/gen_bugsink_admin_bake.sh <輸出路徑>：讀環境變數 GUIDANT_BUGSINK_ADMIN_PASSWORD，缺、少於 12 字元或含 $ → fail 並提示「CI 要設遮罩變數；本機手跑請 export 後再跑」；寫出單行檔、chmod 600。這道檢查放在出包前置檢查的最前面，缺變數不必等到打包尾端才紅。build_bundle.sh 組裝階段呼叫它寫到 $STAGE/bugsink-admin.secret。
• .gitlab-ci.yml package job 不必改腳本行，只需專案層設 masked＋protected 變數 GUIDANT_BUGSINK_ADMIN_PASSWORD（GitLab 遮罩要求 ≥8 字元且字元集受限，產值時避開 $——那個字元進 .env 會被 compose 插值吃掉）。
• bundle-info.txt 只寫「含管理員密碼檔」，不印值；after_script 收 artifacts 的路徑不含 bundle 目錄，確認密碼檔不會進 out/。
• 弱點關卡：bugsink 2.6.1 image 有三條 Critical 上游未修，登記在 scripts/build/vuln-allowlist.txt，到期 2026-12-31——MariaDB 客戶端兩條（image 附帶的程式庫，Bugsink 連的是 Postgres、不載入它）、Python ssl sni_callback 一條（Bugsink 走明文 HTTP 只在內網，TLS 由前門終結）。理由逐條寫在白名單檔；到期未換版即重新擋。

5.3.5 install.sh

函式全部放在新檔 scripts/installer/bugsink.sh，由 install.sh source（install.sh 已近三千行，不往裡塞）；build_bundle.sh 把它收進安裝包。接入點：

• 為什麼要 bugsink_load_env：首次安裝的 write_configs 會整份重寫 .env。重跑安裝時不先讀回，SECRET_KEY 會被換掉（站台全員被登出），DB 密碼也會對不上既有的 bugsink 帳號。
• 為什麼網址與允許主機名每次重算：B0 實證換站台網址後舊主機名被拒，送件端不報錯。允許主機名改為合併而非覆寫：用 IP 安裝、外面再掛網域的客戶，網域不在 SYSTEM_URL 裡，覆寫會在每次升級把它洗掉、人用網域開站台回 400。write_configs 整份重寫 .env，所以 bugsink_load_env 先把舊清單讀進 BUGSINK_ALLOWED_HOSTS_PREV，重寫後才合併得回來。代價：換網址後舊主機名也留在清單（只是多放行一個名字），要清得手改 .env。
• GUIDANT_BUGSINK_BASE_URL 的來源：首次安裝用 ${SITE_URL}/bugsink；升級讀 guidant.env 的 SYSTEM_URL（write_agent_env 用同一來源）再接 /bugsink。讀不到時寫一個能讓 compose 解析的佔位值，並讓 setup_bugsink 略過建站（不停下問人，產品其餘部分照升）。
• 建不了站一律只警告不擋安裝：包內沒有密碼檔、讀不到站台網址、stack 內沒有 guidant-db（客戶自備資料庫）三種情形都 warn 後略過。只有建到一半失敗（DB 寫不進、站台起不來、片段出錯）才 fail。
• 站台只在建站成功時才進啟動與健康等待清單（bugsink_services 依 BUGSINK_READY 決定）：沒有庫的站台會反覆重啟，把整個安裝卡在健康檢查逾時。

setup_bugsink 細節：

1. 讀 ${BUNDLE_DIR}/bugsink-admin.secret；檔案不在 → warn「本包未含錯誤追蹤站管理員密碼，站台不建」並 return（不擋安裝）。
2. 建庫帳號（§5.3.3）。
3. 判斷是否首次建站：庫剛建，或 select count(*) from auth_user 為 0 → 首次，以 shell 環境變數 GUIDANT_BUGSINK_CREATE_SUPERUSER=admin@guidantai.com:<密碼> 帶入 dc up -d guidant-bugsink；否則不帶。緊接著的正式啟動不帶它重建容器，容器設定裡不留密碼。
4. 等 guidant-bugsink healthy，上限 180 秒，逾時 fail（訊息指向 docker logs guidant-bugsink）。
5. 跑建站片段（冪等，bugsink_bootstrap_project）：同一個 team「Guidant AI」下以名稱 get_or_create 三個專案，取得三組 id／key 與一支跨專案唯讀 token（service token：不綁使用者、不綁專案，權限 issues:read／events:read／projects:read）。舊機器只有 guidant-ai 時只補另外兩個。
6. 寫 DSN（bugsink_write_dsn）：

SENTRY_DSN 已有非空值且不指向本機站台（原廠或客戶接了外部站台）→ 保留不動並 warn；此時 GUIDANT_SENTRY_DSN 給空值（沙箱網段只通本機站台，給外部位址也送不出去且不報錯），BUGSINK_API_TOKEN 有值就不動。 7. 首次建站時把密碼寫到 ${GUIDANT_DATA_DIR}/bugsink-admin.secret（root、600）；非首次不寫、不改。 8. chmod 600 guidant.env；ok 一行「錯誤追蹤站就緒：<BASE_URL>」。

服務清單：start_services 與 upgrade_switch_version 的 dc_up 與健康等待迴圈都經 bugsink_services 帶上站台。完成畫面（安裝與升級共用 bugsink_print_summary）加一行站台網址與「密碼存放在 ${GUIDANT_DATA_DIR}/bugsink-admin.secret」（只寫路徑不印值）。

所有密碼不上命令列：寫檔走 awk 讀環境變數、建庫走 psql 的 stdin \set，同機其他帳號從 ps 看不到。

5.3.6 維運子命令（scripts/installer/guidantai）

• GUIDANT_SERVICES 加 guidant-bugsink（start／stop／status／restart <服務> 自動涵蓋）。
• 子命令本體放新檔 scripts/installer/guidantai_bugsink.sh，由 guidantai source（guidantai 已超過檔案上限）。連帶：install.sh 要把它裝到 guidantai 同目錄、build_bundle.sh 把它列為必要素材——缺它 guidantai 整個起不來。
• bugsink-vacuum：不吃參數；docker exec guidant-bugsink bugsink-manage vacuum，印前後事件數。不帶天數參數：站台沒設 MAX_EVENT_AGE_DAYS 時 vacuum 自己略過刪舊事件，行為交給站台設定。
• bugsink-set-password：不吃參數，需要 TTY，互動 read -s 兩次比對；密碼經 docker exec -i 的 stdin 交給一段 Django ORM 程式，先跑 Django 密碼驗證器、合格才改，不放命令列參數（ps 看得到）。成功後覆寫 ${GUIDANT_DATA_DIR}/bugsink-admin.secret（600）。不用 changepassword：密碼不合格時它會重問，stdin 讀完即崩潰。
• 兩支加進子命令分派與參數個數守門（照既有 case 的逐命令寫法）、usage。
• 診斷包的 KNOWN_SERVICES 與 installer 服務清單同步（守衛測試 test_diag_known_services_sync），一併補上 guidant-sandbox、guidant-worker。
• 順手修文件：FR-132-STATE.md 第 19 行與 docs/release_notes/v1.26.0.md §2b 的 guidantai restart 改 guidantai start（restart 底層是 compose restart，不重讀設定檔）。

5.4 子需求 C：客戶端錯誤接回（前端、Agent、沙箱）

5.4.1 BE 轉送端點

• 新模組 api/error_tracking/（route）＋app/error_tracking/（service）＋di_containers wiring，config/app_modules.py 註冊。
• POST /api/1.0/error-tracking/tunnel，守門 jwt_or_agent_pass_required（common/authz/caller.py），不掛能力點（任何登入者踩到的前端錯誤都要收）；在 test_route_guard_inventory.py 的豁免清單登記：「錯誤轉送：登入使用者或 Agent 通行證，各自只能送自己那個專案，大小與次數有上限」。
• 兩種身分、同一個標頭：使用者 JWT 與 Agent 通行證都放在 Authorization: Bearer。守門先讀 token 未驗章的 typ 欄只用來選路：typ 是 Agent 控制通行證 → 交給 jedi_remote_agent 的 agent_pass_required（驗 RS256 簽章、查 remote_agents 那列與租戶）；其他 → verify_jwt_in_request（過期仍回 TOKEN_401002 讓前端換發）。兩條路各自完整驗章，偽造 typ 只會換到另一條路的 401。current_agent_uid() 讓 service 分辨身分，使用者回 None。
• 這支守門放 common/authz、不放 jedi_iam.authz：jedi-iam 層級比 Agent 套件低，不能往上引用。Agent 套件在函式內延後 import，避免每個引用 common.authz 的模組都連帶載入它。
• route 只取 request.get_data(cache=False)，交給 app service；service 規則：

• 送往主機永遠取 SENTRY_DSN，專案 key 與編號取呼叫者那支外部 DSN：三個專案在同一個站台，內網位址只有一個；客戶端給的位址一律不採用，否則這支端點就是開放轉發器。
• 節流按身分：key ratelimit:error-tunnel:user:<user_id> 或 ratelimit:error-tunnel:agent:<agent_uid>，用 common/util/redis_rate_limiter.RedisRateLimiter.acquire。理由：要防的是某個登入者（或被盜的憑證）灌爆站台；全域上限會讓一個人的錯誤風暴擋掉其他人的回報。Redis 掛掉時放行並記一行警告——這層是防濫用不是授權，大小與目的地限制仍在。
• 錯誤碼新檔 common/code/error_tracking_error_code.py，前綴 ERT_：ERT_400001（envelope 格式錯）、ERT_400002（專案不符）、ERT_413001（太大）、ERT_429001（太頻繁）。FE error-code.json 同步四筆。
• test_security_shape_external_calls.py 白名單登記這支 requests.post：「部署設定 SENTRY_DSN（裝機寫入，內網）；envelope 的 dsn 與呼叫者專案不符即拒，不照請求轉」。
• test_version_module_no_error_tracking_endpoints.py 不動，必須照樣綠。
• CSP 不用改：瀏覽器只打同源 /api/1.0/...，大小落在全站 1m 內。

5.4.2 DSN 怎麼交給前端

決策 D4 要求「登入後才拿得到」。登入後前端必打的幾支（/users/me/capabilities、/user/web-menu、/license/status）都屬 jedi 套件，在套件回應塞錯誤追蹤欄位是把宿主關切塞進不相干的套件。故：

• 在 5.4.1 同一模組加 GET /api/1.0/error-tracking/config（只收使用者 jwt_required，登記豁免清單；Agent 通行證打它回 401），回 {"enabled": bool, "dsn": SENTRY_PUBLIC_DSN, "environment": ENV}；SENTRY_DSN 或 SENTRY_PUBLIC_DSN 空 → enabled=false 且不帶 dsn。
• 不回 release：前端 build 時已把 guidant-ai-fe@<版號>+<commit> 烙進常數 VITE_APP_RELEASE（vite.config.js），前端直接用它，出 image 腳本不用改。

5.4.3 FE 接線

• package.json 加回 @sentry/vue（版本照 FE 3a6f317f 那次的接法，取當下最新 10.x 修補版）。
• 邏輯集中在 src/config/errorTracking.js；main.js 只交代 app／router／token 來源。
• 不在 main.js 開頁就初始化。改為**userStore.loadCapabilities() 成功之後**呼叫 initErrorTracking()——登入、OTP、切租戶、F5 重載都會經過這裡，一處涵蓋；有防重複，換頁不會重新初始化。打 5.4.2 拿設定，enabled=false 就整支不載入 @sentry/vue（動態 import）。
• Sentry.init：dsn、environment、release: import.meta.env.VITE_APP_RELEASE、tunnel: '/api/1.0/error-tracking/tunnel'、sendDefaultPii: false、browserTracingIntegration({ router })、tracesSampleRate: 0、tracePropagationTargets: [/^\/api\//]（trace 標頭照 FR-071 的串接方式，讓前後端事件掛同一條 trace）。事件 tag 帶最近一次 API 回應的 request_id（axios 攔截器記下）。
• 拿掉 BrowserSession 整合：它每次換頁送一筆 session，登入一次就送 4～5 筆，吃掉轉送端點每人每分鐘的額度，站台也用不到。
• tunnel 請求要帶 Authorization：SDK 的 tunnel 用 fetch 不經 axios 攔截器，預設不帶 token。自訂 fetch 實作每次送出時才讀 token（換發後拿到新的，不在初始化時快取）。沒 token 或回 401 時回報成 429，讓 SDK 停送 60 秒，不會每個錯誤都再打一次必定失敗的請求。
• 登出（resetStore，全站唯一清 token 的地方）時 Sentry.close()，避免下一位使用者沿用前一位的 transport。
• initErrorTracking 整段 try／catch，掛不起來不影響前端。CSP 不用改（只打同源）。

驗收：登入後在 console 執行一段故意 throw 的程式 → 站台 guidant-ai-fe 專案出現該事件，release 為 guidant-ai-fe@<版號>+<commit>、tags 有 request_id、能點到同 trace 的後端事件（若同時觸發）；未登入 curl -X POST .../error-tracking/tunnel → 401；登入後送一個 dsn 指向別的 project id 的 envelope → 400；守衛測試全綠。

5.4.4 Agent 錯誤回報

D9 的外網客戶端路：Agent 連不到站台，經同一支轉送端點、帶自己的通行證送進 guidant-agent 專案。

BE：設定附帶在註冊與心跳回應

• 新檔 core/plugins/_agent_error_tracking.py，core/plugins/remote_agent.py::mount() 在 blueprint 掛上前疊 bp.after_request(...)。只對註冊與心跳兩支的 200 回應，在 data 補 error_tracking: {enabled, environment, dsn}；dsn 取 SENTRY_AGENT_DSN，它或 SENTRY_DSN 缺一 → enabled=false 且不帶 dsn（與轉送端點同條件）。
• 心跳也帶：已註冊的 Agent 升版後啟動時跳過註冊，只靠註冊回應會永遠拿不到設定。
• 不改套件：套件的 SchemaExtensions.response_enricher 插槽存在，但路由沒有呼叫它；錯誤追蹤是宿主關切，不塞進套件。
• 補欄位失敗只記 log，絕不讓註冊或心跳失敗（那會讓 Agent 掉線）。

Agent（evidence-agent 1.4.1）

• 回應的 error_tracking.enabled 為真且有 dsn 才 sentry_sdk.init，否則不載入 SDK；同一 dsn 只初始化一次，通行證與 agent_uid 每次回應都更新。
• release guidant-agent@<版號>+<commit 前 12 碼>；tag agent_id 用 get_global_scope().set_tag（2.x 的 set_tag 只寫當前執行緒，心跳執行緒設的 tag 其他執行緒的事件看不到）。
• 自寫轉送 transport：Python SDK 沒有前端的 tunnel 選項。envelope POST 到 <CLOUD_ENDPOINT>/api/1.0/error-tracking/tunnel，帶通行證，TLS 信任與註冊／心跳同一條；envelope 標頭補 dsn（SDK 預設不放，轉送端點靠它比對專案）。背景送、不擋呼叫端。401／403 → 記住被拒的那顆通行證，換新前不再送，不無限重試。送失敗只記 debug，避免離線時錯誤回報自己生出更多事件。
• 遮罩：Agent 釘的 jedi-common 版本太舊，不能依賴 jedi-log，規則複製進 Agent 並註明來源；另遮 log 訊息內嵌的 JSON、logentry／breadcrumbs、例外訊息三處。遮罩失敗丟事件不送。
• 出包整包收 sentry_sdk（Nuitka 不會自動收延後載入的 integrations）。
• 已知限制：註冊完成前拿不到設定，那之前的錯誤不回報。

升級順序：先升雲端（BE 要有轉送端點的雙身分守門與回應補欄位），再升 Agent。Agent 升級後靠心跳拿設定，不需重新註冊。

5.4.5 證據分類沙箱

D9 的內網路的例外形：沙箱刻意不連 DB／Redis／物件儲存，所以多給一個只看得到站台的網段。

• compose 新網段 guidant-sandbox-errors（internal: true），成員只有 guidant-sandbox 與 guidant-bugsink；沙箱原網段不動。
• 沙箱加 SENTRY_DSN: ${GUIDANT_SENTRY_DSN:-}（.env，安裝器寫入，與後端同一個 guidant-ai 專案）與 ENV。不讀 guidant.env：那份檔有 DB 與登入金鑰。
• 事件 tag app=guidant-classifier、release guidant-classifier@<版號>+<commit>。
• 套件 jedi-evidence-classification 1.6.4 不裝 jedi-log：那會把 Flask、SQLAlchemy 一整串帶進沙箱、加大攻擊面；改用同參數的單一初始化函式，遮罩規則從 jedi-log／jedi-common 複製並註明來源（含 Bearer 值規則）。
• 拆檔程式炸掉時回 HTTP 500，不讓連線直接斷；後端看到的仍是同一種「沙箱失敗」，站台收得到現場。
• GUIDANT_SENTRY_DSN 空時服務照常起，錯誤追蹤不啟用。

驗收：從沙箱內打 guidant-db／guidant-redis／guidant-seaweedfs／對外位址都不通，只有 guidant-bugsink:8000 通；沙箱觸發一次錯誤 → 站台 guidant-ai 專案出現 app=guidant-classifier 的事件，全文找不到共享密鑰。

5.5 子需求 D：診斷包改 canonical API

• infra/support/diag_event_fetcher.py：
  • base URL 由 SENTRY_DSN 推導（scheme＋host＋port，不含 DSN 的 project 段），沿用 _derive_base_url 的推導部分、拿掉顯式變數分支。
  • token 讀 BUGSINK_API_TOKEN（跨專案唯讀）。專案編號取 SENTRY_DSN、SENTRY_PUBLIC_DSN、SENTRY_AGENT_DSN 三者聯集（空的略過、重複去重），三個專案都撈。對外 DSN 的主機後端不一定連得到，只拿它的編號。
  • 每個專案 GET /api/canonical/0/issues/?project=<id>（依最後發生時間由新到舊）→ 依 last_seen 落在 [since, until] 篩；每個 issue 再取最近事件詳情（含堆疊）。
  • --request-id 有值：讀取 API 不能依 tag 篩（B0 實證，加什麼參數都回全部），所以逐 issue 拉事件詳情、客端比對 tags 的 request_id。為免請求暴增：請求總數上限 80、每個 issue 最多看 10 筆，超過即標「截斷」並寫進 manifest。fetch() 因此多一個 request-id 參數，由 diag_bundle_app_service 帶入。
  • 分頁跟回應的 next，MAX_PAGES／PAGE_SIZE／TIMEOUT_SECONDS 照舊上限。
  • 檔名 ARCNAME 改 events/bugsink-events.json；manifest 摘要欄位改用 Bugsink 的對應欄位（issue id、標題、等級、次數）。
  • 失敗訊息機制不變：沒 DSN、沒 token、連不上、401 各回帶白話原因的 UNAVAILABLE，不讓整包失敗。
• 移除 GLITCHTIP_BASE_URL／GLITCHTIP_ORG_SLUG／GLITCHTIP_API_TOKEN：先 grep 全 codebase 確認除本檔外無讀者；.env.sample 與 deployment-env.md 同步刪。
• infra/support/collector/host_collector.py 的 KNOWN_SERVICES 刪 glitchtip 四個、加 guidant-bugsink；staged_collector.py docstring 範例的 guidant-glitchtip 改 guidant-bugsink。
• ERROR_TRACKING_* 與 BUGSINK_API_TOKEN 名稱含 TOKEN，診斷包遮罩規則已會蓋掉 token 值；照樣在 T-D 驗包內 guidant.env 快照的這一行是遮罩後的值。

驗收：DEV 產一次 500 → RUN_MODE=diag python main.py --since 1h → 包內 events/bugsink-events.json 有該事件含堆疊、manifest 標「已取得」；拿掉 BUGSINK_API_TOKEN 重跑 → manifest 寫「未取得：沒有設定權杖」且其他內容照產；停掉 bugsink 容器重跑 → 「未取得：連不上」。

5.6 子需求 E：文件

用 T-V 出的新安裝包，兩台機各跑一次：乾淨機首裝、1.26.0 機升級。

版號註記：jedi-log 1.3.4 曾推上 Nexus，含開關但沒有 Bearer 遮罩；1.3.5 沒有位置參數遮罩。主專案釘 1.3.6，其他 consumer 不應釘 1.3.4／1.3.5——全收模式下 1.3.5 會把登入密碼送進站台。