Skip to content

Script Development / System Patches

Added in version 8.0.11

System patches are a mechanism for replacing runtime files according to the DataFlux Func version. After placing patch files and configuration into the directory corresponding to the current version, Server, Worker, and Beat copy the patch files to the specified locations when each of them starts.

System patches are suitable for applying verified fix files when you cannot replace the image temporarily, not as a general code extension or resource deployment method. If you need to install system dependencies or Python packages, use corresponding mechanisms such as Script Development / Pre-run Scripts.

System patches overwrite DataFlux Func runtime files

Before applying a patch, verify the patch source, applicable version, and target path, and back up the files to be replaced. An incorrect patch may cause Server, Worker, or Beat to fail to run normally.

1. Preparing System Patches

1.1 Confirming the Current Version

Confirm the current DataFlux Func version in Management / About. The system only reads patch directories whose names exactly match the current version; patches for other versions are ignored.

The system patch directories are as follows:

Environment Location
In container /data/resources/system-patches/{current-version}/
On host {installation-directory}/data/resources/system-patches/{current-version}/

For example, when the current version is 8.0.19, the patch directory on the host is:

Text Only
1
{installation-directory}/data/resources/system-patches/8.0.19/

1.2 Preparing Patch Files

The patch directory for each version must contain patch.yaml. Patch files can be placed directly in the current version directory; the actual target location only needs to be correctly specified in patch.yaml. For example:

Text Only
1
2
3
4
5
system-patches/
└── 8.0.19/
    ├── patch.yaml
    ├── example.json
    └── example.py

Here, the files configuration in patch.yaml is a mapping from patch file names to target paths:

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

The path rules in the configuration are as follows:

  • The keys of files are file names within the current version's patch directory. The files must exist in the current version directory.
  • Target paths starting with @/ are relative to the DataFlux Func application root directory. For example, @/worker/utils/example.py refers to worker/utils/example.py in the application directory.
  • For target paths not starting with @/, absolute paths are recommended to avoid ambiguity caused by different working directories.
  • If the target directory does not exist, it is created automatically; if the target file already exists, it is overwritten directly without automatic backup.

The same files configuration is applied by Server, Worker, and Beat separately; filtering patches by service is not supported. When preparing patches, ensure that all target paths are valid for the runtime containers of these services.

1.3 Uploading Patches

If you have access to the host machine, you can place patch.yaml and patch files directly into the host directory corresponding to the current version.

You can also upload them using File Management:

  1. Enable the File Manager module in Management / Experimental Features.
  2. Go to Management / File Management / system-patches.
  3. Click Create Patch Directory for the Current Version (x.y.z), and enter the newly created version directory.
  4. Upload patch.yaml and the patch files directly to the current version directory, and confirm that the file names and target paths in files are correct.

2. Applying and Checking System Patches

2.1 Restarting DataFlux Func

After preparation, restart DataFlux Func as described in System Maintenance / Upgrade and Restart, so that Server, Worker, and Beat recreate and apply the patches.

When each service starts, it performs the following steps in order:

  1. Read the current DataFlux Func version.
  2. Locate system-patches/{current version}/patch.yaml.
  3. Copy each patch file according to the files configuration.
  4. Record the current host, service, version, application time, and application result of each file.

If the current version directory or patch.yaml does not exist, the service skips system patches. If patch.yaml is not a valid YAML mapping or lacks a valid files mapping, patch processing reports an error and interrupts the startup of the corresponding service.

If an individual patch file does not exist, its path is invalid, or copying fails, the system records that file as failed and continues processing other files, then continues starting the service. Therefore, a successful service startup does not mean all patches have been successfully applied.

2.2 Checking Application Results

Go to Management / About / System Tools and click View System Patch Log.

The log is grouped by version and similar application times, and displays the following information:

  • Service and host name
  • DataFlux Func version
  • Application time
  • Total, successful, and failed patch counts
  • Each patch file, target path, application result, and error message

You should confirm that every Server, Worker, and Beat node has a corresponding record, and that all patch files are displayed as successful. Container logs also output the application result of each file with a [SYSTEM PATCH] prefix.

3. Updating or Removing System Patches

The system re-applies the current version's patches every time a service starts. Therefore, after modifying patch files or patch.yaml, you must restart DataFlux Func again for the changes to take effect.

Deleting patch configuration does not immediately restore files that have already been overwritten in the currently running container. For @/ target paths, delete the corresponding configuration and recreate the related services so that they start from the original image files; for absolute target paths in persistent directories, you also need to restore the files using the backup taken before the operation.

After upgrading DataFlux Func, patches in the old version directory are not applied to the new version. Please re-check whether the patches are still necessary and compatible based on the new version code, and create a new version directory only after obtaining patches that are suitable for the new version. Do not directly copy old version patches to the new version directory.