FR-198 · 討論稿(第二輪:CI 調整)· 2026-11-16

包版前把能驗的都驗完

包版只負責組裝;失敗時不必等 30 分鐘的編譯與打包

1.32.0 出版按了 8 次,多數錯誤要等編譯、打包約 30 分鐘後才看得到。這一輪把不需要編譯產物的檢查全部搬到 pipeline 第一步,並整理 scripts/、Release 頁附件與沙箱的歸屬。本稿列出已裁定的方向、改完後的流程與時間、拆卡與批次,給決策者看過再開卡。

已裁定 13 項 待確認 3 項 12 張卡 4 批(含 6 張既有卡)

包版前把能驗的都驗完

分工概述

這一輪的目標只有一句:發版 pipeline 第一步就把所有不需要編譯產物的檢查跑完,包版之後只剩「要有產物才驗得出來」的三件事(冒煙測試、演練、上架)。改完後,SQL、名單、白名單、公鑰、第三方映像這類錯誤會在第一步的 10~12 分鐘內失敗,修完重打 tag 只損失這段時間,不必再等編譯與打包。

工作分四批,每批的卡可以同時跑:

批 做什麼 完成怎麼判定(決策者檢查法)
1 SQL 套 STG 資料提前到第一步;第三方映像補弱掃;出版前檢查改版;測試版發布同步套件環境;Agent 分支參數化;套件 repo CI 修綠 用一個測試 tag 跑正式發版到第一步為止:log 裡看得到「逐表筆數比對」與 postgres/redis/seaweedfs 的弱掃結果;本機跑 release_precheck.sh 不再出現重開機那項、多一項升級路徑
2 演練改版(名單自動推、不再因 SQL 強制、冒煙沿用臨時庫);打包前檢查搬到第一步;前端套件清單只產一份;閘道刪殘留 同一個測試 tag 再跑一次:第一步多出「公鑰、第三方釘版、弱點資料包」三項;打包 job 時間比 1.32.0 的 12.8 分短;演練不勾也能發(有 SQL 時不再被擋)
3 Release 頁附件收成總表+zip 打開 GitLab Release 頁,只看到 vuln-summary.md 與一包 zip;zip 打開有 README
4 scripts/ 整理搬遷 scripts/ 根目錄只剩說明檔與子資料夾;scripts/build/ 分成 ci/lib/probe/config;跑一次測試版發布全綠

依賴:批 2 用到批 1 抽出的共用腳本;批 4 搬路徑會動到前面每一張卡的檔,所以排最後。沙箱搬出套件 repo 等決策者開好 guidant-sandbox repo 後另外開卡,不在這四批內。

1. 問題在哪

1.32.0 正式發版的實測時間(pipeline 3070346817):第一步 2.8 分 → 前端 4.1 分(同時跑)→ 編譯+冒煙+建映像 16.9 分 → 打包 12.8 分 → 簽署、上架約 4 分。另外演練一次約 19 分。

出版當天失敗 8 次,按原因分三類:

  • 第一步就能知道,卻到後段才失敗:逐表筆數名單漏 4 張、起點填錯、章的新舊、白名單只複查一層。這類錯誤的檢查只需要 SQL 檔、設定檔或 lock 檔,不需要編譯產物,卻排在演練或打包裡。
  • 演練腳本自己的錯:讀加密設定兩處舊假設。演練腳本從 tag 讀,修了只能重打 tag 整條重跑。
  • 主機環境:188、190 核心更新後沒重開。修法是重開後重試那個 job,不用重打 tag。

第一類是這一輪要解決的。第二類的根本解(只改發版腳本時不重編)這輪先不做,見第 6 節。

2. 改完後的流程

