Dify 整体架构设计
从 10000 英尺高度俯瞰 Dify 的技术栈和系统架构
📖 内容概述
本文将从宏观视角全面介绍 Dify 的整体架构设计,包括技术栈选型、系统架构、核心模块划分、部署架构等内容。通过本文学习,你将建立对 Dify 系统的全局认知。
🎯 学习目标
- 理解 Dify 的技术栈选型理由
- 掌握 Dify 的三层架构设计
- 熟悉核心模块的职责划分
- 了解不同场景的部署架构
- 掌握 Dify 的部署最佳实践
📂 关键文件路径
dify/
├── web/ # 前端项目(Next.js)
│ ├── app/ # App Router 目录
│ ├── components/ # React 组件
│ ├── service/ # API 调用封装
│ └── package.json # 依赖管理
│
├── api/ # 后端项目(Flask)
│ ├── app_factory.py # Flask 应用工厂 ⭐
│ ├── controllers/ # API 控制器层
│ ├── services/ # 业务逻辑层
│ ├── core/ # 核心引擎层 ⭐
│ ├── models/ # 数据模型层
│ ├── extensions/ # Flask 扩展
│ ├── tasks/ # Celery 异步任务
│ └── pyproject.toml # Python 依赖管理
│
├── docker/ # Docker 配置
│ └── docker-compose.yaml # 容器编排
│
└── README.md # 项目说明一、Dify 技术栈全景
1.1 前端技术栈
核心框架
| 技术 | 版本 | 用途 |
|---|---|---|
| Next.js | 15.x | React 全栈框架,支持 SSR、SSG、App Router |
| React | 19.x | UI 组件库,采用最新的 Server Components |
| TypeScript | 5.x | 类型安全的 JavaScript 超集 |
| Tailwind CSS | 3.x | 原子化 CSS 框架,快速构建 UI |
状态管理与数据获取
typescript
// Zustand - 轻量级状态管理
import { create } from 'zustand'
const useAppStore = create((set) => ({
apps: [],
setApps: (apps) => set({ apps }),
}))
// SWR - 数据获取和缓存
import useSWR from 'swr'
const { data, error, mutate } = useSWR('/api/apps', fetcher, {
revalidateOnFocus: true,
dedupingInterval: 5000,
})为什么选择 Next.js?
- 全栈能力:支持 API Routes,可以快速开发 BFF 层
- SSR/SSG:提升首屏加载速度和 SEO
- App Router:文件系统路由,开发体验好
- 生态丰富:React 生态完善,组件库众多
- 性能优化:自动代码分割、图片优化等
1.2 后端技术栈
核心框架
| 技术 | 版本 | 用途 |
|---|---|---|
| Flask | 3.x | 轻量级 Web 框架,灵活可扩展 |
| Python | 3.11+ | 后端开发语言,AI 生态丰富 |
| Celery | 5.x | 分布式异步任务队列 |
| SQLAlchemy | 2.x | Python ORM 框架 |
为什么选择 Flask?
python
# Flask 的简洁和灵活性
from flask import Flask
from extensions import ext_database, ext_redis, ext_celery
app = Flask(__name__)
# 灵活的扩展加载机制
ext_database.init_app(app)
ext_redis.init_app(app)
ext_celery.init_app(app)
# Blueprint 模块化路由
from controllers.console import bp as console_bp
app.register_blueprint(console_bp, url_prefix='/console/api')优势:
- 轻量灵活:相比 Django,Flask 更轻量,适合微服务
- 扩展丰富:丰富的第三方扩展生态
- 易于定制:没有过多约束,可以灵活设计架构
- Python 生态:AI/ML 库都基于 Python
1.3 数据存储技术栈
数据库与缓存
| 技术 | 版本 | 用途 |
|---|---|---|
| PostgreSQL | 15+ | 主数据库,存储结构化数据 |
| pgvector | 0.5+ | PostgreSQL 向量扩展,支持向量检索 |
| Redis | 7+ | 缓存、消息队列、分布式锁 |
向量数据库(可选)
- Weaviate:云原生向量数据库
- Qdrant:高性能向量搜索引擎
- Milvus:开源向量数据库
- Chroma:轻量级向量数据库
为什么选择 PostgreSQL + pgvector?
sql
-- pgvector 向量存储示例
CREATE TABLE document_segments (
id UUID PRIMARY KEY,
content TEXT,
embedding vector(1536), -- 支持向量类型
metadata JSONB -- 支持 JSON 类型
);
-- 向量相似度检索
SELECT content, 1 - (embedding <=> '[0.1,0.2,...]'::vector) AS similarity
FROM document_segments
ORDER BY embedding <=> '[0.1,0.2,...]'::vector
LIMIT 10;
-- 创建向量索引,加速检索
CREATE INDEX ON document_segments
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);优势:
- 统一存储:结构化数据和向量数据在同一数据库
- ACID 保证:事务支持,数据一致性强
- 成熟稳定:PostgreSQL 久经考验
- 降低成本:不需要额外的向量数据库
1.4 中间件与工具
消息队列与任务调度
python
# Celery 异步任务示例
from celery import Celery
celery = Celery('dify', broker='redis://localhost:6379/1')
@celery.task
def index_document_task(dataset_id: str, document_id: str):
"""异步索引文档"""
# 文档处理、分块、向量化
# 这些耗时操作不会阻塞 API 响应
pass其他工具
- Docker:容器化部署
- Nginx:反向代理和负载均衡
- Supervisor:进程管理
- Sentry:错误监控
二、系统架构设计
2.1 整体架构图
┌─────────────────────────────────────────────────────────────┐
│ 用户层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Web 控制台│ │ API 客户端│ │ Chatbot │ │ 插件市场 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└───────────────────────┬─────────────────────────────────────┘
│ HTTPS
┌───────────────────────┴─────────────────────────────────────┐
│ 接入层 │
│ ┌──────────────────────┐ │
│ │ Nginx / Caddy │ │
│ │ (反向代理/SSL终结) │ │
│ └──────────────────────┘ │
└───────────────────────┬─────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌───────▼──────┐ ┌──────▼──────┐ ┌─────▼──────┐
│ 前端服务 │ │ API 服务 │ │ 静态资源 │
│ (Next.js) │ │ (Flask) │ │ (CDN) │
│ │ │ │ │ │
│ ┌──────────┐ │ │ ┌─────────┐ │ │ │
│ │App Router│ │ │ │Controller│ │ │ │
│ │Components│ │ │ │Service │ │ │ │
│ │ Hooks │ │ │ │Core │ │ │ │
│ └──────────┘ │ │ │Models │ │ │ │
│ │ │ └─────────┘ │ │ │
└──────────────┘ └──────┬──────┘ └────────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌───────▼──────┐ ┌──────▼──────┐ ┌─────▼──────┐
│ Celery │ │ PostgreSQL │ │ Redis │
│ Worker │ │ + pgvector │ │ │
│ │ │ │ │ - 缓存 │
│ - 文档索引 │ │ - 业务数据 │ │ - 队列 │
│ - 数据清洗 │ │ - 向量数据 │ │ - Session │
│ - 定时任务 │ │ │ │ │
└──────────────┘ └─────────────┘ └────────────┘
│
│ (可选)
┌───────▼──────────────────────────────────────┐
│ 向量数据库 (可选) │
│ Weaviate / Qdrant / Milvus / Chroma │
└──────────────────────────────────────────────┘
│
│ (外部服务)
┌───────▼──────────────────────────────────────┐
│ LLM 服务商 │
│ OpenAI / Anthropic / Azure / 国产模型 │
└──────────────────────────────────────────────┘2.2 请求流程示例
场景:用户发送对话消息
mermaid
sequenceDiagram
participant U as 用户浏览器
participant N as Nginx
participant W as Next.js
participant F as Flask API
participant S as Service 层
participant C as Core 引擎
participant L as LLM
participant D as PostgreSQL
participant R as Redis
U->>N: POST /chat-messages
N->>W: 转发请求
W->>F: API 调用
F->>F: 身份验证
F->>S: 调用 MessageService
S->>D: 查询对话历史
D-->>S: 返回历史记录
S->>C: 调用 CompletionApp
C->>R: 获取缓存的 Prompt
C->>L: 调用 LLM (流式)
loop 流式响应
L-->>C: 返回 Chunk
C-->>S: 处理 Chunk
S-->>F: SSE 推送
F-->>W: SSE Stream
W-->>U: 显示内容
end
C->>D: 保存消息记录
D-->>C: 保存成功2.3 三层架构设计
Dify 后端采用经典的三层架构:
┌─────────────────────────────────────────────┐
│ Controller 层(控制器层) │
│ - API 路由定义 │
│ - 请求参数验证 │
│ - 响应格式化 │
│ - 权限控制 │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ Service 层(业务逻辑层) │
│ - 业务逻辑处理 │
│ - 事务管理 │
│ - 跨模块协调 │
│ - 数据转换 │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ Core 层(核心引擎层) │
│ - Model Runtime (模型运行时) │
│ - Workflow Engine (工作流引擎) │
│ - RAG Pipeline (检索增强) │
│ - Agent Framework (智能代理) │
│ - Plugin System (插件系统) │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ Data 层(数据访问层) │
│ - ORM 模型定义 (models/) │
│ - 数据库操作 │
│ - 缓存管理 │
└─────────────────────────────────────────────┘代码示例:层次调用
python
# ===== Controller 层 =====
# api/controllers/console/app/completion.py
@app.route('/completion-messages', methods=['POST'])
@setup_required
@login_required
@account_initialization_required
def completion():
"""对话补全接口"""
# 1. 参数验证
parser = reqparse.RequestParser()
parser.add_argument('query', type=str, required=True)
args = parser.parse_args()
# 2. 调用 Service 层
try:
response = CompletionService.generate(
app_id=app_id,
query=args['query'],
user=current_user,
stream=True
)
return Response(response, mimetype='text/event-stream')
except Exception as e:
return {'error': str(e)}, 500
# ===== Service 层 =====
# api/services/completion_service.py
class CompletionService:
@staticmethod
def generate(app_id: str, query: str, user: Account, stream: bool):
"""生成对话补全"""
# 1. 查询应用配置
app = App.query.filter_by(id=app_id).first()
# 2. 获取对话历史
conversation = ConversationService.get_conversation(...)
# 3. 构建输入
inputs = {
'query': query,
'conversation_id': conversation.id
}
# 4. 调用 Core 层
from core.app.apps.completion_app import CompletionApp
completion_app = CompletionApp()
result = completion_app.run(
app_config=app.app_model_config,
inputs=inputs,
user=user
)
# 5. 处理结果并返回
return result
# ===== Core 层 =====
# api/core/app/apps/completion_app.py
class CompletionApp:
def run(self, app_config, inputs, user):
"""运行补全应用"""
# 1. 加载 Prompt 模板
prompt_template = self._load_prompt_template(app_config)
# 2. 构建 Prompt
prompt = prompt_template.format(**inputs)
# 3. 调用 Model Runtime
from core.model_runtime import ModelFactory
model = ModelFactory.get_model_instance(
provider='openai',
model_type='llm'
)
# 4. 执行模型调用
result = model.invoke(
model='gpt-4',
prompt_messages=[{'role': 'user', 'content': prompt}],
stream=True
)
return result三、核心模块划分
3.1 Controller 层(API 路由)
目录结构
api/controllers/
├── console/ # 控制台 API(需要登录)
│ ├── app/ # 应用管理
│ │ ├── completion.py # 对话补全
│ │ ├── workflow.py # 工作流
│ │ └── annotation.py # 标注
│ ├── datasets/ # 知识库管理
│ ├── auth/ # 认证授权
│ └── workspace/ # 工作空间
│
├── service_api/ # 服务 API(API Key 认证)
│ ├── app/ # 应用调用
│ └── dataset/ # 知识库查询
│
└── web/ # Web 端 API(面向终端用户)
├── app.py # 应用访问
├── completion.py # 对话接口
└── conversation.py # 会话管理职责
- 定义 API 路由和 HTTP 方法
- 请求参数验证和解析
- 身份验证和权限控制
- 响应格式化和错误处理
3.2 Service 层(业务逻辑)
核心 Service
python
api/services/
├── app_service.py # 应用管理
├── conversation_service.py # 对话管理
├── dataset_service.py # 知识库管理
├── model_provider_service.py # 模型供应商管理
└── workflow_service.py # 工作流管理Service 层设计原则
- 单一职责:每个 Service 负责一个业务领域
- 事务管理:在 Service 层处理数据库事务
- 解耦 Core:Service 层是 Controller 和 Core 的桥梁
- 可测试性:便于编写单元测试
示例:AppService
python
# api/services/app_service.py
class AppService:
@staticmethod
def create_app(account: Account, app_mode: str, name: str):
"""创建应用"""
with db.session.begin():
# 1. 创建应用
app = App(
tenant_id=account.tenant_id,
app_mode=app_mode,
name=name,
created_by=account.id
)
db.session.add(app)
db.session.flush()
# 2. 创建默认配置
config = AppModelConfig(
app_id=app.id,
model_provider='openai',
model_name='gpt-4'
)
db.session.add(config)
# 3. 记录操作日志
OperationService.log(
account=account,
action='create_app',
resource_id=app.id
)
return app3.3 Core 层(核心引擎)
核心模块
api/core/
├── model_runtime/ # 模型运行时 ⭐
│ ├── model_providers/ # 各模型供应商适配
│ └── entities/ # 模型相关实体
│
├── workflow/ # 工作流引擎 ⭐
│ ├── nodes/ # 工作流节点
│ ├── graph_engine/ # 图执行引擎
│ └── entities/ # 工作流实体
│
├── rag/ # RAG 检索增强 ⭐
│ ├── retrieval/ # 检索器
│ ├── extractor/ # 文本提取
│ ├── splitter/ # 文档分块
│ └── rerank/ # 重排序
│
├── agent/ # Agent 框架 ⭐
│ ├── agent_executor.py # Agent 执行器
│ └── output_parser/ # 输出解析
│
├── plugin/ # 插件系统
├── prompt/ # Prompt 管理
└── app/ # 应用引擎
└── apps/ # 各类型应用实现Core 层特点
- 框架无关:不依赖 Flask,可以独立使用
- 高度抽象:提供统一的接口和实体
- 可扩展:支持插件和自定义扩展
- 复杂逻辑:包含了 Dify 最核心的技术实现
3.4 Data 层(数据模型)
核心模型
python
# api/models/
├── account.py # 用户和租户
├── app.py # 应用和配置
├── dataset.py # 知识库
├── document.py # 文档
├── message.py # 对话消息
├── workflow.py # 工作流
└── provider.py # 模型供应商ORM 示例
python
# api/models/app.py
from extensions.ext_database import db
from sqlalchemy.dialects.postgresql import UUID
class App(db.Model):
"""应用模型"""
__tablename__ = 'apps'
id = db.Column(UUID(as_uuid=True), primary_key=True)
tenant_id = db.Column(UUID(as_uuid=True), nullable=False)
name = db.Column(db.String(255), nullable=False)
app_mode = db.Column(db.String(50), nullable=False) # 'completion', 'workflow', 'agent-chat'
icon = db.Column(db.String(255))
icon_background = db.Column(db.String(255))
# 关系
app_model_config = db.relationship('AppModelConfig', backref='app')
conversations = db.relationship('Conversation', backref='app')
# 索引
__table_args__ = (
db.Index('idx_tenant_id', 'tenant_id'),
db.Index('idx_app_mode', 'app_mode'),
)四、部署架构
4.1 单机部署(开发/小规模)
┌────────────────────────────────────────────┐
│ 单台服务器 (8C16G) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│ │ Nginx │ │ Next.js │ │ Flask │ │
│ │ :80 │ │ :3000 │ │ :5001 │ │
│ └──────────┘ └──────────┘ └─────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│ │PostgreSQL│ │ Redis │ │ Celery │ │
│ │ :5432 │ │ :6379 │ │ Worker │ │
│ └──────────┘ └──────────┘ └─────────┘ │
└────────────────────────────────────────────┘Docker Compose 配置
yaml
# docker/docker-compose.yaml
version: '3'
services:
# API 服务
api:
build: ./api
ports:
- "5001:5001"
environment:
- DB_HOST=postgres
- REDIS_HOST=redis
depends_on:
- postgres
- redis
# Worker 服务
worker:
build: ./api
command: celery -A celery_app worker
depends_on:
- redis
- postgres
# Web 服务
web:
build: ./web
ports:
- "3000:3000"
environment:
- NEXT_PUBLIC_API_URL=http://api:5001
# 数据库
postgres:
image: pgvector/pgvector:pg15
environment:
- POSTGRES_PASSWORD=dify
volumes:
- postgres_data:/var/lib/postgresql/data
# 缓存
redis:
image: redis:7-alpine
volumes:
- redis_data:/data
# Nginx
nginx:
image: nginx:alpine
ports:
- "80:80"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf4.2 分布式部署(生产环境)
┌─────────────┐
│ CDN / DNS │
└──────┬──────┘
│
┌─────────▼────────┐
│ Load Balancer │
│ (HAProxy) │
└─────────┬────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌─────▼─────┐ ┌──────▼──────┐ ┌────▼──────┐
│ Nginx 1 │ │ Nginx 2 │ │ Nginx 3 │
└─────┬─────┘ └──────┬──────┘ └────┬──────┘
│ │ │
┌─────┴───────────────┴───────────────┴─────┐
│ │
│ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│ │ Next.js │ │ Next.js │ │Next.js │ │
│ │ 节点 1 │ │ 节点 2 │ │ 节点 3 │ │
│ └──────────┘ └──────────┘ └─────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│ │ Flask │ │ Flask │ │ Flask │ │
│ │ 节点 1 │ │ 节点 2 │ │ 节点 3 │ │
│ └──────────┘ └──────────┘ └─────────┘ │
│ │
│ ┌────────────────────────────────────┐ │
│ │ Celery Worker 集群 (5+ 节点) │ │
│ └────────────────────────────────────┘ │
└────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌─────▼─────┐ ┌──────▼──────┐ ┌────▼──────┐
│PostgreSQL │ │ Redis │ │ 向量DB │
│ 主从集群 │ │ Cluster │ │ (可选) │
└───────────┘ └─────────────┘ └───────────┘特点
- 高可用:多节点部署,单点故障不影响服务
- 水平扩展:根据负载动态增减节点
- 数据分离:数据库独立部署,支持主从复制
- 监控完善:集成 Prometheus + Grafana
4.3 容器化部署(Kubernetes)
yaml
# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: dify-api
spec:
replicas: 3
selector:
matchLabels:
app: dify-api
template:
metadata:
labels:
app: dify-api
spec:
containers:
- name: api
image: dify/api:latest
ports:
- containerPort: 5001
env:
- name: DB_HOST
valueFrom:
configMapKeyRef:
name: dify-config
key: db-host
resources:
requests:
memory: "2Gi"
cpu: "1"
limits:
memory: "4Gi"
cpu: "2"
livenessProbe:
httpGet:
path: /health
port: 5001
initialDelaySeconds: 30
readinessProbe:
httpGet:
path: /ready
port: 5001
initialDelaySeconds: 10
---
apiVersion: v1
kind: Service
metadata:
name: dify-api-service
spec:
selector:
app: dify-api
ports:
- protocol: TCP
port: 80
targetPort: 5001
type: LoadBalancer五、实践项目
项目 1:绘制 Dify 架构全景图
目标:使用 draw.io 或 Excalidraw 绘制一张完整的架构图
要求:
- 包含前端、后端、数据库、中间件
- 标注各组件的版本和作用
- 标出数据流向和请求路径
- 包含部署架构
参考:本文的「系统架构设计」章节
项目 2:搭建本地开发环境
目标:使用 Docker Compose 搭建完整的 Dify 开发环境
bash
# 1. Clone 代码
git clone https://github.com/langgenius/dify.git
cd dify
# 2. 复制配置文件
cp docker/.env.example docker/.env
# 3. 启动服务
cd docker
docker-compose up -d
# 4. 查看日志
docker-compose logs -f api
# 5. 访问
# Web: http://localhost:3000
# API: http://localhost:5001📚 扩展阅读
🎓 自测题
- Dify 为什么选择 Flask 而不是 Django?
- 三层架构中,Controller、Service、Core 各自的职责是什么?
- Celery 在 Dify 中处理哪些类型的任务?
- pgvector 相比独立的向量数据库有什么优势和劣势?
- Dify 1.9.2 相比 1.2.0 在工作流引擎上有哪些重要改进?
- 如何设计一个可扩展的插件系统?
- 分布式部署时,如何保证 Celery Worker 的高可用?
✅ 小结
本文从宏观视角介绍了 Dify 的整体架构设计:
关键要点:
- ✅ 技术栈:Next.js + Flask + PostgreSQL + Redis
- ✅ 三层架构:Controller → Service → Core → Data
- ✅ 核心模块:Model Runtime、Workflow、RAG、Agent、Plugin
- ✅ 部署方式:单机 / 分布式 / K8s
- ✅ 版本演进:1.2.0 → 1.9.2 的重要改进
下一步:
学习进度: ⬜ 未开始 | 🚧 进行中 | ✅ 已完成