agentic_huge_data_base / wiki
页面 Dify · 2 系统架构总览·DeepWiki 中文全文译文
DeepWiki 中文译文 / Dify / 2

2 · 系统架构总览（System Architecture Overview）

应用编排与外部知识接入 · 聚焦本章的模块关系、源码依据与实现要点。

项目Dify 章节2 状态全文译文 模块系统架构、存储与持久化、配置治理、文档对象与元数据
项目要点页2.5 参考项目 项目章节目录Dify DeepWiki 原始章节System Architecture Overview 上一章1 下一章2.1
源码线索
  • api/.env.example
  • api/Dockerfile
  • api/app.py
  • api/app_factory.py
  • api/configs/feature/__init__.py
  • api/configs/middleware/__init__.py
  • api/configs/observability/__init__.py
  • api/configs/observability/otel/otel_config.py
  • api/configs/packaging/__init__.py
  • api/controllers/console/datasets/datasets.py
模块标签
  • 系统架构
  • 存储与持久化
  • 配置治理
  • 文档对象与元数据
  • 智能体运行时

章节正文

系统架构总览

原始 DeepWiki 页面https://deepwiki.com/langgenius/dify/2-system-architecture-overview

系统架构总览

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • api/.env.example
  • api/Dockerfile
  • api/app.py
  • api/app_factory.py
  • api/configs/feature/__init__.py
  • api/configs/middleware/__init__.py
  • api/configs/observability/__init__.py
  • api/configs/observability/otel/otel_config.py
  • api/configs/packaging/__init__.py
  • api/controllers/console/datasets/datasets.py
  • api/core/rag/datasource/vdb/vector_factory.py
  • api/core/rag/datasource/vdb/vector_type.py
  • api/extensions/ext_compress.py
  • api/extensions/ext_otel.py
  • api/extensions/otel/instrumentation.py
  • api/models/account.py
  • api/models/api_based_extension.py
  • api/models/dataset.py
  • api/models/model.py
  • api/models/provider.py
  • api/models/source.py
  • api/models/task.py
  • api/models/tools.py
  • api/models/web.py
  • api/models/workflow.py
  • api/pyproject.toml
  • api/tests/unit_tests/configs/test_dify_config.py
  • api/tests/unit_tests/core/workflow/graph_engine/test_table_runner.py
  • api/uv.lock
  • docker/.env.example
  • docker/README.md
  • docker/docker-compose-template.yaml
  • docker/docker-compose.middleware.yaml
  • docker/docker-compose.yaml
  • docker/envs/core-services/shared.env.example
  • docker/envs/infrastructure/nginx.env.example
  • docker/envs/security.env.example
  • docker/nginx/conf.d/default.conf.template
  • web/.env.example
  • web/Dockerfile
  • web/app/layout.tsx
  • web/config/index.ts
  • web/docker/entrypoint.sh
  • web/package.json
  • web/types/feature.ts

目的与范围

本文档全面介绍了 Dify 的系统架构，包括服务拓扑、核心组件、数据模型和部署结构。文档描述了平台各层之间如何交互，以实现 AI 应用的开发与运行。

如需了解特定子系统的详细信息，请参见：

高层架构

Dify 是一个全栈 AI 应用开发平台，按不同的架构层次进行组织。系统在前端、API、业务逻辑、后台处理、专用服务和数据持久化层之间实现了清晰的关注点分离。

架构层次图
Dify · 架构层次图 · 图 1
Dify · 架构层次图 · 图 1

来源： docker/docker-compose.yaml:206-350, docker/docker-compose-template.yaml:200-350, api/pyproject.toml:12-18, docker/docker-compose.middleware.yaml:1-130

服务拓扑

容器架构

Dify 的 Docker 部署由多个互联的服务组成，这些服务运行在共享网络中。架构使用单一的 API 镜像（langgenius/dify-api），通过 MODE 环境变量控制其运行在不同模式。

Docker Compose 服务拓扑

Dify · 容器架构 · 图 2
Dify · 容器架构 · 图 2

关键设计模式：

