跳轉到

Guidant AI v1.15.0 Release Note

項目 內容
版本 1.15.0（功能版號；主軸＝落地版交付三部曲收官——編譯打包／防竄改／客戶自裝安裝器）
發布日期 2026-08-19
上一版本 1.14.0（2026-08-10）
涵蓋區間 2026-08-10 ~ 2026-08-19
涵蓋需求 FR-063 Nuitka 落地版打包（統一入口／編譯管線／image 出貨）＋ FR-064 防竄改偵測與授權鎖定（分層 manifest／簽章／啟動 gate／執行期抽查／lockdown 殼／離線解鎖）＋ FR-065 落地版 Installer（full-stack compose／DB init／install.sh／Web 設定精靈／升級回滾／SeaweedFS 出廠即啟用／客戶安裝手冊）＋ FR-050 雜項與合規修補
規模 BE 194 commits（feat 67／fix 25／docs 79／chore 23）；FE 對應 commits；jedi 套件 3 支發版（jedi-file-upload 0.0.22、jedi-project 0.0.8、jedi-oscal-v2 2.2.3）；DB migration 10 支
適用部署 dev（已驗）；STG／POC 尚未上版（本版為落地版出貨版本，三環境上版與 migration 補套見 §5、§8）
部署性質 含 10 支 DB migration（DEV 已全數套用；STG／POC 待補，見 §5）。新增出貨形態：落地版 tar bundle（客戶端 install.sh 一鍵安裝，見 §8）。物件儲存預設改為內建 SeaweedFS（出廠即啟用，取代 MinIO 選配）。移除 PyMuPDF（AGPL-3.0）授權相依。

0. 發版前回歸 gate

本版未執行 site-regression 自動 Core gate。放行依據為決策者於 188 落地版裝機環境的逐輪實測驗收——FR-065 全程共三輪裝機實測，每輪針對當輪修補項逐項複驗（root admin 建立與登入、SMTP/LDAP 下放、儲存設定頁、SeaweedFS 上傳下載、install log、升級四步等），問題以 Notion 卡回修後重裝複驗至通過。自動化 gate 待落地版 E2E 套件補齊後於後續版本恢復。

1. 概述

v1.15.0 是落地版（on-premise）交付能力的收官版本。在此之前，產品只能由原廠工程師手動部署；本版之後，客戶拿到一個 tar 檔就能自行完成安裝、開通與升級。

三個前後相依的需求構成完整交付鏈：

  1. FR-063：把 Python 原始碼編譯成機器碼（Nuitka），產出不含原始碼的 image——能出貨。
  2. FR-064：對出貨產物蓋簽章、啟動時驗章、執行期抽查，被竄改就鎖定——出貨後安全。
  3. FR-065：把 image 包成客戶可自裝的 bundle，附安裝器、Web 設定精靈、升級流程與客戶手冊——客戶自己裝得起來。

同期完成物件儲存從 MinIO 換為內建 SeaweedFS（出廠即啟用），以及 PyMuPDF（AGPL-3.0）的授權合規替換。

2. 重點新功能

2.1 FR-065 落地版 Installer（本版主軸）

產品 compose 全 stack：PostgreSQL／Redis／BE api＋socketio／FE nginx／SeaweedFS 六服務一次起，單一入口 443，BE 埠收進內網。HTTPS 憑證由 install.sh 裝機當下產生 per-install 自簽（客戶可覆蓋為正式憑證）。

DB 初始化：分段 SQL 腳本＋one-shot init 容器，最高權限憑證只存在建庫當下，服務容器僅持 cm_app 憑證。init 內含 schema／權限／RLS／字典 seed／CMMC 2.0 框架資料與框架 PDF，客戶不需自行匯入。

install.sh 安裝器：環境檢查（OS／Docker／machine-id／磁碟／埠）→ image 載入含 sha256 digest 驗證 → 產生 8 組獨立憑證（只寫設定檔不上畫面）→ 建庫 → 起服務 → 印出設定精靈網址與一次性 setup token。另含維運子命令：status／restart／logs／credentials [--export]／rotate-credentials／fingerprint／uninstall。全程輸出落檔 <資料目錄>/log/install-*.log（自動遮蔽密碼類鍵值，setup token 不落檔）。

Web 設定精靈：首次開站引導建立客戶第一個業務租戶與租戶管理員（密碼客戶自設、不經終端留痕），並顯示機器指紋供申請授權檔。

