Upstream sync conflict

问题场景

问题出现在一个 RAGFlow 下游 fork 的自动化同步流程中：工作流检测到 upstream main 领先 605 个提交，且无法干净地合并进 sync/upstream-main 分支，于是自动创建了这条 Issue，要求人工解决冲突并提交 sync PR。Issue 作者随后澄清，该 Issue 是自动化工作流在错误的 git remote 上运行导致的误报，与 RAGFlow 本身的运行、模型推理、WebUI 或 SDK 使用无关。

报错原文

Upstream sync conflict

Upstream main is 605 commits ahead and cannot merge cleanly into `sync/upstream-main`.

Conflicted files:

.github/workflows/sep-tests.yml
api/apps/restful_apis/document_api.py
docker/.env
sdk/python/ragflow_sdk/modules/document.py
web/src/locales/vi.ts
web/src/pages/dataset/dataset/use-upload-document.ts

Resolve the conflicts manually and open a sync PR.

原因分析

按 Issue 作者的说明，根因是自动化工作流解析到了错误的 git remote，即它以为在同步 upstream，实际上作用在了另一个远端仓库上，因此才出现“upstream 领先 605 个提交且无法干净合并”的结果，并自动开出了这条 Issue。换句话说，这是同步脚本/工作流的仓库指向配置问题，不是 RAGFlow 代码冲突或环境依赖问题。由于 Issue 关闭前没有给出工作流配置的具体内容，这里只能作为已由作者确认的结论引用，不再做额外推断。

环境排查

• 确认触发报错的仓库是否为你自己的 fork，而不是 RAGFlow 官方仓库。
• 确认自动化同步工作流中 upstream remote 的 URL 是否指向预期的 RAGFlow 仓库。
• 确认工作流运行的分支是否为 sync/upstream-main 之类的同步分支。
• Issue 未提供 Python、CUDA、PyTorch、显卡、节点或依赖版本信息，无需也无法据此排查这些项目。

解决步骤

1. 判断该 Issue 是否出现在你的 fork 上。如果是 RAGFlow 官方仓库或与你的使用无关，直接忽略并关闭即可，Issue 作者已确认“Nothing to act on here”。
2. 如果是你自己的 fork 反复自动生成同类 Issue，优先检查同步工作流里 upstream remote 的地址配置，确认它没有解析到错误仓库。这一步是基于本节原因分析的“可优先尝试”排查方向，并非 Issue 中验证过的修复步骤。
3. 不要按 Issue 正文的提示手动解决那 6 个文件的冲突或提交 sync PR，因为该 Issue 本身已被判定为误报。

验证方法

确认该 Issue 已关闭且无后续处理需求；如果你修改了自己 fork 的同步工作流 remote 配置，可观察下一轮自动同步是否还会生成类似的 “Upstream sync conflict” Issue，若不再生成则说明配置已纠正。

参考来源

infiniflow/ragflow #19681

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。