%%{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','fontSize':'18px'},'fontSize':18,'flowchart':{'useMaxWidth':false,'nodeSpacing':44,'rankSpacing':52,'padding':14},'sequence':{'useMaxWidth':false,'messageFontSize':17,'noteFontSize':16,'actorFontSize':18,'width':150,'height':64,'messageMargin':52,'boxMargin':14,'actorMargin':30,'mirrorActors':false}}}%%
sequenceDiagram
    autonumber
    actor P as 決策者
    participant V as 第一步 verify
    participant F as 前端 pipeline
    participant B as 編譯與冒煙
    participant K as 打包
    participant R as 演練(預設勾)
    participant U as 簽署、上架
    P->>V: 打 tag、手動觸發
    Note over V: 預檢、守衛、套件弱點
    Note over V: SQL 套 STG、逐表筆數
    Note over V: 第三方弱掃、公鑰、釘版
    V->>F: 成功後觸發
    V->>B: 同時開始編譯
    Note over B: 冒煙沿用臨時庫
    B->>K: 映像建好
    Note over K: 自家映像弱掃、壓縮
    K->>R: 打好的安裝包
    R->>U: 升級演練通過
    U-->>P: 發布完成
圖 1 改完後的正式發版流程。第一步承接所有不需要編譯產物的檢查,包版後只剩冒煙、演練、上架。

第一步的三個註記中,後兩個(SQL 套 STG、第三方弱掃與公鑰釘版)是這一輪新增的內容;圖太寬時可點圖放大。第一步任何一項失敗,後面全部不跑;修完重打 tag,損失的只有第一步這 10~12 分鐘。

演練仍在打包之後,因為它要拿真的安裝包升一次。這一輪把演練改成預設勾選但不強制:有 SQL 時不再因此必須演練(SQL 已在第一步驗過),但升級程式(scripts/installer/)在 1.29.0~1.32.0 四版中有三版有改,多數版本仍值得跑。

3. 時間預估

情境 1.32.0 實測 改完(推估)
一次就過、不演練 約 50 分 約 47 分
一次就過、有演練 約 70 分 約 66 分
SQL/名單/白名單/設定類錯誤,多久才失敗 30~70 分後 10~12 分內

一次就過的總時間差不多,改變的是失敗發生在哪裡。第一步會從 2.8 分變長到約 10~12 分:SQL 套 STG 資料約 2 分(依 build 階段冒煙臨時庫實測:dump 12 秒、還原 48 秒、套 SQL 2 秒)、第三方映像弱掃約 2~3 分、打包前檢查搬來約 1.5 分。這三個數字是推估,批 1、批 2 的卡要回寫實測時間。

4. 已裁定的事項

以下是 2026-11-16 討論中決策者已裁定的內容,開卡時直接照做。

檢查搬到第一步

  • SQL 套在 STG 資料上並逐表比對筆數,提前到第一步,強制、不能關。
  • 打包階段不需要產物的檢查搬到第一步:發布公鑰、第三方映像釘版、弱點資料包、tpm2 安裝檔。打包時保留既有的檢查(那時才確定真正出貨的是哪一顆),兩處重複驗一次。
  • 第三方映像 postgres、redis、seaweedfs 補弱掃。正式發版、每日掃描、出版前檢查目前都沒有掃這三顆;隨安裝包出貨的第三方映像只有 bugsink 有掃。

演練

  • 預設勾選、不強制。rehearse_gate.sh 目前「有 SQL 就強制」的規則拿掉,起點不可低於可直升起始版的檢查保留。
  • 允許變多的表名單改成讀這版 SQL 的 INSERT 自動推出,手寫名單只留「服務運作會寫」的表(api_logs、通知佇列這類)。
  • 臨時庫在第一步建一次,編譯後的冒煙測試沿用,不建第二次。

出版前檢查(本機跑的那支)

  • 拿掉「主機要不要重開」:不是我們能控制的。核心更新後沒重開,安裝程式本身仍會擋升級、容器也起不來,修法是重開後重試該 job。
  • 補「現場版本升到這一版會不會被安裝程式擋」:主系統低於可直升起始版、Agent 1.7.4 以前被 rootless 守門擋。

其他

  • 前端套件清單(SBOM)只產一份:後端改拿前端 pipeline 判定過的那份放進安裝包,不自己再產。
  • GitLab Release 頁 32 個附件收成兩個:vuln-summary.md 加一包 security-reports-<版號>.zip,zip 內照類型分資料夾並附 README。安裝包的 sbom/ 也補 README。
  • scripts/ 整理:build/ 分 ci(CI 直接呼叫的入口)/lib(只被其他腳本呼叫)/probe(冒煙探針)/config(人會改的名單);根目錄 5 支發版用的移進 build/;migrate_encryption_keys.py 移到 init/;疑似沒人用的先移 archive/,不刪;每個子資料夾一份 README。
  • 沙箱搬出套件 repo 成為 guidant-sandbox:決策者開好 repo 後搬遷,映像名稱 evidence-classifier 不改、版號從 2.0.0 起,開發機同行程拆檔刪掉。不在本稿四批內。

5. 拆卡與批次

12 張卡,其中 6 張是既有卡(CM-3953~3958)改寫範圍後沿用,6 張新開。表內「批」是工作坊同時派的那一組;同一批的卡不改同一支檔、不依賴對方的產出(handoff/plan_v2.py 已用程式檢查)。

批 卡 做什麼 Repo 既有卡
1 A1 SQL 套 STG 資料+逐表筆數提前到第一步,抽出共用的筆數比對腳本 主系統 CM-3953
1 A2 第三方映像(postgres/redis/seaweedfs)補弱掃 主系統 新開
1 A3 出版前檢查:拿掉重開機、補升級路徑 主系統 新開
1 A4 測試版發布第一步同步 188 套件環境 主系統 CM-3955
1 A5 Agent 出版的 update-center 分支改成 pipeline 參數 Agent CM-3956
1 A6 套件 repo CI 修到會綠 套件 CM-3957
2 B1 演練:名單自動推、不再因 SQL 強制、冒煙沿用臨時庫 主系統 CM-3954
2 B2 打包前的檢查搬到第一步 主系統 新開
2 B3 前端套件清單改用前端 pipeline 的那份 主系統 新開
2 B4 jedi-ai-gateway 刪掉殘留的沙箱掃描 client 套件 CM-3958
3 C1 Release 頁附件收成總表+zip,安裝包 sbom/ 補 README 主系統 新開
4 D1 scripts/ 整理搬遷 主系統 新開

排序理由:

  • A1 先做:它抽出的筆數比對共用腳本,B1 演練要用;B2 也要在第一步的同一段加檢查,A1 先把那段的位置定下來。
  • B3 排在 A2 後:兩張都改 sbom.sh。
  • C1 排在 B2 後:兩張都改 build_bundle.sh。
  • D1 最後:搬路徑會動到前面每張卡改過的檔,提早做會讓其他卡全部撞檔。搬完要跑一次測試版發布確認全綠。

6. 這一輪不做的

  • 只改發版腳本時不重編:前天演練腳本錯了兩次,每次都要重編 30 分。根本解是正式發版也能沿用上次編好的映像,但要先確認映像跟這次 tag 的產品程式是同一份、而且 188 上那顆沒被別條 pipeline 覆蓋,需要另外設計。這一輪把大部分錯誤搬到第一步之後,這題的急迫性降低,之後另外討論。
  • 把建置時的作業系統套件釘死:自家映像裡包版前無法預知的只剩 Dockerfile 的 apt-get upgrade/apk upgrade 這一層。要提前就得先建一顆「基底+作業系統套件」的映像並釘版,改動 Dockerfile 與基底更新流程,另開題目。
  • build 機與 STG 分開、下載網址改用固定網域、舊章私鑰匯入 KMS:FR-198 STATE「待討論」裡的其他題目,維持原狀。

7. 待確認

D1 批 1 的第一步要不要先用測試 tag 驗一次

第一步的改動只有正式發版會跑(測試版發布走另一條路),出錯要到下一次正式發版才看得到。1.32.0 當天的預檢網址錯誤就是這樣漏掉的。

建議:批 1 合回後,打一個 v0.0.0-precheck 之類的測試 tag 跑正式發版到第一步為止,看到第一步全綠就取消,不往後跑。tag 用完刪掉。

D2 第一步的時間上限

第一步會從 2.8 分變長到約 10~12 分。實測如果明顯超過,要不要把第三方映像弱掃改成和前端 pipeline 同時跑(不擋編譯開始,但擋打包)?

建議:先照本稿做,A1、A2 回寫實測時間;超過 15 分再調整。

D3 六張既有卡怎麼處理

CM-3953~3958 的範圍在這一輪有變(例如 CM-3954 多了「不再因 SQL 強制」與「冒煙沿用臨時庫」,CM-3955 只剩測試版發布一條線)。

建議:沿用原卡,卡上 append 一段「範圍調整」寫明新範圍並改 Stage,不另開新卡;理由是卡號與歷史回寫留在同一張卡比較好追。