模式实现目的
共享镜像langgenius/dify-api 以 api、worker、worker_beat 模式运行单一 Docker 构建，通过 MODE 环境变量实现多种部署模式 docker/docker-compose-template.yaml:221-348
模式选择入口脚本检查 MODE（api/worker/beat）分别启动 gunicorn、celery worker 或 celery beat docker/docker-compose-template.yaml:221-348
非 root 用户服务以 1001:1001 用户运行通过非 root 容器实现安全加固 docker/docker-compose-template.yaml:226-226
初始化容器使用 busybox 的 init_permissions确保存储卷具有正确的所有权 docker/docker-compose-template.yaml:202-218
基于配置文件的数据库Docker Compose 配置文件（postgresql、mysql）仅启动所需的关系型数据库 docker/docker-compose.middleware.yaml:5-7, docker/docker-compose.middleware.yaml:45-46
共享环境YAML 锚点 &shared-api-worker-config后端服务之间共享环境变量 docker/docker-compose.yaml:8-72

来源： docker/docker-compose.yaml:8-205, docker/docker-compose-template.yaml:202-350, docker/docker-compose.middleware.yaml:1-130, docker/.env.example:53-70

核心组件

业务逻辑服务

核心逻辑按服务类进行组织。这些服务类负责在 API 控制器与底层数据模型之间建立桥梁。

服务职责位置
AccountService用户认证与租户管理api/services/account_service.py
DatasetService知识库与文档管理api/services/dataset_service.py api/controllers/console/datasets/datasets.py:60-60
DocumentService文档处理与片段切分api/services/dataset_service.py api/controllers/console/datasets/datasets.py:60-60
IndexingRunner知识索引的 ETL 管线api/core/indexing_runner.py api/controllers/console/datasets/datasets.py:25-25

来源： api/controllers/console/datasets/datasets.py:25-60, api/models/model.py:65-68

数据模型与关系

Dify 使用 SQLAlchemy 进行对象关系映射。主数据库存储账户、租户、应用和工作流定义。

核心实体关系图

Dify · 数据模型与关系 · 图 3
Dify · 数据模型与关系 · 图 3

关键模型类：

  • Account：用户凭证与个人资料 api/models/model.py:32-32
  • Tenant：工作空间容器，用于存放资源 api/models/model.py:32-32
  • App：AI 应用实体 api/models/model.py:72-75
  • Workflow：基于图的逻辑定义 api/models/workflow.py:147-213
  • Dataset：知识库容器 api/models/dataset.py:167-213

如需深入了解模式细节，请参见核心数据模型与领域实体。

来源： api/models/model.py:32-58, api/models/workflow.py:147-213, api/models/dataset.py:167-213

配置管理

Dify 使用基于 Pydantic BaseSettings 的集中式配置系统。配置从环境变量和 .env 文件中加载。

配置层次结构

Dify · 配置管理 · 图 4
Dify · 配置管理 · 图 4

关键配置类别：

  • 数据库：DB_TYPE、DB_HOST、DB_PORT、DB_DATABASE docker/.env.example:72-77
  • Redis：REDIS_HOST、REDIS_PORT、REDIS_PASSWORD docker/.env.example:96-99
  • 存储：STORAGE_TYPE、OPENDAL_SCHEME api/.env.example:111-114
  • 沙箱：CODE_EXECUTION_ENDPOINT、CODE_EXECUTION_API_KEY api/configs/feature/__init__.py:108-116

有关配置流程的详细信息，请参见配置管理系统。

来源： api/configs/feature/__init__.py:20-220, api/.env.example:88-213, docker/.env.example:72-115

向量数据库与检索增强生成（RAG）

Dify 通过统一的工厂模式支持 23 种以上的向量数据库实现。

向量工厂模式

Dify · 向量数据库与检索增强生成（RAG） · 图 5
Dify · 向量数据库与检索增强生成（RAG） · 图 5

来源： api/core/rag/datasource/vdb/vector_factory.py:1-50, api/core/rag/datasource/vdb/vector_type.py:1-30, api/.env.example:203-205, api/pyproject.toml:62-91