腳本開發 / 系統補丁

於 8.0.11 版本新增

系統補丁是一種按 DataFlux Func 版本替換運行文件的機制。將補丁文件和配置放入當前版本對應的目錄後，Server、Worker 和 Beat 會在各自啓動時，將補丁文件複製到指定位置。

系統補丁適合在暫時無法更換鏡像時應用經過確認的修復文件，不適合作為普通的代碼擴展或資源部署方式。如需安裝系統依賴或 Python 包，請使用腳本開發 / 預執行腳本等對應機制。

系統補丁會覆蓋 DataFlux Func 的運行文件

應用補丁前，請確認補丁來源、適用版本和目標路徑，並備份被替換的文件。錯誤的補丁可能導致 Server、Worker 或 Beat 無法正常運行。

1. 準備系統補丁

在「管理 / 關於」中確認當前 DataFlux Func 版本。系統只會讀取與當前版本名稱完全一致的補丁目錄，不會讀取其他版本的補丁。

系統補丁目錄如下：

環境	位置
容器內	`/data/resources/system-patches/{當前版本}/`
宿主機內	`{安裝目錄}/data/resources/system-patches/{當前版本}/`

例如，當前版本為 8.0.19 時，宿主機內的補丁目錄為：

Text Only
{安裝目錄}/data/resources/system-patches/8.0.19/

每個版本的補丁目錄必須包含 patch.yaml，補丁文件可以直接平鋪在當前版本目錄中，實際目標位置只需在 patch.yaml 中正確指定。例如：

Text Only
system-patches/
└── 8.0.19/
    ├── patch.yaml
    ├── example.json
    └── example.py

其中，patch.yaml 的 files 配置為「補丁文件名到目標路徑」的映射：

patch.yaml
files:
  example.py  : '@/worker/utils/example.py'
  example.json: /data/resources/example.json

配置中的路徑規則如下：

files 的鍵是當前版本補丁目錄內的文件名。文件必須存在於當前版本目錄中。
以 @/ 開頭的目標路徑相對於 DataFlux Func 應用根目錄。例如，@/worker/utils/example.py 表示應用目錄下的 worker/utils/example.py。
不以 @/ 開頭的目標路徑建議使用絕對路徑，避免相對路徑因運行目錄不同而產生歧義。
目標目錄不存在時會自動創建；目標文件已經存在時會被直接覆蓋，不會自動備份。

同一份 files 配置會由 Server、Worker 和 Beat 分別應用，不支持按服務篩選補丁。準備補丁時，應確保所有目標路徑都適用於這些服務的運行容器。

具有宿主機訪問權限時，可以直接將 patch.yaml 和補丁文件放入當前版本對應的宿主機目錄。

也可以使用「文件管理」上傳：

準備完成後，按照系統維護 / 升級和重啓重新啓動 DataFlux Func，使 Server、Worker 和 Beat 重新創建並應用補丁。

每個服務啓動時會依次進行以下處理：

如果當前版本目錄或 patch.yaml 不存在，服務會跳過系統補丁。patch.yaml 不是有效的 YAML 映射或缺少有效的 files 映射時，補丁處理會報錯並中斷對應服務的啓動。

單個補丁文件不存在、路徑無效或複製失敗時，系統會將該文件記錄為失敗並繼續處理其他文件，隨後繼續啓動服務。因此，服務成功啓動不代表所有補丁都已成功應用。

進入「管理 / 關於 / 系統工具」，點擊【查看系統補丁日誌】。

日誌按照版本和相近的應用時間分組，並展示以下信息：

應確認每個 Server、Worker 和 Beat 節點都有對應記錄，且所有補丁文件均顯示為成功。容器日誌中也會以 [SYSTEM PATCH] 開頭輸出每個文件的應用結果。

系統會在每次服務啓動時重新應用當前版本的補丁。因此，修改補丁文件或 patch.yaml 後，必須再次重啓 DataFlux Func 才會生效。

刪除補丁配置不會立即還原當前運行容器中已經被覆蓋的文件。對於 @/ 目標路徑，應刪除對應配置並重新創建相關服務，使其從原鏡像文件啓動；對於持久化目錄中的絕對目標路徑，還需要使用操作前的備份還原文件。

升級 DataFlux Func 後，舊版本目錄中的補丁不會應用到新版本。請根據新版本代碼重新確認補丁是否仍有必要和兼容，並僅在獲得適用於新版本的補丁後，創建新的版本目錄。不要直接複製舊版本補丁到新版本目錄。