Dify 宏观学习知识架构与学习路线

豆破苍琼

62人浏览 · 2026-03-29 20:22:50

豆破苍琼 · 2026-03-29 20:22:50 发布

1. 背景

Dify 是一个面向 LLM 应用开发的开源平台。它不是单一的聊天应用，也不是单纯的模型调用 SDK，而是一套把 模型接入、应用编排、知识库/RAG、Agent、工作流、可观测性、多租户控制台 和 对外 API 组合在一起的完整工程系统。

如果从“学习一个仓库”转向“理解一个 AI 应用平台”，那么阅读 Dify 的正确方式不应是直接扎进某个文件，而应先建立宏观知识架构，再按主链路逐层下钻。

本文档的目标是：

梳理当前仓库的项目目录与模块职责
建立学习 Dify 的宏观知识地图
给出一条从部署、读代码到二次开发的学习路线

2. 项目目录宏观梳理

2.1 仓库一级目录

当前仓库可以先按“产品运行链路”而不是“技术栈”理解：

api/: 后端主服务，Flask + DDD/Clean Architecture，承接应用配置、工作流执行、模型调用、知识库处理、任务调度等核心业务
web/: 前端控制台与 Web App，Next.js + TypeScript + React，承接控制台页面、应用配置、数据集、插件、工作流 UI
docker/: Docker Compose 部署与中间件配置，是理解系统运行拓扑的最佳入口之一
docs/: 多语言文档，偏使用与部署说明
sdks/: 面向外部接入方的 SDK
scripts/、dev/: 开发辅助脚本、启动脚本、测试和本地开发工具
images/: README 等文档图片资源

2.2 后端目录重点

api/ 是 Dify 的业务中枢，建议重点关注这些目录：

api/controllers/: HTTP 接口入口层
api/services/: 应用服务层，连接控制器与领域逻辑
api/core/: 真正的核心能力区，包含 workflow、model_runtime、rag 等关键模块
api/models/: 数据模型
api/repositories/: 数据访问抽象
api/tasks/、api/schedule/: Celery 异步任务与定时任务
api/extensions/: 扩展能力
api/tests/: 测试

其中最值得优先读的是：

api/core/workflow/: 工作流图引擎，Dify 差异化能力之一
api/core/model_runtime/: 模型运行时与多模型供应商抽象层
api/core/rag/: 知识库与检索增强相关能力

2.3 前端目录重点

web/ 不是简单的页面层，它承担了控制台、应用编排和部分平台抽象表达。

web/app/: Next.js App Router 主目录，包含控制台页面与分享页面
web/app/components/: 页面级和领域级组件，覆盖 apps、datasets、workflow、plugins、provider 等
web/service/: 面向后端接口的服务层
web/contract/: 前端接口契约层
web/hooks/: 通用 Hooks
web/i18n/: 用户可见文案，多语言资源
web/types/、web/models/: 类型与前端数据模型
web/utils/: 工具函数

从页面组织上看，web/app/(commonLayout) 下聚合了主要控制台能力：

app/、apps/: 应用与应用编排
datasets/: 知识库
plugins/: 插件生态
tools/: 工具能力
explore/: 探索与展示类页面

2.4 部署目录重点

docker/ 对理解 Dify 很重要，因为它直接揭示系统依赖：

docker-compose.yaml: 完整部署入口
docker-compose.middleware.yaml: 本地开发常用中间件编排
关键依赖包括：
- PostgreSQL
- Redis
- 向量数据库服务，如 Weaviate 等
- Nginx / Certbot / OpenTelemetry 等外围组件

如果想先从系统全景而不是代码细节入手，优先看 docker/ 会比优先看 api/controllers/ 更高效。

3. Dify 的宏观知识架构

可以把 Dify 拆成 6 个学习层次。

3.1 产品能力层

这是“Dify 是什么”。

应用构建平台
Prompt IDE
Workflow 编排
Agent 能力
RAG/知识库
模型管理与供应商接入
LLMOps / 观测分析
API 化输出能力

这一层决定你阅读代码时的目标感。如果不知道产品能力边界，就很容易把仓库误读成“一个 Flask 项目 + 一个 Next.js 项目”。

3.2 系统运行层

这是“Dify 怎么跑起来”。

Web 前端负责控制台与 Web App
API 后端负责业务逻辑与对外接口
PostgreSQL 负责主业务数据
Redis 负责缓存、消息协同、异步支撑
Celery 负责异步任务
向量数据库负责检索增强
Docker Compose 负责本地或自部署环境编排

这一层建议先建立完整链路：浏览器 -> Web -> API -> DB/Redis/Vector DB -> Worker

3.3 业务域层

这是“Dify 的核心业务对象是什么”。

建议重点围绕以下域来理解：

应用域：聊天应用、工作流应用、Agent 应用
模型域：Provider、Model、凭证、能力类型
知识库域：文档导入、切片、索引、召回、重排
工作流域：Graph、Node、Edge、Runtime State、Event
插件/工具域：内置工具、外部工具、插件接入
运营域：日志、观测、发布、租户与权限

3.4 核心引擎层

这是“Dify 的技术护城河在哪里”。

核心看三块：

workflow graph engine
- 图执行
- 节点调度
- 并行/迭代/条件分支
- 事件传播
- 暂停、恢复、终止控制
model runtime
- 多模型供应商统一抽象
- 多模型能力统一调用
- 凭证校验与参数规则
rag pipeline
- 文档处理
- 向量化
- 检索
- 重排
- 上下文拼装

3.5 工程支撑层

这是“为什么这个平台能持续演进”。

DDD / Clean Architecture 的分层约束
前后端分仓式目录组织但单仓协作
测试体系
i18n 约束
Docker 化部署
SDK 对外能力输出

3.6 扩展生态层

这是“Dify 为什么适合作为平台而不是 Demo”。

Provider 可扩展
Workflow Node 可扩展
Tool / Plugin 可扩展
API / SDK 可集成到外部业务

4. 推荐学习路线

4.1 第一阶段：先建立全局认知

目标：知道 Dify 解决什么问题、由哪些大模块组成。

建议顺序：

阅读根目录 README.md
阅读 docker/README.md
阅读 api/README.md 和 web/README.md
浏览仓库一级目录与 api/、web/ 的二级目录

此阶段产出应该是：

你能讲清 Dify 的产品定位
你能画出主要运行架构图
你知道前后端和中间件分别承担什么职责

4.2 第二阶段：跑通系统主链路

目标：理解一个请求是如何穿过整个系统的。

建议动作：

用 docker/ 看部署依赖
用 dev/ 脚本看本地开发启动顺序
启动 Web、API、Middleware
在浏览器里完成初始化
创建一个最简单的应用，观察前后端交互

此阶段重点不是“改代码”，而是“建立运行感”。

4.3 第三阶段：按核心能力分专题学习

目标：从“会跑”升级到“知道为什么这样设计”。

建议优先级如下：

工作流
- 读 api/core/workflow/README.md
- 重点理解 Graph、Node、Edge、Event、Layer、Command Channel
- 这是 Dify 最值得深挖的部分
模型运行时
- 读 api/core/model_runtime/README.md
- 理解 Provider 和 Model 的双层抽象
- 这是多模型接入能力的基础
知识库 / RAG
- 继续下钻 api/core/rag/
- 理解导入、切片、索引、召回、重排链路
前端控制台
- 看 web/app/ 的页面分区
- 看 web/app/components/ 的领域组件组织
- 看 web/service/ 与 web/contract/ 如何对接后端