640 lines
18 KiB
Markdown
640 lines
18 KiB
Markdown
|
# Dify Lightweight Customization and Upgrade
|
|||
|
|
|
|||
|
|
## 1. 文档目标
|
|||
|
|
|
|||
|
|
本文档用于定义当前阶段基于 Dify 的最简定制与升级策略。
|
|||
|
|
|
|||
|
|
这份策略专门适用于下面这种现实约束：
|
|||
|
|
|
|||
|
|
- Dify 官方仓库在 GitHub
|
|||
|
|
- 公司正式仓库必须放在内网 Gitea
|
|||
|
|
- 当前没有时间做复杂的深度二开
|
|||
|
|
- 主要只打算做轻量前端定制
|
|||
|
|
- 一般情况下不修改 Python 后端代码
|
|||
|
|
|
|||
|
|
本文档的目标不是追求最完美的工程形态，而是提供一套简单、能长期执行、升级成本可控的实践方案。
|
|||
|
|
|
|||
|
|
本文内容结合 `langgenius/dify` 官方仓库当前公开信息整理，重点参考：
|
|||
|
|
|
|||
|
|
- 仓库根目录结构
|
|||
|
|
- `web/` 前端目录结构
|
|||
|
|
- `web/package.json`
|
|||
|
|
- 官方 release 中的 upgrade guide
|
|||
|
|
|
|||
|
|
## 2. 核心结论
|
|||
|
|
|
|||
|
|
当前阶段最适合的策略是：
|
|||
|
|
|
|||
|
|
1. 选择一个稳定的 Dify `tag` 作为基线版本。
|
|||
|
|
2. 将该版本代码放入公司内网 Gitea 仓库。
|
|||
|
|
3. 只做轻量前端定制。
|
|||
|
|
4. 尽量不改 Python 后端逻辑。
|
|||
|
|
5. 如果后续 Dify 发布新版本，再单独开升级分支进行适配。
|
|||
|
|
6. 验证通过后合并回主分支，并更新 README 中记录的 Dify 基线版本。
|
|||
|
|
|
|||
|
|
一句话概括：
|
|||
|
|
|
|||
|
|
**把 Dify 当作固定版本的上游产品来使用，只在前端做一层薄定制，升级时再重新适配这层薄定制。**
|
|||
|
|
|
|||
|
|
## 3. 当前推荐策略为什么成立
|
|||
|
|
|
|||
|
|
你的实际目标不是长期深度维护一个 Dify 二开发行版，而是：
|
|||
|
|
|
|||
|
|
- 借助 Dify 的现成 workflow 能力快速落地
|
|||
|
|
- 补一层更适合 AIOps 场景的页面
|
|||
|
|
- 保证后续还能跟上 Dify 的版本演进
|
|||
|
|
|
|||
|
|
在这种情况下，最重要的不是“保留最完整的上游工程关系”，而是：
|
|||
|
|
|
|||
|
|
- 当前基线版本清楚
|
|||
|
|
- 定制范围足够小
|
|||
|
|
- 升级时知道要改哪些地方
|
|||
|
|
|
|||
|
|
只要这三点明确，直接基于固定 tag 工作就是可行的。
|
|||
|
|
|
|||
|
|
## 3.1 结合 Dify 官方仓库的实际情况
|
|||
|
|
|
|||
|
|
当前 `langgenius/dify` 官方仓库并不是一个只有前端的仓库，而是一个完整 monorepo，根目录至少包含：
|
|||
|
|
|
|||
|
|
- `api/`
|
|||
|
|
- `web/`
|
|||
|
|
- `docker/`
|
|||
|
|
- `docs/`
|
|||
|
|
- `scripts/`
|
|||
|
|
- `sdks/`
|
|||
|
|
|
|||
|
|
这意味着你当前的真实策略应该理解为：
|
|||
|
|
|
|||
|
|
- 你是基于整个 Dify 仓库选一个稳定 `tag`
|
|||
|
|
- 但你自己的定制重点只放在 `web/`
|
|||
|
|
- 后续升级时，虽然你主要改前端，但仍然要留意官方 release 对 `api/`、数据库迁移、环境变量的升级要求
|
|||
|
|
|
|||
|
|
换句话说：
|
|||
|
|
|
|||
|
|
- 你的定制范围是前端为主
|
|||
|
|
- 但你的基线版本仍然是整个 Dify 项目版本
|
|||
|
|
|
|||
|
|
## 4. 仓库策略
|
|||
|
|
|
|||
|
|
## 4.1 推荐的现实做法
|
|||
|
|
|
|||
|
|
由于正式仓库必须放在公司内网 Gitea，当前建议采用：
|
|||
|
|
|
|||
|
|
- GitHub：只作为 Dify 官方代码和版本 tag 的来源
|
|||
|
|
- Gitea：作为你的正式开发仓库
|
|||
|
|
- 本地开发环境：用于拉取官方 tag、做定制开发、做升级适配
|
|||
|
|
|
|||
|
|
这意味着：
|
|||
|
|
|
|||
|
|
- 你的正式仓库不一定需要是 GitHub fork
|
|||
|
|
- 直接把某个 Dify tag 的代码放入内网仓库也是可接受的
|
|||
|
|
- 真正重要的是在文档里记录当前基线版本
|
|||
|
|
|
|||
|
|
## 4.2 当前基线管理方式
|
|||
|
|
|
|||
|
|
建议在 README 或专门说明文档中记录：
|
|||
|
|
|
|||
|
|
- 当前 Dify 基线版本
|
|||
|
|
- 当前对应的 baseline 分支
|
|||
|
|
- 当前定制范围
|
|||
|
|
- 当前不做的内容
|
|||
|
|
|
|||
|
|
例如：
|
|||
|
|
|
|||
|
|
- Dify baseline: `v1.0.3`
|
|||
|
|
- Baseline branch: `baseline/dify-1.0.3`
|
|||
|
|
- Customization scope: `frontend only`
|
|||
|
|
- Out of scope: `python backend changes`, `database schema changes`
|
|||
|
|
|
|||
|
|
## 4.3 推荐分支模型
|
|||
|
|
|
|||
|
|
结合你当前的实际情况，推荐使用三类分支：
|
|||
|
|
|
|||
|
|
- `baseline/dify-<version>`
|
|||
|
|
- `main`
|
|||
|
|
- `upgrade/dify-<version>`
|
|||
|
|
|
|||
|
|
这三类分支的职责分别如下。
|
|||
|
|
|
|||
|
|
### `baseline/dify-<version>`
|
|||
|
|
|
|||
|
|
用于保存某个 Dify 官方 tag 对应的纯净基线版本。
|
|||
|
|
|
|||
|
|
例如：
|
|||
|
|
|
|||
|
|
- `baseline/dify-1.13.3`
|
|||
|
|
- `baseline/dify-1.13.4`
|
|||
|
|
|
|||
|
|
这个分支的原则是：
|
|||
|
|
|
|||
|
|
- 尽量保持和官方 tag 一致
|
|||
|
|
- 不放你的业务定制
|
|||
|
|
- 只作为“官方版本快照”存在
|
|||
|
|
|
|||
|
|
你可以把它理解成内网里的“官方镜像基线”。
|
|||
|
|
|
|||
|
|
### `main`
|
|||
|
|
|
|||
|
|
用于保存当前稳定可用的定制版本。
|
|||
|
|
|
|||
|
|
这个分支的原则是：
|
|||
|
|
|
|||
|
|
- 是团队默认开发和使用的主分支
|
|||
|
|
- 已经包含你的轻量前端定制
|
|||
|
|
- 应该始终保持可运行状态
|
|||
|
|
|
|||
|
|
可以理解为：
|
|||
|
|
|
|||
|
|
- `main = baseline + 你的轻量前端定制`
|
|||
|
|
|
|||
|
|
### `upgrade/dify-<version>`
|
|||
|
|
|
|||
|
|
用于处理新版本升级适配。
|
|||
|
|
|
|||
|
|
例如：
|
|||
|
|
|
|||
|
|
- `upgrade/dify-1.13.4`
|
|||
|
|
|
|||
|
|
这个分支的原则是：
|
|||
|
|
|
|||
|
|
- 从新的 baseline 分支拉出
|
|||
|
|
- 在这个分支中把 `main` 的定制重新合进来
|
|||
|
|
- 专门用于解决冲突、修页面、做验证
|
|||
|
|
|
|||
|
|
## 4.4 为什么这个分支模型适合当前阶段
|
|||
|
|
|
|||
|
|
这套模型的好处是把三件事拆开了：
|
|||
|
|
|
|||
|
|
- `baseline`：记录官方原始版本是什么
|
|||
|
|
- `main`：记录你当前稳定定制版本是什么
|
|||
|
|
- `upgrade`：记录这次升级是怎么适配的
|
|||
|
|
|
|||
|
|
这样做有几个现实好处：
|
|||
|
|
|
|||
|
|
- 你以后不会搞混“官方基线”和“你的定制版本”
|
|||
|
|
- 升级时不会直接污染 `main`
|
|||
|
|
- 以后回头看某次升级时，更容易知道冲突和改动来自哪里
|
|||
|
|
|
|||
|
|
## 4.5 分支命名建议
|
|||
|
|
|
|||
|
|
不要使用模糊命名，例如：
|
|||
|
|
|
|||
|
|
- `dify/1.2.x_baseline`
|
|||
|
|
|
|||
|
|
更推荐精确版本命名，例如：
|
|||
|
|
|
|||
|
|
- `baseline/dify-1.13.3`
|
|||
|
|
- `baseline/dify-1.13.4`
|
|||
|
|
- `upgrade/dify-1.13.4`
|
|||
|
|
|
|||
|
|
原因是：
|
|||
|
|
|
|||
|
|
- 模糊版本号不利于排查问题
|
|||
|
|
- 不利于和 README 中记录的版本对应
|
|||
|
|
- 以后很难快速判断当前分支到底对应哪个官方 tag
|
|||
|
|
|
|||
|
|
## 5. 定制范围边界
|
|||
|
|
|
|||
|
|
## 5.0 结合 Dify 实际目录的定制范围
|
|||
|
|
|
|||
|
|
根据 Dify 当前仓库结构，你最可能会接触的是 `web/` 下这些目录：
|
|||
|
|
|
|||
|
|
- `web/app/`
|
|||
|
|
- `web/app/components/`
|
|||
|
|
- `web/service/`
|
|||
|
|
- `web/hooks/`
|
|||
|
|
- `web/constants/`
|
|||
|
|
- `web/context/`
|
|||
|
|
- `web/i18n/`
|
|||
|
|
- `web/public/`
|
|||
|
|
|
|||
|
|
其中：
|
|||
|
|
|
|||
|
|
- `web/app/` 是页面路由和页面组织核心目录
|
|||
|
|
- `web/app/components/` 是页面组件和基础 UI 组件的重要入口
|
|||
|
|
- `web/service/` 通常承接前端调用接口的封装
|
|||
|
|
- `web/i18n/` 和 `web/i18n-config/` 关联国际化内容
|
|||
|
|
|
|||
|
|
如果你的目标只是“轻量前端定制”，那你应尽量把改动集中在这些目录，而不是扩散到整个仓库。
|
|||
|
|
|
|||
|
|
## 5.1 当前允许的轻量定制
|
|||
|
|
|
|||
|
|
建议只在以下范围内修改：
|
|||
|
|
|
|||
|
|
- 菜单入口
|
|||
|
|
- 页面导航结构
|
|||
|
|
- 新增少量业务页面
|
|||
|
|
- workflow 相关展示页面
|
|||
|
|
- 结果展示组件
|
|||
|
|
- AIOps 场景下的说明文案
|
|||
|
|
- 少量样式调整
|
|||
|
|
|
|||
|
|
结合 Dify 当前前端结构，更建议优先改这些地方：
|
|||
|
|
|
|||
|
|
- `web/app/` 下你新增的页面目录
|
|||
|
|
- `web/app/components/` 下与你新增页面强相关的组件
|
|||
|
|
- 少量导航或入口组件
|
|||
|
|
- 少量 `web/service/` 下的数据读取封装
|
|||
|
|
|
|||
|
|
这样做的好处是：
|
|||
|
|
|
|||
|
|
- 你的改动会更集中
|
|||
|
|
- 以后升级时更容易定位冲突文件
|
|||
|
|
- 不容易被 Dify 大量公共组件改动牵连
|
|||
|
|
|
|||
|
|
## 5.2 当前不建议做的事情
|
|||
|
|
|
|||
|
|
当前阶段尽量不要做以下改动：
|
|||
|
|
|
|||
|
|
- 修改 Python 后端业务逻辑
|
|||
|
|
- 修改数据库表结构
|
|||
|
|
- 修改 Dify 核心 workflow 执行逻辑
|
|||
|
|
- 修改底层鉴权、任务运行框架、队列机制
|
|||
|
|
- 大范围重构前端公共基础组件
|
|||
|
|
|
|||
|
|
结合 Dify 当前仓库，尤其不建议你现在去碰：
|
|||
|
|
|
|||
|
|
- `api/` 里的运行逻辑
|
|||
|
|
- `docker/` 里的部署主逻辑，除非是环境适配
|
|||
|
|
- `web/package.json` 的大范围依赖调整
|
|||
|
|
- `web/app/components/base/` 一类全局基础组件的大面积重构
|
|||
|
|
|
|||
|
|
原因很简单：
|
|||
|
|
|
|||
|
|
- 这些改动会显著提高未来升级成本
|
|||
|
|
- 这些改动也超出了当前“轻量定制”的目标
|
|||
|
|
|
|||
|
|
## 5.3 最重要的判断标准
|
|||
|
|
|
|||
|
|
以后每做一个改动，都可以先问一句：
|
|||
|
|
|
|||
|
|
**如果 Dify 升级，我是不是只需要重新适配前端页面？**
|
|||
|
|
|
|||
|
|
如果答案是“是”，那当前改动通常是安全的。
|
|||
|
|
|
|||
|
|
如果答案变成：
|
|||
|
|
|
|||
|
|
- 还要改 Python
|
|||
|
|
- 还要改数据库
|
|||
|
|
- 还要改内部运行逻辑
|
|||
|
|
|
|||
|
|
那说明这个改动已经开始偏重，需要谨慎。
|
|||
|
|
|
|||
|
|
## 6. 推荐的开发流程
|
|||
|
|
|
|||
|
|
## 6.1 初始化阶段
|
|||
|
|
|
|||
|
|
建议按照以下流程开始：
|
|||
|
|
|
|||
|
|
1. 从 GitHub 选择一个稳定的 Dify `tag`
|
|||
|
|
2. 将该版本代码放入公司内网 Gitea 仓库
|
|||
|
|
3. 在 README 中记录当前 Dify 基线版本
|
|||
|
|
4. 在当前基线上开始轻量前端定制
|
|||
|
|
|
|||
|
|
建议在 README 里明确写清楚类似信息：
|
|||
|
|
|
|||
|
|
- 当前 Dify baseline：例如 `1.13.3`
|
|||
|
|
- 当前定制目录：例如 `web/app/aiops`、`web/app/components/aiops`
|
|||
|
|
- 当前不修改：`api/`、数据库 schema、核心 workflow runtime
|
|||
|
|
|
|||
|
|
## 6.2 日常开发阶段
|
|||
|
|
|
|||
|
|
日常开发时建议：
|
|||
|
|
|
|||
|
|
- 以当前基线版本为基础
|
|||
|
|
- 所有新增页面和改动都尽量集中在前端目录
|
|||
|
|
- 保持改动点尽可能少
|
|||
|
|
- 尽量避免散落式修改多个不相关页面
|
|||
|
|
|
|||
|
|
结合 Dify 官方前端 README，当前前端开发的基本事实也要记住：
|
|||
|
|
|
|||
|
|
- 前端项目在 `web/`
|
|||
|
|
- 当前前端是 Next.js 项目
|
|||
|
|
- `web/package.json` 使用 `pnpm`
|
|||
|
|
- `web/package.json` 当前声明的 Node 版本为 `^22.22.1`
|
|||
|
|
- 官方前端 README 提供了 `pnpm run dev`、`pnpm run dev:vinext`、`pnpm run dev:proxy`
|
|||
|
|
|
|||
|
|
这意味着你后续本地改前端页面时，应该优先围绕 `web/` 这套官方开发方式来跑，而不是自己再造一套目录结构。
|
|||
|
|
|
|||
|
|
## 6.3 为什么“集中改动”很重要
|
|||
|
|
|
|||
|
|
升级痛苦的根源通常不是“改了前端”，而是“改动散得到处都是”。
|
|||
|
|
|
|||
|
|
因此建议：
|
|||
|
|
|
|||
|
|
- 尽量集中在少数目录
|
|||
|
|
- 尽量集中在少数页面
|
|||
|
|
- 尽量把通用 patch 控制在小范围内
|
|||
|
|
|
|||
|
|
## 7. 分支策略
|
|||
|
|
|
|||
|
|
## 7.1 推荐分支模型
|
|||
|
|
|
|||
|
|
建议按下面方式使用分支：
|
|||
|
|
|
|||
|
|
- `baseline/dify-<version>`
|
|||
|
|
- 官方 tag 的纯净基线快照
|
|||
|
|
- `main`
|
|||
|
|
- 当前稳定定制版本
|
|||
|
|
- `feature/...`
|
|||
|
|
- 日常轻量前端功能开发
|
|||
|
|
- `upgrade/dify-<version>`
|
|||
|
|
- 某次 Dify 升级的适配分支
|
|||
|
|
|
|||
|
|
如果当前主线是 Dify `1.13.3`，那么一个典型状态可能是：
|
|||
|
|
|
|||
|
|
- `baseline/dify-1.13.3`
|
|||
|
|
- `main`
|
|||
|
|
- `feature/aiops-workflow-ui`
|
|||
|
|
|
|||
|
|
如果准备升级到 `1.13.4`，则新增：
|
|||
|
|
|
|||
|
|
- `baseline/dify-1.13.4`
|
|||
|
|
- `upgrade/dify-1.13.4`
|
|||
|
|
|
|||
|
|
## 7.2 为什么升级必须走独立分支
|
|||
|
|
|
|||
|
|
因为升级本质上不是普通功能开发，而是：
|
|||
|
|
|
|||
|
|
- 引入新的上游代码
|
|||
|
|
- 重新适配已有前端改动
|
|||
|
|
- 重新验证页面可用性
|
|||
|
|
|
|||
|
|
如果直接在 `main` 上升级，很容易把稳定版本打乱。
|
|||
|
|
|
|||
|
|
更准确地说，推荐做法是：
|
|||
|
|
|
|||
|
|
1. 先创建新的 `baseline/dify-<version>`
|
|||
|
|
2. 再从这个新的 baseline 拉出 `upgrade/dify-<version>`
|
|||
|
|
3. 在 upgrade 分支里把当前 `main` 的定制合进来
|
|||
|
|
4. 在 upgrade 分支里解决兼容问题
|
|||
|
|
5. 验证通过后再合回 `main`
|
|||
|
|
|
|||
|
|
## 8. 升级策略
|
|||
|
|
|
|||
|
|
## 8.1 什么时候升级
|
|||
|
|
|
|||
|
|
不要因为 Dify 发布了新版本就立刻升级。
|
|||
|
|
|
|||
|
|
建议只有在以下情况才升级：
|
|||
|
|
|
|||
|
|
- 需要某个新功能
|
|||
|
|
- 需要某个关键修复
|
|||
|
|
- 当前版本存在明显问题
|
|||
|
|
- 团队决定统一升级基线
|
|||
|
|
|
|||
|
|
再补一个很现实的判断条件：
|
|||
|
|
|
|||
|
|
- 官方 release 明确修复了你实际会碰到的 `workflow`、`knowledge retrieval`、`web` 页面或运行问题
|
|||
|
|
|
|||
|
|
## 8.2 升级频率建议
|
|||
|
|
|
|||
|
|
建议：
|
|||
|
|
|
|||
|
|
- 不追 `latest`
|
|||
|
|
- 尽量按明确版本升级
|
|||
|
|
- 每次升级跨度不要太大
|
|||
|
|
|
|||
|
|
例如优先这样升级：
|
|||
|
|
|
|||
|
|
- `v1.0.3 -> v1.0.5`
|
|||
|
|
- 再视情况评估是否升级到 `v1.1.x`
|
|||
|
|
|
|||
|
|
## 8.3 升级流程
|
|||
|
|
|
|||
|
|
推荐升级流程如下：
|
|||
|
|
|
|||
|
|
1. 查看 GitHub 上 Dify 新版本 tag
|
|||
|
|
2. 选择目标版本
|
|||
|
|
3. 创建新的 baseline 分支，例如 `baseline/dify-1.13.4`
|
|||
|
|
4. 在该 baseline 分支中保存新的官方基线代码
|
|||
|
|
5. 从新的 baseline 分支拉出升级分支，例如 `upgrade/dify-1.13.4`
|
|||
|
|
6. 在 upgrade 分支里把当前 `main` 的定制改动合进来
|
|||
|
|
7. 解决冲突并重新适配你的前端页面
|
|||
|
|
8. 本地运行并验证关键页面
|
|||
|
|
9. 验证通过后把 `upgrade/dify-1.13.4` 合并回 `main`
|
|||
|
|
10. 更新 README 中记录的 Dify 基线版本和 baseline 分支
|
|||
|
|
|
|||
|
|
如果你采用的是“把官方 tag 的代码直接放进公司 Gitea”这种方式，那么第 4 步在你这里通常会表现为：
|
|||
|
|
|
|||
|
|
- 用新的官方 tag 覆盖当前基线代码
|
|||
|
|
- 再把你自己的前端轻量改动重新适配回来
|
|||
|
|
|
|||
|
|
这不是最优雅的 git 方案，但对你当前阶段是可接受的。
|
|||
|
|
|
|||
|
|
## 8.3.1 一个完整例子
|
|||
|
|
|
|||
|
|
假设你当前状态如下：
|
|||
|
|
|
|||
|
|
- 当前官方基线：`1.13.3`
|
|||
|
|
- 当前基线分支：`baseline/dify-1.13.3`
|
|||
|
|
- 当前稳定定制分支：`main`
|
|||
|
|
|
|||
|
|
现在准备升级到 `1.13.4`，推荐流程是：
|
|||
|
|
|
|||
|
|
1. 新建 `baseline/dify-1.13.4`
|
|||
|
|
2. 把 Dify 官方 `1.13.4` tag 的代码放到这个 baseline 分支
|
|||
|
|
3. 从 `baseline/dify-1.13.4` 拉出 `upgrade/dify-1.13.4`
|
|||
|
|
4. 在 `upgrade/dify-1.13.4` 上把 `main` 合进来
|
|||
|
|
5. 处理前端冲突和页面兼容问题
|
|||
|
|
6. 本地验证通过后，把 `upgrade/dify-1.13.4` 合并回 `main`
|
|||
|
|
7. 更新 README：
|
|||
|
|
- Dify baseline = `1.13.4`
|
|||
|
|
- Baseline branch = `baseline/dify-1.13.4`
|
|||
|
|
|
|||
|
|
这样做的结果是：
|
|||
|
|
|
|||
|
|
- 旧基线仍然保留在 `baseline/dify-1.13.3`
|
|||
|
|
- 新基线清晰记录在 `baseline/dify-1.13.4`
|
|||
|
|
- `main` 永远代表“当前稳定可用版本`
|
|||
|
|
|
|||
|
|
## 8.4 升级的本质理解
|
|||
|
|
|
|||
|
|
升级不是“自动同步所有定制”，而是：
|
|||
|
|
|
|||
|
|
**换一个新的 Dify 上游版本，然后把你那层轻量前端定制重新贴上去。**
|
|||
|
|
|
|||
|
|
只要这层定制足够薄，升级就不会太痛苦。
|
|||
|
|
|
|||
|
|
## 9. 升级时重点检查什么
|
|||
|
|
|
|||
|
|
对当前这种轻量定制场景，不需要设计太复杂的验证体系。
|
|||
|
|
|
|||
|
|
升级后重点检查以下内容即可：
|
|||
|
|
|
|||
|
|
- 页面能否正常打开
|
|||
|
|
- 菜单入口是否正常
|
|||
|
|
- 新增页面是否还能访问
|
|||
|
|
- 你修改过的 workflow 相关页面是否还能正常渲染
|
|||
|
|
- 页面调用的数据接口是否仍然可用
|
|||
|
|
- 基础流程是否正常
|
|||
|
|
- 查看 workflow
|
|||
|
|
- 查看结果
|
|||
|
|
- 查看详情页
|
|||
|
|
|
|||
|
|
这本质上就是一次轻量 smoke test。
|
|||
|
|
|
|||
|
|
## 9.1 结合 Dify release note 需要特别留意的事项
|
|||
|
|
|
|||
|
|
根据 Dify 最近公开 release 的 upgrade guide，后续升级时即使你“不改 Python”，也仍然需要关注这些上游变化：
|
|||
|
|
|
|||
|
|
- 是否有新的数据库迁移要求
|
|||
|
|
- 官方 release 中会出现 `uv run flask db upgrade`
|
|||
|
|
- 是否有新的 Python 依赖同步要求
|
|||
|
|
- 官方 release 中会出现 `cd api && uv sync`
|
|||
|
|
- 是否有 Sandbox 配置变更
|
|||
|
|
- 例如 release 中提到 Python 和 Node.js 默认路径变化
|
|||
|
|
- 是否有队列配置要求变化
|
|||
|
|
- 例如某些版本会要求 `CELERY_QUEUES` 必须包含指定队列
|
|||
|
|
|
|||
|
|
这部分非常重要，因为它说明：
|
|||
|
|
|
|||
|
|
- 你虽然不打算改 Python 代码
|
|||
|
|
- 但升级整个 Dify 基线时，不能只盯前端页面
|
|||
|
|
- 仍然要读一下官方 release 的 upgrade guide
|
|||
|
|
|
|||
|
|
所以你最现实的升级习惯应该是：
|
|||
|
|
|
|||
|
|
1. 先看 release note
|
|||
|
|
2. 看有没有 backend migration / env 变更
|
|||
|
|
3. 再做前端适配
|
|||
|
|
4. 最后一起验证
|
|||
|
|
|
|||
|
|
## 9.2 结合 Dify 当前前端结构的检查重点
|
|||
|
|
|
|||
|
|
由于 Dify 当前 `web/` 下是 App Router 风格的页面组织，升级时建议重点检查这些位置：
|
|||
|
|
|
|||
|
|
- `web/app/` 下你新增或修改过的页面目录
|
|||
|
|
- `web/app/components/` 下你改过的业务组件
|
|||
|
|
- `web/service/` 下你依赖的数据接口封装
|
|||
|
|
- `web/i18n/` 下你新增的文案 key
|
|||
|
|
- `web/package.json` 是否有前端主版本依赖升级
|
|||
|
|
|
|||
|
|
如果官方 release 里出现下面这些关键词，你要提高警惕：
|
|||
|
|
|
|||
|
|
- `workflow`
|
|||
|
|
- `web`
|
|||
|
|
- `toast`
|
|||
|
|
- `base ui`
|
|||
|
|
- `knowledge retrieval`
|
|||
|
|
- `streaming`
|
|||
|
|
- `next`
|
|||
|
|
- `react`
|
|||
|
|
|
|||
|
|
因为这些都很可能直接影响你的页面兼容性。
|
|||
|
|
|
|||
|
|
## 10. README 应记录的最小信息
|
|||
|
|
|
|||
|
|
建议在 README 中长期保留以下最小信息：
|
|||
|
|
|
|||
|
|
- 当前 Dify 基线版本
|
|||
|
|
- 当前 baseline 分支
|
|||
|
|
- 当前定制范围
|
|||
|
|
- 当前升级策略
|
|||
|
|
- 当前 workflow 相关文档入口
|
|||
|
|
|
|||
|
|
建议格式示例：
|
|||
|
|
|
|||
|
|
| 项目 | 当前值 |
|
|||
|
|
| --- | --- |
|
|||
|
|
| Dify baseline | `v1.0.3` |
|
|||
|
|
| Baseline branch | `baseline/dify-1.0.3` |
|
|||
|
|
| Customization scope | `frontend pages, menu, workflow views` |
|
|||
|
|
| Backend policy | `no python customization by default` |
|
|||
|
|
| Upgrade policy | `upgrade in dedicated branch, merge after validation` |
|
|||
|
|
|
|||
|
|
## 11. 推荐保留的变更记录
|
|||
|
|
|
|||
|
|
为了避免以后忘记自己改过什么，建议记录两类信息：
|
|||
|
|
|
|||
|
|
### 11.1 当前改动范围
|
|||
|
|
|
|||
|
|
例如：
|
|||
|
|
|
|||
|
|
- 修改了哪些前端目录
|
|||
|
|
- 新增了哪些页面
|
|||
|
|
- 改了哪些导航入口
|
|||
|
|
|
|||
|
|
### 11.2 升级影响记录
|
|||
|
|
|
|||
|
|
例如每次升级后记录：
|
|||
|
|
|
|||
|
|
- 从哪个版本升级到哪个版本
|
|||
|
|
- 哪些页面需要重新适配
|
|||
|
|
- 是否发生接口字段变化
|
|||
|
|
- 是否有已知兼容问题
|
|||
|
|
|
|||
|
|
这类记录不需要很长，但会非常有用。
|
|||
|
|
|
|||
|
|
建议你把升级记录写得更贴近 Dify 仓库实际结构，例如：
|
|||
|
|
|
|||
|
|
| 项目 | 记录示例 |
|
|||
|
|
| --- | --- |
|
|||
|
|
| From | `1.13.2` |
|
|||
|
|
| To | `1.13.3` |
|
|||
|
|
| Baseline branch | `baseline/dify-1.13.3` |
|
|||
|
|
| Frontend touched | `web/app/...`, `web/app/components/...` |
|
|||
|
|
| Upstream notes | `workflow editor fix`, `knowledge retrieval fix` |
|
|||
|
|
| Backend actions | `uv sync`, `flask db upgrade` |
|
|||
|
|
| Result | `passed smoke test` |
|
|||
|
|
|
|||
|
|
这样以后你回头看，会比抽象描述有用得多。
|
|||
|
|
|
|||
|
|
## 11.3 建议保留一个“自定义文件清单”
|
|||
|
|
|
|||
|
|
这个清单非常适合你当前模式。
|
|||
|
|
|
|||
|
|
建议维护一个简短列表，记录你实际改过的文件或目录，例如：
|
|||
|
|
|
|||
|
|
- `web/app/aiops/...`
|
|||
|
|
- `web/app/components/aiops/...`
|
|||
|
|
- `web/app/components/sidebar/...`
|
|||
|
|
- `web/service/...`
|
|||
|
|
|
|||
|
|
这样以后升级时，你第一时间就知道先检查哪里。
|
|||
|
|
|
|||
|
|
## 12. 当前最适合的工程原则
|
|||
|
|
|
|||
|
|
结合当前阶段，建议坚持以下原则：
|
|||
|
|
|
|||
|
|
1. 先把版本固定住，不要追最新。
|
|||
|
|
2. 先把前端薄定制做好，不要做后端深度二开。
|
|||
|
|
3. 升级时一定走独立分支。
|
|||
|
|
4. 升级完成后同步更新 README 和基线版本说明。
|
|||
|
|
5. 如果未来发现前端定制越来越重，再考虑把更多页面迁到你自己的平台前端。
|
|||
|
|
|
|||
|
|
## 13. 什么情况下需要调整当前策略
|
|||
|
|
|
|||
|
|
当前这套轻量策略适合“前端轻改 + 后端基本不动”的阶段。
|
|||
|
|
|
|||
|
|
当出现下面任一情况时，应考虑升级策略：
|
|||
|
|
|
|||
|
|
- 你开始频繁修改 Python 后端
|
|||
|
|
- 你需要控制 Dify 的内部权限或运行逻辑
|
|||
|
|
- 你需要大量自定义 workflow 管理页面
|
|||
|
|
- 你发现每次升级都要改很多核心文件
|
|||
|
|
|
|||
|
|
如果发生这些情况，说明你已经逐渐从“轻量定制”进入“中度二开”，那时再重新设计仓库与升级策略更合适。
|
|||
|
|
|
|||
|
|
## 14. 结论
|
|||
|
|
|
|||
|
|
当前阶段，最现实、最省时间、也最适合长期推进的做法就是：
|
|||
|
|
|
|||
|
|
- 用一个固定 Dify `tag` 做基线
|
|||
|
|
- 把代码放进公司内网 Gitea
|
|||
|
|
- 只做轻量前端定制
|
|||
|
|
- 后续如果 Dify 有新版本，就开升级分支重新适配前端改动
|
|||
|
|
- 验证通过后合并回 `main`
|
|||
|
|
- 最后更新 README 中的基线版本说明
|
|||
|
|
|
|||
|
|
这不是最复杂的工程方案，但它是当前最务实、最容易执行、最符合你时间约束的方案。
|
|||
|
|
|
|||
|
|
## 15. 参考依据
|
|||
|
|
|
|||
|
|
本文主要基于 `https://github.com/langgenius/dify` 官方公开信息整理，重点参考：
|
|||
|
|
|
|||
|
|
- 根目录结构：`api/`、`web/`、`docker/`、`docs/`
|
|||
|
|
- `web/README.md`
|
|||
|
|
- `web/package.json`
|
|||
|
|
- 官方 release 中的 upgrade guide 与 release notes
|