从零开始：基于 RAGFlow v0.26.4 的私有仓库二次开发、多人协作、Docker 部署与长期维护
·
适用对象：第一次接触 Git、GitHub、Pull Request、Docker 和开源项目二次开发的开发者。
示例私有仓库：https://github.com/<你的GitHub用户名>/ragflow-customized.git
RAGFlow 官方仓库：https://github.com/infiniflow/ragflow.git
当前定制基线：RAGFlow v0.26.4
已创建定制标签：custom-v0.26.4.0
目录
- 我们到底要做什么
- 先理解几个基础概念
- 为什么仍然使用 Docker
- 建立私有二次开发仓库
- 检查并理解远程仓库
- 基于 v0.26.4 建立定制基线
- 标签 custom-v0.26.4.0 的意义
- 多人开发应该采用什么分支模型
- 什么叫短期分支
- 一次完整的功能开发流程
- 一次完整的缺陷修复流程
- GitHub Pull Request 评审流程
- GitHub 能否实现类似 Gerrit 的评审
- 配置 main 分支保护规则
- Target branches 页面是什么意思
- 配置 CODEOWNERS
- 建立 Pull Request 模板
- 建立 GitHub Actions 持续集成
- RAGFlow 二次开发代码应该放在哪里
- 本地源码开发环境
- 构建自定义 Docker 镜像
- 推送镜像到 GitHub Container Registry
- 生产环境部署
- 未来如何合并 RAGFlow 官方更新
- 什么时候需要 release 分支
- 什么时候需要 maintenance 分支
- 版本号如何设计
- 常见错误和处理方法
- 最终推荐工作流
- 术语表
1. 我们到底要做什么
目标不是简单地“把 RAGFlow 下载下来改几行代码”，而是建立一套可以长期维护的定制版本：
RAGFlow 官方代码
|
| 定期获取稳定版本
v
你的私有 GitHub 仓库
|
| UI、接口、文档切片和业务功能二次开发
v
自定义 Docker 镜像
|
| 测试、发布、部署、回滚
v
测试环境和生产环境
这套方案需要同时满足：
1. 可以修改 RAGFlow 的 UI。
2. 可以增加后端接口和业务功能。
3. 可以接入自定义文档切片服务。
4. 可以继续使用 Docker 部署。
5. 多个人可以同时开发。
6. 代码必须经过评审才能进入主分支。
7. 未来仍然可以合并 RAGFlow 官方更新。
8. 生产版本能够准确追踪和回滚。
2. 先理解几个基础概念
2.1 Git 是什么
Git 是一个版本控制工具。
它记录每次代码修改，因此可以：
查看谁修改了什么；
比较两个版本；
回退到旧版本；
多人同时开发；
建立不同分支；
合并开发成果。
Git 运行在你的本地电脑上。
2.2 GitHub 是什么
GitHub 是一个托管 Git 仓库的平台。
它提供：
远程代码保存；
多人协作；
Pull Request；
代码评审；
Issue；
GitHub Actions；
Docker 镜像仓库；
权限管理。
可以把 Git 理解为“版本控制工具”，把 GitHub 理解为“放置和管理 Git 项目的在线平台”。
2.3 仓库是什么
仓库，也叫 Repository，简称 Repo。
一个仓库通常包含：
源代码；
配置；
文档；
测试；
提交历史；
分支；
标签。
你的仓库是：
https://github.com/<你的GitHub用户名>/ragflow-customized.git
2.4 分支是什么
分支可以理解为一条独立的代码修改线路。
例如：
main
└── 当前稳定代码
feature/custom-ui
└── 正在开发新的 UI
fix/upload-error
└── 正在修复上传问题
不同开发者可以在不同分支中修改代码，互不直接覆盖。
2.5 标签是什么
标签用于给某一个明确的 Git 提交起一个永久名称。
例如：
custom-v0.26.4.0
它表示：
这是基于 RAGFlow v0.26.4 建立的定制版初始基线。
分支会继续向前移动，标签通常不移动。
因此：
分支 = 会继续变化的开发线路
标签 = 固定不变的历史版本标记
2.6 Pull Request 是什么
Pull Request，简称 PR。
它不是“下载请求”，而是：
请求把一个分支中的修改合并到另一个分支。
例如：
feature/custom-ui
|
| Pull Request
v
main
PR 中可以：
查看代码差异；
逐行评论；
要求修改；
批准；
执行自动测试；
最终合并。
2.7 Docker 镜像和容器是什么
Docker 镜像可以理解为一个只读的软件安装包。
它包含：
程序代码；
运行环境；
依赖库；
启动脚本；
必要配置。
Docker 容器是由镜像启动出来的运行实例。
可以类比为：
Docker 镜像 = 操作系统安装镜像
Docker 容器 = 已经启动运行的系统
修改 RAGFlow 后，应该重新构建自己的 Docker 镜像，而不是进入运行中的容器手工修改文件。
3. 为什么仍然使用 Docker
RAGFlow 二次开发后仍然可以使用 Docker。
推荐做法是：
官方镜像
↓
替换为你自己构建的镜像
不是：
直接进入官方容器修改代码
完整过程：
GitHub 私有仓库中的定制源码
|
| docker build
v
自定义 RAGFlow 镜像
|
| docker compose
v
运行中的 RAGFlow 容器
Docker 的优势：
开发环境和生产环境更一致；
部署方式稳定；
依赖不会散落在服务器上；
可以通过镜像标签回滚；
同一镜像可以在多台服务器运行。
4. 建立私有二次开发仓库
你的私有仓库：
https://github.com/<你的GitHub用户名>/ragflow-customized.git
推荐使用两个远程地址：
origin
└── 你的私有仓库
upstream
└── RAGFlow 官方仓库
4.1 克隆官方仓库
git clone https://github.com/infiniflow/ragflow.git ragflow-customized
逐段解释：
git clone
表示把远程 Git 仓库完整下载到本地。
https://github.com/infiniflow/ragflow.git
这是 RAGFlow 官方仓库地址。
ragflow-customized
这是本地目录名称。
执行后，本地会出现：
ragflow-customized/
进入目录：
cd ragflow-customized
cd 是 change directory，表示切换工作目录。
4.2 把官方仓库改名为 upstream
刚克隆完成时，Git 默认把官方仓库称为：
origin
但我们希望：
origin = 你的私有仓库
upstream = 官方仓库
因此执行：
git remote rename origin upstream
逐段解释：
git remote
表示管理远程仓库。
rename origin upstream
表示把原来的远程名称 origin 改成 upstream。
4.3 添加你的私有仓库
git remote add origin https://github.com/<你的GitHub用户名>/ragflow-customized.git
逐段解释：
git remote add
表示新增一个远程仓库。
origin
是给这个远程仓库起的本地名称。
https://github.com/<你的GitHub用户名>/ragflow-customized.git
是你的私有仓库地址。
5. 检查并理解远程仓库
执行：
git remote -v
逐段解释：
git remote
查看远程仓库。
-v
表示 verbose，显示详细地址。
正确结果类似：
origin https://github.com/<你的GitHub用户名>/ragflow-customized.git (fetch)
origin https://github.com/<你的GitHub用户名>/ragflow-customized.git (push)
upstream https://github.com/infiniflow/ragflow.git (fetch)
upstream https://github.com/infiniflow/ragflow.git (push)
其中：
fetch = 从这个地址获取代码
push = 向这个地址推送代码
虽然 upstream 也显示了 push 地址，但你通常没有向官方仓库直接推送代码的权限。
你只需要记住：
git fetch upstream
获取 RAGFlow 官方更新。
git push origin
上传你自己的定制代码。
6. 基于 v0.26.4 建立定制基线
6.1 获取官方标签
git fetch upstream --tags --prune
逐段解释：
git fetch
下载远程仓库中的最新提交、分支和标签，但不会自动修改当前工作区。
upstream
从 RAGFlow 官方仓库获取。
--tags
同时获取版本标签，例如：
v0.26.4
v0.27.0
--prune
清理远程已经删除、但本地还残留的远程分支引用。
6.2 检查 v0.26.4 是否存在
git tag -l "v0.26.4"
逐段解释：
git tag
操作标签。
-l
表示 list，列出标签。
"v0.26.4"
只查找这个名称。
正确输出：
v0.26.4
没有输出说明：
标签还没有获取；
版本号写错；
远程配置有问题。
6.3 切换到 v0.26.4
git switch --detach v0.26.4
逐段解释：
git switch
切换分支或提交。
--detach
进入分离头指针状态。
这意味着当前指向一个固定版本，而不是某个可继续开发的分支。
v0.26.4
切换到官方版本标签。
这一步的目的只是找到正确起点。
6.4 创建自己的 main
git switch -c main
逐段解释：
-c
表示 create，创建新分支。
main
新分支名称。
此时：
main
└── 起点是官方 RAGFlow v0.26.4
6.5 推送到私有仓库
git push -u origin main
逐段解释：
git push
把本地提交和分支上传到远程仓库。
-u
设置上游跟踪关系。
以后在 main 上可以直接执行：
git push
不需要重复输入 origin main。
origin
你的私有仓库。
main
要推送的分支。
7. 标签 custom-v0.26.4.0 的意义
你已经执行了：
git push origin custom-v0.26.4.0
这表示把本地标签：
custom-v0.26.4.0
上传到了你的 GitHub 私有仓库。
推荐版本含义：
custom-v0.26.4.0
│ │ │
│ │ └── 定制版修订号
│ └────── RAGFlow 官方版本
└──────── 定制版本前缀
建议约定：
custom-v0.26.4.0
└── 初始定制基线
custom-v0.26.4.1
└── 基于 v0.26.4 的第一次正式定制发布
custom-v0.26.4.2
└── 第二次定制修复或发布
custom-v0.27.0.0
└── 升级到官方 v0.27.0 后的新基线
查看标签：
git show custom-v0.26.4.0
只查看概要：
git show --no-patch --oneline custom-v0.26.4.0
8. 多人开发应该采用什么分支模型
推荐只保留一个长期主分支：
main
短期使用：
feature/*
fix/*
upgrade/*
按需使用：
release/*
maintenance/*
结构如下：
main
│
├── feature/101-custom-branding
├── feature/102-document-preprocess-ui
├── feature/103-custom-chunker-api
├── fix/201-upload-timeout
├── upgrade/v0.27.0
├── release/0.26.4.1
└── maintenance/0.26
不建议一开始就建立长期 develop 分支。
原因：
main 已经可以作为持续集成主线；
真实发布状态由标签确定；
多个长期分支会增加同步成本；
小团队容易忘记 develop 和 main 之间的合并关系；
官方升级本身已经需要单独处理。
9. 什么叫短期分支
短期分支不是“只能存在几天”。
它的真正含义是：
分支只为完成一个明确任务而存在，任务完成并合并后删除。
例如：
fix/201-upload-timeout
生命周期：
创建分支
→ 修复问题
→ 提交 Pull Request
→ 代码评审
→ 自动测试
→ 合并到 main
→ 删除分支
删除分支不会删除已经合并的代码。
只要 PR 已经合并：
代码仍然在 main；
提交记录仍然存在；
Pull Request 仍然存在；
评论和评审记录仍然存在。
删除远程分支：
git push origin --delete fix/201-upload-timeout
删除本地分支：
git switch main
git pull --ff-only origin main
git branch -d fix/201-upload-timeout
其中：
git branch -d
是安全删除。
如果分支未合并，Git 会拒绝删除。
不要直接改成：
git branch -D fix/201-upload-timeout
-D 是强制删除，可能导致未合并代码丢失。
10. 一次完整的功能开发流程
假设要增加：
文档预处理管理页面
10.1 先创建 Issue
在 GitHub 仓库中：
Issues
→ New issue
标题示例：
增加文档预处理管理页面
假设生成：
Issue #102
10.2 更新 main
git switch main
git pull --ff-only origin main
解释：
git switch main
切换到主分支。
git pull
从远程获取并合并最新代码。
--ff-only
只允许快进合并。
如果本地存在额外提交导致历史分叉，这条命令会拒绝执行，而不是自动制造意外合并提交。
origin main
从你的私有仓库获取 main。
10.3 创建功能分支
git switch -c feature/102-document-preprocess-ui
命名规则：
feature/
表示功能开发。
102
对应 GitHub Issue 编号。
document-preprocess-ui
简短描述功能。
10.4 修改代码
修改完成后先检查：
git status
它会显示：
哪些文件被修改；
哪些文件未被跟踪；
哪些文件已进入暂存区。
查看差异：
git diff
查看即将提交的差异：
git diff --cached
10.5 精准添加文件
不建议无脑执行：
git add .
推荐：
git add web/src/pages/company/document-preprocess/
git add web/src/services/company/document-preprocess.ts
这样可以避免误提交：
.env；
日志；
测试数据；
下载文件；
API Key；
临时文件。
10.6 提交
git commit -m "feat(document): add preprocessing management UI"
说明：
feat
表示新增功能。
(document)
表示影响文档模块。
add preprocessing management UI
描述具体修改。
推荐常用提交类型：
feat 新功能
fix 修复缺陷
docs 文档
test 测试
chore 工程或配置维护
refactor 重构，但不改变外部行为
10.7 推送功能分支
git push -u origin feature/102-document-preprocess-ui
首次推送使用 -u。
以后继续修改时：
git push
10.8 创建 Pull Request
GitHub 页面会提示：
Compare & pull request
目标应为：
base: main
compare: feature/102-document-preprocess-ui
含义：
把 feature/102-document-preprocess-ui 合并到 main。
11. 一次完整的缺陷修复流程
假设发现上传超时。
创建 Issue：
Issue #201：修复大文件上传超时
创建分支：
git switch main
git pull --ff-only origin main
git switch -c fix/201-upload-timeout
修复并测试：
git status
git diff
git add <修复涉及的文件>
git commit -m "fix(upload): handle large file timeout"
git push -u origin fix/201-upload-timeout
创建 PR：
fix/201-upload-timeout
↓
main
合并后删除分支。
如果需要发布补丁版本：
git switch main
git pull --ff-only origin main
git tag -a custom-v0.26.4.1 \
-m "Custom RAGFlow v0.26.4 patch 1"
git push origin custom-v0.26.4.1
12. GitHub Pull Request 评审流程
推荐流程：
1. 开发者创建 Issue。
2. 从 main 创建短期分支。
3. 开发者提交代码。
4. 创建 Draft Pull Request。
5. GitHub Actions 自动运行。
6. 开发完成后标记 Ready for review。
7. CODEOWNERS 自动请求审核人。
8. 审核人逐行评论。
9. 审核人选择 Approve 或 Request changes。
10. 开发者继续向原分支 push 修改。
11. CI 重新运行。
12. 审核人再次检查。
13. 所有评论标记 Resolved。
14. 审核通过。
15. CI 全部通过。
16. 合并到 main。
17. 删除短期分支。
12.1 Draft Pull Request
Draft PR 表示：
代码还没有完全开发完成；
暂时不应该合并；
可以提前让其他人查看。
完成开发后点击：
Ready for review
12.2 Review 的三个选项
GitHub 评审时有：
Comment
Approve
Request changes
含义：
Comment
└── 只发表意见，不阻止合并。
Approve
└── 认可当前修改。
Request changes
└── 要求修改；在启用强制审核后会阻止合并。
13. GitHub 能否实现类似 Gerrit 的评审
可以实现接近 Gerrit 的流程，但模型不同。
对应关系：
| Gerrit | GitHub |
|---|---|
| Change | Pull Request |
| Patch Set | 向 PR 分支继续 push |
| Code-Review +2 | Approve + Required approvals |
| Code-Review -2 | Request changes |
| Verified +1 | GitHub Actions 状态检查 |
| Submit | Merge Pull Request |
| Owner/Reviewer | CODEOWNERS / Reviewers |
| 新 Patch Set 后重新审核 | Dismiss stale approvals |
差异：
Gerrit 更强调一个 Change 和多个 Patch Set；
GitHub 更强调一个功能分支和一个 Pull Request。
GitHub 没有完全相同的：
Code-Review -2、-1、0、+1、+2
但以下组合已经足够严格：
Pull Request
+ Required approvals
+ Request changes
+ CODEOWNERS
+ Required status checks
+ Dismiss stale approvals
+ Require conversation resolution
14. 配置 main 分支保护规则
进入：
仓库
→ Settings
→ Rules
→ Rulesets
→ New ruleset
→ New branch ruleset
建议规则名称：
Protect main branch
状态：
Active
14.1 必须通过 Pull Request
启用：
Require a pull request before merging
作用：
禁止直接把代码推送到 main；
必须经过 Pull Request。
14.2 至少一人批准
配置：
Required approvals: 1
作用：
PR 作者不能只靠自己完成审核；
至少需要另一名审核人批准。
高风险项目可以设置为：
2
14.3 新提交后旧批准失效
启用：
Dismiss stale pull request approvals
when new commits are pushed
流程：
审核人批准
→ 开发者继续修改代码
→ 原批准失效
→ 必须重新审核
这接近 Gerrit 新 Patch Set 后重新评审。
14.4 最新提交必须由他人批准
启用：
Require approval of the most recent reviewable push
防止：
审核人批准
→ PR 作者自己再推送未审核代码
→ 直接合并
14.5 评论必须解决
启用：
Require conversation resolution before merging
作用：
未解决的代码评审线程会阻止合并。
14.6 禁止强制推送
启用：
Block force pushes
强制推送可能重写分支历史。
主分支不应允许。
14.7 禁止删除 main
启用：
Block deletions
防止误删除主分支。
14.8 CI 必须通过
等 GitHub Actions 工作流运行过至少一次后，再启用：
Require status checks to pass
选择：
backend-test
frontend-lint
frontend-test
docker-build
如果工作流从未运行，GitHub 页面可能找不到这些检查名称。
15. Target branches 页面是什么意思
你看到的页面：
Target branches
Which branches should be matched?
意思是：
当前 Ruleset 应该应用到哪些分支。
选项包括：
15.1 Include default branch
表示：
包含默认分支。
如果默认分支是：
main
规则只保护 main。
这是当前最推荐的选择。
操作：
Add target
→ Include default branch
15.2 Include all branches
表示保护所有分支，包括：
main
feature/*
fix/*
upgrade/*
不建议一开始选择。
否则可能导致开发者无法正常向自己的功能分支推送。
15.3 Include by pattern
按分支名称模式包含。
例如：
main
只匹配 main。
例如：
maintenance/*
匹配：
maintenance/0.26
maintenance/0.27
15.4 Exclude by pattern
按名称模式排除。
例如：
Include all branches
Exclude by pattern: feature/*
意思是：
保护所有分支，但排除 feature/*。
当前没有必要使用这么复杂的配置。
15.5 推荐选择
Add target
→ Include default branch
前提是默认分支确实是 main。
检查：
Settings
→ General
→ Default branch
16. 配置 CODEOWNERS
创建文件：
.github/CODEOWNERS
示例：
# 默认负责人
* @<你的GitHub用户名>
# 前端
/web/ @frontend-owner
# 后端
/api/ @backend-owner
# RAG 核心
/rag/ @rag-owner
# 文档解析
/deepdoc/ @document-owner
# Docker
/docker/ @devops-owner
# 自定义切片
/platform/document_chunker/ @chunker-owner
# CODEOWNERS 文件本身
/.github/CODEOWNERS @<你的GitHub用户名>
说明：
* @<你的GitHub用户名>
表示没有被其他规则匹配的文件由 <你的GitHub用户名> 负责。
/web/ @frontend-owner
修改 web/ 下文件时，请求前端负责人审核。
/.github/CODEOWNERS @<你的GitHub用户名>
防止其他人随意修改代码所有者规则。
注意：
CODEOWNERS 中的账号必须有仓库访问权限；
GitHub 用户名必须真实存在；
团队名称需要 GitHub Organization。
17. 建立 Pull Request 模板
创建：
.github/pull_request_template.md
内容：
## 修改目的
说明本次修改解决什么问题。
## 关联 Issue
Closes #
## 修改范围
- [ ] 前端
- [ ] 后端 API
- [ ] RAG 核心
- [ ] 文档解析
- [ ] 数据库
- [ ] Docker/部署
- [ ] 自定义切片
- [ ] 文档
## 关键修改
列出本次主要修改。
## 修改的 RAGFlow 原生文件
列出直接修改的官方文件；没有则填写“无”。
## 测试结果
- [ ] 后端测试通过
- [ ] 前端 lint 通过
- [ ] 前端测试通过
- [ ] Docker 构建通过
- [ ] 原有知识库功能正常
- [ ] 自定义功能正常
## 数据库和配置
- 数据库迁移：
- 新增环境变量：
- 配置文件变更：
## 回滚方式
说明如何安全回滚。
作用：
每个 PR 自动显示统一模板；
开发者不会漏写测试和影响范围；
审核人更容易判断风险。
18. 建立 GitHub Actions 持续集成
GitHub Actions 用于自动执行：
代码检查；
单元测试；
前端检查；
Docker 构建；
敏感信息扫描。
创建：
.github/workflows/ci.yml
一个简化示例：
name: CI
on:
pull_request:
branches:
- main
push:
branches:
- main
jobs:
backend-test:
runs-on: ubuntu-latest
steps:
- name: Checkout source
uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v6
- name: Install Python dependencies
run: uv sync --python 3.13
- name: Run backend tests
run: uv run pytest
frontend-lint:
runs-on: ubuntu-latest
defaults:
run:
working-directory: web
steps:
- name: Checkout source
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
cache-dependency-path: web/package-lock.json
- name: Install frontend dependencies
run: npm ci
- name: Run frontend lint
run: npm run lint
docker-build:
runs-on: ubuntu-latest
steps:
- name: Checkout source
uses: actions/checkout@v4
- name: Build Docker image
run: |
docker build \
--platform linux/amd64 \
-f Dockerfile \
-t ragflow-customized:test \
.
注意：
这只是结构示例；
具体命令必须以 v0.26.4 仓库中的 package.json、测试配置和工作流要求为准；
RAGFlow 完整 Docker 构建可能耗时较长。
19. RAGFlow 二次开发代码应该放在哪里
RAGFlow 原有主要目录：
api/ 后端 API
rag/ RAG 核心
deepdoc/ 文档解析
agent/ Agent
web/ 前端
docker/ Docker 配置
sdk/ SDK
test/ 测试
推荐新增独立模块。
19.1 UI 代码
建议：
web/src/
├── pages/company/
│ ├── document-preprocess/
│ ├── chunk-preview/
│ └── requirement-relation/
├── components/company/
└── services/company/
原则：
新增优于直接重写；
业务代码集中；
原生路由和菜单只做少量注册；
不要把公司业务代码散落在大量官方页面中。
19.2 后端接口
建议：
api/apps/company/
├── document_preprocess.py
├── chunk_preview.py
└── requirement_relation.py
推荐调用关系：
company API
↓
company service
↓
ragflow adapter
↓
RAGFlow 原生服务
这样官方内部接口变化时，只需要调整适配层。
19.3 自定义文档切片
建议独立维护：
platform/document_chunker/
├── loaders/
├── cleaners/
├── parsers/
├── chunkers/
├── metadata/
├── relation_extractor/
├── integrations/ragflow/
└── tests/
优点：
与 RAGFlow 核心解耦；
可以独立测试；
可以独立部署；
官方升级冲突更少；
后续可以复用于其他知识库。
20. 本地源码开发环境
推荐环境：
Windows 11
+ WSL2 Ubuntu
+ Docker Desktop
不要优先在 Windows 原生命令行中运行全部 Linux 脚本。
20.1 检查环境
git --version
docker --version
docker compose version
python --version
node --version
npm --version
20.2 安装 uv
pipx install uv
如果没有 pipx：
python -m pip install --user pipx
python -m pipx ensurepath
重新打开终端，再执行：
pipx install uv
20.3 安装 Python 依赖
在仓库根目录：
uv sync --python 3.13
解释：
uv sync
根据项目锁定文件安装依赖。
--python 3.13
指定 Python 3.13。
下载额外依赖：
uv run python3 ragflow_deps/download_deps.py
解释：
uv run
在项目虚拟环境中执行命令。
20.4 安装 Git Hook
lefthook install
作用：
在提交前自动执行项目定义的检查；
减少格式和低级错误进入仓库。
20.5 启动基础依赖
docker compose -f docker/docker-compose-base.yml up -d
解释：
docker compose
启动多个相关容器。
-f docker/docker-compose-base.yml
指定 Compose 文件。
up
创建并启动服务。
-d
后台运行。
它通常启动：
MySQL；
Redis；
MinIO；
Elasticsearch 或 Infinity；
其他基础服务。
查看容器：
docker compose -f docker/docker-compose-base.yml ps
查看日志：
docker compose -f docker/docker-compose-base.yml logs -f
20.6 启动后端
source .venv/bin/activate
export PYTHONPATH=$(pwd)
bash docker/launch_backend_service.sh
解释：
source .venv/bin/activate
激活 Python 虚拟环境。
export PYTHONPATH=$(pwd)
把当前项目根目录加入 Python 模块搜索路径。
bash docker/launch_backend_service.sh
执行 RAGFlow 后端启动脚本。
20.7 启动前端
新开一个终端：
cd web
npm install
npm run dev
解释：
npm install
安装前端依赖。
npm run dev
启动前端开发服务器。
开发 UI 时，保存代码后通常会自动刷新，不需要每次重新构建 Docker 镜像。
21. 构建自定义 Docker 镜像
开发和测试完成后，在项目根目录执行：
docker build \
--platform linux/amd64 \
-f Dockerfile \
-t ragflow-customized:0.26.4-custom.1 \
.
逐段解释：
docker build
构建 Docker 镜像。
--platform linux/amd64
指定目标平台为 Linux x86_64。
-f Dockerfile
使用项目根目录的 Dockerfile。
-t ragflow-customized:0.26.4-custom.1
设置镜像名称和标签。
.
使用当前目录作为构建上下文。
查看镜像：
docker images | grep ragflow-customized
22. 推送镜像到 GitHub Container Registry
GitHub Container Registry，简称 GHCR。
镜像地址格式：
ghcr.io/<用户名>/<镜像名>:<标签>
你的示例：
ghcr.io/<你的GitHub用户名>/ragflow-customized:0.26.4-custom.1
22.1 给本地镜像增加 GHCR 标签
docker tag \
ragflow-customized:0.26.4-custom.1 \
ghcr.io/<你的GitHub用户名>/ragflow-customized:0.26.4-custom.1
docker tag 不会复制镜像内容，只是增加一个新的名称。
22.2 登录 GHCR
需要创建 GitHub Personal Access Token。
Token 至少需要：
write:packages
read:packages
登录：
echo "<你的GitHub Token>" | \
docker login ghcr.io \
-u <你的GitHub用户名> \
--password-stdin
注意：
不要把 Token 写入代码；
不要提交到 Git；
不要把 Token 发给其他人；
泄露后立即撤销。
22.3 推送镜像
docker push \
ghcr.io/<你的GitHub用户名>/ragflow-customized:0.26.4-custom.1
23. 生产环境部署
生产服务器中：
docker/.env
设置：
RAGFLOW_IMAGE=ghcr.io/<你的GitHub用户名>/ragflow-customized:0.26.4-custom.1
启动：
cd docker
docker compose -f docker-compose.yml up -d
查看状态：
docker compose -f docker-compose.yml ps
查看 RAGFlow 日志：
docker compose -f docker-compose.yml logs -f
不要在生产环境使用：
latest
main
nightly
因为这些标签可能移动，无法确定实际运行的代码。
生产环境应该使用：
0.26.4-custom.1
0.26.4-custom.2
0.27.0-custom.0
24. 未来如何合并 RAGFlow 官方更新
假设官方发布：
v0.27.0
不要直接在 main 上合并。
24.1 获取官方版本
git fetch upstream --tags --prune
确认标签：
git tag -l "v0.27.0"
24.2 创建升级分支
git switch main
git pull --ff-only origin main
git switch -c upgrade/v0.27.0
24.3 合并官方版本
git merge --no-ff v0.27.0
解释：
git merge
把另一个版本的修改合并到当前分支。
--no-ff
即使可以快进，也创建一个明确的合并提交。
这有助于保留：
这次修改是从官方 v0.27.0 合并而来。
24.4 解决冲突
查看：
git status
冲突文件通常包含：
<<<<<<< HEAD
你的定制代码
=======
官方新代码
>>>>>>> v0.27.0
处理原则：
先理解双方修改目的；
保留仍然需要的定制逻辑；
吸收官方修复和新结构；
不要无脑 Accept all current；
不要无脑 Accept all incoming。
处理后：
git add <已解决文件>
git commit
24.5 完整回归测试
至少测试：
登录；
用户权限；
模型配置；
知识库创建；
历史知识库读取；
文档上传；
文档解析；
检索；
问答；
Agent；
自定义 UI；
自定义 API；
自定义切片；
数据库迁移；
Docker 构建；
容器重启后的数据持久化。
24.6 推送升级分支并评审
git push -u origin upgrade/v0.27.0
创建 PR：
upgrade/v0.27.0
↓
main
升级 PR 推荐：
Create a merge commit
普通功能 PR 推荐：
Squash and merge
24.7 更新版本记录
更新：
UPSTREAM_VERSION
CUSTOM_CHANGELOG.md
docs/company/upgrade.md
UPSTREAM_VERSION：
v0.27.0
打新标签：
git switch main
git pull --ff-only origin main
git tag -a custom-v0.27.0.0 \
-m "Initial custom release based on RAGFlow v0.27.0"
git push origin custom-v0.27.0.0
25. 什么时候需要 release 分支
默认不需要。
正常流程：
功能合并 main
→ 自动测试
→ 测试环境验证
→ main 打标签
→ 生产发布
只有以下情况才创建：
测试冻结期持续多天；
测试期间 main 还要继续开发下一版本；
发布候选版本只能接受修复；
当前测试版本和下一开发版本必须并行。
创建：
git switch main
git pull --ff-only origin main
git switch -c release/0.26.4.1
git push -u origin release/0.26.4.1
发布完成后：
合并回 main；
从 main 打标签；
删除 release 分支。
26. 什么时候需要 maintenance 分支
默认不需要。
例如：
main 已升级到 v0.27.0；
某个生产环境还在使用 v0.26.4；
v0.26.4 出现严重问题；
旧版本暂时不能升级。
这时创建：
git switch -c maintenance/0.26 custom-v0.26.4.0
git push -u origin maintenance/0.26
旧版修复：
fix/301-v026-security-fix
↓
maintenance/0.26
打标签：
custom-v0.26.4.1
相同修复还需要同步到最新 main。
27. 版本号如何设计
推荐 Git 标签：
custom-v0.26.4.0
custom-v0.26.4.1
custom-v0.26.4.2
custom-v0.27.0.0
推荐 Docker 镜像：
ghcr.io/<你的GitHub用户名>/ragflow-customized:0.26.4-custom.0
ghcr.io/<你的GitHub用户名>/ragflow-customized:0.26.4-custom.1
ghcr.io/<你的GitHub用户名>/ragflow-customized:0.27.0-custom.0
对应关系：
Git 标签 custom-v0.26.4.1
↓
Docker 镜像 0.26.4-custom.1
不要重复覆盖同一个生产镜像标签。
28. 常见错误和处理方法
28.1 首次 push 被拒绝
错误：
non-fast-forward
常见原因：
GitHub 私有仓库创建时自动生成了 README；
本地和远程具有不同初始提交。
如果确认远程只有自动生成的 README，没有重要代码：
git fetch origin
git push --force-with-lease -u origin main
--force-with-lease 比 --force 更安全。
28.2 main 已经存在
错误：
fatal: a branch named 'main' already exists
不要重复创建。
执行：
git switch main
查看：
git log --oneline --decorate -5
28.3 标签已经存在
错误：
fatal: tag 'custom-v0.26.4.0' already exists
查看标签：
git show custom-v0.26.4.0
如果标签正确，不需要重新创建。
如果本地有、远程没有：
git push origin custom-v0.26.4.0
28.4 GitHub 看不到状态检查
原因：
CI 工作流尚未运行；
Job 名称写错；
工作流没有触发 PR；
工作流失败或被跳过。
先提交一个测试 PR，让 GitHub Actions 至少运行一次。
28.5 feature 分支落后于 main
更新方式：
git switch feature/102-document-preprocess-ui
git fetch origin
git merge origin/main
或者使用 rebase：
git rebase origin/main
零基础团队建议先统一使用 merge，避免错误重写历史。
28.6 删除分支后担心代码丢失
确认 PR 已合并：
Pull Request 页面显示 Merged。
代码已经进入 main，删除分支不会删除合并结果。
28.7 直接修改运行中的容器
不推荐：
docker exec -it <容器> bash
然后直接修改源码。
容器重建后修改会丢失。
正确流程：
修改 Git 仓库源码
→ 提交
→ 评审
→ 构建镜像
→ 部署新镜像
28.8 生产环境执行 down -v
危险命令：
docker compose down -v
-v 可能删除 Compose 管理的数据卷。
生产环境执行前必须明确：
哪些数据会被删除；
数据库是否备份；
MinIO 是否备份；
索引是否可重建。
29. 最终推荐工作流
29.1 日常开发
Issue
↓
feature/* 或 fix/*
↓
Draft Pull Request
↓
CI
↓
代码评审
↓
Approve
↓
合并 main
↓
删除短期分支
29.2 发布
main
↓
测试环境验证
↓
custom-v* 标签
↓
GitHub Actions 构建镜像
↓
GHCR
↓
生产环境部署
29.3 官方升级
upstream 官方 Tag
↓
upgrade/*
↓
解决冲突
↓
完整回归测试
↓
Pull Request
↓
main
↓
新 custom-v* 标签
29.4 最终原则
官方更新只从 upstream 获取；
定制代码只推送到 origin；
main 是唯一长期主线；
功能和修复使用短期分支；
所有代码通过 Pull Request；
所有 PR 需要评审和 CI；
标签表示真正发布版本；
生产环境只部署标签对应的 Docker 镜像；
定制功能尽量放在独立目录和独立服务；
尽量减少对 RAGFlow 核心文件的直接修改。
30. 术语表
| 术语 | 含义 |
|---|---|
| Git | 本地版本控制工具 |
| GitHub | 在线代码托管和协作平台 |
| Repository | 仓库，保存代码和历史 |
| Commit | 一次代码提交 |
| Branch | 分支，独立开发线路 |
| Tag | 标签，固定版本标记 |
| main | 主分支 |
| feature | 功能开发分支 |
| fix | 缺陷修复分支 |
| upgrade | 官方版本升级分支 |
| release | 发布冻结分支 |
| maintenance | 旧版本维护分支 |
| Pull Request | 请求将一个分支合并到另一个分支 |
| Review | 代码评审 |
| Approve | 批准代码 |
| Request changes | 要求修改 |
| CODEOWNERS | 文件或目录的代码负责人规则 |
| Ruleset | GitHub 分支和标签规则集合 |
| CI | 持续集成，自动检查和测试 |
| GitHub Actions | GitHub 的自动化平台 |
| upstream | RAGFlow 官方远程仓库 |
| origin | 你的私有远程仓库 |
| Dockerfile | Docker 镜像构建说明 |
| Docker image | Docker 镜像 |
| Container | 由镜像启动的容器 |
| Docker Compose | 管理多个容器的工具 |
| GHCR | GitHub Container Registry |
| Merge | 合并代码 |
| Squash Merge | 将 PR 多个提交压缩成一个提交 |
| Merge Commit | 保留分支合并边界的合并方式 |
| Rebase | 将提交重新放到另一个基线上 |
| Rollback | 回滚到旧版本 |
参考资料
更多推荐
8
0- 0
已为社区贡献3条内容
所有评论(0)