Dify 架构全景：从模块设计到部署实践的完整指南

项目概述

Dify 是一个开源的 LLM 应用开发平台，提供直观的界面，结合了AI Agent工作流、RAG 管道、智能体能力、模型管理和可观察性功能等，使用户能够快速从原型转向生产环境。Dify 允许开发者通过可视化界面构建功能强大的 AI 应用，同时提供相应的 API 服务供集成使用。

graph TB
classDef coreModule fill:#ffe6cc,stroke:#FFA500,stroke-width:2px
classDef webModule fill:#d4f1f9,stroke:#87CEFA,stroke-width:2px
classDef sdkModule fill:#d5e8d4,stroke:#82B366,stroke-width:2px
classDef dockerModule fill:#fff2cc,stroke:#D6B656,stroke-width:2px
classDef devModule fill:#e1d5e7,stroke:#9673A6,stroke-width:2px

DIFY[Dify LLM 应用开发平台]
SDK[SDK 模块<br/>/sdks]:::sdkModule
API[API 服务模块<br/>/api]:::coreModule
WEB[Web 前端模块<br/>/web]:::webModule
DOCKER[Docker 部署模块<br/>/docker]:::dockerModule
DEV[开发工具模块<br/>/dev]:::devModule

DIFY --> SDK
DIFY --> DOCKER
DIFY --> API
DIFY --> WEB
DIFY --> DEV

MODELS[(LLM 模型)]
DB[(数据存储)]

SDK --- API
WEB --> API
API --- DB
API --- MODELS

style DIFY font-size:18px,font-weight:bold

核心模块概览与关系

Dify 项目主要由以下几个核心模块组成，它们协同工作形成一个完整的 LLM 应用开发平台：

1. API 服务模块 (/api): 后端核心，基于 Flask 构建，提供所有功能的 RESTful API 接口，包括模型管理、应用逻辑、数据处理等服务。

2. Web 前端模块 (/web): 基于 Next.js 构建的用户界面，提供工作流设计器、模型管理、应用配置等可视化操作界面。

3. SDK 模块 (/sdks): 提供多语言客户端 SDK (Node.js、PHP、Python)，方便开发者在自己的应用中集成 Dify 功能。

4. Docker 部署模块 (/docker): 提供容器化部署相关的配置文件和脚本，简化系统部署和环境配置。

5. 开发工具模块 (/dev): 包含开发相关的工具和脚本，辅助项目开发和质量控制。

模块间关系

graph TD
Web["Web 前端模块<br>/web"] -->|HTTP 请求| API["API 服务模块<br>/api"]
SDK["SDK 模块<br>/sdks"] -->|API 调用| API
API -->|调用外部服务| Models["外部模型服务<br>OpenAI等"]
API -->|读写数据| DB["数据存储服务<br>PostgreSQL等"]

style Web fill:#d4f1f9,stroke:#87CEFA
style API fill:#ffe6cc,stroke:#FFA500
style SDK fill:#d5e8d4,stroke:#82B366
style Models fill:#e1d5e7,stroke:#9673A6
style DB fill:#fff2cc,stroke:#D6B656

1. 前端-后端交互: Web 前端通过 HTTP 请求与 API 服务交互，实现用户界面操作
2. API-模型集成: API 服务连接各种外部 LLM 模型服务 (如 OpenAI、Anthropic 等)
3. SDK-API 集成: SDK 模块封装 API 调用，方便第三方应用集成
4. 持久化存储: API 服务连接数据库和文件存储服务，保存应用配置和数据

详细模块介绍

1. API 服务模块 (/api)

flowchart TB
subgraph api["API 服务模块"]
direction TB
API[API模块]
AppEntry[app.py/app_factory.py<br>应用入口]
Controllers[controllers/<br>控制器]
Core[core/<br>核心业务逻辑]
Services[services/<br>服务层]
Models[models/<br>数据模型]

API --> AppEntry
API --> Controllers
API --> Core
API --> Services
API --> Models
end

subgraph controllers["控制器层"]
direction TB
ConsoleAPI[console/<br>控制台API]
ServiceAPI[service_api/<br>服务API]
FilesAPI[files/<br>文件API]
end

subgraph core["核心层"]
direction TB
AgentCore[agent/<br>智能体能力]
RAGCore[rag/<br>RAG引擎]
WorkflowCore[workflow/<br>工作流引擎]
LLMGenerator[llm_generator/<br>大模型生成]
end

