API 后端架构

相关源文件

• .devcontainer/Dockerfile
• .devcontainer/README.md
• .devcontainer/devcontainer.json
• .devcontainer/noop.txt
• .devcontainer/post_create_command.sh
• .devcontainer/post_start_command.sh
• .devcontainer/troubleshooting.png
• .github/actions/setup-uv/action.yml
• .github/workflows/api-tests.yml
• .github/workflows/db-migration-test.yml
• .github/workflows/docker-build.yml
• .github/workflows/style.yml
• .github/workflows/vdb-tests.yml
• api/Dockerfile
• api/README.md
• api/constants/recommended_apps.json
• api/core/app/apps/common/__init__.py
• api/core/app/apps/common/workflow_response_converter.py
• api/core/repositories/sqlalchemy_workflow_node_execution_repository.py
• api/core/workflow/entities/workflow_node_execution.py
• api/core/workflow/repositories/workflow_node_execution_repository.py
• api/core/workflow/workflow_cycle_manager.py
• api/docker/entrypoint.sh
• api/events/app_event.py
• api/events/event_handlers/__init__.py
• api/events/event_handlers/delete_tool_parameters_cache_when_sync_draft_workflow.py
• api/migrations/README
• api/migrations/versions/2024_10_10_0516-bbadea11becb_add_name_and_size_to_tool_files.py
• api/migrations/versions/2024_12_23_1154-d7999dfa4aae_remove_workflow_node_executions_retry_.py
• api/migrations/versions/5fda94355fce_custom_disclaimer.py
• api/migrations/versions/b2602e131636_add_workflow_run_id_index_for_message.py
• api/models/__init__.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/tools.py
• api/models/web.py
• api/models/workflow.py
• api/services/recommended_app_service.py
• api/services/workflow_run_service.py
• api/services/workflow_service.py
• api/tasks/remove_app_and_related_data_task.py
• api/tests/unit_tests/core/workflow/test_workflow_cycle_manager.py
• api/tests/unit_tests/models/test_workflow.py
• api/tests/unit_tests/repositories/workflow_node_execution/test_sqlalchemy_repository.py
• dev/pytest/pytest_vdb.sh
• dev/reformat
• web/.husky/pre-commit
• web/Dockerfile
• web/README.md

本文档介绍了 Dify 基于 Flask 的 API 后端架构，包括其数据模型、服务层、存储库模式和多租户设计。后端作为核心应用程序服务器，负责处理 API 请求、管理业务逻辑以及与外部服务协调。

有关 Web 前端架构的信息，请参阅 Web 前端架构。有关数据库模式详细信息，请参阅 数据库和存储架构。有关部署配置，请参阅 Docker 部署。

应用程序结构和入口点

Dify API 后端是一个 Flask 应用程序，可根据部署需求以多种模式运行。该应用程序通过入口脚本管理三种主要执行模式。

执行模式

应用程序入口点在 Dockerfile 中通过 FLASK_APP=app.py 配置，并使用 uv 进行 Python 依赖项管理。生产部署通常使用 gunicorn 作为 WSGI 服务器，而开发则使用 Flask 内置服务器。

来源： api/Dockerfile27-41 api/docker/entrypoint.sh10-41

Flask 应用程序配置

Flask 应用程序遵循标准结构，具有关键配置元素

组件	目的	关键文件
模型	SQLAlchemy ORM 模型	api/models/ 目录
服务	业务逻辑层	api/services/ 目录
存储库	数据访问抽象	api/core/repositories/ 目录
扩展	Flask 扩展设置	extensions/ 目录
迁移	数据库模式版本管理	api/migrations/ 目录

来源： api/README.md1-94 api/models/__init__.py1-95

数据层架构

后端使用 SQLAlchemy 作为 ORM，并以 PostgreSQL 作为主要数据库。数据层实现了多租户架构，其中大多数实体都按 tenant_id 进行范围划分。

核心数据模型

模型继承和基类

数据模型遵循一致的继承模式，使用 Base 类

模型的主要特点包括

• 使用 StringUUID 类型进行 UUID 主键
• 自动时间戳字段（created_at、updated_at）
• 用于灵活配置存储的 JSON 字段
• 用于计算值和相关对象访问的属性方法

来源： api/models/model.py75-306 api/models/workflow.py75-243 api/models/dataset.py37-259 api/models/base.py api/models/account.py83-302

多租户实现

系统实现了行级别多租户，其中大多数实体都包含一个 tenant_id 字段

TenantAccountJoin 模型管理用户对多个租户的访问，并通过 TenantAccountRole 中定义的基于角色的权限进行控制。

来源： api/models/account.py15-73 api/models/account.py224-241

服务层架构

服务层实现了业务逻辑，并协调数据层和 API 端点。服务遵循一致的模式，即提供处理特定业务操作的无状态类。

核心服务类

工作流服务实现

WorkflowService 类展示了服务层模式

核心服务方法包括

• get_draft_workflow() 和 get_published_workflow() 用于检索工作流
• sync_draft_workflow() 用于保存草稿更改
• publish_workflow() 用于创建新的工作流版本
• run_draft_workflow_node() 用于单节点调试

来源： api/services/workflow_service.py43-529 api/services/workflow_run_service.py21-154 api/services/recommended_app_service.py7-38

存储库模式实现

后端实现存储库模式，以抽象复杂域实体（特别是工作流节点执行）的数据访问。此模式在域逻辑和数据持久性之间提供了清晰的分离。

仓库架构

域模型 vs 数据库模型

存储库模式将域模型与数据库模型分离

方面	域模型	数据库模型
位置	core/workflow/entities/	models/workflow.py
目的	业务逻辑表示	数据库持久化
依赖项	框架无关	SQLAlchemy 特定
上下文	无租户/应用上下文	包含 tenant_id、app_id

SQLAlchemyWorkflowNodeExecutionRepository 在这些表示之间进行转换

来源： api/core/repositories/sqlalchemy_workflow_node_execution_repository.py33-406 api/core/workflow/entities/workflow_node_execution.py1-150 api/core/workflow/repositories/workflow_node_execution_repository.py1-100

后台任务处理

应用程序使用 Celery 进行后台任务处理，以 Redis 作为消息代理。任务根据其功能组织到特定的队列中。

Celery 配置

任务实现示例

remove_app_and_related_data_task 演示了后台任务模式

任务遵循一致的模式

• 基于装饰器的配置，带有队列分配
• 重试逻辑以处理暂时性故障
• 用于大型数据操作的批处理
• 全面清理相关实体

来源： api/docker/entrypoint.sh10-26 api/tasks/remove_app_and_related_data_task.py36-301

工作流执行架构

工作流系统实现了一个复杂的执行引擎，它能够处理具有多种节点类型和执行模式的复杂工作流图。

工作流执行组件

节点执行流程

工作流执行遵循特定的节点处理模式

执行会创建域对象，然后通过存储库模式进行持久化，从而在执行逻辑和存储关注点之间保持分离。

来源： api/services/workflow_service.py255-415 api/core/workflow/workflow_cycle_manager.py40-300

API 响应和错误处理

后端在不同的执行上下文中实现了结构化的响应处理和错误管理。

响应转换管道

响应转换系统处理实时流式处理和批量处理场景，将内部执行事件转换为 API 格式的响应。

来源： api/core/app/apps/common/workflow_response_converter.py1-700

该架构为 Dify 平台的 AI 应用开发能力提供了强大、可扩展的基础，具有清晰的职责分离和强大的多租户隔离。