How to Update RAGFlow to New Features While Preserving Local Custom Modifications?

[wikj163]

Hi RAGFlow team and community,
I have been using a custom version of RAGFlow (started from v0.21.1 and cherry-picked some commits to include v0.22.0+ features, especially the new Data Sources module). I have made quite a few local modifications to the project files, such as:

Custom parser logic in deepdoc/parser and rag/app/parser
Modified prompts and agent behavior in rag/app/agent
Some changes in rag/svr/task_executor.py and common/utils

These modifications are critical for my use case and I cannot afford to lose them.
Now I want to update to the latest official version (or at least merge new features like improved Data Sources, Docling parser, multi-source sync, etc.), but I want to preserve all my local changes as much as possible and avoid massive conflicts or having to re-apply my modifications manually every time.
My questions are:

Is there a recommended workflow or best practice to merge new official features/updates into a forked/customized repository without overwriting my local changes?
Are there any plugin/extension mechanisms, config overrides, or directory-based hooks that allow adding new features (especially new data sources or parsers) without modifying core files?
For features that require changes to core modules (e.g., new connectors in common/data_source, new parser registrations), what is the cleanest way to keep my modifications while integrating upstream changes?

My actual scenario:

I heavily customized several core parts of the code.
I use source code deployment (not pure Docker image).
I frequently cherry-pick commits or copy new files from upstream.
I want to keep receiving new features (like better data source sync, UI improvements, agent enhancements) without having to resolve thousands of conflicts or rewrite my custom code every time.

Any advice, documentation links, or real-world examples from other users who maintain a custom fork would be greatly appreciated. Thank you!
Best regards,
yikang

[dosubot[bot]]

To keep your local RAGFlow customizations while updating to new features, the safest workflow is to use Git: commit your changes to a dedicated branch, pull the latest upstream code, and then merge or rebase your branch, resolving conflicts as needed. This approach is widely used for preserving local modifications during upgrades and is recommended by both maintainers and other users maintaining custom forks. Always back up your config files and data before major updates, especially if you use Docker or similar environments [source].

For extensibility, RAGFlow offers several mechanisms to minimize core file changes:

• Parsers: Parsers are registered centrally in the FACTORY dictionary in rag/svr/task_executor.py. To add or override a parser, create your parser module (e.g., in rag/app or deepdoc/parser), then update the FACTORY mapping. This lets you swap in custom logic without deep framework changes [source].
• Connectors/Data Sources: The common/data_source/interfaces.py module defines abstract base classes for connectors. You can add new data sources by subclassing these interfaces and wiring them into the connector runner, without touching core logic [source].
• LLM Tool Plugins: RAGFlow supports a plugin system for LLM tools. Drop new tool modules into plugin/embedded_plugins and subclass LLMToolPlugin with your logic. These plugins are auto-discovered at startup, so you don’t need to modify the main server code [source].

For features that require touching core modules, try to isolate your logic in separate modules and only update central registries (like the parser FACTORY or connector lists). This reduces merge conflicts and makes future upgrades easier.

Real-world users maintaining custom forks follow this workflow: fork the repo, add an upstream remote, make and commit changes on feature branches, and regularly merge upstream changes, resolving conflicts as they arise. This is especially important for core modifications [source].

There isn’t official documentation for all extension points, but the codebase is structured to make these kinds of customizations as modular as possible. If you want to see concrete examples, check the plugin README and the parser/connector interface files linked above.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[Magicbook1108]

take them out and put them back after upgrade......