subgraph services["服务层"]
direction TB
AuthService[auth/<br>认证服务]
WorkflowService[workflow/<br>工作流服务]
EntitiesService[entities/<br>实体服务]
end

Controllers --> controllers
Core --> core
Services --> services

style API fill:#ffe6cc,stroke:#FFA500,stroke-width:2px
style AppEntry fill:#d4f1f9,stroke:#87CEFA
style Core fill:#f8cecc,stroke:#b85450
style Controllers fill:#f8cecc,stroke:#b85450
style Services fill:#f8cecc,stroke:#b85450
style Models fill:#f8cecc,stroke:#b85450

API 模块是 Dify 的后端核心，提供所有功能的 RESTful API 接口。该模块基于 Flask 构建，实现了应用的核心业务逻辑和服务接口。

核心文件

• app_factory.py: 应用工厂，负责创建和配置 Flask 应用实例，初始化扩展（数据库、缓存、任务队列等）
• app.py: 应用程序入口点，配置服务运行环境，启动应用服务
• dify_app.py: Dify 应用程序的核心类，继承自 Flask，实现应用基础功能
• commands.py: 定义命令行工具功能，如数据库初始化、模型同步等维护命令

核心子模块

• controllers/: 控制器层，处理 HTTP 请求，是前端和SDK与后端交互的接口

  • console/: 管理控制台相关接口，提供应用管理、模型配置等功能
  • service_api/: 对外服务API接口，提供应用运行时调用的接口
  • files/: 文件处理接口，处理文档上传、解析等功能
  • common/: 通用控制器组件
  • inner_api/: 内部API接口

• core/: 核心业务逻辑实现，包含应用的主要功能模块

  • agent/: 智能体能力实现，提供AI智能体的功能支持
  • rag/: 检索增强生成(RAG)引擎，处理文档检索与生成集成
  • workflow/: 工作流引擎，实现可视化工作流的执行逻辑
  • llm_generator/: LLM生成器，处理大模型文本生成
  • model_runtime/: 模型运行时，管理模型调用
  • tools/: 工具库，提供各种功能工具
  • prompt/: 提示词管理，处理提示词模板
  • memory/: 对话记忆管理

• services/: 服务层实现，提供具体业务功能的服务

  • auth/: 认证服务，处理用户认证和授权
  • workflow/: 工作流服务，提供工作流管理功能
  • entities/: 实体服务，处理业务实体对象
  • plugin/: 插件服务，管理第三方插件
  • enterprise/: 企业版特性服务
  • errors/: 错误处理服务

• models/: 数据模型定义，映射数据库表结构，为系统提供数据持久化能力

支持模块

• configs/: 配置管理，存储系统各项配置参数

  • feature/: 功能特性配置
  • deploy/: 部署相关配置
  • middleware/: 中间件配置
  • enterprise/: 企业版功能配置

• extensions/: Flask 扩展集成，连接外部服务和组件

  • storage/: 存储扩展，处理文件存储

• tasks/: 异步任务定义，使用 Celery 实现后台计算任务

  • annotation/: 标注相关任务

• events/: 事件系统，处理系统内部事件通知

  • event_handlers/: 事件处理器

• libs/: 通用库和工具函数，提供底层功能支持

• migrations/: 数据库迁移脚本，管理数据库结构变更

  • versions/: 版本化的迁移文件

• tests/: 测试代码目录

  • unit_tests/: 单元测试
  • integration_tests/: 集成测试
  • artifact_tests/: 工件测试

2. Web 前端模块 (/web)

graph TD
Web[Web前端模块] --> App[app/<br>Next.js应用]
Web --> Service[service/<br>API调用]
Web --> Context[context/<br>状态管理]
Web --> Utils[utils/<br>工具函数]
Web --> I18n[i18n/<br>国际化]

App --> CommonLayout[commonLayout/<br>通用布局]
App --> ShareLayout[shareLayout/<br>共享布局]
App --> AccountRoutes[account/<br>账户相关]
App --> Components[components/<br>页面组件]
App --> Signin[signin/<br>登录页面]

