脚本开发 / 系统补丁

于 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 后，旧版本目录中的补丁不会应用到新版本。请根据新版本代码重新确认补丁是否仍有必要和兼容，并仅在获得适用于新版本的补丁后，创建新的版本目录。不要直接复制旧版本补丁到新版本目录。