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

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

应用编排与外部知识接入 · 本章是 Dify DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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
翻译时间：2026-05-27T08:44:30.207Z
翻译模型：deepseek-chat
原文字符数：13958
项目：Dify (dify)

---

系统架构总览

相关源文件

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

  • 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、业务逻辑、后台处理、专用服务和数据持久化层之间实现了清晰的关注点分离。

架构层次图
graph TB
    subgraph "客户端层"
        Browser["Web 浏览器"]
        APIClient["API 客户端<br/>（SDK、cURL）"]
    end

    subgraph "反向代理层"
        Nginx["nginx<br/>端口 80/443<br/>SSL 终止"]
    end

    subgraph "前端层"
        NextJS["web 服务<br/>langgenius/dify-web<br/>Next.js 15+<br/>端口 3000"]
    end

    subgraph "API 层"
        API["api 服务<br/>langgenius/dify-api<br/>Flask 3.1+<br/>PORT=5001<br/>MODE=api"]
        Worker["worker 服务<br/>langgenius/dify-api<br/>Celery Worker<br/>MODE=worker"]
        WorkerBeat["worker_beat 服务<br/>langgenius/dify-api<br/>Celery Beat<br/>MODE=beat"]
    end

    subgraph "业务逻辑层"
        AccountSvc["AccountService<br/>认证"]
        DatasetSvc["DatasetService<br/>知识库"]
        WorkflowEngine["WorkflowEngine<br/>图执行"]
        ModelManager["ModelManager<br/>大语言模型（LLM）集成"]
    end

    subgraph "专用服务"
        Sandbox["sandbox<br/>langgenius/dify-sandbox<br/>端口 8194<br/>代码执行"]
        PluginDaemon["plugin_daemon<br/>langgenius/dify-plugin-daemon<br/>端口 5002"]
        SSRFProxy["ssrf_proxy<br/>ubuntu/squid<br/>端口 3128"]
    end

    subgraph "数据持久化层"
        PostgreSQL["db_postgres<br/>PostgreSQL 15<br/>主数据库"]
        MySQL["db_mysql<br/>MySQL 8<br/>主数据库"]
        Redis["redis<br/>Redis 6<br/>缓存与队列"]
        VectorDB["向量数据库<br/>23+ 种选择<br/>weaviate/qdrant/milvus 等"]
        Storage["对象存储<br/>S3/Azure/本地/OpenDAL"]
    end

    Browser --> Nginx
    APIClient --> Nginx
    Nginx --> NextJS
    Nginx --> API
    NextJS --> API

    API --> AccountSvc
    API --> DatasetSvc
    API --> WorkflowEngine
    API --> ModelManager

    Worker --> DatasetSvc
    Worker --> WorkflowEngine
    WorkerBeat --> Redis

    AccountSvc --> PostgreSQL
    AccountSvc --> MySQL
    DatasetSvc --> PostgreSQL
    DatasetSvc --> MySQL
    DatasetSvc --> VectorDB
    WorkflowEngine --> PostgreSQL
    WorkflowEngine --> MySQL
    ModelManager --> Redis

    API --> Sandbox
    API --> PluginDaemon
    Worker --> Sandbox
    Sandbox --> SSRFProxy

    DatasetSvc --> Storage

来源： 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 服务拓扑

graph TB
    subgraph "初始化"
        init_permissions["init_permissions<br/>镜像：busybox:latest<br/>chown -R 1001:1001<br/>/app/api/storage"]
    end

    subgraph "前端服务"
        nginx["nginx<br/>langgenius/dify-nginx<br/>端口：80/443"]
        web["web<br/>langgenius/dify-web:1.14.2<br/>端口：3000"]
    end

    subgraph "后端服务"
        api["api<br/>langgenius/dify-api:1.14.2<br/>MODE=api<br/>DIFY_PORT=5001"]
        worker["worker<br/>langgenius/dify-api:1.14.2<br/>MODE=worker<br/>CELERY_WORKER_AMOUNT"]
        worker_beat["worker_beat<br/>langgenius/dify-api:1.14.2<br/>MODE=beat"]
    end

    subgraph "专用服务"
        sandbox["sandbox<br/>langgenius/dify-sandbox:0.2.15<br/>端口 8194"]
        plugin_daemon["plugin_daemon<br/>langgenius/dify-plugin-daemon:0.6.1-local<br/>端口 5002"]
        ssrf_proxy["ssrf_proxy<br/>端口 3128"]
    end

    subgraph "数据服务"
        db_postgres["db_postgres<br/>postgres:15-alpine<br/>profile: postgresql"]
        db_mysql["db_mysql<br/>mysql:8.0<br/>profile: mysql"]
        redis["redis<br/>redis:6-alpine<br/>CELERY_BROKER_URL"]
    end

    subgraph "向量数据库"
        weaviate["weaviate<br/>profile: weaviate"]
        qdrant["qdrant<br/>profile: qdrant"]
        milvus["milvus<br/>profile: milvus"]
    end

    init_permissions --> api
    init_permissions --> worker

    nginx --> web
    nginx --> api
    web --> api

    api --> db_postgres
    api --> redis
    api --> sandbox

    worker --> db_postgres
    worker --> redis
    worker --> sandbox

    worker_beat --> redis

    api --> weaviate

关键设计模式：

模式实现目的
共享镜像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 进行对象关系映射。主数据库存储账户、租户、应用和工作流定义。

核心实体关系图

erDiagram
    Tenant ||--o{ Account : "拥有成员"
    Tenant ||--o{ App : "拥有"
    Tenant ||--o{ Dataset : "拥有"

    Account ||--o{ TenantAccountJoin : "属于"
    Tenant ||--o{ TenantAccountJoin : "包含"

    App ||--o{ Conversation : "拥有"
    App ||--o| Workflow : "可选使用"

    Dataset ||--o{ Document : "包含"
    Document ||--o{ DocumentSegment : "切分为"

    Workflow ||--o{ WorkflowRun : "执行"

关键模型类：

  • 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 文件中加载。

配置层次结构

graph TB
    env[".env 文件"] --> DifyConfig["DifyConfig（Pydantic）<br/>api/configs/app_config.py"]

    DifyConfig --> Middleware["MiddlewareConfig<br/>数据库、Redis、向量数据库"]
    DifyConfig --> Feature["FeatureConfig<br/>安全、应用执行"]
    DifyConfig --> CodeExecution["CodeExecutionSandboxConfig<br/>沙箱 URL、超时设置"]

关键配置类别：

  • 数据库：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 种以上的向量数据库实现。

向量工厂模式

graph TB
    VectorFactory["VectorFactory.create()<br/>api/core/rag/datasource/vdb/vector_factory.py"]

    VectorFactory --> VectorType{"VECTOR_STORE<br/>环境变量"}

    VectorType -->|weaviate| Weaviate["WeaviateVector"]
    VectorType -->|qdrant| Qdrant["QdrantVector"]
    VectorType -->|milvus| Milvus["MilvusVector"]
    VectorType -->|pgvector| PGVector["PGVectorVector"]

来源： 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