Service --> AppService[apps.ts<br>应用服务]
Service --> WorkflowService[workflow.ts<br>工作流服务]
Service --> DatasetsService[datasets.ts<br>数据集服务]
Service --> KnowledgeService[knowledge/<br>知识库服务]

style Web fill:#d4f1f9,stroke:#87CEFA,stroke-width:2px
style App fill:#f8cecc,stroke:#b85450
style Service fill:#f8cecc,stroke:#b85450
style Context fill:#f8cecc,stroke:#b85450
style Utils fill:#f8cecc,stroke:#b85450
style I18n fill:#f8cecc,stroke:#b85450

Web 模块是 Dify 的前端实现，基于 Next.js 构建，提供用户友好的界面。它实现了所有的用户交互功能，包括应用管理、账户控制、登录认证等。

核心目录

• app/: Next.js 应用结构，包含各页面路由和组件

  • (commonLayout)/: 通用布局组件，提供一致的UI框架
  • (shareLayout)/: 共享布局组件，用于共享页面的布局结构
  • account/: 账户管理相关页面
  • components/: 页面级组件
  • signin/: 登录认证页面
  • forgot-password/: 密码找回页面
  • reset-password/: 密码重置页面
  • activate/: 账户激活页面
  • init/: 初始化配置页面
  • install/: 安装向导页面

• service/: API 服务调用封装，负责与后端API交互

  • apps.ts: 应用相关API调用
  • workflow.ts: 工作流相关API调用
  • datasets.ts: 数据集相关API调用
  • knowledge/: 知识库相关API调用
  • base.ts: 基础API请求封装
  • fetch.ts: 网络请求工具
  • billing.ts: 计费相关服务
  • common.ts: 通用服务接口

支持模块

• context/: React 上下文管理，提供全局状态管理
• hooks/: 自定义 React Hooks，封装常用逻辑
• i18n/: 国际化多语言支持，包含各种语言的翻译资源
  • de-DE/, en-US/, es-ES/, fr-FR/ 等: 不同语言的翻译文件
• utils/: 工具函数，提供通用功能支持
• themes/: 主题配置，管理应用界面风格
• models/: 前端数据模型定义
• types/: TypeScript 类型定义
• assets/: 静态资源文件
• public/: 公共资源目录，包含图片、logo等静态资源

构建与配置

• next.config.js: Next.js 配置文件
• tailwind.config.js: TailwindCSS 配置
• eslint.config.mjs: ESLint 代码规范配置
• tsconfig.json: TypeScript 配置
• jest.config.ts: 测试配置

3. SDK 模块 (/sdks)

graph TD
SDK[SDK模块] --> JSClient[nodejs-client]
SDK --> PyClient[python-client]
SDK --> PHPClient[php-client]

PyClient --> PyCore[CompletionClient<br>ChatClient<br>DifyClient]
JSClient --> JSCore[DifyClient<br>ChatClient<br>CompletionClient]
PHPClient --> PHPCore[DifyClient<br>ChatClient<br>CompletionClient]

style SDK fill:#d5e8d4,stroke:#82B366,stroke-width:2px
style JSClient fill:#f8cecc,stroke:#b85450
style PyClient fill:#f8cecc,stroke:#b85450
style PHPClient fill:#f8cecc,stroke:#b85450

SDK 模块提供多语言的客户端库，目前支持 Node.js、Python 和 PHP 三种主要编程语言，便于开发者在不同技术栈中接入 Dify 平台。

核心组件与功能

各语言 SDK 均提供三个关键类：

1. DifyClient：基础客户端类

   • 获取应用参数 (getApplicationParameters/get_application_parameters)
   • 提交消息反馈 (messageFeedback/message_feedback)
   • 文件上传功能 (fileUpload/file_upload)

2. ChatClient：对话型应用接口

   • 创建对话消息 (createChatMessage/create_chat_message)
   • 获取对话列表 (getConversations/get_conversations)
   • 获取对话消息 (getConversationMessages/get_conversation_messages)
   • 重命名对话 (renameConversation/rename_conversation)

3. CompletionClient：文本补全型应用接口

   • 创建补全消息 (createCompletionMessage/create_completion_message)

4. Docker 部署模块 (/docker)

graph TD
Docker[Docker部署模块] --> ComposeFile[docker-compose.yaml<br>服务编排]
Docker --> Generator[generate_docker_compose<br>配置生成]
Docker --> EnvExample[middleware.env.example<br>环境变量模板]

