指令碼開發 / 系統補丁

於 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 後，舊版本目錄中的補丁不會應用到新版本。請根據新版本程式碼重新確認補丁是否仍有必要和相容，並僅在獲得適用於新版本的補丁後，建立新的版本目錄。不要直接複製舊版本補丁到新版本目錄。