Skip to content

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.js15.xReact 全栈框架,支持 SSR、SSG、App Router
React19.xUI 组件库,采用最新的 Server Components
TypeScript5.x类型安全的 JavaScript 超集
Tailwind CSS3.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?

  1. 全栈能力:支持 API Routes,可以快速开发 BFF 层
  2. SSR/SSG:提升首屏加载速度和 SEO
  3. App Router:文件系统路由,开发体验好
  4. 生态丰富:React 生态完善,组件库众多
  5. 性能优化:自动代码分割、图片优化等

1.2 后端技术栈

核心框架

技术版本用途
Flask3.x轻量级 Web 框架,灵活可扩展
Python3.11+后端开发语言,AI 生态丰富
Celery5.x分布式异步任务队列
SQLAlchemy2.xPython 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')

优势:

  1. 轻量灵活:相比 Django,Flask 更轻量,适合微服务
  2. 扩展丰富:丰富的第三方扩展生态
  3. 易于定制:没有过多约束,可以灵活设计架构
  4. Python 生态:AI/ML 库都基于 Python

1.3 数据存储技术栈

数据库与缓存

技术版本用途
PostgreSQL15+主数据库,存储结构化数据
pgvector0.5+PostgreSQL 向量扩展,支持向量检索
Redis7+缓存、消息队列、分布式锁

向量数据库(可选)

  • 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);

优势:

  1. 统一存储:结构化数据和向量数据在同一数据库
  2. ACID 保证:事务支持,数据一致性强
  3. 成熟稳定:PostgreSQL 久经考验
  4. 降低成本:不需要额外的向量数据库

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 层设计原则

  1. 单一职责:每个 Service 负责一个业务领域
  2. 事务管理:在 Service 层处理数据库事务
  3. 解耦 Core:Service 层是 Controller 和 Core 的桥梁
  4. 可测试性:便于编写单元测试

示例: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 app

3.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.conf

4.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 绘制一张完整的架构图

要求

  1. 包含前端、后端、数据库、中间件
  2. 标注各组件的版本和作用
  3. 标出数据流向和请求路径
  4. 包含部署架构

参考:本文的「系统架构设计」章节

项目 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

📚 扩展阅读

🎓 自测题

  1. Dify 为什么选择 Flask 而不是 Django?
  2. 三层架构中,Controller、Service、Core 各自的职责是什么?
  3. Celery 在 Dify 中处理哪些类型的任务?
  4. pgvector 相比独立的向量数据库有什么优势和劣势?
  5. Dify 1.9.2 相比 1.2.0 在工作流引擎上有哪些重要改进?
  6. 如何设计一个可扩展的插件系统?
  7. 分布式部署时,如何保证 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 的重要改进

下一步


学习进度: ⬜ 未开始 | 🚧 进行中 | ✅ 已完成