当前位置：首页 > news >正文

Dify-15: 开发指南

news 2025/7/31 9:15:49

本指南为希望为 Dify 贡献代码或扩展其功能的开发者提供全面指导，涵盖本地开发环境搭建、代码库架构理解、测试运行，以及自定义模型提供方或 UI 组件等扩展功能的实现方法。

开发环境搭建

Dify 包含两个主要组件：API 后端（Python/Flask）和 Web 前端（Next.js），本地开发需同时配置这两部分。

前置条件

Python：3.11 或 3.12 版本
Node.js：18.18.0 或更高版本
PNPM：10.x 版本（用于 Web 开发）
UV：Python API 开发的包管理器
Docker & Docker Compose：运行中间件服务（数据库、Redis、向量存储等）

后端（API）设置

启动中间件服务（Docker Compose）：

cd docker  
cp middleware.env.example middleware.env  
docker compose -f docker-compose.middleware.yaml --profile weaviate -p dify up -d  
cd ../api

配置环境变量：

cp .env.example .env  
# Linux 生成密钥  
sed -i "/^SECRET_KEY=/c\SECRET_KEY=$(openssl rand -base64 42)" .env  # Mac 生成密钥  
secret_key=$(openssl rand -base64 42); sed -i '' "/^SECRET_KEY=/c\\SECRET_KEY=${secret_key}" .env

安装依赖
```
pip install uv  
uv sync --dev  
```
应用数据库迁移：
```
uv run flask db upgrade  
```

启动 API 开发服务器：

uv run flask run --host 0.0.0.0 --port=5001 --debug

启动异步任务 Worker（数据集导入等）：

uv run celery -A app.celery worker -P gevent -c 1 --loglevel INFO -Q dataset,generation,mail,ops_trace,app_deletion

前端（Web）设置

安装依赖：
```
cd web  
pnpm install  
```
配置环境：
```
cp .env.example .env.local  
```
启动开发服务器：
```
pnpm run dev  
```
Web 界面将在http://localhost:3000可用。

架构概述

Dify 采用基于微服务的架构，组件通过容器化实现部署和扩展。

架构图：Dify 开发架构

组件概述

API 后端（Flask）：
分层架构包括控制器（处理 HTTP 请求）、服务层（业务逻辑）、数据模型（数据库模式）和扩展（外部系统集成），并通过 Celery 处理异步任务（文档索引、数据集处理、邮件发送等）。
Web 前端（Next.js）：
包含控制台界面（创建和管理 AI 应用）、应用界面（用户交互）和可复用组件库。
中间件服务（Docker）：
包括 PostgreSQL（主数据库）、Redis（缓存和消息代理）、向量数据库（存储文档嵌入）、沙箱（安全代码执行）、插件守护进程（插件管理）和 SSRF 代理（出站请求安全）。

开发工作流程

环境变量

Dify 通过环境变量配置，主要文件包括：

api/.env：API 后端配置
web/.env.local：Web 前端配置
docker/.env：Docker 部署配置
docker/middleware.env：中间件服务配置

工作流流程

使用开发环境

在为 Dify 开发时，通常需要执行以下操作：

通过 Docker Compose 运行中间件服务
以调试模式运行 Flask 开发的 API 后端
以开发模式运行 Next.js 开发的 Web 前端
进行代码修改并实时查看更改效果
运行测试以确保更改不会破坏现有功能

对于更复杂的工作流，可能还需要：

运行 Celery 工作进程处理异步任务
设置和与向量数据库进行交互
测试插件功能

扩展 Dify

添加模型提供方

在对应模块创建新提供方实现；
实现文本生成、嵌入等模型类型的接口；
在提供方管理器中注册新提供方；
更新 UI 显示新提供方选项。

向量数据库集成

在 core/rag/datasource/vdb 目录创建新数据库实现；
实现向量数据库接口（创建、删除、搜索等）；
在向量工厂（Vector Factory）中注册新数据库。

插件开发

创建插件包并实现接口；
向插件守护进程注册插件。

前端组件开发

在对应目录创建新组件；
使用现有组件和样式保持一致性；
通过 Storybook 调试组件：
```
cd web && pnpm storybook  
```
访问http://localhost:6006查看组件库。

国际化（i18n）

Dify 支持多语言。若要添加或更新翻译，请执行以下步骤：

将新的翻译字符串添加到相应的 JSON 文件中
在组件中使用翻译钩子
运行 i18n 检查命令以确保所有翻译保持同步：

cd web
pnpm check-i18n

测试

Dify 拥有针对 API 后端和 Web 前端的全面测试套件。

API 测试

API 后端使用 pytest 进行测试，包含多个测试脚本：

单元测试：对单个组件进行独立测试
集成测试：测试组件之间的交互逻辑
向量数据库测试：测试与各种向量数据库的集成功能

要运行 API 测试：

# 运行所有 API 测试  
cd api && uv run bash dev/pytest/pytest_all_tests.sh  
# 仅运行向量数据库测试  
cd api && uv run bash dev/pytest/pytest_vdb.sh

Web 测试

使用 Jest 和 React Testing Library：

cd web && pnpm test

代码检查与格式化

Dify 通过代码检查工具和格式化工具维护代码质量：

API 后端：使用 Ruff 检查和格式化 Python 代码
Web 前端：使用 ESLint 检查 JavaScript/TypeScript 代码

运行代码检查

# API 后端（Python）  
cd api  
uv run ruff check ./    # 运行代码检查  
uv run ruff format ./   # 自动格式化代码  # Web 前端（JavaScript/TypeScript）  
cd web  
pnpm run lint          # 运行代码检查

可通过以下脚本一键重新格式化代码：

./dev/reforma

生产环境构建

Docker 构建

Dify 在生产部署中使用 Docker。API 和 Web 组件的 Dockerfile 位于各自的目录中。
要构建 Docker 镜像：

# 构建 API 镜像  
docker build -t dify-api:latest ./api  # 构建 Web 镜像  
docker build -t dify-web:latest ./web  # 完整部署（Docker Compose）  
cd docker && cp .env.example .env && docker-compose up -d

生产配置注意事项

设置 DEBUG=false 关闭调试模式；
配置数据库连接、存储和安全密钥；
参考 .env.example 完成生产环境变量配置。

常见问题排查

向量数据库连接问题：

确保数据库服务运行；
检查 .env 中的配置；
验证数据库初始化；

插件守护进程故障：

查看守护进程日志；
检查配置和通信端口。

Worker 不处理任务：

确认 Redis 运行正常；
检查 Celery Worker 日志和队列订阅。

开发命令参考

# 启动 API 服务器  
cd api && uv run flask run --host 0.0.0.0 --port=5001 --debug  # 启动 Celery Worker  
cd api && uv run celery -A app.celery worker -P gevent -c 1 --loglevel INFO -Q dataset,generation,mail,ops_trace,app_deletion  # 运行API测试
cd api && uv run bash dev/pytest/pytest_all_tests.sh# 启动 Web 开发服务器
cd web && pnpm run dev# 运行 Web 测试  
cd web && pnpm test  # 启动 Storybook  
cd web && pnpm storybook