升級與回滾：install.sh --upgrade 四步（備份 → 載入新 image 含 digest 驗證 → 套增量 migration → 換版重啟），資料保留；同版號重套需明示 --force（CM-1302）。回滾＝restore 備份＋回舊 tag，定位為災難逃生非常規操作。

出貨 bundle：build_bundle.sh 產出含全部 image tar、compose、install.sh、客戶手冊、GCB 公版基準 8 支、框架 PDF storage-seed 的 tar.gz，附 manifest digest。缺 PROD 簽章鑰時預設拒絕產包（內測包需明示 --skip-prod-key-check）。

客戶安裝手冊：docs/user-manual/onprem/ 11 章，涵蓋安裝／開通／升級／回滾／排錯／維運子命令，隨 bundle 出貨。

2.2 物件儲存改為內建 SeaweedFS（FR-065.5）

MinIO 社群版閉源化後改採 SeaweedFS：jedi-file-upload 新增 SEAWEEDFS 正式儲存類型（S3 gateway 與既有 adapter 全相容），產品 compose 常駐該服務，root tenant 與預設 STORAGE_CONFIG 出廠即指向它。精靈與後台兩個建租戶入口都會繼承 root 的儲存設定（避免業務租戶檔案落 tmpfs 蒸發）。系統檔（框架 PDF）隨 bundle 出貨、安裝時原 key 灌回。MinIO 選配段移除；minio 類型保留供客戶自備 S3 相容儲存切換。

2.3 root tenant 定位與系統殼帳號

root tenant 定位為原廠管理的系統殼：root admin 由 DB init seed 建立（只存 bcrypt hash，明文不入版控）、is_super_admin、掛 root Administrator 角色，並具不可刪除保護（刪除／停用／降權四個入口一律 403，只允許改回啟用）。密碼豁免 90 天強制改密政策。客戶側的第一個業務租戶與管理員由設定精靈建立，兩者互不混淆。

2.4 郵件（SMTP）與 LDAP 設定管理下放

這兩頁的管理權下放給業務租戶（能力點 is_platform 翻轉，扣除式授權自動涵蓋兩個建租戶入口），但設定本身維持全系統共用一組——讀寫兩端一律落 root 那一列。其餘 system_configs（storage、通知等）維持 tenant-scoped 不受影響。

2.5 FR-064 防竄改（前置，本版隨落地版一併出貨）

分層 manifest → 簽章 → 啟動 gate → 執行期抽查 → 雙落點事件記錄 → lockdown 殼 → 離線 unlock 的完整鏈路；含容器 machine-id 指紋錨定與 tamper 終止的承載分流處理。

3. 重要修補

  • PyMuPDF（AGPL-3.0）移除：PDF 讀取改走 pdfplumber + pypdfium2 既有棧，新增 pdf_backend.py shim 統一介面；連帶 jedi-project 0.0.8 拔除誤留宣告，lock 內 pymupdf 歸零（授權合規硬前置，CM-1235）。
  • 登入間歇失敗（P0）：user_context ContextVar 跨請求殘留，導致無 JWT 的登入請求在 gunicorn 承載下有機率讀到前一請求的 RLS 脈絡，root admin 被 RLS 藏起而回「使用者不存在」。修法為請求級 auth context 隔離（before_request／teardown 各歸零一次）。
  • 容器指紋每次重啟就變（P0）：Debian base image 的 /etc/machine-id 是空檔會退回隨機 MAC，改掛載宿主 machine-id。
  • tamper 終止無效：killpg 打不到容器 PID 1，改依承載送訊號。
  • 儲存設定頁欄位全空：FE 綁舊 minio_* 鍵名與 DB 通用鍵不符，且空值會覆寫回 DB；鍵名正規化＋防空值覆蓋＋系統內建儲存資訊條。
  • 共用設定儲存恆失敗：root 寫入器 SQL 引用不存在的稽核欄位；同時補齊讀取端落 root（先前只修寫入端，業務租戶開頁仍空白）。
  • install.sh 修補：改用 sudo 執行、偵測既有安裝、資料目錄改名 /srv/guidant-ai、資源門檻改警告、compose up 掛住防護、憑證管理三件（查看／匯出／輪換）。

4. Breaking Changes

  • 物件儲存預設變更：新安裝出廠即使用內建 SeaweedFS。既有部署不受影響（設定不動即維持原後端）；若客戶自行切換儲存後端，系統檔（框架 PDF 等）會立即讀取不到——system-scope 檔案讀取走當下 root STORAGE_CONFIG，不看檔案自記類型。手冊已收錄警語章；遷移工具列為後續（CM-1279）。
  • BE 部署路徑標準名：改為 /opt/guidant-ai-be（AGENT_CERT_DIR 預設與部署文件同步）。
  • debug view 移除：debug_org_units／v_tenant_parent_debug 確認零引用後於全環境刪除。

