手冊首頁 ／ Release Notes ／ Guidant AI v1.6.0 Release Note

Guidant AI v1.6.0 Release Note

項目 內容
版本 1.6.0（功能版號；FR-039 分散式檔案 agent + cloud↔︎agent 認證 v2）
發布日期 2026-06-19
上一版本 1.5.0（2026-06-18）
涵蓋區間 2026-06-18 ~ 2026-06-19
規模 FR-039 分散式檔案 agent（evidence-agent 客戶端落地 + 雲端 RemoteAgentAdapter）+ 認證 v2（自我註冊 / CA 簽發 / mTLS / 短效 JWT / 設備指紋 / 身分模型 v3），跨 BE + evidence-agent + FE 三 repo
適用部署 dev / staging（staging 已於 2026-06-19 套用 9 支 FR-039 migration）；poc / prod 待辦
部署性質 非破壞（加表 / 加欄，無 drop）。新增「正式一律 mTLS」的 agent 部署：需雲端 PKI + agent docker（nginx mTLS sidecar）。AGENT_AUTH_MODE=none 維持現狀 demo、不破既有行為。

1. 概述

v1.6.0 是 FR-039 分散式檔案 agent 整個大弧的發版：把證據檔案的儲存從雲端拉出、落地到客戶自有設備（evidence-agent），雲端依租戶呼叫對應 agent，binary 不存雲端磁碟；並把 cloud↔︎agent 從「demo 無認證」升級成正式的 mTLS + 短效 JWT + 設備指紋認證。

  • 資料面（檔案）：雲端新增 RemoteAgentAdapter，把上傳/下載/刪除/預覽轉發到客戶端 agent 的 /blob*，含 SHA-256 雙邊對帳防竄改。
  • 控制面（認證）：agent 開機算設備指紋 → 自我註冊（送 CSR、雲端 CA 簽 server 憑證回傳）→ 定期心跳；穩態資料面走 mTLS + 綁定短效 JWT + 設備指紋驗證。
  • 身分模型 v3：agent 身分鍵改用「伺服器發、agent 持久化的 agent_uid」（對齊 osquery / Teleport / SPIRE），設備指紋降為可更新屬性 → 換硬體不冒新列、不需人工 rebind。
  • 部署一律 mTLS：evidence-agent/deploy/ 提供 docker compose + nginx mTLS sidecar + 完整操作手冊（deploy/README.md）。

2. 重點新功能

2.1 雲端 RemoteAgentAdapter + remote_agent registry（FR-039 Phase 2/3）

  • 新 storage backend remote_agent：storage-config 指向 per-tenant 的 agent（agent_uid），雲端 RemoteAgentAdapter 實作 IUploadFileProvider，把檔案操作 relay 給客戶端 agent。
  • compliance.remote_agents registry（per-tenant RLS）+ 管理 CRUD；SHA-256 雙邊對帳（上傳交叉比對 + 對帳 endpoint），偵測傳輸/靜態竄改。
  • 取回/刪除走「檔案自己記的 agent」（upload_files.path），不靠當下 session 的 storage-config → 下載/預覽（瀏覽器導頁無 tenant context）也能打到檔案真正所在的 agent。

2.2 cloud↔︎agent 認證 v2（mTLS + JWT + 指紋）

  • 自我註冊 + 憑證簽發：POST /agents/register（token + CSR → 雲端內部 CA 簽 server 憑證回傳）、POST /agents/heartbeat（online 由 last_seen 推算）。
  • 註冊 token：per-tenant 一組，存 sha256、明文僅產生時回傳一次，可重生/撤銷。
  • 資料面：mode=full 走 https + mTLS（雲端 client 憑證）+ 綁定短效 JWT（RS256，aud=agent_uid / bound_fp / tenant_id）+ 比對 X-Agent-Fingerprint + 擋 status=revoked。
  • 撤銷：status=revoked + JWT 短效 → 標記後幾乎即時失效。
  • AGENT_AUTH_MODE（none|full）全程包覆：none 維持現狀 demo，full 啟用整套。

2.3 身分模型 v3（決策 B）

  • 身分主鍵 device_fingerprint → 伺服器發的 agent_uid（agent 持久化）；指紋降為可更新屬性。
  • 換硬體 → register/heartbeat 自動更新指紋 + 記稽核（FILE_AGENT_FINGERPRINT_CHANGED 6082），不冒新列。
  • 平台刪該列 → heartbeat 回 404 → agent 自動重新 enroll。
  • 取捨理由：docs/analysis/2026-06-19-fr039-agent-identity-v3-uid-vs-fingerprint.md。