Docker --> Nginx[nginx/<br>Web服务器]
Docker --> PGVector[pgvector/<br>向量数据库]
Docker --> ES[elasticsearch/<br>搜索引擎]
Docker --> Volumes[volumes/<br>数据持久化]

style Docker fill:#fff2cc,stroke:#D6B656,stroke-width:2px
style ComposeFile fill:#f8cecc,stroke:#b85450
style Generator fill:#f8cecc,stroke:#b85450
style EnvExample fill:#f8cecc,stroke:#b85450
style Nginx fill:#d5e8d4,stroke:#82B366
style PGVector fill:#d5e8d4,stroke:#82B366
style ES fill:#d5e8d4,stroke:#82B366

Docker 模块提供容器化部署相关的配置文件和脚本，简化系统部署和环境配置。

核心文件

• docker-compose.yaml: 定义多容器服务编排，包含Web、API、数据库等服务配置
• generate_docker_compose: 生成 docker-compose 配置的脚本，根据用户需求自定义配置
• middleware.env.example: 中间件环境变量示例，提供配置参考

关键子目录

• nginx/: Web 服务器和反向代理配置，处理请求转发和静态资源

  • nginx.conf: Nginx主配置文件
  • ssl/: SSL证书配置

• pgvector/: PostgreSQL 向量扩展配置，为RAG提供向量存储支持

  • init-scripts/: 数据库初始化脚本

• elasticsearch/: Elasticsearch 搜索引擎配置，为知识库提供全文搜索能力

  • plugins/: ES插件配置

• volumes/: 持久化数据卷配置，确保数据在容器重启后不丢失

支持组件

• certbot/: HTTPS 证书自动化，提供SSL证书申请和续期
• tidb/: TiDB 配置，提供可选的分布式数据库支持
• couchbase-server/: Couchbase 配置，提供可选的NoSQL数据库支持

5. 开发工具模块 (/dev)

graph TD
Dev[开发工具模块] --> Reformat[reformat<br>代码格式化]
Dev --> MypyCheck[mypy-check<br>类型检查]
Dev --> UVTools[sync-uv/update-uv<br>依赖管理]
Dev --> PyTest[pytest/<br>测试工具]

style Dev fill:#e1d5e7,stroke:#9673A6,stroke-width:2px
style Reformat fill:#f8cecc,stroke:#b85450
style MypyCheck fill:#f8cecc,stroke:#b85450
style UVTools fill:#f8cecc,stroke:#b85450
style PyTest fill:#f8cecc,stroke:#b85450

开发工具模块包含开发相关的工具和脚本，辅助项目开发和质量控制。

核心工具

• reformat: 代码格式化工具，确保代码风格一致性

  • 使用Black、isort等工具格式化Python代码
  • 使用ESLint、Prettier格式化JavaScript/TypeScript代码

• mypy-check: 类型检查工具，提供静态类型检查能力

  • 验证类型注解正确性
  • 提前发现潜在类型错误

• sync-uv/update-uv: UV包管理工具，管理Python包依赖

  • 同步项目依赖
  • 更新包版本

• pytest/: 测试相关工具，支持自动化测试

  • 单元测试辅助工具
  • 集成测试配置

功能特点

这些工具共同确保了代码质量和开发效率：

• 代码质量控制：通过格式化和类型检查确保代码质量
• 依赖管理：简化包依赖管理流程
• 测试自动化：提供测试辅助工具

部署架构

Dify 支持多种部署方式:

1. Docker Compose 部署：

   • 使用 docker-compose.yaml 一键部署所有服务
   • 适合小规模使用和测试

2. Kubernetes 部署：

   • 使用社区贡献的 Helm Charts 和 YAML 文件
   • 适合大规模、高可用性需求

3. 云平台部署：

   • AWS CDK 部署
   • Azure Terraform 部署
   • Google Cloud Terraform 部署

总结

Dify 通过模块化的设计，将前端、后端、SDK、部署工具等清晰地分离，同时保持了良好的协作关系。这种设计使得 Dify 能够同时满足简单应用的快速开发需求，也能支持企业级的复杂应用场景。通过提供丰富的 API 和 SDK，Dify 能够无缝集成到现有业务系统中，为开发者提供强大的 LLM 应用开发能力。