5. DB Migration（10 支）

檔名 內容
2026-08-14-fr063-1g-runtime-config-seed.sql RUNTIME_CONFIG 營運參數 seed
2026-08-15-fr064-3-integrity-tamper-events.sql 防竄改事件表
2026-08-17-fr065-t20-shipping-baseline-cleanup.sql 出貨基線清理
2026-08-17-fr065-t20b-baseline-clear-operation-traces.sql 基線操作痕跡清除
2026-08-17-fr065-t22-baseline-drop-legacy-product-rows.sql 舊產品線殘留列移除
2026-08-17-fr065-t23-drop-debug-views.sql debug view 移除
2026-08-18-fr065-t2x-baseline-function-labels.sql FUNCTION 標籤依 ui_routes 重建
2026-08-18-fr065-t52-storage-type-menu-seaweedfs.sql 儲存類型選單加 seaweedfs
2026-08-18-fr065-t5x-baseline-framework-pdf-repair.sql 框架 PDF 資料列修復
2026-08-18-cm1283-smtp-ldap-capability-delegation.sql SMTP/LDAP 能力點下放（is_platform 翻轉）

套用狀態：DEV 已全數套用。STG／POC 待補——除本版 10 支外，另有前版遺留三支需一併補套：fr058-22／fr063-1g／fr064-3。上版時依 sql-migration skill 流程處理。

6. 相依套件版本

套件 版本 變更
jedi-file-upload 0.0.22 新增 SEAWEEDFS 儲存類型＋批次刪檔修補
jedi-project 0.0.8 拔除誤留的 pymupdf 宣告
jedi-oscal-v2 2.2.3 —
jedi-auth 0.1.34 未變
jedi-common 0.0.30 未變
PyMuPDF — 移除（AGPL-3.0 授權合規）

7. 部署順序（既有環境）

  1. 套用 §5 migration（DEV 已完成；STG／POC 依序補套，含前版遺留三支）
  2. 部署 BE（含 jedi 套件更新）
  3. 部署 FE（版號同步 1.15.0）
  4. 驗證：登入、儲存設定頁、SMTP/LDAP 設定、框架 PDF 預覽

8. 落地版出貨（新增交付形態）

出貨包產製（於 build 機）：

cd /opt/guidant-ai-be && git pull
scripts/build/build_all.sh --all        # BE(Nuitka)＋FE＋init 三顆 image
scripts/build/build_bundle.sh           # 產 guidant-ai-1.15.0.tar.gz

PROD 簽章鑰為硬前置：public_keys.py 目前含 DEV／STG／POC 三把，出貨前須完成四步（LC 端生成 PROD 鑰對 → 公鑰加入 public_keys.py → 重 build BE image → 用含鑰 image 重打包），缺一會導致客戶匯入授權檔時報「未知的 kid」。內部測試包可帶 --skip-prod-key-check（產出不可交付客戶）。

客戶端安裝／升級流程見 docs/user-manual/onprem/（隨 bundle 出貨）。

9. 已知 follow-up

項目 卡號 說明
正式真機驗收（縮減版） CM-1264 全鏈一輪＋PROD 鑰窄驗證＋兩個負面案
儲存後端遷移工具 CM-1279 切換 storage 時搬移既有檔案（含系統檔）
服務 log 轉拋 CM-1274 Fluent Bit sidecar＋UI 設定轉拋目標
使用手冊下載端點 CM-1204 MANUAL_FILENAME 未定義（死碼，待裁是否活化）
root admin 密碼形態 — 現為固定式；per-install 隨機生成留 PRD 出貨前再議
Agent 原生安裝包 CM-1284 系列 FR-066，本版後啟動（非 docker，Nuitka 單檔＋tarball＋systemd）

10. 相關文件索引

  • FR-063：docs/features/FR-063-2608-nuitka-packaging/（含 deployment-env.md env 契約）
  • FR-064：docs/features/FR-064-2608-tamper-detection/（含解鎖 SOP 雙份）
  • FR-065：docs/features/FR-065-2608-onprem-installer/（design.md §2 決策表／§4 詳細設計／§5 拆分表；handoff/ STATE＋LOG）
  • 客戶安裝手冊：docs/user-manual/onprem/
  • 出貨基線與 seed 產製：scripts/init/README.md（🔴 改基線庫必跑 gen_seed_sql.sh regenerate）