2.4 部署（evidence-agent）

  • deploy/ docker compose 雙模式（local / minio）+ nginx mTLS sidecar（profile=full）+ collect-host-id.sh。
  • 完整操作手冊 evidence-agent/deploy/README.md（架構 / 雲端 PKI / 註冊 / 啟動順序 / 驗證 / 維運 / 常見錯誤對照）。

3. 重要修補

  • 資料面 mTLS（I2 實測抓出）：httpx 0.28 request(cert=) TypeError、Client(cert=) 靜默不送 client 憑證 → 改自建 ssl.SSLContext + load_cert_chain（唯一能送 client 憑證的方式）。
  • 下載抓錯 agent：下載/預覽端點無 tenant context → storage-config 抓到別租戶 agent → 改走檔案自己記的 agent。
  • _https_base：full 模式非 https 的 agent base_url 明確報錯（FILE_AGENT_500005），不再硬轉 https 製造 WRONG_VERSION_NUMBER。
  • 刪程序書孤兒/FK：刪程序書時連實體檔一起刪、先刪 pool 紀錄再刪實體（避免 FK violation + 儲存後端孤兒）。
  • FR-038 收尾：資源庫範本 AO 讀回（part_id _obj.N 當 AO 識別碼）。

4. Breaking Changes

  • 無破壞性 schema 變更（純加表/加欄）。
  • 行為面：正式部署改為 一律 mTLS（AGENT_AUTH_MODE=full）；none 僅供測試。既有 local/minio 儲存不受影響。

5. DB Migration

STG 已於 2026-06-19 依序套用以下 9 支（poc/prod 待辦）：

  1. 2026-06-18-fr039-file-agents-table.sql
  2. 2026-06-18-fr039-storage-type-remote-agent-menu.sql
  3. 2026-06-19-fr039-upload-files-add-sha256.sql
  4. 2026-06-19-fr039-file-agents-rls.sql
  5. 2026-06-19-fr039-file-agent-manage-permission.sql
  6. 2026-06-19-fr039-rename-file-agents-to-remote-agents.sql
  7. 2026-06-19-fr039-agent-type-menu.sql
  8. 2026-06-19-fr039-remote-agents-auth-columns.sql
  9. 2026-06-19-fr039-agent-enroll.sql

套用：psql --single-transaction -v ON_ERROR_STOP=1 -f <檔>（cmmgr）。非破壞，但仍建議 app 與 DB 同版上線。

6. 相依套件版本

  • jedi-file-upload 0.0.17（pin；SHA-256 對帳 + 開機自癒補 upload_files.sha256 欄）。
  • 其餘 jedi-* 維持 v1.5.0 版本。

7. 部署順序

  1. DB：poc/prod 套用上述 9 支 migration（dev/stg 已套）。
  2. BE：scripts/gen_agent_dev_pki.py 產 PKI → .env 填 AGENT_* + AGENT_AUTH_MODE=full → 重啟 BE。
  3. evidence-agent（每台客戶 server）：依 evidence-agent/deploy/README.md（build image → .env → collect-host-id.sh → up file-agent 完成註冊 → --profile full up nginx）。⚠️ agent 重新註冊後一定要 restart nginx。
  4. FE：版本對齊 1.6.0。

8. 已知 follow-up（非阻塞）

  • MinIO 持久化：agent ↔︎ 客戶 MinIO 環境設定（非本 code）。
  • agent 心跳 client 憑證：同 httpx 0.28 議題（控制面走 http 不受影響；改 mTLS https 才需比照 SSLContext）。
  • evidence-agent 安裝精靈（install.sh）：設計 + 計畫已完成，實作待後續版本。

9. 完整 changelog 索引

  • docs/changelog/2026-06-19-fr039-agent-auth-v2-be.md（feat：B1~B6 / I1 / v3）
  • docs/changelog/2026-06-19-fr039-dataplane-mtls-download-i2-fixes.md（fix：I2 資料面）
  • 更早 FR-039 storage/registry 主題見 docs/changelog/ 2026-06-18 起各篇 commit message。

10. 相關文件索引

  • 設計：docs/features/FR-039-2606-distributed-file-agent/design-agent-auth.md、design.md、implementation-plan.md
  • 決策：docs/analysis/2026-06-19-fr039-agent-identity-v3-uid-vs-fingerprint.md
  • 收尾：docs/features/FR-039-2606-distributed-file-agent/handoff/2026-06-19-agent-auth-v2-SUMMARY.md
  • 部署手冊：evidence-agent/deploy/README.md
Guidant AI 功能 SPEC 手冊 current（持續更新中）｜本頁由 render_html.py 產生，內容源：specs/current/release-notes/v1.6.0.md