# 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